shelving 1.236.0 → 1.236.2

package/util/dictionary.d.ts

@@ -1,56 +1,237 @@
 import type { AnyCaller } from "./function.js";
-/** Readonly dictionary object. */
+/**
+ * Readonly dictionary object.
+ * - A dictionary is a plain object whose keys are arbitrary strings, all sharing the same value type.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/ImmutableDictionary
+ */
 export type ImmutableDictionary<T = unknown> = {
     readonly [K in string]: T;
 };
-/** Writable dictionary object. */
+/**
+ * Writable dictionary object.
+ * - A dictionary is a plain object whose keys are arbitrary strings, all sharing the same value type.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/MutableDictionary
+ */
 export type MutableDictionary<T = unknown> = {
     [K in string]: T;
 };
-/** Single item for a dictionary object in entry format. */
+/**
+ * Single item for a dictionary object in entry format.
+ * - A readonly key/value entry tuple.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/DictionaryItem
+ */
 export type DictionaryItem<T> = readonly [string, T];
-/** Get the type of the _values_ of the items of a dictionary object. */
+/**
+ * Get the type of the _values_ of the items of a dictionary object.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/DictionaryValue
+ */
 export type DictionaryValue<T extends ImmutableDictionary> = T[string];
-/** Value that can be converted to a dictionary object. */
+/**
+ * Value that can be converted to a dictionary object.
+ * - Either the dictionary itself, or an iterable set of key/value entry tuples.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/PossibleDictionary
+ */
 export type PossibleDictionary<T> = ImmutableDictionary<T> | Iterable<DictionaryItem<T>>;
-/** Is an unknown value a dictionary object? */
+/**
+ * Is an unknown value a dictionary object?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a dictionary (plain) object, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/isDictionary
+ */
 export declare function isDictionary(value: unknown): value is ImmutableDictionary;
-/** Assert that an unknown value is a dictionary object */
+/**
+ * Assert that an unknown value is a dictionary object.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertDictionary` itself).
+ * @throws {ValueError} If `value` is not a dictionary object.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/assertDictionary
+ */
 export declare function assertDictionary(value: unknown, caller?: AnyCaller): asserts value is ImmutableDictionary;
-/** Convert a possible dictionary into a dictionary. */
+/**
+ * Convert a possible dictionary into a dictionary.
+ * - If the value is iterable it is converted to a dictionary using `Object.fromEntries()`, otherwise it is returned as-is.
+ *
+ * @param dict The dictionary or iterable set of key/value entry tuples to convert.
+ * @returns The corresponding dictionary object.
+ * @example
+ * requireDictionary([["a", 1], ["b", 2]]); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/requireDictionary
+ */
 export declare function requireDictionary<T>(dict: PossibleDictionary<T>): ImmutableDictionary<T>;
-/** Turn a dictionary object into a set of props. */
+/**
+ * Turn a dictionary object into a set of props.
+ *
+ * @param input The dictionary or iterable set of key/value entry tuples to read.
+ * @returns Iterable set of key/value entry tuples for the dictionary.
+ * @example
+ * getDictionaryItems({ a: 1, b: 2 }); // [["a", 1], ["b", 2]]
+ * @see https://dhoulb.github.io/shelving/util/dictionary/getDictionaryItems
+ */
 export declare function getDictionaryItems<T>(input: ImmutableDictionary<T>): readonly DictionaryItem<T>[];
 export declare function getDictionaryItems<T>(input: PossibleDictionary<T>): Iterable<DictionaryItem<T>>;
-/** Is an unknown value the key for an own prop of a dictionary. */
+/**
+ * Is an unknown value the key for an own prop of a dictionary.
+ *
+ * @param dict The dictionary to test against.
+ * @param key The key to test for.
+ * @returns `true` if `key` is a string and an own prop of `dict`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/isDictionaryItem
+ */
 export declare function isDictionaryItem<T>(dict: ImmutableDictionary<T>, key: unknown): key is string;
