shelving 1.169.0 → 1.170.2

package/README.md

@@ -37,7 +37,7 @@ Shelving does not include code for CommonJS `require()` imports, so using it in
 
 ## Modules
 
-Shelving is created from small individual modules which can be imported individually (using e.g. `import { addProp } from "shelving/object`). Modules marked with `✅` are also re-exported from the main `"shelving"` module.
+Shelving is created from small individual modules which can be imported individually (using e.g. `import { addProp } from "shelving/util/object`). Modules marked with `✅` are also re-exported from the main `"shelving"` module.
 
 @todo Write these docs!
 

package/package.json

@@ -11,8 +11,11 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.169.0",
-	"repository": "https://github.com/dhoulb/shelving",
+	"version": "1.170.2",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dhoulb/shelving.git"
+	},
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
 	"type": "module",

package/store/URLStore.d.ts

@@ -25,14 +25,18 @@ export declare class URLStore extends Store<URL> {
     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;
-    /** Update a single param in this URL. */
-    setParam(key: string, value: unknown): void;
-    /** Update several params in this URL. */
+    /** 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): URL;
     /** Return the current URL with an additional param. */
@@ -41,5 +45,6 @@ export declare class URLStore extends Store<URL> {
     omitParams(...keys: string[]): URL;
     /** Return the current URL with an additional param. */
     omitParam(key: string): URL;
+    equal(a: URL, b: URL): boolean;
     toString(): string;
 }

package/store/URLStore.js

@@ -1,5 +1,5 @@
 import { getGetter, getSetter } from "../util/class.js";
-import { getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
+import { clearURIParams, getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
 import { getURL, requireURL } from "../util/url.js";
 import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
@@ -62,13 +62,17 @@ export class URLStore extends Store {
     requireParam(key) {
         return requireURIParam(this.value.searchParams, key, getSetter(this, "requireParam"));
     }
-    /** Update a single param in this URL. */
+    /** Set all params in this URL (all current params are cleared). */
+    setParams(params) {
+        this.value = withURIParams(clearURIParams(this.value, this.setParams), params, this.setParams);
+    }
+    /** Set a single named param in this URL. */
     setParam(key, value) {
-        this.value = withURIParam(this.value, key, value, this.setParams);
+        this.value = withURIParam(this.value, key, value, this.setParam);
     }
-    /** Update several params in this URL. */
-    setParams(params) {
-        this.value = withURIParams(this.value, params, this.setParams);
+    /** Update several params in this URL (merged with current params). */
+    updateParams(params) {
+        this.value = withURIParams(this.value, params, this.updateParams);
     }
     /** Delete one or more params in this URL. */
     deleteParam(key, ...keys) {
@@ -78,6 +82,10 @@ export class URLStore extends Store {
     deleteParams(key, ...keys) {
         this.value = omitURIParams(this.value, key, ...keys);
     }
+    /** Clear all params from this URL. */
+    clearParams() {
+        this.value = clearURIParams(this.value, this.clearParams);
+    }
     /** Return the current URL with an additional param. */
     withParam(key, value) {
         return withURIParam(this.value, key, value, this.withParam);
@@ -94,6 +102,10 @@ export class URLStore extends Store {
     omitParam(key) {
         return omitURIParams(this.value, key);
     }
+    // Override `equal()` to just compare the hrefs.
+    equal(a, b) {
+        return a.href === b.href;
+    }
     toString() {
         return this.href;
     }

package/util/uri.d.ts

@@ -63,7 +63,10 @@ export declare function requireURIString(possible: PossibleURI, caller?: AnyCall
 export type URIParams = ImmutableDictionary<string>;
 /** Type for things that can be converted to named URI parameters. */
 export type PossibleURIParams = PossibleURI | URLSearchParams | ImmutableDictionary<unknown>;
-/** Get a set of params for a URI as a dictionary. */
+/**
+ * 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;
 /** Get a single named param from a URI. */
 export declare function getURIParam(input: PossibleURIParams, key: string): string | undefined;
@@ -71,13 +74,17 @@ export declare function getURIParam(input: PossibleURIParams, key: string): stri
 export declare function requireURIParam(input: PossibleURIParams, key: string, caller?: AnyCaller): string;
 /**
  * Return a URI with a new param set (or same URI if no changes were made).
- * - Throws `ValueError` if the value could not be converted to a string.
+ * - 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;
 /**
  * Return a URI with several new params set (or same URI if no changes were made).
- * - Throws `ValueError` if any of the values could not be converted to strings.
+ * - Param with `undefined` value will be ignored.
+ *
+ * @throws `ValueError` if any of the values could not be converted to strings.
  */
 export declare function withURIParams(url: URL | URLString, params: PossibleURIParams, caller?: AnyCaller): URL;
 export declare function withURIParams(url: PossibleURI, params: PossibleURIParams, caller?: AnyCaller): URI;
@@ -86,6 +93,9 @@ export declare function omitURIParams(url: URL | URLString, ...keys: string[]):
 export declare function omitURIParams(url: PossibleURI, ...keys: string[]): URI;
 /** Return a URI without a param (or same URI if no changes were made). */
 export declare const omitURIParam: (url: PossibleURI, key: string) => URI;
+/** 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;
 /** A single schema for a URL. */
 export type URIScheme = `${string}:`;
 /** List of allowed URI schemes. */

package/util/uri.js

@@ -43,6 +43,7 @@ export function requireURIString(possible, caller = requireURIString) {
 }
 /**
  * Get a set of entries for a set of possible URI params.
+ *- Any params with `undefined` value will be ignored.
  *
  * 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.
@@ -59,6 +60,8 @@ function* getURIEntries(input, caller = getURIParams) {
     else {
         const done = [];
         for (const [key, value] of getDictionaryItems(input)) {
+            if (value === undefined)
+                continue; // Skip undefined.
             if (done.includes(key))
                 continue;
             done.push(key);
@@ -69,7 +72,10 @@ function* getURIEntries(input, caller = getURIParams) {
         }
     }
 }
-/** Get a set of params for a URI as a dictionary. */
+/**
+ * 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) {
     const output = {};
     for (const [key, str] of getURIEntries(input, caller))
@@ -93,6 +99,8 @@ export function requireURIParam(input, key, caller = requireURIParam) {
 }
 export function withURIParam(url, key, value, caller = withURIParam) {
     const input = requireURI(url, caller);
+    if (value === undefined)
+        return input; // Ignore undefined.
     const output = new URI(input);
     const str = getString(value);
     if (str === undefined)
@@ -116,5 +124,13 @@ export function omitURIParams(url, ...keys) {
 }
 /** 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);
+    if (!input.search.length)
+        return input;
+    const output = new URI(input);
+    output.search = "";
+    return output;
+}
 /** Valid HTTP schemes for a URI. */
 export const HTTP_SCHEMES = ["http:", "https:"];