shelving 1.236.0 → 1.236.2

package/store/URLStore.d.ts

@@ -3,49 +3,207 @@ import type { AbsolutePath } from "../util/index.js";
 import { type PossibleURIParams, type URIParams, type URIScheme } from "../util/uri.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` */
+/**
+ * Store a URL, e.g. `https://top.com/a/b/c`
+ * - Accepts any `PossibleURL` as input and normalises it to an `ImmutableURL` (resolved against `this.base`).
+ * - Exposes the URL's components (`href`, `origin`, `pathname`, etc.) and helpers to read and mutate its search params.
+ *
+ * @param url The initial URL value.
+ * @param base An optional base URL that relative URLs are resolved against.
+ * @example
+ * const store = new URLStore("https://top.com/a/b/c");
+ * store.setParam("page", 2); // https://top.com/a/b/c?page=2
+ * store.isActive("https://top.com/a/b/c?page=2"); // true
+ * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore
+ */
 export declare class URLStore extends BusyStore<ImmutableURL, PossibleURL> {
+    /**
+     * Base URL that relative URL inputs are resolved against, or `undefined` if none was set.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/base
+     */
     readonly base: ImmutableURL | undefined;
     constructor(url: PossibleURL, base?: PossibleURL);
     protected _convert(value: PossibleURL, caller: AnyCaller): ImmutableURL;
     protected _equal(a: ImmutableURL, b: ImmutableURL): boolean;
+    /**
+     * Get or set the full URL string (e.g. `https://top.com/a/b/c?x=1`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/href
+     */
     get href(): URLString;
     set href(href: URLString);
+    /**
+     * Get the origin of the URL (e.g. `https://top.com`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/origin
+     */
     get origin(): URLString;
+    /**
+     * Get the protocol/scheme of the URL (e.g. `https:`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/protocol
+     */
     get protocol(): URIScheme;
+    /**
+     * Get the username component of the URL.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/username
+     */
     get username(): string;
+    /**
+     * Get the password component of the URL.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/password
+     */
     get password(): string;
+    /**
+     * Get the hostname of the URL (e.g. `top.com`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/hostname
+     */
     get hostname(): string;
+    /**
+     * Get the host of the URL including port (e.g. `top.com:8080`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/host
+     */
     get host(): string;
+    /**
+     * Get the port of the URL, or an empty string if none is set.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/port
+     */
     get port(): string;
+    /**
+     * Get the absolute pathname of the URL (e.g. `/a/b/c`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/pathname
+     */
     get pathname(): AbsolutePath;
-    /** Get the URL params as a string. */
+    /**
+     * Get the URL params as a query string (e.g. `?x=1&y=2`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/search
+     */
     get search(): string;
-    /** Get the URL params as a dictionary. */
+    /**
+     * Get the URL params as a dictionary of key/value pairs.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/params
+     */
     get params(): URIParams;
-    /** Return a single param in this URL, or `undefined` if it could not be found. */
+    /**
+     * Return a single param in this URL, or `undefined` if it could not be found.
+     *
+     * @param key The name of the param to read.
+     * @returns The param value, or `undefined` if it is not present.
+     * @example store.getParam("page"); // "2"
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/getParam
+     */
     getParam(key: string): string | undefined;
-    /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
+    /**
+     * Require a single param in this URL, or throw `RequiredError` if it could not be found.
+     *
+     * @param key The name of the param to read.
+     * @returns The param value.
+     * @throws {RequiredError} If the param is not present.
+     * @example store.requireParam("page");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/requireParam
+     */
     requireParam(key: string): string | undefined;
-    /** Set all params in this URL (all current params are cleared). */
+    /**
+     * Set all params in this URL (all current params are cleared first).
+     *
+     * @param params The complete set of params to set.
+     * @returns Nothing.
+     * @example store.setParams({ page: 2, sort: "name" });
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/setParams
+     */
     setParams(params: PossibleURIParams): void;
-    /** Set a single named param in this URL. */
+    /**
+     * Set a single named param in this URL.
+     *
+     * @param key The name of the param to set.
+     * @param value The new value for the param.
+     * @returns Nothing.
+     * @example store.setParam("page", 2);
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/setParam
+     */
     setParam(key: string, value: unknown): void;
-    /** Update several params in this URL (merged with current params). */
+    /**
+     * Update several params in this URL (merged with current params).
+     *
+     * @param params The set of params to merge in.
+     * @returns Nothing.
+     * @example store.updateParams({ sort: "name" });
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/updateParams
+     */
     updateParams(params: PossibleURIParams): void;
-    /** Delete one or more params in this URL. */
+    /**
+     * Delete one or more params from this URL.
+     *
+     * @param key The name of the first param to delete.
+     * @param keys Additional param names to delete.
+     * @returns Nothing.
+     * @example store.deleteParam("page", "sort");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/deleteParam
+     */
     deleteParam(key: string, ...keys: string[]): void;
-    /** Delete one or more params in this URL. */
+    /**
+     * Delete one or more params from this URL.
+     *
+     * @param key The name of the first param to delete.
+     * @param keys Additional param names to delete.
+     * @returns Nothing.
+     * @example store.deleteParams("page", "sort");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/deleteParams
+     */
     deleteParams(key: string, ...keys: string[]): void;
-    /** Clear all params from this URL. */
+    /**
+     * Clear all params from this URL.
+     *
+     * @returns Nothing.
+     * @example store.clearParams();
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/clearParams
+     */
     clearParams(): void;
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with an additional param (without mutating this store).
+     *
+     * @param key The name of the param to add.
+     * @param value The value for the param.
+     * @returns A new `ImmutableURL` with the param applied.
+     * @example store.withParam("page", 2);
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/withParam
+     */
     withParam(key: string, value: unknown): ImmutableURL;
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with additional params (without mutating this store).
+     *
+     * @param params The params to add.
+     * @returns A new `ImmutableURL` with the params applied.
+     * @example store.withParams({ page: 2, sort: "name" });
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/withParams
+     */
     withParams(params: PossibleURIParams): ImmutableURL;
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with one or more params removed (without mutating this store).
+     *
+     * @param keys The param names to remove.
+     * @returns A new `ImmutableURL` with the params removed.
+     * @example store.omitParams("page", "sort");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/omitParams
+     */
     omitParams(...keys: string[]): ImmutableURL;
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with a single param removed (without mutating this store).
+     *
+     * @param key The param name to remove.
+     * @returns A new `ImmutableURL` with the param removed.
+     * @example store.omitParam("page");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/omitParam
+     */
     omitParam(key: string): ImmutableURL;
     /**
      * Is `target` active relative to this store's URL?

package/store/URLStore.js

@@ -2,8 +2,25 @@ import { getGetter, getSetter } from "../util/class.js";
 import { clearURIParams, getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
 import { getURL, isURLActive, isURLProud, requireURL } from "../util/url.js";
 import { BusyStore } from "./BusyStore.js";
-/** Store a URL, e.g. `https://top.com/a/b/c` */
+/**
+ * Store a URL, e.g. `https://top.com/a/b/c`
+ * - Accepts any `PossibleURL` as input and normalises it to an `ImmutableURL` (resolved against `this.base`).
+ * - Exposes the URL's components (`href`, `origin`, `pathname`, etc.) and helpers to read and mutate its search params.
+ *
+ * @param url The initial URL value.
+ * @param base An optional base URL that relative URLs are resolved against.
+ * @example
+ * const store = new URLStore("https://top.com/a/b/c");
+ * store.setParam("page", 2); // https://top.com/a/b/c?page=2
+ * store.isActive("https://top.com/a/b/c?page=2"); // true
+ * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore
+ */
 export class URLStore extends BusyStore {
+    /**
+     * Base URL that relative URL inputs are resolved against, or `undefined` if none was set.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/base
+     */
     base;
     // Override to convert possible URL to URL.
     constructor(url, base) {
@@ -19,89 +36,230 @@ export class URLStore extends BusyStore {
     _equal(a, b) {
         return a.href === b.href;
     }
+    /**
+     * Get or set the full URL string (e.g. `https://top.com/a/b/c?x=1`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/href
+     */
     get href() {
         return this.value.href;
     }
     set href(href) {
         this.value = href;
     }
+    /**
+     * Get the origin of the URL (e.g. `https://top.com`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/origin
+     */
     get origin() {
         return this.value.origin;
     }
+    /**
+     * Get the protocol/scheme of the URL (e.g. `https:`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/protocol
+     */
     get protocol() {
         return this.value.protocol;
     }
+    /**
+     * Get the username component of the URL.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/username
+     */
     get username() {
         return this.value.username;
     }
+    /**
+     * Get the password component of the URL.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/password
+     */
     get password() {
         return this.value.password;
     }
+    /**
+     * Get the hostname of the URL (e.g. `top.com`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/hostname
+     */
     get hostname() {
         return this.value.hostname;
     }
+    /**
+     * Get the host of the URL including port (e.g. `top.com:8080`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/host
+     */
     get host() {
         return this.value.host;
     }
+    /**
+     * Get the port of the URL, or an empty string if none is set.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/port
+     */
     get port() {
         return this.value.port;
     }
+    /**
+     * Get the absolute pathname of the URL (e.g. `/a/b/c`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/pathname
+     */
     get pathname() {
         return this.value.pathname;
     }
-    /** Get the URL params as a string. */
+    /**
+     * Get the URL params as a query string (e.g. `?x=1&y=2`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/search
+     */
     get search() {
         return this.value.search;
     }
-    /** Get the URL params as a dictionary. */
+    /**
+     * Get the URL params as a dictionary of key/value pairs.
+     *
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/params
+     */
     get params() {
         return getURIParams(this.value.searchParams, getGetter(this, "params"));
     }
-    /** Return a single param in this URL, or `undefined` if it could not be found. */
+    /**
+     * Return a single param in this URL, or `undefined` if it could not be found.
+     *
+     * @param key The name of the param to read.
+     * @returns The param value, or `undefined` if it is not present.
+     * @example store.getParam("page"); // "2"
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/getParam
+     */
     getParam(key) {
         return getURIParam(this.value.searchParams, key);
     }
-    /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
+    /**
+     * Require a single param in this URL, or throw `RequiredError` if it could not be found.
+     *
+     * @param key The name of the param to read.
+     * @returns The param value.
+     * @throws {RequiredError} If the param is not present.
+     * @example store.requireParam("page");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/requireParam
+     */
     requireParam(key) {
         return requireURIParam(this.value.searchParams, key, getSetter(this, "requireParam"));
     }
-    /** Set all params in this URL (all current params are cleared). */
+    /**
+     * Set all params in this URL (all current params are cleared first).
+     *
+     * @param params The complete set of params to set.
+     * @returns Nothing.
+     * @example store.setParams({ page: 2, sort: "name" });
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/setParams
+     */
     setParams(params) {
         this.value = withURIParams(clearURIParams(this.value, this.setParams), params, this.setParams);
     }
-    /** Set a single named param in this URL. */
+    /**
+     * Set a single named param in this URL.
+     *
+     * @param key The name of the param to set.
+     * @param value The new value for the param.
+     * @returns Nothing.
+     * @example store.setParam("page", 2);
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/setParam
+     */
     setParam(key, value) {
         this.value = withURIParam(this.value, key, value, this.setParam);
     }
-    /** Update several params in this URL (merged with current params). */
+    /**
+     * Update several params in this URL (merged with current params).
+     *
+     * @param params The set of params to merge in.
+     * @returns Nothing.
+     * @example store.updateParams({ sort: "name" });
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/updateParams
+     */
     updateParams(params) {
         this.value = withURIParams(this.value, params, this.updateParams);
     }
-    /** Delete one or more params in this URL. */
+    /**
+     * Delete one or more params from this URL.
+     *
+     * @param key The name of the first param to delete.
+     * @param keys Additional param names to delete.
+     * @returns Nothing.
+     * @example store.deleteParam("page", "sort");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/deleteParam
+     */
     deleteParam(key, ...keys) {
         this.value = omitURIParams(this.value, key, ...keys);
     }
-    /** Delete one or more params in this URL. */
+    /**
+     * Delete one or more params from this URL.
+     *
+     * @param key The name of the first param to delete.
+     * @param keys Additional param names to delete.
+     * @returns Nothing.
+     * @example store.deleteParams("page", "sort");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/deleteParams
+     */
     deleteParams(key, ...keys) {
         this.value = omitURIParams(this.value, key, ...keys);
     }
-    /** Clear all params from this URL. */
+    /**
+     * Clear all params from this URL.
+     *
+     * @returns Nothing.
+     * @example store.clearParams();
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/clearParams
+     */
     clearParams() {
         this.value = clearURIParams(this.value, this.clearParams);
     }
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with an additional param (without mutating this store).
+     *
+     * @param key The name of the param to add.
+     * @param value The value for the param.
+     * @returns A new `ImmutableURL` with the param applied.
+     * @example store.withParam("page", 2);
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/withParam
+     */
     withParam(key, value) {
         return withURIParam(this.value, key, value, this.withParam);
     }
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with additional params (without mutating this store).
+     *
+     * @param params The params to add.
+     * @returns A new `ImmutableURL` with the params applied.
+     * @example store.withParams({ page: 2, sort: "name" });
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/withParams
+     */
     withParams(params) {
         return withURIParams(this.value, params, this.withParams);
     }
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with one or more params removed (without mutating this store).
+     *
+     * @param keys The param names to remove.
+     * @returns A new `ImmutableURL` with the params removed.
+     * @example store.omitParams("page", "sort");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/omitParams
+     */
     omitParams(...keys) {
         return omitURIParams(this.value, ...keys);
     }
-    /** Return the current URL with an additional param. */
+    /**
+     * Return the current URL with a single param removed (without mutating this store).
+     *
+     * @param key The param name to remove.
+     * @returns A new `ImmutableURL` with the param removed.
+     * @example store.omitParam("page");
+     * @see https://dhoulb.github.io/shelving/store/URLStore/URLStore/omitParam
+     */
     omitParam(key) {
         return omitURIParams(this.value, key);
     }

package/test/basics.d.ts

@@ -1,5 +1,10 @@
 import type { Item } from "../util/item.js";
 import type { ValidatorType } from "../util/validate.js";
+/**
+ * Schema for a test "basic" fixture, exercising string, number, choice, array, boolean, and nested-data props.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/BASIC_SCHEMA
+ */
 export declare const BASIC_SCHEMA: import("../schema/DataSchema.js").DataSchema<{
     str: string;
     num: number;
@@ -14,16 +19,81 @@ export declare const BASIC_SCHEMA: import("../schema/DataSchema.js").DataSchema<
         even: /*elided*/ any;
     };
 }>;
+/**
+ * Validated data shape of a test basic, inferred from `BASIC_SCHEMA`.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/BasicData
+ */
 export type BasicData = ValidatorType<typeof BASIC_SCHEMA>;
+/**
+ * A test basic as a stored `Item` — `BasicData` plus a string `id`.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/BasicItem
+ */
 export type BasicItem = Item<string, BasicData>;
+/**
+ * Test basic fixture: `str: "aaa"`, `num: 100`, group `a`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic1
+ */
 export declare const basic1: BasicItem;
+/**
+ * Test basic fixture: `str: "bbb"`, `num: 200`, group `a`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic2
+ */
 export declare const basic2: BasicItem;
+/**
+ * Test basic fixture: `str: "ccc"`, `num: 300`, group `a`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic3
+ */
 export declare const basic3: BasicItem;
+/**
+ * Test basic fixture: `str: "ddd"`, `num: 400`, group `b`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic4
+ */
 export declare const basic4: BasicItem;
+/**
+ * Test basic fixture: `str: "eee"`, `num: 500`, group `b`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic5
+ */
 export declare const basic5: BasicItem;
+/**
+ * Test basic fixture: `str: "fff"`, `num: 600`, group `b`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic6
+ */
 export declare const basic6: BasicItem;
+/**
+ * Test basic fixture: `str: "ggg"`, `num: 700`, group `c`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic7
+ */
 export declare const basic7: BasicItem;
+/**
+ * Test basic fixture: `str: "hhh"`, `num: 800`, group `c`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic8
+ */
 export declare const basic8: BasicItem;
+/**
+ * Test basic fixture: `str: "iii"`, `num: 900`, group `c`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic9
+ */
 export declare const basic9: BasicItem;
+/**
+ * Array of all nine test basic fixtures in a deliberately shuffled order, for exercising sort/query behaviour.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basics
+ */
 export declare const basics: ReadonlyArray<BasicItem>;
+/**
+ * Standalone test basic data (no `id`): `str: "zzz"`, `num: 999`, for use as new/unsaved data.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic999
+ */
 export declare const basic999: BasicData;