shelving 1.82.0 → 1.83.0

package/util/array.d.ts

@@ -8,135 +8,64 @@ export declare type MutableArray<T = unknown> = T[];
  * - Consistency with `ImmutableObject<T>` and `MutableArray<T>`
  */
 export declare type ImmutableArray<T = unknown> = readonly T[];
-/**
- * Array type: extract the type for the items of an array or readonly array.
- * - Consistency with builtin `ReturnType<T>` and `ObjectType<T>`
- */
-export declare type ArrayType<T extends ImmutableArray> = T[number];
+/** Get the type of the _items_ in an array. */
+export declare type ArrayItem<T extends ImmutableArray> = T[number];
 /** Is an unknown value an array? */
 export declare const isArray: <T extends ImmutableArray<unknown>>(v: unknown) => v is T;
 /** Assert that a value is an array. */
 export declare function assertArray<T>(arr: ImmutableArray<T> | unknown): asserts arr is ImmutableArray<T>;
 /** Is an unknown value an item in a specified array? */
+export declare const isArrayItem: <T>(arr: ImmutableArray<T>, item: unknown) => item is T;
 export declare const isItem: <T>(arr: ImmutableArray<T>, item: unknown) => item is T;
 /** Things that can be converted to arrays. */
 export declare type PossibleArray<T> = ImmutableArray<T> | Iterable<T>;
 /** Convert an iterable to an array (if its not already an array). */
 export declare function getArray<T>(items: PossibleArray<T>): ImmutableArray<T>;
