shelving 1.192.1 → 1.193.0

package/api/endpoint/util.js

@@ -3,18 +3,15 @@ import { ValueError } from "../../error/ValueError.js";
 import { requireDictionary } from "../../util/dictionary.js";
 import { getResponse, isRequestMethod, parseRequestBody } from "../../util/http.js";
 import { isPlainObject } from "../../util/object.js";
-import { requireURL } from "../../util/url.js";
+import { matchURLPrefix } from "../../util/url.js";
 export function handleEndpoints(base, handlers, request, context, caller = handleEndpoints) {
     const { url, method } = request;
     if (!isRequestMethod(method))
         throw new MethodNotAllowedError("Unsupported request method", { received: method, caller });
-    const { origin: baseOrigin, pathname: basePath } = requireURL(base, undefined, caller);
-    const { origin: requestOrigin, pathname: requestPath, searchParams } = requireURL(url, base, caller);
-    if (baseOrigin !== requestOrigin)
-        throw new NotFoundError("No matching base origin", { expected: baseOrigin, received: requestOrigin, caller });
-    const targetPath = _stripPathPrefix(requestPath, basePath);
+    const { pathname: requestPath, searchParams } = new URL(url, base);
+    const targetPath = matchURLPrefix(url, base);
     if (!targetPath)
-        throw new NotFoundError("No matching base path", { received: requestPath, expected: basePath, caller });
+        throw new NotFoundError("No matching base path", { received: requestPath, caller });
     for (const handler of handlers) {
         const pathParams = handler.endpoint.match(method, targetPath, caller);
         if (!pathParams)
@@ -45,13 +42,3 @@ params, request, context, caller) {
         throw thrown;
     }
 }
-/** Strip a prefix like `/a/b` from a path like `/a/b/c/d` to produce a remainder path like `/c/d`. */
-function _stripPathPrefix(path, prefix) {
-    prefix = prefix === "/" ? "/" : prefix.replace(/\/$/, "");
-    if (prefix === "/")
-        return path;
-    if (path === prefix)
-        return "/";
-    if (path.startsWith(`${prefix}/`))
-        return path.slice(prefix.length);
-}

package/api/provider/APIProvider.d.ts

