shelving 1.193.2 → 1.195.0

package/api/cache/APICache.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../../util/function.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointCache } from "./EndpointCache.js";
@@ -12,13 +13,20 @@ export declare class APICache<P, R> implements AsyncDisposable {
     private _get;
     /** Get (or create) the `EndpointCache` for the given endpoint. */
     get<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): EndpointCache<PP, RR>;
+    /**
+     * Fetch (or return a cached result) for the given endpoint and payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number, caller?: AnyCaller): Promise<RR>;
     /** Invalidate a specific store for an endpoint. */
     invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     /** Invalidate all stores for an endpoint. */
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     /** Trigger a refetch on a specific store for an endpoint. */
-    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number): void;
     /** Trigger a refetch on all stores for an endpoint. */
-    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, maxAge?: number): void;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/APICache.js

@@ -17,6 +17,15 @@ export class APICache {
     get(endpoint) {
         return this._get(endpoint) || setMapItem(this._endpoints, endpoint, new EndpointCache(endpoint, this.provider));
     }
+    /**
+     * Fetch (or return a cached result) for the given endpoint and payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    async call(endpoint, payload, maxAge, caller = this.call) {
+        return this.get(endpoint).call(payload, maxAge, caller);
+    }
     /** Invalidate a specific store for an endpoint. */
     invalidate(endpoint, payload) {
         this._get(endpoint)?.invalidate(payload);
@@ -26,12 +35,12 @@ export class APICache {
         this._get(endpoint)?.invalidateAll();
     }
     /** Trigger a refetch on a specific store for an endpoint. */
-    refresh(endpoint, payload) {
-        this._get(endpoint)?.refresh(payload);
+    refresh(endpoint, payload, maxAge) {
+        this._get(endpoint)?.refresh(payload, maxAge);
     }
     /** Trigger a refetch on all stores for an endpoint. */
-    refreshAll(endpoint) {
-        this._get(endpoint)?.refreshAll();
+    refreshAll(endpoint, maxAge) {
+        this._get(endpoint)?.refreshAll(maxAge);
     }
     // Implement `AsyncDisposable`
     [Symbol.asyncDispose]() {

package/api/cache/EndpointCache.d.ts

@@ -13,13 +13,20 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
     constructor(endpoint: Endpoint<P, R>, provider: APIProvider<P, R>);
     /** Get (or create) the `EndpointStore` for the given payload. */
     get(payload: P, caller?: AnyCaller): EndpointStore<P, R>;
+    /**
+     * Fetch (or return a cached result) for the given payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    call(payload: P, maxAge?: number, caller?: AnyCaller): Promise<R>;
     /** Invalidate a specific store. */
     invalidate(payload: P, caller?: AnyCaller): void;
     /** Invalidate all stores. */
     invalidateAll(): void;
     /** Trigger a refetch on a specific store. */
-    refresh(payload: P, caller?: AnyCaller): Promise<void>;
+    refresh(payload: P, maxAge?: number, caller?: AnyCaller): Promise<void>;
     /** Trigger a refetch on all stores. */
-    refreshAll(): Promise<void>;
+    refreshAll(maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/EndpointCache.js

@@ -19,6 +19,17 @@ export class EndpointCache {
         const url = this.provider.renderURL(this.endpoint, payload, caller).href;
         return this._endpoints.get(url) || setMapItem(this._endpoints, url, new EndpointStore(this.endpoint, payload, this.provider));
     }
+    /**
+     * Fetch (or return a cached result) for the given payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    async call(payload, maxAge, caller = this.call) {
+        const store = this.get(payload, caller);
+        await store.refresh(maxAge);
+        return store.value;
+    }
     /** Invalidate a specific store. */
     invalidate(payload, caller = this.invalidate) {
         this.get(payload, caller)?.invalidate();
@@ -29,12 +40,12 @@ export class EndpointCache {
             store.invalidate();
     }
     /** Trigger a refetch on a specific store. */
-    async refresh(payload, caller = this.invalidate) {
-        await this.get(payload, caller)?.refresh();
+    async refresh(payload, maxAge, caller = this.invalidate) {
+        await this.get(payload, caller)?.refresh(maxAge);
     }
     /** Trigger a refetch on all stores. */
-    async refreshAll() {
-        await awaitValues(...this._endpoints.values().map(store => store.refresh()));
+    async refreshAll(maxAge) {
+        await awaitValues(...this._endpoints.values().map(store => store.refresh(maxAge)));
     }
     // Implement `AsyncDisposable`
     [Symbol.asyncDispose]() {

package/api/provider/APIProvider.d.ts

@@ -1,11 +1,10 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.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: BaseURL;
+    abstract readonly url: URL;
     /**
      * 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,12 +2,19 @@ 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 BaseURL, type PossibleURL, type URL } from "../../util/url.js";
+import { type PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { APIProvider } from "./APIProvider.js";
 /** Options for a `ClientAPIProvider`. */
 export interface ClientAPIProviderOptions {
-    /** The common base URL for all rendered endpoint requests. */
+    /**
+     * The common base URL for all rendered endpoint requests.
+     *
+     * Note: When resolving URLs for endpoints this is treated as if it ends in a slash.
+     * - e.g. in `http://p.com/a/b/c` the path will be relative to `c` as if a `/` trailing slash was present.
+     * - This is different to the default behaviour of `new URL()`, but is the more natural expected result
+     * - This is consistent with our e.g. `getURL()` utilities.
+     */
     readonly url: PossibleURL;
     /**
      * Options used for HTTP requests created with `this.getRequest()` and `this.fetch()`
@@ -27,7 +34,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: BaseURL;
+    readonly url: URL;
     /** 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

@@ -28,6 +28,10 @@ export class ClientAPIProvider extends APIProvider {
         this.timeout = timeout;
     }
     renderURL(endpoint, payload, caller = this.renderURL) {
+        // Construct the full URL from `this.url` and the rendered path.
+        // Adding the `.` turns the absolute path from `renderPath()` into a relative URL.
+        // `requireURL()` resolves that path relative to `this.url`
+        // Note that `requireURL()` rendering treats paths as folders, e.g. in `/a/b/c` the path will be relative to `c` not `b`
         const url = requireURL(`.${endpoint.renderPath(payload, caller)}`, this.url, caller);
         // HEAD or GET have no body (but payload can only be data object).
         if (isRequestHeadMethod(endpoint.method)) {

package/api/provider/ThroughAPIProvider.d.ts

@@ -1,7 +1,6 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Sourceable } from "../../util/source.js";
-import type { BaseURL, URL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { APIProvider } from "./APIProvider.js";
 /**
@@ -9,7 +8,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(): BaseURL;
+    get url(): URL;
     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/db/cache/CollectionCache.d.ts

@@ -23,15 +23,15 @@ export declare class CollectionCache<I extends Identifier, T extends Data> imple
     /** Get (or create) the `QueryStore` for the given query. */
     getQuery(query: Query<Item<I, T>>): QueryStore<I, T>;
     /** Refresh a specific item store. */
-    refreshItem(id: I): Promise<void>;
+    refreshItem(id: I, maxAge?: number): Promise<void>;
     /** Refresh every cached item store. */
-    refreshItems(): Promise<void>;
+    refreshItems(maxAge?: number): Promise<void>;
     /** Refresh a specific query store. */
-    refreshQuery(query: Query<Item<I, T>>): Promise<void>;
+    refreshQuery(query: Query<Item<I, T>>, maxAge?: number): Promise<void>;
     /** Refresh every cached query store. */
-    refreshQueries(): Promise<void>;
+    refreshQueries(maxAge?: number): Promise<void>;
     /** Refresh every cached store (items and queries). */
-    refreshAll(): Promise<void>;
+    refreshAll(maxAge?: number): Promise<void>;
     private _queryKey;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/cache/CollectionCache.js

@@ -29,24 +29,24 @@ export class CollectionCache {
         return this._queries.get(key) || setMapItem(this._queries, key, new QueryStore(this.collection, query, this.provider, this.memory));
     }
     /** Refresh a specific item store. */
-    async refreshItem(id) {
-        await this._items.get(id)?.refresh();
+    async refreshItem(id, maxAge) {
+        await this._items.get(id)?.refresh(maxAge);
     }
     /** Refresh every cached item store. */
-    async refreshItems() {
-        await awaitValues(...this._items.values().map(store => store.refresh()));
+    async refreshItems(maxAge) {
+        await awaitValues(...this._items.values().map(store => store.refresh(maxAge)));
     }
     /** Refresh a specific query store. */
-    async refreshQuery(query) {
-        await this._queries.get(this._queryKey(query))?.refresh();
+    async refreshQuery(query, maxAge) {
+        await this._queries.get(this._queryKey(query))?.refresh(maxAge);
     }
     /** Refresh every cached query store. */
-    async refreshQueries() {
-        await awaitValues(...this._queries.values().map(store => store.refresh()));
+    async refreshQueries(maxAge) {
+        await awaitValues(...this._queries.values().map(store => store.refresh(maxAge)));
     }
     /** Refresh every cached store (items and queries). */
-    async refreshAll() {
-        await awaitValues(this.refreshItems(), this.refreshQueries());
+    async refreshAll(maxAge) {
+        await awaitValues(this.refreshItems(maxAge), this.refreshQueries(maxAge));
     }
     _queryKey(query) {
         return JSON.stringify(query);

package/db/cache/DBCache.d.ts

@@ -25,14 +25,14 @@ export declare class DBCache<I extends Identifier = Identifier, T extends Data =
     /** Get (or create) a `QueryStore` for a collection/query in one hop. */
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): QueryStore<II, TT>;
     /** Refresh a specific item store for a collection. */
-    refreshItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    refreshItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, maxAge?: number): Promise<void>;
     /** Refresh every cached item store for a collection. */
-    refreshItems<II extends I, TT extends T>(collection: Collection<string, II, TT>): Promise<void>;
+    refreshItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     /** Refresh a specific query store for a collection. */
-    refreshQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    refreshQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, maxAge?: number): Promise<void>;
     /** Refresh every cached query store for a collection. */
-    refreshQueries<II extends I, TT extends T>(collection: Collection<string, II, TT>): Promise<void>;
+    refreshQueries<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     /** Refresh every cached store (items and queries) for a collection. */
-    refreshAll<II extends I, TT extends T>(collection: Collection<string, II, TT>): Promise<void>;
+    refreshAll<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/cache/DBCache.js

@@ -32,24 +32,24 @@ export class DBCache {
         return this.get(collection).getQuery(query);
     }
     /** Refresh a specific item store for a collection. */
-    async refreshItem(collection, id) {
-        await this._get(collection)?.refreshItem(id);
+    async refreshItem(collection, id, maxAge) {
+        await this._get(collection)?.refreshItem(id, maxAge);
     }
     /** Refresh every cached item store for a collection. */
-    async refreshItems(collection) {
-        await this._get(collection)?.refreshItems();
+    async refreshItems(collection, maxAge) {
+        await this._get(collection)?.refreshItems(maxAge);
     }
     /** Refresh a specific query store for a collection. */
-    async refreshQuery(collection, query) {
-        await this._get(collection)?.refreshQuery(query);
+    async refreshQuery(collection, query, maxAge) {
+        await this._get(collection)?.refreshQuery(query, maxAge);
     }
     /** Refresh every cached query store for a collection. */
-    async refreshQueries(collection) {
-        await this._get(collection)?.refreshQueries();
+    async refreshQueries(collection, maxAge) {
+        await this._get(collection)?.refreshQueries(maxAge);
     }
     /** Refresh every cached store (items and queries) for a collection. */
-    async refreshAll(collection) {
-        await this._get(collection)?.refreshAll();
+    async refreshAll(collection, maxAge) {
+        await this._get(collection)?.refreshAll(maxAge);
     }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.193.2",
+	"version": "1.195.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,12 +9,12 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.13",
+		"@biomejs/biome": "^2.4.14",
 		"@google-cloud/firestore": "^8.5.0",
 		"@types/bun": "^1.3.13",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "^7.0.0-dev.20260421.2",
+		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
 		"firebase": "^12.12.1",
 		"react": "^19.2.5",
 		"react-dom": "^19.2.5"

package/store/FetchStore.d.ts

@@ -14,6 +14,7 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
     get loading(): boolean;
     write(input: StoreInput<TT>): void;
     read(): import("./Store.js").StoreInternal<T>;
+    get age(): number;
     constructor(value: T | typeof NONE, callback?: FetchCallback<TT>);
     /**
      * Fetch the result for this store now.
@@ -21,7 +22,7 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
      */
-    refresh(): Promise<boolean> | boolean;
+    refresh(maxAge?: number): Promise<boolean> | boolean;
     private _pendingRefresh;
     /**
      * Current `AbortSignal` for this store's in-flight fetch.
@@ -36,13 +37,13 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      */
     protected _fetch(signal: AbortSignal): TT | PromiseLike<TT>;
     private _callback;
+    /** Whether this store is has currently been invalidated and needs a refresh. */
+    get invalidated(): boolean;
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
      * - Triggers `abort()` so any current awaits are cancelled.
      */
     invalidate(): void;
     private _invalidation;
-    /** Re-fetch now if the current value is older than `maxAge` milliseconds or has been invalidated. */
-    refreshStale(maxAge: number): Promise<boolean> | boolean;
     abort(): void;
 }

package/store/FetchStore.js

@@ -15,7 +15,7 @@ export class FetchStore extends BusyStore {
     // We optimistically refresh so the value is available the next time the user wants it.
     get loading() {
         const loading = super.loading;
-        if (this._invalidation || loading)
+        if (this.invalidated || loading)
             void this.refresh();
         return loading;
     }
@@ -33,6 +33,10 @@ export class FetchStore extends BusyStore {
         this.loading; // Ping loading to possibly trigger the intiial fetch.
         return super.read();
     }
+    // Override to consider invalid to be really old.
+    get age() {
+        return this.invalidated ? Infinity : super.age;
+    }
     // Override to create to save `callback`
     constructor(value, callback) {
         super(value);
@@ -44,9 +48,11 @@ export class FetchStore extends BusyStore {
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
      */
-    refresh() {
+    refresh(maxAge) {
         if (this._pendingRefresh)
             return this._pendingRefresh;
+        if (!this.stale(maxAge))
+            return false;
         try {
             const value = this._fetch(this.signal); // Retrieving a new signal calls `abort()` which cancels the previous one.
             if (isAsync(value))
@@ -81,6 +87,10 @@ export class FetchStore extends BusyStore {
         return this._callback(signal);
     }
     _callback;
+    /** Whether this store is has currently been invalidated and needs a refresh. */
+    get invalidated() {
+        return !!this._invalidation;
+    }
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
      * - Triggers `abort()` so any current awaits are cancelled.
@@ -90,12 +100,6 @@ export class FetchStore extends BusyStore {
         this._invalidation++;
     }
     _invalidation = 0;
-    /** Re-fetch now if the current value is older than `maxAge` milliseconds or has been invalidated. */
-    refreshStale(maxAge) {
-        if (this._invalidation || this.age > maxAge)
-            return this.refresh();
-        return true;
-    }
     // Override to abort any current in-flight fetch and pending async operation.
     // - Sends `ABORT` to the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
     // - Any pending `await()` result will be silently discarded.

package/store/Store.d.ts

@@ -92,6 +92,15 @@ export declare class Store<T, TT = T> implements AsyncIterable<T, void, void>, A
      * @example if (store.age > MINUTE) refreshStore(store);
      */
     get age(): number;
+    /**
+     * Whether this store is stale based on a `maxAge` value in milliseconds.
+     *
+     * @param maxAge The maximum age for the stale check.
+     * - `0` zero means "always refresh" (this is the default).
+     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - Any other value may or may not be stale based on `this.age`
+     */
+    stale(maxAge?: number): boolean;
     /** Current error of this store, or `undefined` if there is no error. */
     get reason(): unknown;
     set reason(reason: unknown);

package/store/Store.js

@@ -132,6 +132,17 @@ export class Store {
         const time = this.time;
         return typeof time === "number" ? Date.now() - time : Infinity;
     }
+    /**
+     * Whether this store is stale based on a `maxAge` value in milliseconds.
+     *
+     * @param maxAge The maximum age for the stale check.
+     * - `0` zero means "always refresh" (this is the default).
+     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - Any other value may or may not be stale based on `this.age`
+     */
+    stale(maxAge = 0) {
+        return this.age >= maxAge;
+    }
     /** Current error of this store, or `undefined` if there is no error. */
     get reason() {
         return this._reason;

package/store/URLStore.d.ts

@@ -1,14 +1,14 @@
 import type { AnyCaller } from "../util/function.js";
 import type { AbsolutePath } from "../util/index.js";
 import { type PossibleURIParams, type URIParams, type URIScheme } from "../util/uri.js";
-import { type PossibleURL, type URL, type URLString } from "../util/url.js";
+import { type ImmutableURL, type PossibleURL, type URLString } from "../util/url.js";
 import { BusyStore } from "./BusyStore.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
-export declare class URLStore extends BusyStore<URL, PossibleURL> {
-    readonly base: URL | undefined;
+export declare class URLStore extends BusyStore<ImmutableURL, PossibleURL> {
+    readonly base: ImmutableURL | undefined;
     constructor(url: PossibleURL, base?: PossibleURL);
-    protected _convert(value: PossibleURL, caller: AnyCaller): URL;
-    protected _equal(a: URL, b: URL): boolean;
+    protected _convert(value: PossibleURL, caller: AnyCaller): ImmutableURL;
+    protected _equal(a: ImmutableURL, b: ImmutableURL): boolean;
     get href(): URLString;
     set href(href: URLString);
     get origin(): URLString;
@@ -40,12 +40,12 @@ export declare class URLStore extends BusyStore<URL, PossibleURL> {
     /** Clear all params from this URL. */
     clearParams(): void;
     /** Return the current URL with an additional param. */
-    withParam(key: string, value: unknown): URL;
+    withParam(key: string, value: unknown): ImmutableURL;
     /** Return the current URL with an additional param. */
-    withParams(params: PossibleURIParams): URL;
+    withParams(params: PossibleURIParams): ImmutableURL;
     /** Return the current URL with an additional param. */
-    omitParams(...keys: string[]): URL;
+    omitParams(...keys: string[]): ImmutableURL;
     /** Return the current URL with an additional param. */
-    omitParam(key: string): URL;
+    omitParam(key: string): ImmutableURL;
     toString(): string;
 }

package/util/uri.d.ts

@@ -2,7 +2,7 @@ import type { ImmutableArray } from "./array.js";
 import { type ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
 import { type Nullish } from "./null.js";
-import type { URL, URLString } from "./url.js";
+import type { ImmutableURL, URLString } from "./url.js";
 /**
  * Valid URI string is anything following `protocol:resource` format, e.g. `urn:isbn:0451450523` or `http://example.com/path/to/resource`
  *
@@ -14,6 +14,18 @@ import type { URL, URLString } from "./url.js";
  * - All URLs are also URIs, but not all URIs are URLs.
  */
 export type URIString = `${string}:${string}`;
+export type URISearch = `?${string}`;
+export type URIHash = `#${string}`;
+/**
+ * Construct a correctly-typed `URI` object.
+ * - This is a more correctly typed version of the builtin Javascript `URI` constructor.
+ * - Requires a URI string, URI object, or path as input, and optionally a base URI.
+ * - If a path is provided as input, a base URI _must_ also be provided.
+ * - The returned type is
+ */
+export interface ImmutableURIConstructor {
+    new (input: URIString | ImmutableURI): ImmutableURI;
+}
 /**
  * Object that describes a valid URI, e.g. `urn:isbn:0451450523` or `http://example.com/path/to/resource`
  * - Improves the builtin Javascript `URL` class to more accurately type its properties.
@@ -24,37 +36,31 @@ export type URIString = `${string}:${string}`;
  * - The absence of `//` indicates a non-hierarchical URI.
  * - URLs can be considered as "hierarchical URIs".
  * - All URLs are also URIs, but not all URIs are URLs.
- *
- * Javascript URL problems:
- * - Javascript `URL` instance can actually represent any kind of URI (not just URLs).
- * - It's more "correct" terminology to use `URI` to refer to what the Javascript `URL` class represents.
- * - 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 URI extends globalThis.URL {
-    protocol: URIScheme;
-    href: URIString;
-}
-/**
- * Construct a correctly-typed `URI` object.
- * - This is a more correctly typed version of the builtin Javascript `URI` constructor.
- * - Requires a URI string, URI object, or path as input, and optionally a base URI.
- * - If a path is provided as input, a base URI _must_ also be provided.
- * - The returned type is
  */
-export interface URIConstructor {
-    new (input: URIString | URI): URI;
+export interface ImmutableURI extends URL {
+    readonly hash: URIHash | ``;
+    readonly host: string;
+    readonly hostname: string;
+    readonly href: URIString;
+    readonly origin: URIString | `null`;
+    readonly password: string;
+    readonly pathname: string;
+    readonly port: string;
+    readonly protocol: URIScheme;
+    readonly search: URISearch | ``;
+    readonly username: string;
 }
-export declare const URI: URIConstructor;
-/** Values that can be converted to a URI instance. */
-export type PossibleURI = string | globalThis.URL;
+export declare const ImmutableURI: ImmutableURIConstructor;
+/** Values that can be converted to an ImmutableURI instance. */
+export type PossibleURI = string | URL;
 /** Is an unknown value a URI object? */
-export declare function isURI(value: unknown): value is URI;
+export declare function isURI(value: unknown): value is ImmutableURI;
 /** Assert that an unknown value is a URI object. */
-export declare function assertURI(value: unknown, caller?: AnyCaller): asserts value is URI;
+export declare function assertURI(value: unknown, caller?: AnyCaller): asserts value is ImmutableURI;
 /** Convert a possible URI to a URI, or return `undefined` if conversion fails. */
-export declare function getURI(possible: Nullish<PossibleURI>): URI | undefined;
+export declare function getURI(possible: Nullish<PossibleURI>): ImmutableURI | undefined;
 /** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
-export declare function requireURI(possible: PossibleURI, caller?: AnyCaller): URI;
+export declare function requireURI(possible: PossibleURI, caller?: AnyCaller): ImmutableURI;
 /** Convert a possible URI to a URI string, or return `undefined` if conversion fails. */
 export declare function getURIString(possible: Nullish<PossibleURI>): URIString | undefined;
 /** Convert a possible URI to a URI string, or throw `RequiredError` if conversion fails. */
@@ -67,19 +73,19 @@ export type PossibleURIParams = PossibleURI | URLSearchParams | ImmutableDiction
  * Get a set of params for a URI as a dictionary.
  * - Any params with `undefined` value will be ignored.
  */
-export declare function getURIParams(input: PossibleURIParams, caller?: AnyCaller): URIParams;
+export declare function getURIParams(params: PossibleURIParams, caller?: AnyCaller): URIParams;
 /** Get a single named param from a URI. */
-export declare function getURIParam(input: PossibleURIParams, key: string): string | undefined;
+export declare function getURIParam(params: PossibleURIParams, key: string): string | undefined;
 /** Get a single named param from a URI. */
-export declare function requireURIParam(input: PossibleURIParams, key: string, caller?: AnyCaller): string;
+export declare function requireURIParam(params: PossibleURIParams, key: string, caller?: AnyCaller): string;
 /**
  * Return a URI with a new param set (or same URI if no changes were made).
  * - Any params with `undefined` value will be ignored.
  *
  * @throws `ValueError` if the value could not be converted to a string.
  */
-export declare function withURIParam(url: URL | URLString, key: string, value: unknown, caller?: AnyCaller): URL;
-export declare function withURIParam(url: PossibleURI, key: string, value: unknown, caller?: AnyCaller): URI;
+export declare function withURIParam(uri: ImmutableURL | URLString, key: string, value: unknown, caller?: AnyCaller): ImmutableURL;
+export declare function withURIParam(uri: PossibleURI, key: string, value: unknown, caller?: AnyCaller): ImmutableURI;
 /**
  * Return a URI with several new params set (or same URI if no changes were made).
  * - Any params with `undefined` value will be ignored.
@@ -89,18 +95,18 @@ export declare function withURIParam(url: PossibleURI, key: string, value: unkno
  *
  * @throws `ValueError` if any of the values could not be converted to strings.
  */
-export declare function withURIParams(url: URL | URLString, params: Nullish<PossibleURIParams>, caller?: AnyCaller): URL;
-export declare function withURIParams(url: PossibleURI, params: Nullish<PossibleURIParams>, caller?: AnyCaller): URI;
+export declare function withURIParams(uri: ImmutableURL | URLString, params: Nullish<PossibleURIParams>, caller?: AnyCaller): ImmutableURL;
+export declare function withURIParams(uri: PossibleURI, params: Nullish<PossibleURIParams>, caller?: AnyCaller): ImmutableURI;
 /**
  * Return a URI without one or more params (or same URI if no changes were made).
  */
-export declare function omitURIParams(url: URL | URLString, ...keys: string[]): URL;
-export declare function omitURIParams(url: PossibleURI, ...keys: string[]): URI;
+export declare function omitURIParams(uri: ImmutableURL | URLString, ...keys: string[]): ImmutableURL;
+export declare function omitURIParams(uri: PossibleURI, ...keys: string[]): ImmutableURI;
 /** Return a URI without a param (or same URI if no changes were made). */
-export declare const omitURIParam: (url: PossibleURI, key: string) => URI;
+export declare const omitURIParam: (uri: PossibleURI, key: string) => ImmutableURI;
 /** Return a URI with no search params (or same URI if no changes were made). */
-export declare function clearURIParams(url: URL | URLString, caller?: AnyCaller): URL;
-export declare function clearURIParams(url: PossibleURI, caller?: AnyCaller): URI;
+export declare function clearURIParams(uri: ImmutableURL | URLString, caller?: AnyCaller): ImmutableURL;
+export declare function clearURIParams(uri: PossibleURI, caller?: AnyCaller): ImmutableURI;
 /** A single schema for a URL. */
 export type URIScheme = `${string}:`;
 /** List of allowed URI schemes. */

package/util/uri.js

@@ -3,10 +3,10 @@ import { ValueError } from "../error/ValueError.js";
 import { getDictionaryItems, isDictionary } from "./dictionary.js";
 import { notNullish } from "./null.js";
 import { getString, isString } from "./string.js";
-export const URI = globalThis.URL;
+export const ImmutableURI = URL;
 /** Is an unknown value a URI object? */
 export function isURI(value) {
-    return value instanceof URI;
+    return value instanceof ImmutableURI;
 }
 /** Assert that an unknown value is a URI object. */
 export function assertURI(value, caller = assertURI) {
@@ -19,7 +19,7 @@ export function getURI(possible) {
         if (isURI(possible))
             return possible;
         try {
-            return new globalThis.URL(possible, _BASE);
+            return new URL(possible, _BASE);
         }
         catch {
             return undefined;
@@ -50,16 +50,16 @@ export function requireURIString(possible, caller = requireURIString) {
  * 2. So when converting this to a simple data object, only one value per key can be represented, but it needs to be the _first_ one.
  * 3. Since we're looping through anyway, we also take the time to convert values to strings, so we can accept a wider range of input types.
  */
-function* getURIEntries(input, caller = getURIParams) {
-    if (input instanceof URLSearchParams) {
-        yield* input;
+function* getURIEntries(params, caller = getURIParams) {
+    if (params instanceof URLSearchParams) {
+        yield* params;
     }
-    else if (isString(input) || input instanceof globalThis.URL) {
-        yield* requireURI(input, caller).searchParams;
+    else if (isString(params) || params instanceof URL) {
+        yield* requireURI(params, caller).searchParams;
     }
     else {
         const done = [];
-        for (const [key, value] of getDictionaryItems(input)) {
+        for (const [key, value] of getDictionaryItems(params)) {
             if (value === undefined)
                 continue; // Skip undefined.
             if (done.includes(key))
@@ -76,63 +76,63 @@ function* getURIEntries(input, caller = getURIParams) {
  * Get a set of params for a URI as a dictionary.
  * - Any params with `undefined` value will be ignored.
  */
-export function getURIParams(input, caller = getURIParams) {
+export function getURIParams(params, caller = getURIParams) {
     const output = {};
-    for (const [key, str] of getURIEntries(input, caller))
+    for (const [key, str] of getURIEntries(params, caller))
         output[key] = str;
     return output;
 }
 /** Get a single named param from a URI. */
-export function getURIParam(input, key) {
-    if (input instanceof URLSearchParams)
-        return input.get(key) || undefined;
-    if (isDictionary(input))
-        return getString(input[key]);
-    return getURIParams(input)[key];
+export function getURIParam(params, key) {
+    if (params instanceof URLSearchParams)
+        return params.get(key) || undefined;
+    if (isDictionary(params))
+        return getString(params[key]);
+    return getURIParams(params)[key];
 }
 /** Get a single named param from a URI. */
-export function requireURIParam(input, key, caller = requireURIParam) {
-    const value = getURIParam(input, key);
+export function requireURIParam(params, key, caller = requireURIParam) {
+    const value = getURIParam(params, key);
     if (value === undefined)
-        throw new RequiredError(`URI param "${key}" is required`, { received: input, caller });
+        throw new RequiredError(`URI param "${key}" is required`, { received: params, caller });
     return value;
 }
-export function withURIParam(url, key, value, caller = withURIParam) {
-    const input = requireURI(url, caller);
+export function withURIParam(uri, key, value, caller = withURIParam) {
+    const input = requireURI(uri, caller);
     if (value === undefined)
         return input; // Ignore undefined.
-    const output = new URI(input);
+    const output = new ImmutableURI(input);
     const str = getString(value);
     if (str === undefined)
         throw new ValueError(`URI param "${key}" must be string`, { received: value, caller });
     output.searchParams.set(key, str);
     return input.href === output.href ? input : output;
 }
-export function withURIParams(url, params, caller = withURIParams) {
-    const input = requireURI(url, caller);
+export function withURIParams(uri, params, caller = withURIParams) {
+    const input = requireURI(uri, caller);
     if (!params)
         return input;
-    const output = new URI(input);
+    const output = new ImmutableURI(input);
     for (const [key, str] of getURIEntries(params, caller))
         output.searchParams.set(key, str);
     return input.href === output.href ? input : output;
 }
-export function omitURIParams(url, ...keys) {
-    const input = requireURI(url, omitURIParams);
+export function omitURIParams(uri, ...keys) {
+    const input = requireURI(uri, omitURIParams);
     if (!keys.length)
         return input;
-    const output = new URI(input);
+    const output = new ImmutableURI(input);
     for (const key of keys)
         output.searchParams.delete(key);
     return input.href === output.href ? input : output;
 }
 /** Return a URI without a param (or same URI if no changes were made). */
 export const omitURIParam = omitURIParams;
-export function clearURIParams(url, caller = clearURIParams) {
-    const input = requireURI(url, caller);
+export function clearURIParams(uri, caller = clearURIParams) {
+    const input = requireURI(uri, caller);
     if (!input.search.length)
         return input;
-    const output = new URI(input);
+    const output = new URL(input);
     output.search = "";
     return output;
 }

package/util/url.d.ts

@@ -1,22 +1,24 @@
 import type { AnyCaller } from "./function.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;
-};
+import type { ImmutableURI } from "./uri.js";
 /**
  * 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.
  * - URLs have a concept of "absolute" or "relative" URLs, since they have a path.
  */
 export type URLString = `${string}://${string}`;
+/**
+ * Construct a correctly-typed `URL` object.
+ * - This is a more correctly typed version of the builtin Javascript `URL` constructor.
+ * - Requires a URL string, URL object, or path as input, and optionally a base URL.
+ * - If a path is provided as input, a base URL _must_ also be provided.
+ * - The returned type is
+ */
+export interface ImmutableURLConstructor {
+    new (input: URLString | ImmutableURL, base?: URLString | ImmutableURL): ImmutableURL;
+    new (input: URLString | ImmutableURL | string, base: URLString | ImmutableURL): ImmutableURL;
+}
 /**
  * Object that describes a valid URL, e.g. `http://example.com/path/to/resource`
  * - Improves the builtin Javascript `URL` class to more accurately type its properties.
@@ -32,41 +34,35 @@ export type URLString = `${string}://${string}`;
  * - Javascript `URL` instance can actually represent any kind of URI (not just URLs).
  * - It's more "correct" terminology to use `URI` to refer to what the Javascript `URL` class represents.
  * - 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).
+ * - Javascript URLs are mutable which can lead to subtle bugs.
  */
-export interface URL extends URI {
+export interface ImmutableURL extends ImmutableURI {
     readonly href: URLString;
     readonly origin: URLString;
-    readonly pathname: `/` | `/${string}`;
-}
-/**
- * Construct a correctly-typed `URL` object.
- * - This is a more correctly typed version of the builtin Javascript `URL` constructor.
- * - Requires a URL string, URL object, or path as input, and optionally a base URL.
- * - If a path is provided as input, a base URL _must_ also be provided.
- * - The returned type is
- */
-export interface URLConstructor {
-    new (input: URLString | URL, base?: URLString | URL): URL;
-    new (input: URLString | URL | string, base: URLString | URL): URL;
+    readonly pathname: AbsolutePath;
 }
-export declare const URL: URLConstructor;
+export declare const ImmutableURL: ImmutableURLConstructor;
 /** Values that can be converted to a URL instance. */
-export type PossibleURL = string | BuiltinURL;
+export type PossibleURL = string | URL;
 /**
  * Is an unknown value a URL object?
  * - Must be a `URL` instance and its origin must start with `scheme://`
  */
-export declare function isURL(value: unknown): value is URL;
+export declare function isURL(value: unknown): value is ImmutableURL;
 /** Assert that an unknown value is a URL object. */
-export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is URL;
+export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is ImmutableURL;
 /**
- * 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).
+ * Resolve a possible URL relative to a base URL, or return `undefined` if conversion fails.
+ *
+ * Note: When resolving relative URLs this treats `base` as if it ends in a slash.
+ * - e.g. if `base` is `http://p.com/a/b/c` the path will be relative to `c` as if a `/` trailing slash was present.
+ * - This is different to the default behaviour of `new URL()`, but is the more natural expected result
+ * - This is consistent with our e.g. `getURL()` utilities.
+ *
  */
-export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL): URL | undefined;
+export declare function getURL(target: Nullish<PossibleURL>, base?: PossibleURL): ImmutableURL | 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;
+export declare function requireURL(target: PossibleURL, base?: PossibleURL, caller?: AnyCaller): ImmutableURL;
 /**
  * Resolve and match a target URL/path against a base URL and return the remaining path.
  *
@@ -80,7 +76,7 @@ export declare function requireURL(possible: PossibleURL, base?: PossibleURL, ca
  */
 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 {
+export interface BaseURL extends ImmutableURL {
     readonly pathname: `/` | `/${string}/`;
 }
 /** Is an unknown value a valid Base URL. */
@@ -89,4 +85,3 @@ export declare function isBaseURL(value: PossibleURL): value is BaseURL;
 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,12 +1,11 @@
 import { RequiredError } from "../error/RequiredError.js";
-const BuiltinURL = globalThis.URL;
-export const URL = BuiltinURL;
+export const ImmutableURL = URL;
 /**
  * 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 BuiltinURL && _isURL(value);
+    return value instanceof URL && _isURL(value);
 }
 function _isURL(uri) {
     return uri.href.startsWith(`${uri.protocol}//`);
@@ -17,33 +16,37 @@ export function assertURL(value, caller = assertURL) {
         throw new RequiredError("Invalid URL", { received: value, caller });
 }
 /**
- * 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).
+ * Resolve a possible URL relative to a base URL, or return `undefined` if conversion fails.
+ *
+ * Note: When resolving relative URLs this treats `base` as if it ends in a slash.
+ * - e.g. if `base` is `http://p.com/a/b/c` the path will be relative to `c` as if a `/` trailing slash was present.
+ * - This is different to the default behaviour of `new URL()`, but is the more natural expected result
+ * - This is consistent with our e.g. `getURL()` utilities.
+ *
  */
-export function getURL(possible, base) {
-    if (!possible)
+export function getURL(target, base) {
+    if (!target)
         return;
-    const uri = _getBuiltinURL(possible, base);
+    const uri = _getURL(target, base);
     if (uri && _isURL(uri))
         return uri;
 }
-function _getBuiltinURL(possible, base) {
-    if (possible instanceof BuiltinURL)
-        return possible;
+function _getURL(target, base) {
+    if (target instanceof URL)
+        return target;
     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);
+        return new URL(target, baseURL);
     }
     catch {
         //
     }
 }
 /** 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);
+export function requireURL(target, base, caller = requireURL) {
+    const url = getURL(target, base);
     assertURL(url, caller);
     return url;
 }
@@ -83,12 +86,12 @@ function _isBaseURL(uri) {
 export function getBaseURL(input) {
     if (!input)
         return;
-    const uri = _getBuiltinURL(input, undefined);
+    const uri = _getURL(input, undefined);
     if (!uri || !_isURL(uri))
         return;
     if (_isBaseURL(uri))
         return uri;
-    const base = typeof input === "string" ? uri : new BuiltinURL(uri);
+    const base = typeof input === "string" ? uri : new URL(uri);
     base.pathname = `${uri.pathname}/`; // Add a trailing slash.
     return base;
 }