-/**
- * Add multiple items to an array (immutably).
- * - Returns an array that definitely contains the specified item.
- *
- * @param input The input array to add items to.
- * @param items The array of items to add.
- *
- * @return New array with the specified item (or same array if no items were added).
- */
-export declare function withItems<T>(input: ImmutableArray<T>, ...items: T[]): ImmutableArray<T>;
-/**
- * Remove multiple items from an array (immutably).
- * - Finds all instances of a number of items from an array and returns an array that definitely does not contain them.
- *
- * @param input The input array to remove items from.
- * @param items The array of items to add.
- *
- * @return New array without the specified items (or same array if no items were removed).
- */
-export declare function withoutItems<T>(input: ImmutableArray<T>, ...items: T[]): ImmutableArray<T>;
-/**
- * Toggle an item in and out of an array (immutably).
- * - If an item is being removed from the array ALL instances of that item in the array will be removed.
- *
- * @param input The input array to toggle items from.
- * @param items The array of items to toggle.
- *
- * @return New array with or without the specified items (or same array if no items were toggled).
- */
-export declare function toggleItems<T>(input: ImmutableArray<T>, ...items: T[]): ImmutableArray<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>(input: ImmutableArray<T>, ...items: 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 withoutArrayItems<T>(input: ImmutableArray<T>, ...items: 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>(input: ImmutableArray<T>, ...items: T[]): ImmutableArray<T>;
 /** Get the first item from an array or iterable, or `null` if it didn't exist. */
-export declare function getOptionalFirstItem<T>(items: ImmutableArray<T> | Iterable<T>): T | null;
+export declare function getOptionalFirstItem<T>(items: PossibleArray<T>): T | null;
 /** Get the first item from an array or iterable. */
-export declare function getFirstItem<T>(items: ImmutableArray<T> | Iterable<T>): T;
+export declare function getFirstItem<T>(items: PossibleArray<T>): T;
 /** Get the last item from an array or iterable, or `null` if it didn't exist. */
-export declare function getOptionalLastItem<T>(items: ImmutableArray<T> | Iterable<T>): T | null;
+export declare function getOptionalLastItem<T>(items: PossibleArray<T>): T | null;
 /** Get the last item from an array or iterable. */
-export declare function getLastItem<T>(items: ImmutableArray<T> | Iterable<T>): T;
-/**
- * Get the next item in an array.
- *
- * @param arr The target array.
- * @param value The value of the target item.
- * @return The item after the target item, or `undefined` if that item does not exist in the array.
- */
-export declare function getNextItem<T>(arr: ImmutableArray<T>, value: T): T | undefined;
-/**
- * Get the previous item in an array.
- *
- * @param arr The target array.
- * @param value The value of the target item.
- *
- * @return The item before the target item, or `undefined` if that item does not exist in the array.
- */
-export declare function getPrevItem<T>(arr: ImmutableArray<T>, value: T): T | undefined;
-/**
- * Return a shuffled version of an array or iterable.
- * - Uses Fisher Yates algorithm.
- *
- * @param input The input array or iterable to shuffle.
- * @return Copy of in a random order.
- */
-export declare function shuffleArray<T>(input: Iterable<T>): ImmutableArray<T>;
-/**
- * Add an item to an array (by reference).
- * - If the item already exists in the array (using `indexOf()`) then it won't be added again.
- *
- * @param arr The target array to add items to.
- * @param item The item to add.
- */
-export declare function addItem<T>(arr: MutableArray<T>, item: T): T;
-/**
- * Add multiple items to an array (by reference).
- * - If an item already exists in the array (using `indexOf()`) then it won't be added again.
- *
- * @param arr The target array to add items to.
- * @param items The array of items to add.
- */
-export declare function addItems<T>(arr: MutableArray<T>, items: Iterable<T>): void;
-/**
- * Remove an item from an array (by reference).
- * - Deletes all instances of an item from an array by reference, and returns void.
- *
- * @param arr The target array to remove items from.
- * @param item The item to remove.
- */
-export declare function removeItem<T>(arr: MutableArray<T>, item: T): void;
-/**
- * Remove multiple items from an array (by reference).
- * - Deletes all instances of an item from an array by reference, and returns void.
- *
- * @param arr The target array to remove items from.
- * @param items The array of items to remove.
- */
-export declare function removeItems<T>(arr: MutableArray<T>, items: Iterable<T>): void;
+export declare function getLastItem<T>(items: PossibleArray<T>): T;
+/** Get the next item in an array or iterable. */
+export declare function getNextItem<T>(items: PossibleArray<T>, value: T): T | null;
+/** Get the previous item in an array or iterable. */
+export declare function getPrevItem<T>(items: PossibleArray<T>, value: T): T | null;
+/** Return a shuffled version of an array or iterable. */
+export declare function shuffleArray<T>(input: PossibleArray<T>): ImmutableArray<T>;
+/** Add an item to an array (by reference) and return the set item. */
+export declare function addArrayItem<T>(arr: MutableArray<T>, item: T): T;
+/** Add multiple items to an array (by reference). */
+export declare function addArrayItems<T>(arr: MutableArray<T>, ...items: T[]): void;
+/** Remove multiple items from an array (by reference). */
+export declare function removeArrayItems<T>(arr: MutableArray<T>, ...items: T[]): void;
 /** Return an array of the unique items in an array. */
 export declare function uniqueArray<T>(input: Iterable<T>): ImmutableArray<T>;
 /** Apply a limit to an array. */
 export declare function limitArray<T>(arr: ImmutableArray<T>, limit: number): ImmutableArray<T>;
 /** Does an array have the specified minimum length.  */
-export declare function isMinLength<T>(arr: ImmutableArray<T>, min?: 1): arr is [T, ...T[]];
-export declare function isMinLength<T>(arr: ImmutableArray<T>, min: 2): arr is [T, T, ...T[]];
-export declare function isMinLength<T>(arr: ImmutableArray<T>, min: 3): arr is [T, T, T, ...T[]];
-export declare function isMinLength<T>(arr: ImmutableArray<T>, min: 4): arr is [T, T, T, T, ...T[]];
-export declare function isMinLength<T>(arr: ImmutableArray<T>, min: number): boolean;
+export declare function isArrayMin<T>(arr: ImmutableArray<T>, min?: 1): arr is [T, ...T[]];
+export declare function isArrayMin<T>(arr: ImmutableArray<T>, min: 2): arr is [T, T, ...T[]];
+export declare function isArrayMin<T>(arr: ImmutableArray<T>, min: 3): arr is [T, T, T, ...T[]];
+export declare function isArrayMin<T>(arr: ImmutableArray<T>, min: 4): arr is [T, T, T, T, ...T[]];
+export declare function isArrayMin<T>(arr: ImmutableArray<T>, min: number): boolean;
 /** Assert that a value has a specific length (or length is in a specific range). */
-export declare function assertMinLength<T>(arr: ImmutableArray<T> | unknown, min?: 1): asserts arr is [T, ...T[]];
-export declare function assertMinLength<T>(arr: ImmutableArray<T> | unknown, min: 2): asserts arr is [T, T, ...T[]];
-export declare function assertMinLength<T>(arr: ImmutableArray<T> | unknown, min: 3): asserts arr is [T, T, T, ...T[]];
-export declare function assertMinLength<T>(arr: ImmutableArray<T> | unknown, min: 4): asserts arr is [T, T, T, T, ...T[]];
-export declare function assertMinLength<T>(arr: ImmutableArray<T> | unknown, min: number): asserts arr is ImmutableArray<T>;
+export declare function assertArrayMin<T>(arr: ImmutableArray<T> | unknown, min?: 1): asserts arr is [T, ...T[]];
+export declare function assertArrayMin<T>(arr: ImmutableArray<T> | unknown, min: 2): asserts arr is [T, T, ...T[]];
+export declare function assertArrayMin<T>(arr: ImmutableArray<T> | unknown, min: 3): asserts arr is [T, T, T, ...T[]];
+export declare function assertArrayMin<T>(arr: ImmutableArray<T> | unknown, min: 4): asserts arr is [T, T, T, T, ...T[]];
+export declare function assertArrayMin<T>(arr: ImmutableArray<T> | unknown, min: number): asserts arr is ImmutableArray<T>;
 /** Get an array if it has the specified minimum length.  */
-export declare function getMinLength<T>(arr: ImmutableArray<T>, min?: 1): [T, ...T[]];
-export declare function getMinLength<T>(arr: ImmutableArray<T>, min: 2): [T, T, ...T[]];
-export declare function getMinLength<T>(arr: ImmutableArray<T>, min: 3): [T, T, T, ...T[]];
-export declare function getMinLength<T>(arr: ImmutableArray<T>, min: 4): [T, T, T, T, ...T[]];
-export declare function getMinLength<T>(arr: ImmutableArray<T>, min: number): ImmutableArray<T>;
+export declare function getArrayMin<T>(arr: ImmutableArray<T>, min?: 1): [T, ...T[]];
+export declare function getArrayMin<T>(arr: ImmutableArray<T>, min: 2): [T, T, ...T[]];
+export declare function getArrayMin<T>(arr: ImmutableArray<T>, min: 3): [T, T, T, ...T[]];
+export declare function getArrayMin<T>(arr: ImmutableArray<T>, min: 4): [T, T, T, T, ...T[]];
+export declare function getArrayMin<T>(arr: ImmutableArray<T>, min: number): ImmutableArray<T>;

package/util/array.js

@@ -8,61 +8,35 @@ export function assertArray(arr) {
         throw new AssertionError(`Must be array`, arr);
 }
 /** Is an unknown value an item in a specified array? */
-export const isItem = (arr, item) => arr.includes(item);
+export const isArrayItem = (arr, item) => arr.includes(item);
+export const isItem = isArrayItem;
 /** Convert an iterable to an array (if its not already an array). */
 export function getArray(items) {
     return isArray(items) ? items : Array.from(items);
 }
-/**
- * Add multiple items to an array (immutably).
- * - Returns an array that definitely contains the specified item.
- *
- * @param input The input array to add items to.
- * @param items The array of items to add.
- *
- * @return New array with the specified item (or same array if no items were added).
- */
-export function withItems(input, ...items) {
+/** 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 function withArrayItems(input, ...items) {
     const extras = items.filter(_doesNotInclude, input);
     return extras.length ? [...input, ...extras] : input;
 }
-/**
- * Remove multiple items from an array (immutably).
- * - Finds all instances of a number of items from an array and returns an array that definitely does not contain them.
- *
- * @param input The input array to remove items from.
- * @param items The array of items to add.
- *
- * @return New array without the specified items (or same array if no items were removed).
- */
-export function withoutItems(input, ...items) {
+/** 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 withoutArrayItems(input, ...items) {
     const output = input.filter(_doesNotInclude, items);
     return output.length === input.length ? input : output;
 }
 function _doesNotInclude(value) {
     return !this.includes(value);
 }
-/**
- * Toggle an item in and out of an array (immutably).
- * - If an item is being removed from the array ALL instances of that item in the array will be removed.
- *
- * @param input The input array to toggle items from.
- * @param items The array of items to toggle.
- *
- * @return New array with or without the specified items (or same array if no items were toggled).
- */
-export function toggleItems(input, ...items) {
+/** 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(input, ...items) {
     const extras = items.filter(_doesNotInclude, input);
     const output = input.filter(_doesNotInclude, items);
     return extras.length ? [...output, ...extras] : output.length !== input.length ? output : input;
 }
 /** Get the first item from an array or iterable, or `null` if it didn't exist. */
 export function getOptionalFirstItem(items) {
-    var _a;
-    if (isArray(items))
-        return (_a = items[1]) !== null && _a !== void 0 ? _a : null;
-    const [item] = items;
-    return item !== null && item !== void 0 ? item : null;
+    const arr = getArray(items);
+    return 0 in arr ? arr[0] : null;
 }
 /** Get the first item from an array or iterable. */
 export function getFirstItem(items) {
@@ -73,9 +47,9 @@ export function getFirstItem(items) {
 }
 /** Get the last item from an array or iterable, or `null` if it didn't exist. */
 export function getOptionalLastItem(items) {
-    var _a;
     const arr = getArray(items);
-    return (_a = arr[arr.length - 1]) !== null && _a !== void 0 ? _a : null;
+    const j = arr.length - 1;
+    return j in arr ? arr[j] : null;
 }
 /** Get the last item from an array or iterable. */
 export function getLastItem(items) {
@@ -84,40 +58,29 @@ export function getLastItem(items) {
         throw new RequiredError("Last item is required");
     return item;
 }
-/**
- * Get the next item in an array.
- *
- * @param arr The target array.
- * @param value The value of the target item.
- * @return The item after the target item, or `undefined` if that item does not exist in the array.
- */
-export function getNextItem(arr, value) {
+/** Get the next item in an array or iterable. */
+export function getNextItem(items, value) {
+    const arr = getArray(items);
     const i = arr.indexOf(value);
-    if (i >= 0)
-        return arr[i + 1];
-    return undefined;
-}
-/**
- * Get the previous item in an array.
- *
- * @param arr The target array.
- * @param value The value of the target item.
- *
- * @return The item before the target item, or `undefined` if that item does not exist in the array.
- */
-export function getPrevItem(arr, value) {
+    if (i >= 0) {
+        const j = i + 1;
+        if (j in arr)
+            return arr[j];
+    }
+    return null;
+}
+/** Get the previous item in an array or iterable. */
+export function getPrevItem(items, value) {
+    const arr = getArray(items);
     const i = arr.indexOf(value);
-    if (i >= 1)
-        return arr[i - 1];
-    return undefined;
-}
-/**
- * Return a shuffled version of an array or iterable.
- * - Uses Fisher Yates algorithm.
- *
- * @param input The input array or iterable to shuffle.
- * @return Copy of in a random order.
- */
+    if (i >= 1) {
+        const j = i - 1;
+        if (j in arr)
+            return arr[j];
+    }
+    return null;
+}
+/** Return a shuffled version of an array or iterable. */
 export function shuffleArray(input) {
     const output = Array.from(input);
     for (let i = output.length - 1; i > 0; i--) {
@@ -126,50 +89,23 @@ export function shuffleArray(input) {
     }
     return output;
 }
-/**
- * Add an item to an array (by reference).
- * - If the item already exists in the array (using `indexOf()`) then it won't be added again.
- *
- * @param arr The target array to add items to.
- * @param item The item to add.
- */
-export function addItem(arr, item) {
+/** Add an item to an array (by reference) and return the set item. */
+export function addArrayItem(arr, item) {
     if (arr.indexOf(item) < 0)
         arr.push(item);
     return item;
 }
-/**
- * Add multiple items to an array (by reference).
- * - If an item already exists in the array (using `indexOf()`) then it won't be added again.
- *
- * @param arr The target array to add items to.
- * @param items The array of items to add.
- */
-export function addItems(arr, items) {
+/** Add multiple items to an array (by reference). */
+export function addArrayItems(arr, ...items) {
     for (const item of items)
-        addItem(arr, item);
-}
-/**
- * Remove an item from an array (by reference).
- * - Deletes all instances of an item from an array by reference, and returns void.
- *
- * @param arr The target array to remove items from.
- * @param item The item to remove.
- */
-export function removeItem(arr, item) {
-    for (let i = arr.indexOf(item); i >= 0; i = arr.indexOf(item, i))
-        arr.splice(i, 1);
-}
-/**
- * Remove multiple items from an array (by reference).
- * - Deletes all instances of an item from an array by reference, and returns void.
- *
- * @param arr The target array to remove items from.
- * @param items The array of items to remove.
- */
-export function removeItems(arr, items) {
-    for (const item of items)
-        removeItem(arr, item);
+        if (arr.indexOf(item) < 0)
+            arr.push(item);
+}
+/** Remove multiple items from an array (by reference). */
+export function removeArrayItems(arr, ...items) {
+    for (let i = arr.length - 1; i >= 0; i--)
+        if (i in arr && items.includes(arr[i]))
+            arr.splice(i, 1);
 }
 /** Return an array of the unique items in an array. */
 export function uniqueArray(input) {
@@ -183,14 +119,14 @@ export function uniqueArray(input) {
 export function limitArray(arr, limit) {
     return limit > arr.length ? arr : arr.slice(0, limit);
 }
-export function isMinLength(arr, min = 1) {
+export function isArrayMin(arr, min = 1) {
     return arr.length >= min;
 }
-export function assertMinLength(arr, min = 1) {
-    if (isArray(arr) && arr.length < min)
+export function assertArrayMin(arr, min = 1) {
+    if (!isArray(arr) || !isArrayMin(arr, min))
         throw new AssertionError(`Must be array with minimum length ${min}`, arr);
 }
-export function getMinLength(arr, min = 1) {
-    assertMinLength(arr, min);
+export function getArrayMin(arr, min = 1) {
+    assertArrayMin(arr, min);
     return arr;
 }

package/util/clone.d.ts

@@ -1,5 +1,5 @@
-import type { Data } from "./data.js";
 import { ImmutableArray } from "./array.js";
+import { ImmutableObject } from "./object.js";
 /** Cloneable object implement a `clone()` function that returns a cloned copy. */
 export interface Cloneable {
     clone(): this;
@@ -13,4 +13,4 @@ export declare function deepClone<T>(value: T, recursor?: typeof deepClone): T;
 /** Clone an array. */
 export declare function cloneArray<T extends ImmutableArray>(input: T, recursor?: <T_1>(value: T_1) => T_1): T;
 /** Clone an object. */
-export declare function cloneObject<T extends Data>(input: T, recursor?: <T_1>(value: T_1) => T_1): T;
+export declare function cloneObject<T extends ImmutableObject>(input: T, recursor?: <T_1>(value: T_1) => T_1): T;

package/util/clone.js

@@ -1,8 +1,8 @@
 import { isArray } from "./array.js";
-import { isObject } from "./object.js";
-import { mapArray, mapData } from "./transform.js";
+import { isData } from "./data.js";
+import { mapArray, mapObject } from "./transform.js";
 /** Does an object implement `Cloneable` */
-export const isCloneable = (v) => isObject(v) && typeof v.cloneable === "function";
+export const isCloneable = (v) => isData(v) && typeof v.cloneable === "function";
 /** Shallow clone a value. */
 export const shallowClone = (value) => value;
 /** Deep clone a value. */
@@ -11,7 +11,7 @@ export function deepClone(value, recursor = deepClone) {
         return value.clone();
     if (isArray(value))
         return cloneArray(value, recursor);
-    if (isObject(value))
+    if (isData(value))
         return cloneObject(value, recursor);
     return value;
 }
@@ -27,7 +27,7 @@ export function cloneArray(input, recursor = shallowClone) {
 export function cloneObject(input, recursor = shallowClone) {
     if (isCloneable(input))
         return input.clone();
-    const output = mapData(input, recursor);
+    const output = mapObject(input, recursor);
     Object.setPrototypeOf(input, Object.getPrototypeOf(input));
     return output;
 }

package/util/data.d.ts

@@ -1,70 +1,29 @@
+import type { ImmutableArray } from "./array.js";
 /** Data object. */
 export declare type Data = {
     readonly [K in string]: unknown;
 };
-/** Key from a data object. */
-export declare type Key<T extends Data> = keyof T & string;
-/** Value from a data object. */
-export declare type Value<T extends Data> = T[keyof T & string];
-/** Prop from a data object in entry format. */
-export declare type Prop<T extends Data> = readonly [Key<T>, Value<T>];
+/** Prop for a data object. */
+export declare type DataProp<T extends Data> = readonly [keyof T & string, T[keyof T & string]];
+/** Key for a data object prop. */
+export declare type DataKey<T extends Data> = keyof T & string;
+/** Value for a data object prop. */
+export declare type DataValue<T extends Data> = T[keyof T & string];
 /** Data or `null` to indicate the data doesn't exist. */
 export declare type OptionalData<T extends Data> = T | null;
-/** Empty data object. */
-export declare type EmptyData = {
-    readonly [K in never]: never;
-};
 /** Set of named data objects. */
 export declare type Datas = {
     readonly [K in string]: Data;
 };
 /** Is an unknown value a data object? */
 export declare const isData: <T extends Data>(value: unknown) => value is T;
+/** Is an unknown value the key for an own prop of a data object. */
+export declare const isDataKey: <T extends Data>(obj: T, key: unknown) => key is DataKey<T>;
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export declare function getData<T extends Data>(result: OptionalData<T>): T;
-/**
- * Mutable type is the opposite of `Readonly<T>` helper type.
- * - See https://github.com/microsoft/TypeScript/issues/24509
- * - Consistency with `Readonly<T>`
- */
-export declare type Mutable<T> = {
-    -readonly [K in keyof T]: T[K];
-};
-/**
- * Deep partial object: deeply convert an object to its partial version.
- * - Any value that extends `Data` has its props made partial.
- * - Works deeply on nested objects too.
- * - Only works for plain objects (i.e. objects that extend `Data`), not arrays and functions.
- */
-export declare type DeepPartial<T extends Data> = {
-    [K in keyof T]?: T[K] extends Data ? DeepPartial<T[K]> : T[K];
-};
-/**
- * Deep mutable object: deeply convert an object to its mutable version.
- * - Any value that extends `Data` has its props made mutable.
- * - Works deeply on nested objects too.
- * - Only works for plain objects (i.e. objects that extend `Data`), not arrays and functions.
- */
-export declare type DeepMutable<T extends Data> = {
-    -readonly [K in keyof T]: T[K] extends Data ? DeepMutable<T[K]> : T[K];
-};
-/**
- * Deep readonly object: deeply convert an object to its readonly version.
- * - Any value that extends `Data` has its props made readonly.
- * - Works deeply on nested objects too.
- * - Only works for plain objects (i.e. objects that extend `Data`), not arrays and functions.
- */
-export declare type DeepReadonly<T extends Data> = {
-    +readonly [K in keyof T]: T[K] extends Data ? DeepReadonly<T[K]> : T[K];
-};
-/** Pick only the properties of an object that match a type. */
-export declare type PickProps<T, TT> = Pick<T, {
-    [K in keyof T]: T[K] extends TT ? K : never;
-}[keyof T]>;
-/** Omit the properties of an object that match a type. */
-export declare type OmitProps<T, TT> = Omit<T, {
-    [K in keyof T]: T[K] extends TT ? K : never;
-}[keyof T]>;
+/** Get the props of a data object. */
+export declare function getDataProps<T extends Data>(data: T): ImmutableArray<DataProp<T>>;
+export declare function getDataProps<T extends Data>(data: T | Partial<T>): ImmutableArray<DataProp<T>>;
 /**
  * Format a data object as a string.
  * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.
@@ -72,3 +31,11 @@ export declare type OmitProps<T, TT> = Omit<T, {
  * - Use `Object` otherwise.
  */
 export declare function formatData(data: Data): string;
+/** Type that represents an empty data object. */
+export declare type EmptyData = {
+    readonly [K in never]: never;
+};
+/** An empty object. */
+export declare const EMPTY_DATA: EmptyData;
+/** Function that returns an an empty object. */
+export declare const getEmptyData: () => EmptyData;

package/util/data.js

@@ -1,12 +1,18 @@
 import { RequiredError } from "../error/RequiredError.js";
+import { isPlainObject } from "./object.js";
 /** Is an unknown value a data object? */
-export const isData = (value) => typeof value === "object" && value !== null;
+export const isData = (value) => isPlainObject(value);
+/** Is an unknown value the key for an own prop of a data object. */
+export const isDataKey = (obj, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(obj, key);
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export function getData(result) {
     if (!result)
         throw new RequiredError("Data is required");
     return result;
 }
+export function getDataProps(data) {
+    return Object.entries(data);
+}
 /**
  * Format a data object as a string.
  * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.
@@ -25,3 +31,7 @@ export function formatData(data) {
         return id;
     return "Object";
 }
+/** An empty object. */
+export const EMPTY_DATA = {};
+/** Function that returns an an empty object. */
+export const getEmptyData = () => EMPTY_DATA;

package/util/dictionary.d.ts

@@ -0,0 +1,39 @@
+/** Readonly dictionary object. */
+export declare type ImmutableDictionary<T = unknown> = {
+    readonly [K in string]: T;
+};
+/** Writable dictionary object. */
+export declare type MutableDictionary<T = unknown> = {
+    [K in string]: T;
+};
+/** Get the type for an item of a dictionary object in entry format. */
+export declare type DictionaryItem<T> = readonly [string, T];
+/** Get the type of the _values_ of the items of a dictionary object. */
+export declare type DictionaryValue<T extends ImmutableDictionary> = T[string];
+/** Something that can be converted to a dictionary object. */
+export declare type PossibleDictionary<T> = ImmutableDictionary<T> | Iterable<DictionaryItem<T>>;
+/** Is an unknown value a dictionary object? */
+export declare const isDictionary: <T extends ImmutableDictionary<T>>(value: unknown) => value is T;
+/** Assert that an unknown value is a dictionary object */
+export declare function assertDictionary<T>(value: ImmutableDictionary<T> | unknown): asserts value is ImmutableDictionary<T>;
+/** Is an unknown value the key for an own prop of an dictionary. */
+export declare const isDictionaryKey: <T>(obj: ImmutableDictionary<T>, key: unknown) => key is string;
+/** turn a possible dictionary into an dictionary. */
+export declare function getDictionary<T>(obj: PossibleDictionary<T>): ImmutableDictionary<T>;
+/** Turn a dictionary object into a set of props. */
+export declare function getDictionaryItems<T>(obj: ImmutableDictionary<T>): readonly DictionaryItem<T>[];
+export declare function getDictionaryItems<T>(obj: PossibleDictionary<T>): Iterable<DictionaryItem<T>>;
+/** Set a prop on a dictionary object (immutably) and return a new object including that prop. */
+export declare const withDictionaryItem: <T>(input: ImmutableDictionary<T>, key: string, value: T) => ImmutableDictionary<T>;
+/** Set several props on a dictionary object (immutably) and return a new object including those props. */
+export declare const withDictionaryItems: <T>(input: 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 withoutDictionaryItems: <T>(input: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
+/** Pick several props from a dictionary object and return a new object with only thos props. */
+export declare const pickDictionaryItems: <T>(input: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
+/** Set a single named prop on a dictionary object (by reference) and return its value. */
+export declare const setDictionaryEntry: <T>(dict: MutableDictionary<T>, key: string, value: T) => T;
+/** Set several named props on a dictionary object (by reference). */
+export declare const setDictionaryEntries: <T>(dict: MutableDictionary<T>, entries: PossibleDictionary<T>) => void;
+/** Remove several key/value entries from a dictionary object (by reference). */
+export declare const deleteDictionaryEntries: <T extends MutableDictionary>(dict: T, ...keys: string[]) => void;

package/util/dictionary.js

@@ -0,0 +1,33 @@
+import { AssertionError } from "../error/AssertionError.js";
+import { isIterable } from "./iterate.js";
+import { deleteProps, isPlainObject, omitProps, pickProps, setProp, setProps, withProp, withProps } from "./object.js";
+/** Is an unknown value a dictionary object? */
+export const isDictionary = (value) => isPlainObject(value);
+/** Assert that an unknown value is a dictionary object */
+export function assertDictionary(value) {
+    if (!isDictionary(value))
+        throw new AssertionError(`Must be dictionary`, value);
+}
+/** Is an unknown value the key for an own prop of an dictionary. */
+export const isDictionaryKey = (obj, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(obj, key);
+/** turn a possible dictionary into an dictionary. */
+export function getDictionary(obj) {
+    return isIterable(obj) ? Object.fromEntries(obj) : obj;
+}
+export function getDictionaryItems(obj) {
+    return isIterable(obj) ? obj : Object.entries(obj);
+}
+/** Set a prop on a dictionary object (immutably) and return a new object including that prop. */
+export const withDictionaryItem = withProp;
+/** Set several props on a dictionary object (immutably) and return a new object including those props. */
+export const withDictionaryItems = withProps;
+/** Remove several key/value entries from a dictionary object (immutably) and return a new object without those props. */
+export const withoutDictionaryItems = 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. */
+export const setDictionaryEntry = setProp;
+/** Set several named props on a dictionary object (by reference). */
+export const setDictionaryEntries = setProps;
+/** Remove several key/value entries from a dictionary object (by reference). */
+export const deleteDictionaryEntries = deleteProps;