shelving/util/pathmodule

Typed helpers for working with filesystem and URL paths. Used throughout the router to represent and manipulate AbsolutePath values — strings that always start with /.

Things to know:

  • AbsolutePath is a template-literal type (/${string}). TypeScript enforces it at compile time.
  • All helpers normalise runs of //, convert \ Windows separators, and strip trailing slashes.
  • getPath() returns undefined on invalid input; requirePath() throws RequiredError instead.
  • splitPath("/") returns [] — the root has no segments.

Usage

Checking and converting paths

ts
import { isAbsolutePath, isRelativePath, getPath, requirePath } from "shelving/util";

isAbsolutePath("/foo/bar");   // true
isAbsolutePath("./foo");      // false
isRelativePath("./foo");      // true

getPath("/a//b/./c/");        // "/a/b/c"
getPath("./child", "/parent"); // "/parent/child"
getPath(null);                 // undefined

requirePath("not-a-path");     // throws RequiredError

Building and splitting paths

ts
import { joinPath, splitPath, cleanPath } from "shelving/util";

joinPath("/foo", "bar", "baz");       // "/foo/bar/baz"
joinPath("/foo", ["bar", "baz"]);     // "/foo/bar/baz"
joinPath("/a//", "/b/");              // "/a/b"

splitPath("/foo/bar/baz");  // ["foo", "bar", "baz"]
splitPath("/");             // []

cleanPath("/a//./b/");      // "/a/b"

Matching and navigation checks

ts
import { matchPathPrefix, isPathActive, isPathProud } from "shelving/util";

matchPathPrefix("/app/settings/profile", "/app"); // "/settings/profile"
matchPathPrefix("/app", "/app");                   // "/"
matchPathPrefix("/other", "/app");                 // undefined

isPathActive("/app", "/app");           // true  (exact match)
isPathProud("/app/sub", "/app");        // true  (current is ancestor)
isPathProud("/app", "/app/sub");        // false

Functions

Go

isAbsolutePath()function

Is a string path an absolute path?

isAbsolutePath(path: PossiblePath): path is AbsolutePath
Go

isRelativePath()function

Is a string path a relative path?

isRelativePath(path: PossiblePath): path is RelativePath
Go

getPath()function

Resolve a relative or absolute path and return the absolute path, or undefined if not a valid path.

getPath(inputPath: Nullish<PossiblePath>, inputBase: AbsolutePath = "/"): AbsolutePath | undefined
Go

cleanPath()function

Normalise a path.

cleanPath(path: AbsolutePath): AbsolutePath
cleanPath(path: string): string
Go

requirePath()function

Resolve a relative or absolute path and return the path, or throw RequiredError if not a valid path.

requirePath(path: PossiblePath, base?: AbsolutePath, caller: AnyCaller = requirePath): AbsolutePath
Go

matchPathPrefix()function

Match and strip a base path prefix from a path using segment-aware pathname rules.

matchPathPrefix(target: PossiblePath, base: PossiblePath, caller: AnyCaller = matchPathPrefix): AbsolutePath | undefined
Go

isPathActive()function

Is a target path active relative to the current path?

isPathActive(target: AbsolutePath, current: AbsolutePath): boolean
Go

isPathProud()function

Is a target path proud relative to the current path?

isPathProud(target: AbsolutePath, current: AbsolutePath): boolean
Go

splitPath()function

Get the "segments" in an absolute path.

splitPath(path: PossiblePath): readonly string[]
Go

joinPath()function

Join one or more path parts into a single path string.

joinPath(first: AbsolutePath, ...rest: PathPart[]): AbsolutePath
joinPath(...parts: PathPart[]): string

Types

Go

AbsolutePathtype

Absolute path string starting with a / slash.

`/` | `/${string}`
Go

RelativePathtype

Relative path string that is . dot, or starts with ./ dot slash.

`.` | `./` | `./${string}`
Go

Pathtype

Either an absolute or relative path.

AbsolutePath | RelativePath
Go

PossiblePathtype

Things that can be converted to a path.

string | readonly string[]
Go

PathParttype

A single argument accepted by joinPath() — either a string (full path or single segment) or an array of segments.

string | readonly string[]