-/** Assert that an unknown value is the key for an own prop of a dictionary. */
+/**
+ * Assert that an unknown value is the key for an own prop of a dictionary.
+ *
+ * @param dict The dictionary to assert against.
+ * @param key The key to assert is an own prop.
+ * @param caller Function to attribute a thrown error to (defaults to `assertDictionaryItem` itself).
+ * @throws {RequiredError} If `key` is not an own prop of `dict`.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/assertDictionaryItem
+ */
 export declare function assertDictionaryItem<T>(dict: ImmutableDictionary<T>, key: string, caller?: AnyCaller): asserts key is string;
-/** Get an item in a map or throw `RequiredError` if it doesn't exist. */
+/**
+ * Get an item in a dictionary object, or throw `RequiredError` if it doesn't exist.
+ *
+ * @param dict The dictionary to read the item from.
+ * @param key The key of the item to read.
+ * @param caller Function to attribute a thrown error to (defaults to `requireDictionaryItem` itself).
+ * @returns The value of the item.
+ * @throws {RequiredError} If `key` is not an own prop of `dict`.
+ * @example
+ * requireDictionaryItem({ a: 1 }, "a"); // 1
+ * @see https://dhoulb.github.io/shelving/util/dictionary/requireDictionaryItem
+ */
 export declare function requireDictionaryItem<T>(dict: ImmutableDictionary<T>, key: string, caller?: AnyCaller): T;
-/** Get an item in a map or `undefined` if it doesn't exist. */
+/**
+ * Get an item in a dictionary object, or `undefined` if it doesn't exist.
+ *
+ * @param dict The dictionary to read the item from.
+ * @param key The key of the item to read.
+ * @returns The value of the item, or `undefined` if `key` is not an own prop of `dict`.
+ * @example
+ * getDictionaryItem({ a: 1 }, "a"); // 1
+ * @see https://dhoulb.github.io/shelving/util/dictionary/getDictionaryItem
+ */
 export declare function getDictionaryItem<T>(dict: ImmutableDictionary<T>, key: string): T | undefined;
-/** Set a prop on a dictionary object (immutably) and return a new object including that prop. */
+/**
+ * Set an item on a dictionary object (immutably) and return a new object including that item.
+ * - If the value is unchanged the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to set the item on.
+ * @param key The key of the item to set.
+ * @param value The value of the item to set.
+ * @returns A new dictionary including the set item, or the original dictionary if the value was unchanged.
+ * @example
+ * withDictionaryItem({ a: 1 }, "b", 2); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/withDictionaryItem
+ */
 export declare const withDictionaryItem: <T>(dict: ImmutableDictionary<T>, key: string, value: T) => ImmutableDictionary<T>;
-/** Set several props on a dictionary object (immutably) and return a new object including those props. */
+/**
+ * Set several items on a dictionary object (immutably) and return a new object including those items.
+ * - If all values are unchanged the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to set the items on.
+ * @param props The items to set, as a dictionary or iterable set of key/value entry tuples.
+ * @returns A new dictionary including the set items, or the original dictionary if all values were unchanged.
+ * @example
+ * withDictionaryItems({ a: 1 }, { b: 2, c: 3 }); // { a: 1, b: 2, c: 3 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/withDictionaryItems
+ */
 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. */
+/**
+ * Remove several items from a dictionary object (immutably) and return a new object without those items.
+ * - If none of the keys exist the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to remove the items from.
+ * @param keys The keys of the items to remove.
+ * @returns A new dictionary without the removed items, or the original dictionary if no keys were present.
+ * @example
+ * omitDictionaryItems({ a: 1, b: 2, c: 3 }, "b", "c"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/omitDictionaryItems
+ */
 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. */
+/**
+ * Remove an item from a dictionary object (immutably) and return a new object without that item.
+ * - If the key doesn't exist the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to remove the item from.
+ * @param key The key of the item to remove.
+ * @returns A new dictionary without the removed item, or the original dictionary if the key was not present.
+ * @example
+ * omitDictionaryItem({ a: 1, b: 2 }, "b"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/omitDictionaryItem
+ */
 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. */
+/**
+ * Pick several items from a dictionary object and return a new object with only those items.
+ *
+ * @param dict The dictionary to pick the items from.
+ * @param keys The keys of the items to pick.
+ * @returns A new dictionary containing only the picked items.
+ * @example
+ * pickDictionaryItems({ a: 1, b: 2, c: 3 }, "a", "b"); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/pickDictionaryItems
+ */
 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. */