@@ -1,11 +1,11 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
-import type { URL, URLString } from "../../util/url.js";
+import type { BaseURL, URL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 /** Provider for API endpoints rooted at a common base URL. */
 export declare abstract class APIProvider<P = unknown, R = unknown> {
     /** The base URL for this API. */
-    abstract readonly url: URLString;
+    abstract readonly url: BaseURL;
     /**
      * Render the full final URL for an API request to a given endpoint with a given payload.
      * - Includes `?query` params if this is a `HEAD` or `GET` request.

package/api/provider/ClientAPIProvider.d.ts

@@ -2,7 +2,7 @@ import type { AnyCaller } from "../../util/function.js";
 import { type RequestBodyMethod, type RequestHeadMethod, type RequestOptions } from "../../util/http.js";
 import type { Nullish } from "../../util/null.js";
 import { type PossibleURIParams } from "../../util/uri.js";
-import { type PossibleURL, type URL, type URLString } from "../../util/url.js";
+import { type BaseURL, type PossibleURL, type URL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { APIProvider } from "./APIProvider.js";
 /** Options for a `ClientAPIProvider`. */
@@ -27,7 +27,7 @@ export interface ClientAPIProviderOptions {
  */
 export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProvider<P, R> {
     /** The common base URL for all rendered endpoint requests. */
-    readonly url: URLString;
+    readonly url: BaseURL;
     /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
     readonly options: RequestOptions;
     /** Timeout in milliseconds, or `undefined` for no timeout. */

package/api/provider/ClientAPIProvider.js

@@ -23,7 +23,7 @@ export class ClientAPIProvider extends APIProvider {
     timeout;
     constructor({ url, options = {}, timeout }) {
         super();
-        this.url = requireBaseURL(url, undefined, ClientAPIProvider);
+        this.url = requireBaseURL(url, ClientAPIProvider);
         this.options = options;
         this.timeout = timeout;
     }

package/api/provider/DebugAPIProvider.js

@@ -9,29 +9,29 @@ export class DebugAPIProvider extends ThroughAPIProvider {
             request = this.getRequest(endpoint, payload, options, caller);
         }
         catch (reason) {
-            console.error("✘ FETCH", this.url, endpoint.toString(), payload, reason);
+            console.error("✘ FETCH", this.url.toString(), endpoint.toString(), payload, reason);
             throw reason;
         }
         const debuggedRequest = await debugFullRequest(request);
-        console.debug("… FETCH", this.url, endpoint.toString(), payload, debuggedRequest);
+        console.debug("… FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest);
         // Fetch the response and debug if it throws.
         let response;
         try {
             response = await this.fetch(request);
         }
         catch (reason) {
-            console.error("✘ FETCH", this.url, endpoint.toString(), payload, debuggedRequest, reason);
+            console.error("✘ FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest, reason);
             throw reason;
         }
         const debuggedResponse = await debugFullResponse(response);
         // Convert the  result or any parsing error.
         try {
             const result = await this.parseResponse(endpoint, response, caller);
-            console.debug("✔ FETCH", this.url, endpoint.toString(), payload, debuggedRequest, debuggedResponse, result);
+            console.debug("✔ FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest, debuggedResponse, result);
             return result;
         }
         catch (reason) {
-            console.error("✘ FETCH", this.url, endpoint.toString(), payload, debuggedRequest, debuggedResponse, reason);
+            console.error("✘ FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest, debuggedResponse, reason);
             throw reason;
         }
     }

package/api/provider/ThroughAPIProvider.d.ts

@@ -1,7 +1,7 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Sourceable } from "../../util/source.js";
-import type { URL, URLString } from "../../util/url.js";
+import type { BaseURL, URL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { APIProvider } from "./APIProvider.js";
 /**
@@ -9,7 +9,7 @@ import { APIProvider } from "./APIProvider.js";
  * - Extend this when you want to intercept only selected API operations, such as injecting auth headers or logging.
  */
 export declare class ThroughAPIProvider<P, R> extends APIProvider<P, R> implements Sourceable<APIProvider<P, R>> {
-    get url(): URLString;
+    get url(): BaseURL;
     readonly source: APIProvider<P, R>;
     constructor(source: APIProvider<P, R>);
     renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.192.1",
+	"version": "1.193.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/store/PathStore.d.ts

@@ -1,5 +1,5 @@
 import type { AnyCaller } from "../util/function.js";
-import type { AbsolutePath, PossiblePath } from "../util/path.js";
+import type { AbsolutePath, RelativePath } from "../util/path.js";
 import { BusyStore } from "./BusyStore.js";
 /**
  * Store an absolute path, e.g. `/a/b/c`
@@ -7,16 +7,16 @@ import { BusyStore } from "./BusyStore.js";
  * @param path: The initial value for the store.
  * @param base: The base path to resolve relative paths against.
  */
-export declare class PathStore extends BusyStore<AbsolutePath, PossiblePath> {
+export declare class PathStore extends BusyStore<AbsolutePath, AbsolutePath | RelativePath> {
     readonly base: AbsolutePath;
-    constructor(path?: string, base?: AbsolutePath);
-    protected _convert(possible: PossiblePath, caller: AnyCaller): AbsolutePath;
+    constructor(path?: AbsolutePath | RelativePath, base?: AbsolutePath);
+    protected _convert(possible: AbsolutePath | RelativePath, caller: AnyCaller): AbsolutePath;
     protected _equal(a: AbsolutePath, b: AbsolutePath): boolean;
     /** Based on the current store path, is a path active? */
     isActive(path: AbsolutePath): boolean;
     /** Based on the current store path, is a path proud (i.e. a child of the current store path)? */
     isProud(path: AbsolutePath): boolean;
     /** Get an absolute path from a path relative to the current store path. */
-    getPath(path: string): AbsolutePath;
+    getPath(path: AbsolutePath | RelativePath): AbsolutePath;
     toString(): string;
 }

package/store/PathStore.js

@@ -1,4 +1,4 @@
-import { isPathActive, isPathProud, requirePath } from "../util/path.js";
+import { isPathActive, isPathProud, requireAbsolutePath } from "../util/path.js";
 import { BusyStore } from "./BusyStore.js";
 /**
  * Store an absolute path, e.g. `/a/b/c`
@@ -10,12 +10,12 @@ export class PathStore extends BusyStore {
     base;
     // Override to set default path to `.` and base to `/`
     constructor(path = ".", base = "/") {
-        super(requirePath(path, base, PathStore));
+        super(requireAbsolutePath(path, base, PathStore));
         this.base = base;
     }
     // Override to convert a possible path to an absolute path (relative to `this.base`).
     _convert(possible, caller) {
-        return requirePath(possible, this.base, caller);
+        return requireAbsolutePath(possible, this.base, caller);
     }
     // Override for fast equality.
     _equal(a, b) {
@@ -31,7 +31,7 @@ export class PathStore extends BusyStore {
     }
     /** Get an absolute path from a path relative to the current store path. */
     getPath(path) {
-        return requirePath(path, this.value);
+        return requireAbsolutePath(path, this.value);
     }
     toString() {
         return this.value;

package/util/path.d.ts

@@ -1,37 +1,66 @@
+import type { ImmutableArray } from "./array.js";
 import type { AnyCaller } from "./function.js";
 import type { Nullish } from "./null.js";
 /** Absolute path string starts with `/` slash. */
 export type AbsolutePath = `/` | `/${string}`;
-/** Relative path string starts with `./` or `../` */
-export type RelativePath = `.` | `./${string}` | `..` | `../${string}`;
-/** Either an absolute path string or a relative path string. */
-export type Path = AbsolutePath | RelativePath;
+/** Base path string starts with `/` slash and ends with `/` */
+export type BasePath = `/` | `/${string}`;
+/** Relative path string is `.` dot, or starts with `./` dot slash. */
+export type RelativePath = `.` | `./` | `./${string}`;
+/** Simple path string like `a/b/c` */
+export type SimplePath = string;
 /** Things that can be converted to a path. */
-export type PossiblePath = string | URL;
-/** Is a string path an absolute path? */
-export declare function isAbsolutePath(path: Path): path is AbsolutePath;
+export type PossiblePath = string;
+/** List of non-empty path segments. */
+export type PathSegments = ImmutableArray<string>;
+/**
+ * Is a string a valid path segment, e.g. `abc` or `myFile.pdf` or `.myFile`
+ * - Disallows `""` empty string.
+ * - Disallows runs of `.` as the only contents (e.g. `.`, `..` or `...`).
+ * - Disallows characters outside `A-Za-z0-9_.-`
+ */
+export declare function isPathSegment(segment: string): boolean;
+/** Get a simple path segment after filtering out invalid characters. */
+export declare function getPathSegment(input: string): string;
+/**
+ * Is a string a simple path, e.g. `a/b/c`
+ * - Separated by `/` slashes.
+ * - No leading/trailing slashes.
+ */
+export declare function isPath(path: string): boolean;
 /** Is a string path an absolute path? */
-export declare function isRelativePath(path: Path): path is RelativePath;
+export declare function isAbsolutePath(path: string): path is AbsolutePath;
+/** Is a string path an relative path? */
+export declare function isRelativePath(path: string): path is RelativePath;
+/** Split a path into simple path segments, e.g. `a/b/c` -> ["a", "b", "c"] */
+export declare function splitPath(path: string): PathSegments;
+/** Join path segments into an absolute path, e.g. ["a", "b", "c"] -> `/a/b/c` */
+export declare function joinPath(...segments: PathSegments): AbsolutePath;
 /**
  * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
- * - Uses `new URL` to do path processing, so URL strings can also be resolved.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @param base Absolute path used for resolving relative paths in `possible`
- * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
+ * @return Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`
  */
-export declare function getPath(value: Nullish<PossiblePath>, base?: AbsolutePath): AbsolutePath | undefined;
+export declare function getAbsolutePath(path: Nullish<PossiblePath>, base?: AbsolutePath): AbsolutePath | undefined;
 /**
  * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
  * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function requirePath(value: PossiblePath, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
+export declare function requireAbsolutePath(path: AbsolutePath | RelativePath, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
+/**
+ * Match and strip a base path prefix from a path using segment-aware pathname rules.
+ * - Both inputs must be absolute paths that begin with `/`.
+ * - Returns `/` when the paths are an exact match.
+ */
+export declare function matchPathPrefix(target: AbsolutePath | RelativePath, base: AbsolutePath, caller?: AnyCaller): AbsolutePath | undefined;
 /** Is a target path active? */
 export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
 /** Is a target path proud (i.e. is the current path, or is a child of the current path)? */

package/util/path.js

@@ -1,49 +1,91 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { getURL } from "./url.js";
+const SPLIT_SEGMENTS = /[\\/]+/g;
+const ALL_DOTS = /^\.+$/;
+const UNSAFE_CHARS = /[^A-Za-z0-9_.-]+/g;
+/**
+ * Is a string a valid path segment, e.g. `abc` or `myFile.pdf` or `.myFile`
+ * - Disallows `""` empty string.
+ * - Disallows runs of `.` as the only contents (e.g. `.`, `..` or `...`).
+ * - Disallows characters outside `A-Za-z0-9_.-`
+ */
+export function isPathSegment(segment) {
+    return segment.length > 0 && !ALL_DOTS.test(segment) && !UNSAFE_CHARS.test(segment);
+}
+/** Get a simple path segment after filtering out invalid characters. */
+export function getPathSegment(input) {
+    const output = input.replace(UNSAFE_CHARS, "");
+    return ALL_DOTS.test(output) ? "" : output;
+}
+/**
+ * Is a string a simple path, e.g. `a/b/c`
+ * - Separated by `/` slashes.
+ * - No leading/trailing slashes.
+ */
+export function isPath(path) {
+    return !path.length || path.split("/").every(isPathSegment);
+}
 /** Is a string path an absolute path? */
 export function isAbsolutePath(path) {
-    return path.startsWith("/");
+    return path.startsWith("/") && isPath(path.slice(1));
 }
-/** Is a string path an absolute path? */
+/** Is a string path an relative path? */
 export function isRelativePath(path) {
-    return path.startsWith("./") || path.startsWith("../");
+    return path === "." || (path.startsWith("./") && isPath(path.slice(2)));
 }
-function _cleanPath(path) {
-    return path
-        .replace(/[/\\]+/g, "/") // Normalise slashes.
-        .replace(/(?!^)\/$/g, ""); // Trim trailing slashes.
+/** Split a path into simple path segments, e.g. `a/b/c` -> ["a", "b", "c"] */
+export function splitPath(path) {
+    return path?.split(SPLIT_SEGMENTS).map(getPathSegment).filter(Boolean) ?? [];
+}
+/** Join path segments into an absolute path, e.g. ["a", "b", "c"] -> `/a/b/c` */
+export function joinPath(...segments) {
+    return `/${segments.join("/")}`;
 }
 /**
  * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
- * - Uses `new URL` to do path processing, so URL strings can also be resolved.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @param base Absolute path used for resolving relative paths in `possible`
- * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
+ * @return Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`
  */
-export function getPath(value, base) {
-    const url = getURL(value, base ? `http://j.com${base}${base.endsWith("/") ? "" : "/"}` : "http://j.com");
-    if (url) {
-        const { pathname, search, hash } = url;
-        if (isAbsolutePath(pathname))
-            return `${_cleanPath(pathname)}${search}${hash}`;
-    }
+export function getAbsolutePath(path, base = "/") {
+    if (!path)
+        return;
+    if (path === "/")
+        return "/"; // Hot passthrough.
+    if (path.startsWith("/"))
+        return joinPath(...splitPath(path));
+    return joinPath(...splitPath(base), ...splitPath(path));
 }
 /**
  * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
  * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export function requirePath(value, base, caller = requirePath) {
-    const path = getPath(value, base);
-    if (!path)
-        throw new RequiredError("Invalid path", { received: value, caller });
-    return path;
+export function requireAbsolutePath(path, base, caller = requireAbsolutePath) {
+    const output = getAbsolutePath(path, base);
+    if (!output)
+        throw new RequiredError("Invalid path", { received: path, caller });
+    return output;
+}
+/**
+ * Match and strip a base path prefix from a path using segment-aware pathname rules.
+ * - Both inputs must be absolute paths that begin with `/`.
+ * - Returns `/` when the paths are an exact match.
+ */
+export function matchPathPrefix(target, base, caller = matchPathPrefix) {
+    const basePath = requireAbsolutePath(base, undefined, caller);
+    const targetPath = requireAbsolutePath(target, basePath, caller);
+    if (basePath === "/")
+        return targetPath;
+    if (targetPath === basePath)
+        return "/";
+    if (targetPath.startsWith(`${basePath}/`))
+        return targetPath.slice(basePath.length);
 }
 /** Is a target path active? */
 export function isPathActive(target, current) {

package/util/url.d.ts

@@ -1,7 +1,16 @@
 import type { AnyCaller } from "./function.js";
-import { type Nullish } from "./null.js";
-import type { AbsolutePath, Path } from "./path.js";
+import type { Nullish } from "./null.js";
+import type { AbsolutePath } from "./path.js";
 import type { URI } from "./uri.js";
+type BuiltinURL = globalThis.URL;
+declare const BuiltinURL: {
+    new (url: string | globalThis.URL, base?: string | globalThis.URL): globalThis.URL;
+    prototype: globalThis.URL;
+    canParse(url: string | globalThis.URL, base?: string | globalThis.URL): boolean;
+    createObjectURL(obj: Blob | MediaSource): string;
+    parse(url: string | globalThis.URL, base?: string | globalThis.URL): globalThis.URL | null;
+    revokeObjectURL(url: string): void;
+};
 /**
  * A URL string has a protocol and a `//`.
  * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
@@ -25,9 +34,9 @@ export type URLString = `${string}://${string}`;
  * - You can tell the difference because a URL will have a non-empty `host` property, whereas URIs will never have a `host` (it will be `""` empty string).
  */
 export interface URL extends URI {
-    href: URLString;
-    origin: URLString;
-    pathname: AbsolutePath;
+    readonly href: URLString;
+    readonly origin: URLString;
+    readonly pathname: `/` | `/${string}`;
 }
 /**
  * Construct a correctly-typed `URL` object.
@@ -38,11 +47,11 @@ export interface URL extends URI {
  */
 export interface URLConstructor {
     new (input: URLString | URL, base?: URLString | URL): URL;
-    new (input: URLString | URL | Path, base: URLString | URL): URL;
+    new (input: URLString | URL | string, base: URLString | URL): URL;
 }
 export declare const URL: URLConstructor;
 /** Values that can be converted to a URL instance. */
-export type PossibleURL = string | globalThis.URL;
+export type PossibleURL = string | BuiltinURL;
 /**
  * Is an unknown value a URL object?
  * - Must be a `URL` instance and its origin must start with `scheme://`
@@ -50,18 +59,34 @@ export type PossibleURL = string | globalThis.URL;
 export declare function isURL(value: unknown): value is URL;
 /** Assert that an unknown value is a URL object. */
 export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is URL;
-/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
-export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL | undefined): URL | undefined;
-/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
-export declare function requireURL(possible: PossibleURL, base?: PossibleURL | undefined, caller?: AnyCaller): URL;
 /**
- * Convert a possible URL to a base URL string containing only `origin + pathname`.
- * - The returned pathname always ends in `/`.
- * - Search params and hash fragments are removed.
+ * Convert a possible URL to a URL, or return `undefined` if conversion fails.
+ * - Slightly subverts the builtin relative URL parsing by appending a '/' trailing slash to `base`
+ * - This means if the current URL has a path segment like `/a/b/c` then a relative path like `d/e/f` will be parsed relative to `c` (default behaviour is to strip segments without a trailing slash, which is usually unexpected).
  */
-export declare function getBaseURL(possible: Nullish<PossibleURL>, base?: PossibleURL | undefined): URLString | undefined;
+export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL): URL | undefined;
+/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
+export declare function requireURL(possible: PossibleURL, base?: PossibleURL, caller?: AnyCaller): URL;
 /**
- * Convert a possible URL to a base URL string containing only `origin + pathname`, or throw if conversion fails.
- * - The returned pathname always ends in `/`.
+ * Resolve and match a target URL/path against a base URL and return the remaining path.
+ *
+ * - Need to be valid _URLs_ not just _URIs_, i.e. needs to have `protocol://` at the start.
+ * - Origins need to match, i.e. `http://localhost` !== `http://localhost:4020`
+ * - Relative targets are resolved against the normalized base URL.
+ *
+ * @param target URL to match against `base` — if this is a relative path it will be resolved against `base`
+ *
+ * @returns Absolute path starting with `/`, or `undefined` for origin mismatches or non-matching paths.
  */
-export declare function requireBaseURL(possible: PossibleURL, base?: PossibleURL | undefined, caller?: AnyCaller): URLString;
+export declare function matchURLPrefix(target: PossibleURL, base: PossibleURL, caller?: AnyCaller): AbsolutePath | undefined;
+/** BaseURL is a URL with a guaranteed trailing slash on pathname. */
+export interface BaseURL extends URL {
+    readonly pathname: `/` | `/${string}/`;
+}
+/** Is an unknown value a valid Base URL. */
+export declare function isBaseURL(value: PossibleURL): value is BaseURL;
+/** Get a Base URL. */
+export declare function getBaseURL(input: Nullish<PossibleURL>): BaseURL | undefined;
+/** Require a Base URL. */
+export declare function requireBaseURL(value: PossibleURL, caller: AnyCaller): BaseURL;
+export {};

package/util/url.js

@@ -1,41 +1,46 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { notNullish } from "./null.js";
-export const URL = globalThis.URL;
+const BuiltinURL = globalThis.URL;
+export const URL = BuiltinURL;
 /**
  * Is an unknown value a URL object?
  * - Must be a `URL` instance and its origin must start with `scheme://`
  */
 export function isURL(value) {
-    return value instanceof globalThis.URL && _isValidURL(value);
+    return value instanceof BuiltinURL && _isURL(value);
 }
-function _isValidURL(url) {
-    return url.href.startsWith(`${url.protocol}//`);
+function _isURL(uri) {
+    return uri.href.startsWith(`${uri.protocol}//`);
 }
 /** Assert that an unknown value is a URL object. */
 export function assertURL(value, caller = assertURL) {
     if (!isURL(value))
         throw new RequiredError("Invalid URL", { received: value, caller });
 }
-/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
-export function getURL(possible, base = _BASE) {
-    if (notNullish(possible)) {
-        if (possible instanceof globalThis.URL) {
-            if (_isValidURL(possible))
-                return possible;
-        }
-        else {
-            try {
-                const url = new globalThis.URL(possible, base);
-                if (_isValidURL(url))
-                    return url;
-            }
-            catch {
-                //
-            }
-        }
+/**
+ * Convert a possible URL to a URL, or return `undefined` if conversion fails.
+ * - Slightly subverts the builtin relative URL parsing by appending a '/' trailing slash to `base`
+ * - This means if the current URL has a path segment like `/a/b/c` then a relative path like `d/e/f` will be parsed relative to `c` (default behaviour is to strip segments without a trailing slash, which is usually unexpected).
+ */
+export function getURL(possible, base) {
+    if (!possible)
+        return;
+    const uri = _getBuiltinURL(possible, base);
+    if (uri && _isURL(uri))
+        return uri;
+}
+function _getBuiltinURL(possible, base) {
+    if (possible instanceof BuiltinURL)
+        return possible;
+    try {
+        // We need a base URL to potentially parse this URL against.
+        // Use the document base (if set) as the default URL.
+        const baseURL = getBaseURL(base ?? (typeof document === "object" ? document.baseURI : undefined));
+        return new BuiltinURL(possible, baseURL);
+    }
+    catch {
+        //
     }
 }
-const _BASE = typeof document === "object" ? document.baseURI : undefined;
 /** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
 export function requireURL(possible, base, caller = requireURL) {
     const url = getURL(possible, base);
@@ -43,24 +48,54 @@ export function requireURL(possible, base, caller = requireURL) {
     return url;
 }
 /**
- * Convert a possible URL to a base URL string containing only `origin + pathname`.
- * - The returned pathname always ends in `/`.
- * - Search params and hash fragments are removed.
+ * Resolve and match a target URL/path against a base URL and return the remaining path.
+ *
+ * - Need to be valid _URLs_ not just _URIs_, i.e. needs to have `protocol://` at the start.
+ * - Origins need to match, i.e. `http://localhost` !== `http://localhost:4020`
+ * - Relative targets are resolved against the normalized base URL.
+ *
+ * @param target URL to match against `base` — if this is a relative path it will be resolved against `base`
+ *
+ * @returns Absolute path starting with `/`, or `undefined` for origin mismatches or non-matching paths.
  */
-export function getBaseURL(possible, base = _BASE) {
-    const url = getURL(possible, base);
-    if (url)
-        return _toBaseURL(url);
+export function matchURLPrefix(target, base, caller = matchURLPrefix) {
+    const baseURL = requireBaseURL(base, caller);
+    const targetURL = requireURL(target, baseURL, caller);
+    if (targetURL.origin !== baseURL.origin)
+        return;
+    const basePath = baseURL.pathname;
+    const targetPath = targetURL.pathname;
+    if (basePath === "/")
+        return targetPath;
+    if (targetPath === basePath.slice(0, -1))
+        return "/"; // e.g. `/abc` and `/abc/`
+    if (targetPath.startsWith(basePath))
+        return targetPath.slice(basePath.length - 1);
 }
-function _toBaseURL({ origin, pathname }) {
-    return `${origin}${pathname.endsWith("/") ? pathname : `${pathname}/`}`;
+/** Is an unknown value a valid Base URL. */
+export function isBaseURL(value) {
+    return isURL(value) && _isBaseURL(value);
 }
-/**
- * Convert a possible URL to a base URL string containing only `origin + pathname`, or throw if conversion fails.
- * - The returned pathname always ends in `/`.
- */
-export function requireBaseURL(possible, base, caller = requireBaseURL) {
-    const url = getURL(possible, base);
-    assertURL(url, caller);
-    return _toBaseURL(url);
+function _isBaseURL(uri) {
+    return uri.pathname.endsWith("/");
+}
+/** Get a Base URL. */
+export function getBaseURL(input) {
+    if (!input)
+        return;
+    const uri = _getBuiltinURL(input, undefined);
+    if (!uri || !_isURL(uri))
+        return;
+    if (_isBaseURL(uri))
+        return uri;
+    const base = typeof input === "string" ? uri : new BuiltinURL(uri);
+    base.pathname = `${uri.pathname}/`; // Add a trailing slash.
+    return base;
+}
+/** Require a Base URL. */
+export function requireBaseURL(value, caller) {
+    const url = getBaseURL(value);
+    if (!url)
+        throw new RequiredError("Invalid base URL", { received: value, caller });
+    return url;
 }