shelving 1.160.4 → 1.161.0

package/db/MemoryProvider.js

@@ -1,5 +1,5 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
-import { getArray } from "../util/array.js";
+import { requireArray } from "../util/array.js";
 import { isArrayEqual } from "../util/equal.js";
 import { getItem } from "../util/item.js";
 import { countItems } from "../util/iterate.js";
@@ -163,7 +163,7 @@ export class MemoryTable {
         return query ? countItems(queryItems(this._data.values(), query)) : this._data.size;
     }
     getQuery(query) {
-        return getArray(query ? queryItems(this._data.values(), query) : this._data.values());
+        return requireArray(query ? queryItems(this._data.values(), query) : this._data.values());
     }
     async *getQuerySequence(query) {
         let lastItems = this.getQuery(query);

package/package.json

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

package/schema/ArraySchema.d.ts

@@ -3,11 +3,18 @@ import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
 /** Allowed options for `ArraySchema` */
 export interface ArraySchemaOptions<T> extends SchemaOptions {
+    /** The default value */
     readonly value?: ImmutableArray;
+    /** A schema all the array items in the value must conform to */
     readonly items: Schema<T>;
+    /** Minimum number of items. */
     readonly min?: number;
+    /** Maximum number of items. */
     readonly max?: number;
+    /** Whether to deduplicate the items. */
     readonly unique?: boolean;
+    /** Separator is used */
+    readonly separator?: string | RegExp;
 }
 /**
  * Define a valid array.
@@ -15,13 +22,6 @@ export interface ArraySchemaOptions<T> extends SchemaOptions {
  * Validates arrays and ensures the array's items match a specified format.
  * Only returns a new instance of the object if it changes (for immutability).
  *
- * Schema options:
- * - `value` The default value
- * - `length` The exact array length required
- * - `min` The minimum array length required
- * - `max` The maximum array length required
- * - `values` A schema all the array items in the value must conform to
- *
  * @example
  *  const schema = new ArraySchema({ min: 1, max: 2, default: [10,11,12], required: true });
  *  schema.validate([1,2,3], schema); // Returns [1,2,3]
@@ -42,7 +42,8 @@ export declare class ArraySchema<T> extends Schema<ImmutableArray<T>> {
     readonly unique: boolean;
     readonly min: number;
     readonly max: number;
-    constructor({ items, one, many, title, placeholder, unique, min, max, value, ...options }: ArraySchemaOptions<T>);
+    readonly separator: string | RegExp;
+    constructor({ items, one, many, title, placeholder, unique, min, max, separator, value, ...options }: ArraySchemaOptions<T>);
     validate(unsafeValue?: unknown): ImmutableArray<T>;
 }
 /** Valid array with specifed items. */

package/schema/ArraySchema.js

@@ -8,13 +8,6 @@ import { Schema } from "./Schema.js";
  * Validates arrays and ensures the array's items match a specified format.
  * Only returns a new instance of the object if it changes (for immutability).
  *
- * Schema options:
- * - `value` The default value
- * - `length` The exact array length required
- * - `min` The minimum array length required
- * - `max` The maximum array length required
- * - `values` A schema all the array items in the value must conform to
- *
  * @example
  *  const schema = new ArraySchema({ min: 1, max: 2, default: [10,11,12], required: true });
  *  schema.validate([1,2,3], schema); // Returns [1,2,3]
@@ -34,17 +27,20 @@ export class ArraySchema extends Schema {
     unique;
     min;
     max;
-    constructor({ items, one = items.one, many = items.many, title = "Items", placeholder = `No ${many}`, unique = false, min = 0, max = Number.POSITIVE_INFINITY, value = [], ...options }) {
+    separator;
+    constructor({ items, one = items.one, many = items.many, title = "Items", placeholder = `No ${many}`, unique = false, min = 0, max = Number.POSITIVE_INFINITY, separator = ",", value = [], ...options }) {
         super({ one, many, title, placeholder, value, ...options });
         this.items = items;
         this.unique = unique;
         this.min = min;
         this.max = max;
+        this.separator = separator;
     }
     validate(unsafeValue = this.value) {
-        if (!isArray(unsafeValue))
+        const unsafeArray = typeof unsafeValue === "string" ? unsafeValue.split(this.separator).filter(Boolean) : unsafeValue;
+        if (!isArray(unsafeArray))
             throw new ValueFeedback("Must be array", unsafeValue);
-        const validArray = validateArray(unsafeValue, this.items);
+        const validArray = validateArray(unsafeArray, this.items);
         const uniqueArray = this.unique ? getUniqueArray(validArray) : validArray;
         if (uniqueArray.length < this.min)
             throw new ValueFeedback(uniqueArray.length ? `Minimum ${this.min} ${this.many}` : "Required", uniqueArray);

package/schema/BooleanSchema.js

@@ -1,10 +1,13 @@
 import { Schema } from "./Schema.js";
+const NEGATIVE = ["", "false", "0", "no", "n", "off"];
 /** Define a valid boolean. */
 export class BooleanSchema extends Schema {
     constructor({ value = false, ...options }) {
         super({ value, ...options });
     }
     validate(unsafeValue = this.value) {
+        if (typeof unsafeValue === "string")
+            return !NEGATIVE.includes(unsafeValue.toLowerCase().trim());
         return !!unsafeValue;
     }
 }

package/schema/DataSchema.d.ts

@@ -1,4 +1,4 @@
-import type { Data, Database } from "../util/data.js";
+import type { Data, Database, PartialData } from "../util/data.js";
 import type { Identifier, Item } from "../util/item.js";
 import type { NullableSchema } from "./NullableSchema.js";
 import type { SchemaOptions, Schemas } from "./Schema.js";
@@ -25,6 +25,6 @@ export declare const DATA: <T extends Data>(props: Schemas<T>) => DataSchema<T>;
 /** Valid data object with specifed properties, or `null` */
 export declare const NULLABLE_DATA: <T extends Data>(props: Schemas<T>) => NullableSchema<T>;
 /** Create a `DataSchema` that validates partially, i.e. properties can be their value, or `undefined` */
-export declare function PARTIAL<T extends Data>(source: Schemas<T> | DataSchema<T>): DataSchema<Partial<T>>;
+export declare function PARTIAL<T extends Data>(source: Schemas<T> | DataSchema<T>): DataSchema<PartialData<T>>;
 /** Create a `DataSchema` that validates a data item, i.e. it has a string or number `.id` identifier property. */
 export declare function ITEM<I extends Identifier, T extends Data>(id: Schema<I>, schemas: Schemas<T> | DataSchema<T>): DataSchema<Item<I, T>>;

package/store/DictionaryStore.d.ts

@@ -14,8 +14,8 @@ export declare class DictionaryStore<T> extends Store<ImmutableDictionary<T>> im
     get(name: string): T | undefined;
     /** Set an item in this dictionary. */
     set(name: string, value: T): void;
-    /** Delete an item in this dictionary. */
-    delete(name: string): void;
+    /** Delete an item (or several items) in this dictionary. */
+    delete(name: string, ...names: string[]): void;
     /** Iterate over the entries of the object. */
     [Symbol.iterator](): Iterator<DictionaryItem<T>>;
 }

package/store/DictionaryStore.js

@@ -27,9 +27,9 @@ export class DictionaryStore extends Store {
     set(name, value) {
         this.value = withProp(this.value, name, value);
     }
-    /** Delete an item in this dictionary. */
-    delete(name) {
-        this.value = omitProps(this.value, name);
+    /** Delete an item (or several items) in this dictionary. */
+    delete(name, ...names) {
+        this.value = omitProps(this.value, name, ...names);
     }
     /** Iterate over the entries of the object. */
     [Symbol.iterator]() {

package/store/PathStore.d.ts

@@ -11,4 +11,5 @@ export declare class PathStore extends Store<AbsolutePath> {
     isProud(path: AbsolutePath): boolean;
     /** Get an absolute path from a path relative to the current store path. */
     getPath(path: string): AbsolutePath;
+    toString(): string;
 }

package/store/PathStore.js

@@ -24,4 +24,7 @@ export class PathStore extends Store {
     getPath(path) {
         return requirePath(path, this.value);
     }
+    toString() {
+        return this.value;
+    }
 }

package/store/URLStore.d.ts

@@ -0,0 +1,46 @@
+import type { Data } from "../util/data.js";
+import { type ImmutableDictionary } from "../util/dictionary.js";
+import { type PossibleURL } 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> {
+    readonly base: URL | undefined;
+    constructor(url: PossibleURL, base?: PossibleURL);
+    set value(url: PossibleURL);
+    get value(): URL;
+    get href(): string;
+    set href(href: string);
+    get origin(): string;
+    get protocol(): string;
+    get username(): string;
+    get password(): string;
+    get hostname(): string;
+    get host(): string;
+    get port(): string;
+    get pathname(): string;
+    /** Get the URL params as a string. */
+    get search(): string;
+    /** Get the URL params as a dictionary. */
+    get params(): ImmutableDictionary<string>;
+    /** 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;
+    /** Update a single param in this URL. */
+    setParam(key: string, value: unknown): void;
+    /** Update several params in this URL. */
+    setParams(params: Data): 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;
+    /** 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;
+    /** Return the current URL with an additional param. */
+    omitParams(...keys: string[]): URL;
+    /** Return the current URL with an additional param. */
+    omitParam(key: string): URL;
+    toString(): string;
+}

package/store/URLStore.js

@@ -0,0 +1,100 @@
+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 { Store } from "./Store.js";
+/** Store a URL, e.g. `https://top.com/a/b/c` */
+export class URLStore extends Store {
+    base;
+    constructor(url, base) {
+        const baseURL = getURL(base);
+        super(requireURL(url, baseURL));
+        this.base = baseURL;
+    }
+    set value(url) {
+        super.value = requireURL(url, this.base, getSetter(this, "value"));
+    }
+    get value() {
+        return super.value;
+    }
+    get href() {
+        return this.value.href;
+    }
+    set href(href) {
+        this.value = requireURL(href, this.base, getSetter(this, "href"));
+    }
+    get origin() {
+        return this.value.origin;
+    }
+    get protocol() {
+        return this.value.protocol;
+    }
+    get username() {
+        return this.value.username;
+    }
+    get password() {
+        return this.value.password;
+    }
+    get hostname() {
+        return this.value.hostname;
+    }
+    get host() {
+        return this.value.host;
+    }
+    get port() {
+        return this.value.port;
+    }
+    get pathname() {
+        return this.value.pathname;
+    }
+    /** Get the URL params as a string. */
+    get search() {
+        return this.value.search;
+    }
+    /** Get the URL params as a dictionary. */
+    get params() {
+        return getDictionary(this.value.searchParams);
+    }
+    /** Return a single param in this URL, or `undefined` if it could not be found. */
+    getParam(key) {
+        return getURLParam(this.value.searchParams, key);
+    }
+    /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
+    requireParam(key) {
+        return requireURLParam(this.value.searchParams, key, getSetter(this, "requireParam"));
+    }
+    /** Update a single param in this URL. */
+    setParam(key, value) {
+        this.value = withURLParam(this.value, key, value, this.setParams);
+    }
+    /** Update several params in this URL. */
+    setParams(params) {
+        this.value = withURLParams(this.value, params, this.setParams);
+    }
+    /** Delete one or more params in this URL. */
+    deleteParam(key, ...keys) {
+        this.value = omitURLParams(this.value, key, ...keys);
+    }
+    /** Delete one or more params in this URL. */
+    deleteParams(key, ...keys) {
+        this.value = omitURLParams(this.value, key, ...keys);
+    }
+    /** Return the current URL with an additional param. */
+    withParam(key, value) {
+        return withURLParam(this.value, key, value, this.withParam);
+    }
+    /** Return the current URL with an additional param. */
+    withParams(params) {
+        return withURLParams(this.value, params, this.withParams);
+    }
+    /** Return the current URL with an additional param. */
+    omitParams(...keys) {
+        return omitURLParams(this.value, ...keys);
+    }
+    /** Return the current URL with an additional param. */
+    omitParam(key) {
+        return omitURLParams(this.value, key);
+    }
+    toString() {
+        return this.href;
+    }
+}

package/store/index.d.ts

@@ -4,3 +4,4 @@ export * from "./DataStore.js";
 export * from "./DictionaryStore.js";
 export * from "./PathStore.js";
 export * from "./Store.js";
+export * from "./URLStore.js";

package/store/index.js

@@ -4,3 +4,4 @@ export * from "./DataStore.js";
 export * from "./DictionaryStore.js";
 export * from "./PathStore.js";
 export * from "./Store.js";
+export * from "./URLStore.js";

package/util/array.d.ts

@@ -42,9 +42,9 @@ export declare function assertArray<T>(arr: ImmutableArray<T>, min: 3, max: 3, c
 export declare function assertArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is readonly [T, ...T[]];
 export declare function assertArray<T>(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, ...T[]];
 export declare function assertArray<T>(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, T, ...T[]];
-export declare function assertArray<T>(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is ImmutableArray<T>;
+export declare function assertArray<T>(arr: ImmutableArray<T>, min?: number, max?: number, caller?: AnyCaller): asserts arr is ImmutableArray<T>;
 /** Convert a possible array to an array. */
-export declare function getArray<T>(list: PossibleArray<T>): ImmutableArray<T>;
+export declare function getArray(list: unknown): ImmutableArray<unknown> | undefined;
 /** Convert a possible array to an array (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */
 export declare function requireArray<T>(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): [T];
 export declare function requireArray<T>(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): [T, T];
@@ -66,12 +66,20 @@ export declare function isArrayItem<T>(list: PossibleArray<T>, item: unknown): i
 export declare function assertArrayItem<T>(arr: PossibleArray<T>, item: unknown, caller?: AnyCaller): asserts item is T;
 /** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */
 export declare function withArrayItems<T>(list: PossibleArray<T>, ...add: T[]): ImmutableArray<T>;
+/** Add an item to an array (immutably) and return a new array with that item (or the same array if no changes were made). */
+export declare const withArrayItem: <T>(items: PossibleArray<T>, add: T) => ImmutableArray<T>;
 /** Pick multiple items from an array (immutably) and return a new array with those items (or the same array if no changes were made). */
 export declare function pickArrayItems<T>(items: PossibleArray<T>, ...pick: T[]): ImmutableArray<T>;
+/** Pick an item from an array (immutably) and return a new array with that item (or the same array if no changes were made). */
+export declare const pickArrayItem: <T>(items: PossibleArray<T>, pick: T) => ImmutableArray<T>;
 /** Remove multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
 export declare function omitArrayItems<T>(items: PossibleArray<T>, ...omit: T[]): ImmutableArray<T>;
+/** Remove an item from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
+export declare const omitArrayItem: <T>(items: PossibleArray<T>, omit: T) => ImmutableArray<T>;
 /** Toggle an item in and out of an array (immutably) and return a new array with or without the specified items (or the same array if no changes were made). */
 export declare function toggleArrayItems<T>(items: PossibleArray<T>, ...toggle: T[]): ImmutableArray<T>;
+/** Toggle an item in and out of an array (immutably) and return a new array with or without the specified item (or the same array if no changes were made). */
+export declare const toggleArrayItem: <T>(items: PossibleArray<T>, toggle: T) => ImmutableArray<T>;
 /** Return a shuffled version of an array or iterable. */
 export declare function shuffleArray<T>(items: PossibleArray<T>): ImmutableArray<T>;
 /**
@@ -84,11 +92,10 @@ export declare function addArrayItem<T>(arr: MutableArray<T>, item: T): T;
  * - Skip items that already exist.
  */
 export declare function addArrayItems<T>(arr: MutableArray<T>, ...items: T[]): void;
-/**
- * Remove multiple items from an array (by reference).
- * - Skip items that already exist.
- */
+/** Remove multiple items from an array (by reference). */
 export declare function deleteArrayItems<T>(arr: MutableArray<T>, ...items: T[]): void;
+/** Remove an item from an array (by reference). */
+export declare const deleteArrayItem: <T>(arr: MutableArray<T>, item: T) => void;
 /** Return an array of the unique items in an array. */
 export declare function getUniqueArray<T>(list: PossibleArray<T>): ImmutableArray<T>;
 /** Apply a limit to an array. */

package/util/array.js

@@ -1,5 +1,5 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { interleaveItems, omitItems, pickItems } from "./iterate.js";
+import { interleaveItems, isIterable, omitItems, pickItems } from "./iterate.js";
 export function isArray(value, min = 0, max = Number.POSITIVE_INFINITY) {
     return Array.isArray(value) && value.length >= min && value.length <= max;
 }
@@ -12,10 +12,10 @@ export function assertArray(value, min, max, caller = assertArray) {
 }
 /** Convert a possible array to an array. */
 export function getArray(list) {
-    return Array.isArray(list) ? list : Array.from(list);
+    return Array.isArray(list) ? list : isIterable(list) ? Array.from(list) : undefined;
 }
 export function requireArray(list, min, max, caller = requireArray) {
-    const arr = getArray(list);
+    const arr = Array.isArray(list) ? list : Array.from(list);
     assertArray(arr, min, max, caller);
     return arr;
 }
@@ -42,16 +42,22 @@ export function withArrayItems(list, ...add) {
 function _doesNotInclude(value) {
     return !this.includes(value);
 }
+/** Add an item to an array (immutably) and return a new array with that item (or the same array if no changes were made). */
+export const withArrayItem = withArrayItems;
 /** Pick multiple items from an array (immutably) and return a new array with those items (or the same array if no changes were made). */
 export function pickArrayItems(items, ...pick) {
     const arr = Array.from(pickItems(items, ...pick));
     return isArray(items) && arr.length === items.length ? items : arr;
 }
+/** Pick an item from an array (immutably) and return a new array with that item (or the same array if no changes were made). */
+export const pickArrayItem = pickArrayItems;
 /** Remove multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
 export function omitArrayItems(items, ...omit) {
     const filtered = Array.from(omitItems(items, ...omit));
     return isArray(items) && filtered.length === items.length ? items : filtered;
 }
+/** Remove an item from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
+export const omitArrayItem = omitArrayItems;
 /** Toggle an item in and out of an array (immutably) and return a new array with or without the specified items (or the same array if no changes were made). */
 export function toggleArrayItems(items, ...toggle) {
     const arr = Array.from(items);
@@ -59,6 +65,8 @@ export function toggleArrayItems(items, ...toggle) {
     const filtered = arr.filter(_doesNotInclude, toggle);
     return extras.length ? [...filtered, ...extras] : filtered.length !== arr.length ? filtered : isArray(items) ? items : arr;
 }
+/** Toggle an item in and out of an array (immutably) and return a new array with or without the specified item (or the same array if no changes were made). */
+export const toggleArrayItem = toggleArrayItems;
 /** Return a shuffled version of an array or iterable. */
 export function shuffleArray(items) {
     const arr = Array.from(items);
@@ -86,15 +94,14 @@ export function addArrayItems(arr, ...items) {
         if (arr.indexOf(item) < 0)
             arr.push(item);
 }
-/**
- * Remove multiple items from an array (by reference).
- * - Skip items that already exist.
- */
+/** Remove multiple items from an array (by reference). */
 export function deleteArrayItems(arr, ...items) {
     for (let i = arr.length - 1; i >= 0; i--)
         if (i in arr && items.includes(arr[i]))
             arr.splice(i, 1);
 }
+/** Remove an item from an array (by reference). */
+export const deleteArrayItem = deleteArrayItems;
 /** Return an array of the unique items in an array. */
 export function getUniqueArray(list) {
     const output = [];

package/util/dictionary.d.ts

@@ -35,6 +35,8 @@ export declare const withDictionaryItem: <T>(dict: ImmutableDictionary<T>, key:
 export declare const withDictionaryItems: <T>(dict: ImmutableDictionary<T>, props: PossibleDictionary<T>) => ImmutableDictionary<T>;
 /** Remove several key/value entries from a dictionary object (immutably) and return a new object without those props. */
 export declare const omitDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
+/** Remove a key/value entry from a dictionary object (immutably) and return a new object without that prop. */
+export declare const omitDictionaryItem: <T>(dict: ImmutableDictionary<T>, key: string) => ImmutableDictionary<T>;
 /** Pick several props from a dictionary object and return a new object with only thos props. */
 export declare const pickDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
 /** Set a single named prop on a dictionary object (by reference) and return its value. */
@@ -43,6 +45,8 @@ export declare const setDictionaryItem: <T>(dict: MutableDictionary<T>, key: str
 export declare const setDictionaryItems: <T>(dict: MutableDictionary<T>, entries: PossibleDictionary<T>) => void;
 /** Remove several key/value entries from a dictionary object (by reference). */
 export declare const deleteDictionaryItems: <T extends MutableDictionary>(dict: T, ...keys: string[]) => void;
+/** Remove a key/value entry from a dictionary object (by reference). */
+export declare const deleteDictionaryItem: <T extends MutableDictionary>(dict: T, key: string) => void;
 /** Type that represents an empty dictionary object. */
 export type EmptyDictionary = {
     readonly [K in never]: never;

package/util/dictionary.js

@@ -42,6 +42,8 @@ export const withDictionaryItem = withProp;
 export const withDictionaryItems = withProps;
 /** Remove several key/value entries from a dictionary object (immutably) and return a new object without those props. */
 export const omitDictionaryItems = omitProps;
+/** Remove a key/value entry from a dictionary object (immutably) and return a new object without that prop. */
+export const omitDictionaryItem = omitProps;
 /** Pick several props from a dictionary object and return a new object with only thos props. */
 export const pickDictionaryItems = pickProps;
 /** Set a single named prop on a dictionary object (by reference) and return its value. */
@@ -50,5 +52,7 @@ export const setDictionaryItem = setProp;
 export const setDictionaryItems = setProps;
 /** Remove several key/value entries from a dictionary object (by reference). */
 export const deleteDictionaryItems = deleteProps;
+/** Remove a key/value entry from a dictionary object (by reference). */
+export const deleteDictionaryItem = deleteProps;
 /** An empty dictionary object. */
 export const EMPTY_DICTIONARY = { __proto__: null };

package/util/object.d.ts

@@ -90,6 +90,8 @@ export declare function withProps<T>(input: T, props: Partial<T>): T;
 export declare function withProps<T>(input: T, props: T | Partial<T> | Iterable<Prop<T>>): T;
 /** Remove several props from an object (immutably) and return a new object without those props. */
 export declare function omitProps<T, K extends Key<T>>(input: T, ...keys: K[]): Omit<T, K>;
+/** Remove a prop from an object (immutably) and return a new object without that prop. */
+export declare const omitProp: <T, K extends Key<T>>(input: T, key: K) => Omit<T, K>;
 /** Pick several props from an object and return a new object with only thos props. */
 export declare function pickProps<T, K extends Key<T>>(obj: T, ...keys: K[]): Pick<T, K>;
 /** Set a single named prop on an object (by reference) and return its value. */
@@ -98,6 +100,8 @@ export declare function setProp<T extends MutableObject, K extends Key<T>>(obj:
 export declare function setProps<T extends MutableObject>(obj: T, entries: T | Partial<T> | Iterable<Prop<T>>): void;
 /** Remove several key/value entries from an object (by reference). */
 export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: Key<T>[]): void;
+/** Remove a key/value entry from an object (by reference). */
+export declare const deleteProp: <T extends MutableObject>(input: T, key: Key<T>) => void;
 /**
  * Get the prototype of an object instance.
  * - Recommend to use this because Typescript's default lib specifies `Object.getPrototypeOf()` returning `any`.

package/util/object.js

@@ -66,6 +66,8 @@ export function omitProps(input, ...keys) {
 function _hasntKey([key]) {
     return !this.includes(key);
 }
+/** Remove a prop from an object (immutably) and return a new object without that prop. */
+export const omitProp = omitProps;
 export function pickProps(input, ...keys) {
     return Object.fromEntries(Object.entries(input).filter(_hasKey, keys));
 }
@@ -87,6 +89,8 @@ export function deleteProps(obj, ...keys) {
     for (const key of keys)
         delete obj[key];
 }
+/** Remove a key/value entry from an object (by reference). */
+export const deleteProp = deleteProps;
 /**
  * Get the prototype of an object instance.
  * - Recommend to use this because Typescript's default lib specifies `Object.getPrototypeOf()` returning `any`.

package/util/path.d.ts

@@ -1,5 +1,5 @@
 import type { AnyCaller } from "./function.js";
-import { type Nullish } from "./null.js";
+import type { Nullish } from "./null.js";
 /** Absolute path string starts with `/` slash. */
 export type AbsolutePath = `/` | `/${string}`;
 /** Relative path string starts with `./` or `../` */
@@ -19,7 +19,7 @@ export declare function isRelativePath(path: string): path is RelativePath;
  * @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 getPath(value: Nullish<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
+export declare function getPath(value: Nullish<string | URL>, base?: AbsolutePath): AbsolutePath | undefined;
 /**
  * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
  * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.

package/util/path.js

@@ -1,5 +1,5 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { notNullish } from "./null.js";
+import { getURL } from "./url.js";
 /** Is a string path an absolute path? */
 export function isAbsolutePath(path) {
     return path.startsWith("/");
@@ -23,15 +23,11 @@ function _cleanPath(path) {
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
 export function getPath(value, base = "/") {
-    if (notNullish(value)) {
-        try {
-            const { pathname, search, hash } = new URL(value, `http://j.com${base}/`);
-            if (isAbsolutePath(pathname))
-                return `${_cleanPath(pathname)}${search}${hash}`;
-        }
-        catch {
-            //
-        }
+    const url = getURL(value, `http://j.com${base === "/" || base.endsWith("/") ? base : `${base}/`}`);
+    if (url) {
+        const { pathname, search, hash } = url;
+        if (isAbsolutePath(pathname))
+            return `${_cleanPath(pathname)}${search}${hash}`;
     }
 }
 /**

package/util/regexp.js

@@ -1,6 +1,6 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
-import { getArray } from "./array.js";
+import { requireArray } from "./array.js";
 /** Regular expression that always matches everything. */
 export const ALWAYS_REGEXP = /^.*$/;
 /** Regular expression that never matches anything. */
@@ -28,21 +28,21 @@ export function escapeRegExp(pattern) {
 const REPLACE_ESCAPED = /[-[\]/{}()*+?.\\^$|]/g;
 /** Create regular expression that matches any of a list of other expressions. */
 export function createRegExpAny(patterns, flags) {
-    const arr = getArray(patterns).filter(Boolean);
+    const arr = requireArray(patterns).filter(Boolean);
     // If there are no patterns to match against then _no_ string can ever match against any of nothing.
     if (!arr.length)
         return NEVER_REGEXP;
     // Create RegExp using multiple joined matches like `(?:AAA)|(?:BBB)`
-    return new RegExp(`(?:${getArray(patterns).map(getRegExpSource).join(")|(?:")})`, flags);
+    return new RegExp(`(?:${requireArray(patterns).map(getRegExpSource).join(")|(?:")})`, flags);
 }
 /** Create regular expression that matches all of a list of other expressions. */
 export function createRegExpAll(patterns, flags) {
-    const arr = getArray(patterns).filter(Boolean);
+    const arr = requireArray(patterns).filter(Boolean);
     // If there are no patterns to match against then _every_ string will match against the entire list of nothing.
     if (!arr.length)
         return ALWAYS_REGEXP;
     // Create RegExp using multiple lookaheads like `^(?=.*?(?:AAA))(?=.*?(?:BBB))`
-    return new RegExp(`^(?=.*?(?:${getArray(patterns).map(getRegExpSource).join("))(?=.*?(?:")}))`, flags);
+    return new RegExp(`^(?=.*?(?:${requireArray(patterns).map(getRegExpSource).join("))(?=.*?(?:")}))`, flags);
 }
 /** Match function for finding strings that match against regular expressions (use with `filter()` to positively filter iterable sets of items). */
 export function isMatch(str, regexp) {

package/util/string.d.ts

@@ -10,8 +10,8 @@ export type NotString = {
     toUpperCase?: never;
     toLowerCase?: never;
 };
-/** Things that can be easily converted to a string. */
-export type PossibleString = string | number | Date;
+/** Things that can be reliably converted to a string with no confusion. */
+export type PossibleString = boolean | string | number | Date;
 /** Is a value a string (optionally with specified min/max length). */
 export declare function isString(value: unknown, min?: number, max?: number): value is string;
 /** Assert that a value is a string (optionally with specified min/max length). */

package/util/string.js

@@ -20,8 +20,12 @@ export function getString(value) {
         return value;
     if (typeof value === "number")
         return value.toString();
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
     if (value instanceof Date)
         return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(getString).filter(Boolean).join(",");
     return undefined;
 }
 /** Convert a possible string to a string (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */

package/util/url.d.ts

@@ -1,3 +1,5 @@
+import type { Data } from "./data.js";
+import type { 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. */
@@ -10,3 +12,20 @@ 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;
+/**
+ * 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).
+ */
+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 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). */
+export declare const omitURLParam: (url: PossibleURL, key: string) => URL;

package/util/url.js

@@ -1,5 +1,7 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { notNullish } from "./null.js";
+import { getProps } from "./object.js";
+import { requireString } from "./string.js";
 /** Is an unknown value a URL object? */
 export function isURL(value) {
     return value instanceof URL;
@@ -27,3 +29,50 @@ export function requireURL(possible, base, caller = requireURL) {
     assertURL(url, caller);
     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).
+ */
+export function getURLParams(params) {
+    const output = {};
+    for (const [key, value] of params)
+        if (!Object.hasOwn(output, key))
+            output[key] = value;
+    return output;
+}
+/** Get a param from a URL. */
+export function getURLParam(params, key) {
+    return params.get(key) || undefined;
+}
+/** 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 });
+    return value;
+}
+/** Return a URL with a new param set (or same URL if no changes were made). */
+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));
+    return input.href === output.href ? input : output;
+}
+/** Return a URL with several new params set (or same URL if no changes were made). */
+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));
+    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);
+    for (const key of keys)
+        output.searchParams.delete(key);
+    return input.href === output.href ? input : output;
+}
+/** Return a URL without a param (or same URL if no changes were made). */
+export const omitURLParam = omitURLParams;