+/**
+ * Set a single named item on a dictionary object (by reference) and return its value.
+ *
+ * @param dict The dictionary to set the item on (modified by reference).
+ * @param key The key of the item to set.
+ * @param value The value of the item to set.
+ * @returns The value that was set.
+ * @example
+ * setDictionaryItem(dict, "a", 1); // 1
+ * @see https://dhoulb.github.io/shelving/util/dictionary/setDictionaryItem
+ */
 export declare const setDictionaryItem: <T>(dict: MutableDictionary<T>, key: string, value: T) => T;
-/** Set several named props on a dictionary object (by reference). */
+/**
+ * Set several named items on a dictionary object (by reference).
+ *
+ * @param dict The dictionary to set the items on (modified by reference).
+ * @param entries The items to set, as a dictionary or iterable set of key/value entry tuples.
+ * @example
+ * setDictionaryItems(dict, { a: 1, b: 2 });
+ * @see https://dhoulb.github.io/shelving/util/dictionary/setDictionaryItems
+ */
 export declare const setDictionaryItems: <T>(dict: MutableDictionary<T>, entries: PossibleDictionary<T>) => void;
-/** Remove several key/value entries from a dictionary object (by reference). */
+/**
+ * Remove several key/value entries from a dictionary object (by reference).
+ *
+ * @param dict The dictionary to remove the items from (modified by reference).
+ * @param keys The keys of the items to remove.
+ * @example
+ * deleteDictionaryItems(dict, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/dictionary/deleteDictionaryItems
+ */
 export declare const deleteDictionaryItems: <T extends MutableDictionary>(dict: T, ...keys: string[]) => void;
-/** Remove a key/value entry from a dictionary object (by reference). */
+/**
+ * Remove a key/value entry from a dictionary object (by reference).
+ *
+ * @param dict The dictionary to remove the item from (modified by reference).
+ * @param key The key of the item to remove.
+ * @example
+ * deleteDictionaryItem(dict, "a");
+ * @see https://dhoulb.github.io/shelving/util/dictionary/deleteDictionaryItem
+ */
 export declare const deleteDictionaryItem: <T extends MutableDictionary>(dict: T, key: string) => void;
-/** Type that represents an empty dictionary object. */
+/**
+ * Type that represents an empty dictionary object.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/EmptyDictionary
+ */
 export type EmptyDictionary = {
     readonly [K in never]: never;
 };
-/** An empty dictionary object. */
+/**
+ * An empty dictionary object.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/EMPTY_DICTIONARY
+ */
 export declare const EMPTY_DICTIONARY: EmptyDictionary;

package/util/dictionary.js

@@ -2,57 +2,202 @@ import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.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? */
+/**
+ * Is an unknown value a dictionary object?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a dictionary (plain) object, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/isDictionary
+ */
 export function isDictionary(value) {
     return isPlainObject(value);
 }
-/** Assert that an unknown value is a dictionary object */
+/**
+ * Assert that an unknown value is a dictionary object.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertDictionary` itself).
+ * @throws {ValueError} If `value` is not a dictionary object.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/assertDictionary
+ */
 export function assertDictionary(value, caller = assertDictionary) {
     if (!isDictionary(value))
         throw new ValueError("Must be dictionary object", { received: value, caller });
 }
-/** Convert a possible dictionary into a dictionary. */
+/**
+ * Convert a possible dictionary into a dictionary.
+ * - If the value is iterable it is converted to a dictionary using `Object.fromEntries()`, otherwise it is returned as-is.
+ *
+ * @param dict The dictionary or iterable set of key/value entry tuples to convert.
+ * @returns The corresponding dictionary object.
+ * @example
+ * requireDictionary([["a", 1], ["b", 2]]); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/requireDictionary
+ */
 export function requireDictionary(dict) {
     return isDictionary(dict) ? dict : Object.fromEntries(dict);
 }
 export function getDictionaryItems(input) {
     return isIterable(input) ? input : Object.entries(input);
 }
