A simple library I've made to work easily with paths in Deno 🦕 in a more standardized 🌎 and predictable way.
I know there are great and way more robust path libraries for Deno out there. But honestly, I've never liked how they tend to use your OS' separator instead of using a unified one. That has been a problem for me sometimes, so I decided to code my own library that —at least from my POV— is more predictable in the resulting path string.
I originally created this library for my own personal use, but I thought it could be helpful to others, so I decided to make it public. That said, updates will mostly depend on my own needs as I continue to use way-ts in my projects. While the APIs will reflect my current requirements, I'll aim to keep it user-friendly. Just keep in mind that updates may not be frequent.
The way-ts project follows Deno's official formatting standards. All source code is automatically formatted using the deno fmt command, with settings defined in the deno.json configuration file.
You can import way-ts in your project like this:
import * as way from "jsr:@jabonchan/way-ts";Encapsulates information about a path in a single structured object. The properties correspond to the results returned by the various methods:
way.extnameway.stemnameway.basenameway.dirnameway.dirpathway.separateway.driveletterway.normalizeway.windowsway.unix
In the example below, each property includes a comment indicating the method it derives from:
interface ParsedPath {
entry: {
extension: string | null; // way.extname
stem: string | null; // way.stemname
base: string | null; // way.basename
path: {
windows: string; // way.windows
unix: string; // way.unix
normal: string; // way.normalize
}
}
directory: {
name: string | null; // way.dirname
path: string | null; // way.dirpath
}
entries: string[]; // way.separate
drive: string | null; // way.driveletter
}This section provides an overview of the available methods in way-ts. Each method is designed to simplify path manipulation and ensure consistent behavior across different environments.
way.normalize: Normalize paths for consistency.way.separate: Split paths into components.way.windows: Convert paths to Windows format.way.unix: Convert paths to UNIX format.way.join: Combine multiple paths into one.
way.execPath: Retrieve the executable path.way.cwd: Get the current working directory.
way.basename: Extract the base name of a path.way.extname: Get the extension of a path.way.stemname: Retrieve the stem name of a path.way.dirname: Get the parent directory's name.way.dirpath: Retrieve the parent directory's path.way.driveletter: Extract the drive letter from a path.way.parse: Returns an object containing info about the path.
way.isAbsolute: Check if a path is absolute.way.isRelative: Check if a path is relative.way.isSandboxed: Verify if a path is within a sandbox.way.isDriveLetter: Determine if a string is a valid drive letter.
Each method is documented in detail below, with examples to help you understand its usage.
Unless otherwise stated, all paths returned by the functions in this module are passed to
way.normalizefirst before being returned.
Normalizes a path-like string or URL. Normalizes relative directives, removes surrounding slashes (Except for root-only paths, such as C:/ or /), parses file: URLs, uses upper case for drive letters, removes forbidden characters in Windows (whether you're using UNIX-based systems or Windows). UNIX separators (/) are always used. Empty paths return ./.
function normalize(entrypath: string | URL): stringSplits the path by its separators, returning an array of base names or relative directives.
function separate(entrypath: string | URL): string[]This method builds upon the output of
way.normalize. While it replaces path separators with\for Windows compatibility, all other aspects of the path remain normalized according to the rules defined byway.normalize.
Normalizes and replaces UNIX separators in the path with Windows separators. If it's absolute and doesn't have a drive letter, it adds C:/ at the start of the path.
function windows(entrypath: string | URL): stringThis method builds upon the output of
way.normalize. While it removes the drive letter, all other aspects of the path remain normalized according to the rules defined byway.normalize.
Normalizes the path, and, if it's absolute and has a drive letter, it removes it.
function unix(entrypath: string | URL): stringCombines all the given paths into a single one by appending each one at the end of the previous one. Resolves relative directives. It can't go higher than the root path by using relative directives (i.e. / or C:/).
function join(entrypath1: string | URL, ...entrypaths: (string | URL)[]): string🗝️ Requires
--allow-readpermission.
Returns the path provided by Deno.execPath.
function execPath(): string🗝️ Requires
--allow-readpermission.
Returns the path provided by Deno.cwd.
function cwd(): stringReturns the base name of a given path. If the path consists solely of a relative directive (e.g., ./ or ../), null is returned. Additionally, the drive letter (including the :) is treated as a base name. In this library, the "base name" refers to both the stem and the extension—essentially, the full name of the entry.
function basename(entrypath: string | URL): string | nullReturns the extension name (including the .) of the path in lower case. If it doesn't has an extension (i.e. make or ../) , null is returned instead.
function extname(entrypath: string | URL): string | nullReturns the stem name of the path. If it doesn't has a stem name (i.e. .env or ../), null is returned instead. Additionally, the drive letter (including the :) is treated as a stem name.
function stemname(entrypath: string | URL): string | nullReturns the parent directory's base name of the given path. If it doesn't has a parent directory (i.e. ./entry or ../), null is returned instead.
function dirname(entrypath: string | URL): string | nullReturns the parent directory of the given path. It can't go higher than the root path (i.e. / or C:/).
function dirpath(entrypath: string | URL): stringReturns the given path's drive letter (: is not included). If none found, null is returned.
function driveletter(entrypath: string | URL): string | nullExtracts information from the given path and returns it as a ParsedPath object. For details, see ParsedPath.
function parse(entrypath: string | URL): ParsedPathChecks if the provided path is absolute.
function isAbsolute(entrypath: string | URL): booleanChecks if the provided path is relative.
function isRelative(entrypath: string | URL): booleanChecks whether the entrypath is located within the sandbox path. This check is case-insensitive. It will always return false if one or both paths are relative.
function isSandboxed(sandbox: string | URL, entrypath: string | URL): booleanChecks if drive is a Windows drive letter. Returns true only for LETTER: or LETTER:/. If the path includes anything beyond the drive letter, it returns false.
function isDriveLetter(drive: string | URL): booleanway-ts uses Deno's built-in test feature. To run all the tests, use the following command:
deno testYou can also pass the --filter flag to run specific tests based on their name pattern:
deno test --filter match-patternTo see the available test names, you can check the source code. Some of the test names include:
path-checkspath-infoformatting
way-ts uses Deno's expect from the Deno Standard Library for testing, which is licensed under the MIT license. I do not own nor have any right over this dependency.
way-ts is licensed under the MIT License. By using this library, you agree to all the terms and conditions stated in the license.