shelving/store/URLStore.d.ts

Toolkit for using data in JavaScript.

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 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<ImmutableURL, PossibleURL> {
    readonly base: ImmutableURL | undefined;
    constructor(url: PossibleURL, base?: PossibleURL);
    protected _convert(value: PossibleURL, caller: AnyCaller): ImmutableURL;
    protected _equal(a: ImmutableURL, b: ImmutableURL): boolean;
    get href(): URLString;
    set href(href: URLString);
    get origin(): URLString;
    get protocol(): URIScheme;
    get username(): string;
    get password(): string;
    get hostname(): string;
    get host(): string;
    get port(): string;
    get pathname(): AbsolutePath;
    /** Get the URL params as a string. */
    get search(): string;
    /** Get the URL params as a dictionary. */
    get params(): URIParams;
    /** Return a single param in this URL, or `undefined` if it could not be found. */
    getParam(key: string): string | undefined;
    /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
    requireParam(key: string): string | undefined;
    /** Set all params in this URL (all current params are cleared). */
    setParams(params: PossibleURIParams): void;
    /** Set a single named param in this URL. */
    setParam(key: string, value: unknown): void;
    /** Update several params in this URL (merged with current params). */
    updateParams(params: PossibleURIParams): void;
    /** Delete one or more params in this URL. */
    deleteParam(key: string, ...keys: string[]): void;
    /** Delete one or more params in this URL. */
    deleteParams(key: string, ...keys: string[]): void;
    /** Clear all params from this URL. */
    clearParams(): void;
    /** Return the current URL with an additional param. */
    withParam(key: string, value: unknown): ImmutableURL;
    /** Return the current URL with an additional param. */
    withParams(params: PossibleURIParams): ImmutableURL;
    /** Return the current URL with an additional param. */
    omitParams(...keys: string[]): ImmutableURL;
    /** Return the current URL with an additional param. */
    omitParam(key: string): ImmutableURL;
    /**
     * Is `target` active relative to this store's URL?
     * - Active means `target` resolves to the exact same URL as this store's current value.
     *
     * @param target URL (or relative path resolved against this store's `base`) to test.
     */
    isActive(target: PossibleURL): boolean;
    /**
     * Is `target` proud relative to this store's URL?
     * - Proud means this store's URL is `target` or a descendant of `target` — i.e. `target` sits at or above the current URL in the hierarchy.
     * - Useful for marking a menu item as "current branch" when the user is somewhere deeper in its sub-tree.
     *
     * @param target URL (or relative path resolved against this store's `base`) to test.
     */
    isProud(target: PossibleURL): boolean;
    toString(): string;
}