-/** Is an unknown value the key for an own prop of a dictionary. */
+/**
+ * Is an unknown value the key for an own prop of a dictionary.
+ *
+ * @param dict The dictionary to test against.
+ * @param key The key to test for.
+ * @returns `true` if `key` is a string and an own prop of `dict`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/isDictionaryItem
+ */
 export function isDictionaryItem(dict, key) {
     return typeof key === "string" && Object.hasOwn(dict, key);
 }
-/** Assert that an unknown value is the key for an own prop of a dictionary. */
+/**
+ * Assert that an unknown value is the key for an own prop of a dictionary.
+ *
+ * @param dict The dictionary to assert against.
+ * @param key The key to assert is an own prop.
+ * @param caller Function to attribute a thrown error to (defaults to `assertDictionaryItem` itself).
+ * @throws {RequiredError} If `key` is not an own prop of `dict`.
+ * @see https://dhoulb.github.io/shelving/util/dictionary/assertDictionaryItem
+ */
 export function assertDictionaryItem(dict, key, caller = assertDictionaryItem) {
     if (!isDictionaryItem(dict, key))
         throw new RequiredError("Key must exist in dictionary object", { key, dict, caller });
 }
-/** Get an item in a map or throw `RequiredError` if it doesn't exist. */
+/**
+ * Get an item in a dictionary object, or throw `RequiredError` if it doesn't exist.
+ *
+ * @param dict The dictionary to read the item from.
+ * @param key The key of the item to read.
+ * @param caller Function to attribute a thrown error to (defaults to `requireDictionaryItem` itself).
+ * @returns The value of the item.
+ * @throws {RequiredError} If `key` is not an own prop of `dict`.
+ * @example
+ * requireDictionaryItem({ a: 1 }, "a"); // 1
+ * @see https://dhoulb.github.io/shelving/util/dictionary/requireDictionaryItem
+ */
 export function requireDictionaryItem(dict, key, caller = requireDictionaryItem) {
     assertDictionaryItem(dict, key, caller);
     return dict[key];
 }
-/** Get an item in a map or `undefined` if it doesn't exist. */
+/**
+ * Get an item in a dictionary object, or `undefined` if it doesn't exist.
+ *
+ * @param dict The dictionary to read the item from.
+ * @param key The key of the item to read.
+ * @returns The value of the item, or `undefined` if `key` is not an own prop of `dict`.
+ * @example
+ * getDictionaryItem({ a: 1 }, "a"); // 1
+ * @see https://dhoulb.github.io/shelving/util/dictionary/getDictionaryItem
+ */
 export function getDictionaryItem(dict, key) {
     return dict[key];
 }
-/** Set a prop on a dictionary object (immutably) and return a new object including that prop. */
+/**
+ * Set an item on a dictionary object (immutably) and return a new object including that item.
+ * - If the value is unchanged the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to set the item on.
+ * @param key The key of the item to set.
+ * @param value The value of the item to set.
+ * @returns A new dictionary including the set item, or the original dictionary if the value was unchanged.
+ * @example
+ * withDictionaryItem({ a: 1 }, "b", 2); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/withDictionaryItem
+ */
 export const withDictionaryItem = withProp;
-/** Set several props on a dictionary object (immutably) and return a new object including those props. */
+/**
+ * Set several items on a dictionary object (immutably) and return a new object including those items.
+ * - If all values are unchanged the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to set the items on.
+ * @param props The items to set, as a dictionary or iterable set of key/value entry tuples.
+ * @returns A new dictionary including the set items, or the original dictionary if all values were unchanged.
+ * @example
+ * withDictionaryItems({ a: 1 }, { b: 2, c: 3 }); // { a: 1, b: 2, c: 3 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/withDictionaryItems
+ */
 export const withDictionaryItems = withProps;
-/** Remove several key/value entries from a dictionary object (immutably) and return a new object without those props. */
+/**
+ * Remove several items from a dictionary object (immutably) and return a new object without those items.
+ * - If none of the keys exist the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to remove the items from.
+ * @param keys The keys of the items to remove.
+ * @returns A new dictionary without the removed items, or the original dictionary if no keys were present.
+ * @example
+ * omitDictionaryItems({ a: 1, b: 2, c: 3 }, "b", "c"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/omitDictionaryItems
+ */
 export const omitDictionaryItems = omitProps;
