shelving 1.161.0 → 1.161.2

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.161.0",
+	"version": "1.161.2",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/store/URLStore.d.ts

@@ -1,6 +1,5 @@
 import type { Data } from "../util/data.js";
-import { type ImmutableDictionary } from "../util/dictionary.js";
-import { type PossibleURL } from "../util/url.js";
+import { type PossibleURL, type PossibleURLParams, type URLParams } from "../util/url.js";
 import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
 export declare class URLStore extends Store<URL> {
@@ -21,7 +20,7 @@ export declare class URLStore extends Store<URL> {
     /** Get the URL params as a string. */
     get search(): string;
     /** Get the URL params as a dictionary. */
-    get params(): ImmutableDictionary<string>;
+    get params(): URLParams;
     /** 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. */
@@ -37,7 +36,7 @@ export declare class URLStore extends Store<URL> {
     /** Return the current URL with an additional param. */
     withParam(key: string, value: unknown): URL;
     /** Return the current URL with an additional param. */
-    withParams(params: Data): URL;
+    withParams(params: PossibleURLParams): URL;
     /** Return the current URL with an additional param. */
     omitParams(...keys: string[]): URL;
     /** Return the current URL with an additional param. */

package/store/URLStore.js

@@ -1,6 +1,5 @@
-import { getSetter } from "../util/class.js";
-import { getDictionary } from "../util/dictionary.js";
-import { getURL, getURLParam, omitURLParams, requireURL, requireURLParam, withURLParam, withURLParams, } from "../util/url.js";
+import { getGetter, getSetter } from "../util/class.js";
+import { getURL, getURLParam, getURLParams, omitURLParams, requireURL, requireURLParam, withURLParam, withURLParams, } from "../util/url.js";
 import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
 export class URLStore extends Store {
@@ -52,7 +51,7 @@ export class URLStore extends Store {
     }
     /** Get the URL params as a dictionary. */
     get params() {
-        return getDictionary(this.value.searchParams);
+        return getURLParams(this.value.searchParams, getGetter(this, "params"));
     }
     /** Return a single param in this URL, or `undefined` if it could not be found. */
     getParam(key) {

package/util/path.d.ts

@@ -29,7 +29,7 @@ export declare function getPath(value: Nullish<string | URL>, base?: AbsolutePat
  * @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: string, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
+export declare function requirePath(value: string | URL, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
 /** 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

@@ -11,7 +11,7 @@ export function isRelativePath(path) {
 function _cleanPath(path) {
     return path
         .replace(/[/\\]+/g, "/") // Normalise slashes.
-        .replace(/(?!^)\/$/g, ""); // Trailing slashes.
+        .replace(/(?!^)\/$/g, ""); // Trim trailing slashes.
 }
 /**
  * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
@@ -22,8 +22,8 @@ function _cleanPath(path) {
  * @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 getPath(value, base = "/") {
-    const url = getURL(value, `http://j.com${base === "/" || base.endsWith("/") ? base : `${base}/`}`);
+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))

package/util/url.d.ts

@@ -1,5 +1,5 @@
-import type { Data } from "./data.js";
-import type { ImmutableDictionary } from "./dictionary.js";
+import { type Data } from "./data.js";
+import type { DictionaryItem, ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
 import { type Nullish } from "./null.js";
 /** Values that can be converted to a URL instance. */
@@ -12,19 +12,35 @@ export declare function assertURL(value: unknown, caller?: AnyCaller): asserts v
 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, caller?: AnyCaller): URL;
+/** Type for a set of named URL parameters. */
+export type URLParams = ImmutableDictionary<string>;
+/** Type for things that can be converted to named URL parameters. */
+export type PossibleURLParams = PossibleURL | URLSearchParams | Data | Iterable<DictionaryItem<unknown>>;
 /**
- * Get the params of a URL as a dictionary of strings.
- * - Note: The same param cannot exist multiple times in the returned dictionary, so the first value for a param will be used (which matches `URLSearchParams.get()` behavior).
+ * Get a set of entries for a set of possible URL params.
+ *
+ * Note: Not as simple as just converting with `Object.fromEntries()`:
+ * 1. When `URLSearchParams` contains multiple values for the same key, calling `params.get()` will return the _first_ value.
+ * 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.
+ */
+export declare function getURLEntries(input: PossibleURLParams, caller?: AnyCaller): Iterable<DictionaryItem<string>>;
+/** Get a set of params for a URL as a dictionary. */
+export declare function getURLParams(input: PossibleURLParams, caller?: AnyCaller): URLParams;
+/** Get a single named param from a URL. */
+export declare function getURLParam(input: PossibleURLParams, key: string): string | undefined;
+/** Get a single named param from a URL. */
+export declare function requireURLParam(input: PossibleURLParams, key: string, caller?: AnyCaller): string;
+/**
+ * Return a URL with a new param set (or same URL if no changes were made).
+ * - Throws `ValueError` if the value could not be converted to a string.
  */
-export declare function getURLParams(params: URLSearchParams): ImmutableDictionary<string>;
-/** Get a param from a URL. */
-export declare function getURLParam(params: URLSearchParams, key: string): string | undefined;
-/** Get a param from a URL. */
-export declare function requireURLParam(params: URLSearchParams, key: string, caller?: AnyCaller): string | undefined;
-/** Return a URL with a new param set (or same URL if no changes were made). */
 export declare function withURLParam(url: PossibleURL, key: string, value: unknown, caller?: AnyCaller): URL;
-/** Return a URL with several new params set (or same URL if no changes were made). */
-export declare function withURLParams(url: PossibleURL, params: Data, caller?: AnyCaller): URL;
+/**
+ * Return a URL with several new params set (or same URL if no changes were made).
+ * - Throws `ValueError` if any of the values could not be converted to strings.
+ */
+export declare function withURLParams(url: PossibleURL, params: PossibleURLParams, caller?: AnyCaller): URL;
 /** Return a URL without one or more params (or same URL if no changes were made). */
 export declare function omitURLParams(url: PossibleURL, ...keys: string[]): URL;
 /** Return a URL without a param (or same URL if no changes were made). */

package/util/url.js

@@ -1,7 +1,9 @@
 import { RequiredError } from "../error/RequiredError.js";
+import { ValueError } from "../error/ValueError.js";
+import { isData } from "./data.js";
 import { notNullish } from "./null.js";
 import { getProps } from "./object.js";
-import { requireString } from "./string.js";
+import { getString, isString } from "./string.js";
 /** Is an unknown value a URL object? */
 export function isURL(value) {
     return value instanceof URL;
@@ -13,14 +15,8 @@ export function assertURL(value, caller = assertURL) {
 }
 /** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
 export function getURL(possible, base = _BASE) {
-    if (notNullish(possible)) {
-        try {
-            return isURL(possible) ? possible : new URL(possible, base);
-        }
-        catch (_e) {
-            //
-        }
-    }
+    if (notNullish(possible))
+        return isURL(possible) ? possible : URL.parse(possible, base) || undefined;
 }
 const _BASE = typeof document === "object" ? document.baseURI : undefined;
 /** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
@@ -30,46 +26,83 @@ export function requireURL(possible, base, caller = requireURL) {
     return url;
 }
 /**
- * Get the params of a URL as a dictionary of strings.
- * - Note: The same param cannot exist multiple times in the returned dictionary, so the first value for a param will be used (which matches `URLSearchParams.get()` behavior).
+ * Get a set of entries for a set of possible URL params.
+ *
+ * Note: Not as simple as just converting with `Object.fromEntries()`:
+ * 1. When `URLSearchParams` contains multiple values for the same key, calling `params.get()` will return the _first_ value.
+ * 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.
  */
-export function getURLParams(params) {
+export function* getURLEntries(input, caller = getURLParams) {
+    if (input instanceof URLSearchParams) {
+        yield* input;
+    }
+    else if (isString(input) || isURL(input)) {
+        yield* requireURL(input, undefined, caller).searchParams;
+    }
+    else {
+        const done = [];
+        for (const [key, value] of getProps(input)) {
+            if (done.includes(key))
+                continue;
+            done.push(key);
+            const str = getString(value);
+            if (str === undefined)
+                throw new ValueError(`URL param "${key}" must be string`, { received: value, caller });
+            yield [key, str];
+        }
+    }
+}
+/** Get a set of params for a URL as a dictionary. */
+export function getURLParams(input, caller = getURLParams) {
     const output = {};
-    for (const [key, value] of params)
-        if (!Object.hasOwn(output, key))
-            output[key] = value;
+    for (const [key, str] of getURLEntries(input, caller))
+        output[key] = str;
     return output;
 }
-/** Get a param from a URL. */
-export function getURLParam(params, key) {
-    return params.get(key) || undefined;
+/** Get a single named param from a URL. */
+export function getURLParam(input, key) {
+    if (input instanceof URLSearchParams)
+        return input.get(key) || undefined;
+    if (isData(input))
+        return getString(input[key]);
+    return getURLParams(input)[key];
 }
-/** Get a param from a URL. */
-export function requireURLParam(params, key, caller = requireURLParam) {
-    const value = params.get(key);
-    if (value === null)
-        throw new RequiredError(`URL param "${key}" is required`, { received: params.toString(), caller });
+/** Get a single named param from a URL. */
+export function requireURLParam(input, key, caller = requireURLParam) {
+    const value = getURLParam(input, key);
+    if (value === undefined)
+        throw new RequiredError(`URL param "${key}" is required`, { received: input, caller });
     return value;
 }
-/** Return a URL with a new param set (or same URL if no changes were made). */
+/**
+ * Return a URL with a new param set (or same URL if no changes were made).
+ * - Throws `ValueError` if the value could not be converted to a string.
+ */
 export function withURLParam(url, key, value, caller = withURLParam) {
     const input = requireURL(url);
     const output = new URL(input);
-    output.searchParams.set(key, requireString(value, undefined, undefined, caller));
+    const str = getString(value);
+    if (str === undefined)
+        throw new ValueError(`URL param "${key}" must be string`, { received: value, caller });
+    output.searchParams.set(key, str);
     return input.href === output.href ? input : output;
 }
-/** Return a URL with several new params set (or same URL if no changes were made). */
+/**
+ * Return a URL with several new params set (or same URL if no changes were made).
+ * - Throws `ValueError` if any of the values could not be converted to strings.
+ */
 export function withURLParams(url, params, caller = withURLParams) {
     const input = requireURL(url);
-    const output = requireURL(url);
-    for (const [key, value] of getProps(params))
-        output.searchParams.set(key, requireString(value, undefined, undefined, caller));
+    const output = new URL(input);
+    for (const [key, str] of getURLEntries(params, caller))
+        output.searchParams.set(key, str);
     return input.href === output.href ? input : output;
 }
 /** Return a URL without one or more params (or same URL if no changes were made). */
 export function omitURLParams(url, ...keys) {
     const input = requireURL(url);
-    const output = requireURL(url);
+    const output = new URL(input);
     for (const key of keys)
         output.searchParams.delete(key);
     return input.href === output.href ? input : output;