-/** Remove a key/value entry from a dictionary object (immutably) and return a new object without that prop. */
+/**
+ * Remove an item from a dictionary object (immutably) and return a new object without that item.
+ * - If the key doesn't exist the original dictionary is returned unchanged.
+ *
+ * @param dict The dictionary to remove the item from.
+ * @param key The key of the item to remove.
+ * @returns A new dictionary without the removed item, or the original dictionary if the key was not present.
+ * @example
+ * omitDictionaryItem({ a: 1, b: 2 }, "b"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/omitDictionaryItem
+ */
 export const omitDictionaryItem = omitProps;
-/** Pick several props from a dictionary object and return a new object with only thos props. */
+/**
+ * Pick several items from a dictionary object and return a new object with only those items.
+ *
+ * @param dict The dictionary to pick the items from.
+ * @param keys The keys of the items to pick.
+ * @returns A new dictionary containing only the picked items.
+ * @example
+ * pickDictionaryItems({ a: 1, b: 2, c: 3 }, "a", "b"); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/dictionary/pickDictionaryItems
+ */
 export const pickDictionaryItems = pickProps;
-/** Set a single named prop on a dictionary object (by reference) and return its value. */
+/**
+ * Set a single named item on a dictionary object (by reference) and return its value.
+ *
+ * @param dict The dictionary to set the item on (modified by reference).
+ * @param key The key of the item to set.
+ * @param value The value of the item to set.
+ * @returns The value that was set.
+ * @example
+ * setDictionaryItem(dict, "a", 1); // 1
+ * @see https://dhoulb.github.io/shelving/util/dictionary/setDictionaryItem
+ */
 export const setDictionaryItem = setProp;
-/** Set several named props on a dictionary object (by reference). */
+/**
+ * Set several named items on a dictionary object (by reference).
+ *
+ * @param dict The dictionary to set the items on (modified by reference).
+ * @param entries The items to set, as a dictionary or iterable set of key/value entry tuples.
+ * @example
+ * setDictionaryItems(dict, { a: 1, b: 2 });
+ * @see https://dhoulb.github.io/shelving/util/dictionary/setDictionaryItems
+ */
 export const setDictionaryItems = setProps;
-/** Remove several key/value entries from a dictionary object (by reference). */
+/**
+ * Remove several key/value entries from a dictionary object (by reference).
+ *
+ * @param dict The dictionary to remove the items from (modified by reference).
+ * @param keys The keys of the items to remove.
+ * @example
+ * deleteDictionaryItems(dict, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/dictionary/deleteDictionaryItems
+ */
 export const deleteDictionaryItems = deleteProps;
-/** Remove a key/value entry from a dictionary object (by reference). */
+/**
+ * Remove a key/value entry from a dictionary object (by reference).
+ *
+ * @param dict The dictionary to remove the item from (modified by reference).
+ * @param key The key of the item to remove.
+ * @example
+ * deleteDictionaryItem(dict, "a");
+ * @see https://dhoulb.github.io/shelving/util/dictionary/deleteDictionaryItem
+ */
 export const deleteDictionaryItem = deleteProps;
-/** An empty dictionary object. */
+/**
+ * An empty dictionary object.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dictionary/EMPTY_DICTIONARY
+ */
 export const EMPTY_DICTIONARY = { __proto__: null };

package/util/diff.d.ts

@@ -1,6 +1,11 @@
 import type { ImmutableArray } from "./array.js";
 import type { DeepPartial, ImmutableObject } from "./object.js";
-/** The `SAME` symbol indicates sameness. */
+/**
+ * The `SAME` symbol indicates sameness.
+ * - Returned by the diff functions when two values are deeply equal and no transformation is needed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/diff/SAME
+ */
 export declare const SAME: unique symbol;
 /**
  * Deeply diff two unknown values to produce the transformation needed to transform `left` into `right`, or the `SAME` constant if they are deeply equal.
@@ -8,11 +13,15 @@ export declare const SAME: unique symbol;
  * @param left The old value.
  * @param right The new/target value.
  *
- * @return The transformation needed to transform `left` into `right`
+ * @returns The transformation needed to transform `left` into `right`
  * - If the two values are deeply equal the `SAME` constant is returned.
  * - Unequal scalar values can't be diffed, so `right` is always returned.
  * - If `right` is an array, returns whatever `deepDiffArray()` returns.
  * - If `right` is an object, returns whatever `deepDiffObject()` returns.
+ *
+ * @example deepDiff({ a: 1 }, { a: 1 }) // SAME
+ * @example deepDiff({ a: 1 }, { a: 2 }) // { a: 2 }
+ * @see https://dhoulb.github.io/shelving/util/diff/deepDiff
  */
 export declare function deepDiff<R extends ImmutableObject>(left: unknown, right: R): R | DeepPartial<R> | typeof SAME;
 export declare function deepDiff<R>(left: unknown, right: R): R | typeof SAME;
@@ -20,8 +29,13 @@ export declare function deepDiff<R>(left: unknown, right: R): R | typeof SAME;
  * Diff two arrays to produce the transformation needed to transform `left` into `right`
  * DH: Currently arrays don't diff at an item level, they return the entire new array if not deeply equal.
  *
+ * @param left The old array.
+ * @param right The new/target array.
  * @returns The `right` array if it is different to `left`, or the exact `SAME` constant otherwise.
  * - If the two values are deeply equal the `SAME` constant is returned.
+ * @example deepDiffArray([1, 2], [1, 2]) // SAME
+ * @example deepDiffArray([1, 2], [1, 3]) // [1, 3]
+ * @see https://dhoulb.github.io/shelving/util/diff/deepDiffArray
  */
 export declare function deepDiffArray<R extends ImmutableArray>(left: ImmutableArray, right: R): R | typeof SAME;
 /**
@@ -30,8 +44,13 @@ export declare function deepDiffArray<R extends ImmutableArray>(left: ImmutableA
  * - Includes a constructor check — if `left` and `right` have different constructors they will not be merged and `right` will be returned (ensures arrays aren't compared with objects).
  * - Properties that exist in `left` but not `right` (i.e. have been deleted) are represented with `undefined`
  *
- * @return Object containing the missing/updated properties that `left` needs to become `right`.
+ * @param left The old object.
+ * @param right The new/target object.
+ * @returns Object containing the missing/updated properties that `left` needs to become `right`.
  * - If the two values are deeply equal the `SAME` constant is returned.
  * - If `left` isn't an object then the result can't be diffed so entire `right` is returned.
+ * @example deepDiffObject({ a: 1 }, { a: 1 }) // SAME
+ * @example deepDiffObject({ a: 1, b: 2 }, { a: 1 }) // { b: undefined }
+ * @see https://dhoulb.github.io/shelving/util/diff/deepDiffObject
  */
 export declare function deepDiffObject<R extends ImmutableObject>(left: ImmutableObject, right: R): R | DeepPartial<R> | typeof SAME;

package/util/diff.js

@@ -1,7 +1,12 @@
 import { isArray } from "./array.js";
 import { isArrayEqual, isDeepEqual } from "./equal.js";
 import { isObject } from "./object.js";
-/** The `SAME` symbol indicates sameness. */
+/**
+ * The `SAME` symbol indicates sameness.
+ * - Returned by the diff functions when two values are deeply equal and no transformation is needed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/diff/SAME
+ */
 export const SAME = Symbol("shelving/SAME");
 export function deepDiff(left, right) {
     if (left === right)
@@ -16,8 +21,13 @@ export function deepDiff(left, right) {
  * Diff two arrays to produce the transformation needed to transform `left` into `right`
  * DH: Currently arrays don't diff at an item level, they return the entire new array if not deeply equal.
  *
+ * @param left The old array.
+ * @param right The new/target array.
  * @returns The `right` array if it is different to `left`, or the exact `SAME` constant otherwise.
  * - If the two values are deeply equal the `SAME` constant is returned.
+ * @example deepDiffArray([1, 2], [1, 2]) // SAME
+ * @example deepDiffArray([1, 2], [1, 3]) // [1, 3]
+ * @see https://dhoulb.github.io/shelving/util/diff/deepDiffArray
  */
 export function deepDiffArray(left, right) {
     if (left === right)