shelving 1.236.0 → 1.236.2

package/util/entity.d.ts

@@ -1,17 +1,50 @@
 import type { AnyCaller } from "./function.js";
 import type { Nullish } from "./null.js";
-/** Entity strings combine a type and ID, e.g. `challenge:a1b2c3` */
+/**
+ * Entity string combining a type and ID, e.g. `challenge:a1b2c3`
+ *
+ * @see https://dhoulb.github.io/shelving/util/entity/Entity
+ */
 export type Entity<T extends string = string> = `${T}:${string}`;
-/** Extract the type from an `Entity` string. */
+/**
+ * Extract the type portion from an `Entity` string.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entity/EntityType
+ */
 export type EntityType<E extends Entity> = E extends Entity<infer T> ? T : never;
-/** Empty entity has undefined type and ID. */
+/**
+ * Tuple representing an empty (invalid) entity, with `undefined` type and ID.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entity/EmptyEntity
+ */
 export type EmptyEntity = [type: undefined, id: undefined];
-/** Empty entity. */
+/**
+ * Shared `EmptyEntity` constant returned when an entity string is invalid.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entity/EMPTY_ENTITY
+ */
 export declare const EMPTY_ENTITY: EmptyEntity;
-/** Split an optional entity tag like `challenge:a1b2c3` into `["challenge", "a1b2c3"]`, or return `EmptyEntity` if the entity was invalid. */
+/**
+ * Split an optional entity tag like `challenge:a1b2c3` into its `type` and `id`, or return `EmptyEntity` if the entity was invalid.
+ *
+ * @param entity The entity string to split, or a nullish value.
+ * @returns A `[type, id]` tuple, or `EMPTY_ENTITY` if the entity was missing or invalid.
+ * @example getEntity("challenge:a1b2c3") // ["challenge", "a1b2c3"]
+ * @example getEntity(undefined) // [undefined, undefined]
+ * @see https://dhoulb.github.io/shelving/util/entity/getEntity
+ */
 export declare function getEntity<T extends string>(entity: Entity<T>): [type: T, id: string];
 export declare function getEntity<T extends string>(entity: Nullish<Entity<T>>): [type: T, id: string] | EmptyEntity;
 export declare function getEntity(entity: Nullish<string>): [type: string, id: string] | EmptyEntity;
-/** Split an entity tag like `challenge:a1b2c3` into `type` and `id`, or throw `RequiredError` if the entity tag was invalid. */
+/**
+ * Split an entity tag like `challenge:a1b2c3` into its `type` and `id`, or throw `RequiredError` if the entity tag was invalid.
+ *
+ * @param entity The entity string to split.
+ * @param caller Function to attribute a thrown error to (defaults to `requireEntity`).
+ * @returns A `[type, id]` tuple.
+ * @throws {RequiredError} If the entity string is missing or invalid.
+ * @example requireEntity("challenge:a1b2c3") // ["challenge", "a1b2c3"]
+ * @see https://dhoulb.github.io/shelving/util/entity/requireEntity
+ */
 export declare function requireEntity<T extends string>(entity: Entity<T>, caller?: AnyCaller): [type: T, id: string];
 export declare function requireEntity(entity: string, caller?: AnyCaller): [type: string, id: string];

package/util/entity.js

@@ -1,5 +1,9 @@
 import { RequiredError } from "../error/RequiredError.js";
-/** Empty entity. */
+/**
+ * Shared `EmptyEntity` constant returned when an entity string is invalid.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entity/EMPTY_ENTITY
+ */
 export const EMPTY_ENTITY = [undefined, undefined];
 export function getEntity(entity) {
     if (entity) {

package/util/entry.d.ts

@@ -2,31 +2,78 @@ import type { ImmutableArray } from "./array.js";
 import type { ImmutableObject } from "./object.js";
 import type { ImmutableSet } from "./set.js";
 /**
- * Single entry from a map-like object.
+ * Single key/value entry from a map-like object.
  * - Consistency with `UnknownObject`
  * - Always readonly.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entry/Entry
  */
 export type Entry<K = unknown, T = unknown> = readonly [K, T];
-/** Helper type to extract the type for the value of an entry. */
+/**
+ * Extract the key type from an `Entry`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entry/EntryKey
+ */
 export type EntryKey<X> = X extends Entry<infer Y, unknown> ? Y : never;
-/** Helper type to extract the type for the value of an entry. */
+/**
+ * Extract the value type from an `Entry`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/entry/EntryValue
+ */
 export type EntryValue<X> = X extends Entry<unknown, infer Y> ? Y : never;
 /**
- * Helper type to turn an entry back into an object with one property.
+ * Turn an `Entry` type back into an object with a single property.
  * i.e. `EntryObject<Entry<"a", string>>` produces `{ a: string }`
+ *
+ * @see https://dhoulb.github.io/shelving/util/entry/EntryObject
  */
 export type EntryObject<T extends Entry<PropertyKey, unknown>> = {
     readonly [E in T as E[0]]: E[1];
 };
-/** Extract the key from an object entry. */
+/**
+ * Extract the key from an object entry.
+ *
+ * @param entry The `[key, value]` entry to read from.
+ * @returns The key (first element) of the entry.
+ * @example getEntryKey(["a", 1]) // "a"
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryKey
+ */
 export declare function getEntryKey<K, T>([k]: Entry<K, T>): K;
-/** Extract the value from an object entry. */
+/**
+ * Extract the value from an object entry.
+ *
+ * @param entry The `[key, value]` entry to read from.
+ * @returns The value (second element) of the entry.
+ * @example getEntryValue(["a", 1]) // 1
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryValue
+ */
 export declare function getEntryValue<K, T>([, v]: Entry<K, T>): T;
-/** Yield the keys of an iterable set of entries. */
+/**
+ * Yield the keys of an iterable set of entries.
+ *
+ * @param input Iterable of `[key, value]` entries.
+ * @returns Iterable yielding each entry's key.
+ * @example Array.from(getEntryKeys([["a", 1], ["b", 2]])) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryKeys
+ */
 export declare function getEntryKeys<K, T>(input: Iterable<Entry<K, T>>): Iterable<K>;
-/** Yield the values of an iterable set of entries. */
+/**
+ * Yield the values of an iterable set of entries.
+ *
+ * @param input Iterable of `[key, value]` entries.
+ * @returns Iterable yielding each entry's value.
+ * @example Array.from(getEntryValues([["a", 1], ["b", 2]])) // [1, 2]
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryValues
+ */
 export declare function getEntryValues<K, T>(input: Iterable<Entry<K, T>>): Iterable<T>;
-/** Yield the entries in something that can yield entries. */
+/**
+ * Yield the entries from one or more entry-yielding sources (sets, objects, maps, arrays, or iterables of entries).
+ *
+ * @param input One or more sources that can yield `[key, value]` entries.
+ * @returns Iterable yielding the combined entries from every input.
+ * @example Array.from(getEntries({ a: 1, b: 2 })) // [["a", 1], ["b", 2]]
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntries
+ */
 export declare function getEntries<K extends string, T = K>(...input: (ImmutableSet<K & T> | Partial<ImmutableObject<K, T>> | Iterable<Entry<K, T>>)[]): Iterable<Entry<K, T>>;
 export declare function getEntries<K extends number, T = K>(...input: (ImmutableArray<T> | ImmutableSet<K & T> | Iterable<Entry<K, T>>)[]): Iterable<Entry<K, T>>;
 export declare function getEntries<K, T = K>(...input: (ImmutableSet<K & T> | Iterable<Entry<K, T>>)[]): Iterable<Entry<K, T>>;

package/util/entry.js

@@ -1,20 +1,48 @@
 import { isArray } from "./array.js";
 import { isIterable } from "./iterate.js";
 import { isSet } from "./set.js";
-/** Extract the key from an object entry. */
+/**
+ * Extract the key from an object entry.
+ *
+ * @param entry The `[key, value]` entry to read from.
+ * @returns The key (first element) of the entry.
+ * @example getEntryKey(["a", 1]) // "a"
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryKey
+ */
 export function getEntryKey([k]) {
     return k;
 }
-/** Extract the value from an object entry. */
+/**
+ * Extract the value from an object entry.
+ *
+ * @param entry The `[key, value]` entry to read from.
+ * @returns The value (second element) of the entry.
+ * @example getEntryValue(["a", 1]) // 1
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryValue
+ */
 export function getEntryValue([, v]) {
     return v;
 }
-/** Yield the keys of an iterable set of entries. */
+/**
+ * Yield the keys of an iterable set of entries.
+ *
+ * @param input Iterable of `[key, value]` entries.
+ * @returns Iterable yielding each entry's key.
+ * @example Array.from(getEntryKeys([["a", 1], ["b", 2]])) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryKeys
+ */
 export function* getEntryKeys(input) {
     for (const [k] of input)
         yield k;
 }
-/** Yield the values of an iterable set of entries. */
+/**
+ * Yield the values of an iterable set of entries.
+ *
+ * @param input Iterable of `[key, value]` entries.
+ * @returns Iterable yielding each entry's value.
+ * @example Array.from(getEntryValues([["a", 1], ["b", 2]])) // [1, 2]
+ * @see https://dhoulb.github.io/shelving/util/entry/getEntryValues
+ */
 export function* getEntryValues(input) {
     for (const [, v] of input)
         yield v;

package/util/env.d.ts

@@ -1,21 +1,43 @@
 import type { AnyCaller } from "./function.js";
 /**
  * Get a `process.env` variable safely in all environments, or `undefined` if it doesn't exist or this environment does not support `process.env` (i.e. web environments).
+ *
+ * @param name Name of the environment variable to read.
+ * @returns The variable's string value, or `undefined` if missing or unsupported.
+ * @example getEnv("NODE_ENV") // "production"
+ * @see https://dhoulb.github.io/shelving/util/env/getEnv
  */
 export declare function getEnv(name: string): string | undefined;
 /**
  * Get a `process.env` variable safely in all environments, or throw `RequiredError` if it doesn't exist or this environment does not support `process.env` (i.e. web environments).
+ *
+ * @param name Name of the environment variable to read.
+ * @param caller Function to attribute a thrown error to (defaults to `requireEnv`).
+ * @returns The variable's string value.
+ * @throws `RequiredError` if the variable is missing or `process.env` is unsupported.
+ * @example requireEnv("DATABASE_URL") // "postgres://..."
+ * @see https://dhoulb.github.io/shelving/util/env/requireEnv
  */
 export declare function requireEnv(name: string, caller?: AnyCaller): string;
 /**
- * Get a `process.env` variable and resolve it to to `true` or `false`, or `undefined` if it isn't a true/false value.
+ * Get a `process.env` variable and resolve it to `true` or `false`, or `undefined` if it isn't a true/false value.
+ * - Truthy values: `1`, `on`, `yes`, `true` (case-insensitive).
+ * - Falsy values: `0`, `off`, `no`, `false` (case-insensitive).
+ *
+ * @param name Name of the environment variable to read.
+ * @returns `true` or `false` if the value is recognised, otherwise `undefined`.
+ * @example getEnvBoolean("FEATURE_FLAG") // true
+ * @see https://dhoulb.github.io/shelving/util/env/getEnvBoolean
  */
 export declare function getEnvBoolean(name: string): boolean | undefined;
 /**
- * Get a `process.env` variable and resolve it to to `true` or `false`
+ * Get a `process.env` variable and resolve it to `true` or `false`, or throw `RequiredError` if it isn't a true/false value.
  *
- * @returns `false` if the environment variable is `0`, `off`, `no`, `false`
- * @returns `true` if the environment variable is `1`, `on`, `yes`, `true`
+ * @param name Name of the environment variable to read.
+ * @param caller Function to attribute a thrown error to (defaults to `requireEnvBoolean`).
+ * @returns `false` if the environment variable is `0`, `off`, `no`, `false`; `true` if it is `1`, `on`, `yes`, `true`.
  * @throws `RequiredError` if the env variable is any other value.
+ * @example requireEnvBoolean("FEATURE_FLAG") // true
+ * @see https://dhoulb.github.io/shelving/util/env/requireEnvBoolean
  */
 export declare function requireEnvBoolean(name: string, caller?: AnyCaller): boolean;

package/util/env.js

@@ -1,6 +1,11 @@
 import { RequiredError } from "../error/RequiredError.js";
 /**
  * Get a `process.env` variable safely in all environments, or `undefined` if it doesn't exist or this environment does not support `process.env` (i.e. web environments).
+ *
+ * @param name Name of the environment variable to read.
+ * @returns The variable's string value, or `undefined` if missing or unsupported.
+ * @example getEnv("NODE_ENV") // "production"
+ * @see https://dhoulb.github.io/shelving/util/env/getEnv
  */
 export function getEnv(name) {
     if (typeof process === "object" && typeof process.env === "object")
@@ -8,6 +13,13 @@ export function getEnv(name) {
 }
 /**
  * Get a `process.env` variable safely in all environments, or throw `RequiredError` if it doesn't exist or this environment does not support `process.env` (i.e. web environments).
+ *
+ * @param name Name of the environment variable to read.
+ * @param caller Function to attribute a thrown error to (defaults to `requireEnv`).
+ * @returns The variable's string value.
+ * @throws `RequiredError` if the variable is missing or `process.env` is unsupported.
+ * @example requireEnv("DATABASE_URL") // "postgres://..."
+ * @see https://dhoulb.github.io/shelving/util/env/requireEnv
  */
 export function requireEnv(name, caller = requireEnv) {
     const env = getEnv(name);
@@ -16,7 +28,14 @@ export function requireEnv(name, caller = requireEnv) {
     return env;
 }
 /**
- * Get a `process.env` variable and resolve it to to `true` or `false`, or `undefined` if it isn't a true/false value.
+ * Get a `process.env` variable and resolve it to `true` or `false`, or `undefined` if it isn't a true/false value.
+ * - Truthy values: `1`, `on`, `yes`, `true` (case-insensitive).
+ * - Falsy values: `0`, `off`, `no`, `false` (case-insensitive).
+ *
+ * @param name Name of the environment variable to read.
+ * @returns `true` or `false` if the value is recognised, otherwise `undefined`.
+ * @example getEnvBoolean("FEATURE_FLAG") // true
+ * @see https://dhoulb.github.io/shelving/util/env/getEnvBoolean
  */
 export function getEnvBoolean(name) {
     const env = getEnv(name)?.toLowerCase();
@@ -28,11 +47,14 @@ export function getEnvBoolean(name) {
 const _TRUES = [`1`, `on`, `yes`, `true`];
 const _FALSES = [`0`, `off`, `no`, `false`];
 /**
- * Get a `process.env` variable and resolve it to to `true` or `false`
+ * Get a `process.env` variable and resolve it to `true` or `false`, or throw `RequiredError` if it isn't a true/false value.
  *
- * @returns `false` if the environment variable is `0`, `off`, `no`, `false`
- * @returns `true` if the environment variable is `1`, `on`, `yes`, `true`
+ * @param name Name of the environment variable to read.
+ * @param caller Function to attribute a thrown error to (defaults to `requireEnvBoolean`).
+ * @returns `false` if the environment variable is `0`, `off`, `no`, `false`; `true` if it is `1`, `on`, `yes`, `true`.
  * @throws `RequiredError` if the env variable is any other value.
+ * @example requireEnvBoolean("FEATURE_FLAG") // true
+ * @see https://dhoulb.github.io/shelving/util/env/requireEnvBoolean
  */
 export function requireEnvBoolean(name, caller = requireEnvBoolean) {
     const env = getEnv(name);

package/util/equal.d.ts

@@ -3,64 +3,207 @@ import type { Match } from "./filter.js";
 import type { AnyCaller } from "./function.js";
 import type { ImmutableMap } from "./map.js";
 import type { ImmutableObject } from "./object.js";
-/** Assert two values are equal. */
+/**
+ * Assert that two values are exactly (referentially) equal, narrowing `left` to the type of `right`.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value `left` must equal.
+ * @param caller Function to attribute a thrown error to (defaults to `assertEqual`).
+ * @throws {RequiredError} If the values are not equal.
+ * @example assertEqual(1, 1); // passes
+ * @see https://dhoulb.github.io/shelving/util/equal/assertEqual
+ */
 export declare function assertEqual<T>(left: unknown, right: T, caller?: AnyCaller): asserts left is T;
-/** Assert two values are equal. */
+/**
+ * Assert that two values are not equal, narrowing `left` to exclude the type of `right`.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value `left` must not equal.
+ * @param caller Function to attribute a thrown error to (defaults to `assertNot`).
+ * @throws {RequiredError} If the values are equal.
+ * @example assertNot(1, 2); // passes
+ * @see https://dhoulb.github.io/shelving/util/equal/assertNot
+ */
 export declare function assertNot<T, N>(left: T | N, right: N, caller?: AnyCaller): asserts left is T;
-/** Is unknown value `left` exactly equal to `right`? */
+/**
+ * Is unknown value `left` exactly (referentially) equal to `right`?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are strictly equal.
+ * @example isEqual(1, 1) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isEqual
+ */
 export declare function isEqual<T>(left: unknown, right: T): left is T;
-/** Is unknown value `left` not exactly equal to `right`? */
+/**
+ * Is unknown value `left` not exactly (referentially) equal to `right`?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are not strictly equal.
+ * @example notEqual(1, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notEqual
+ */
 export declare function notEqual<T, N>(left: T | N, right: N): left is T;
-/** Is unknown value `left` less than `right`? */
+/**
+ * Is unknown value `left` less than `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts before `right`.
+ * @example isLess(1, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isLess
+ */
 export declare function isLess(left: unknown, right: unknown): boolean;
-/** Is unknown value `left` less than or equal to `right`? */
+/**
+ * Is unknown value `left` less than or equal to `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts before or equal to `right`.
+ * @example isEqualLess(2, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isEqualLess
+ */
 export declare function isEqualLess(left: unknown, right: unknown): boolean;
-/** Is unknown value `left` greater than `right`? */
+/**
+ * Is unknown value `left` greater than `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts after `right`.
+ * @example isGreater(2, 1) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isGreater
+ */
 export declare function isGreater(left: unknown, right: unknown): boolean;
-/** Is unknown value `left` greater than or equal to `right`? */
+/**
+ * Is unknown value `left` greater than or equal to `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts after or equal to `right`.
+ * @example isEqualGreater(2, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isEqualGreater
+ */
 export declare function isEqualGreater(left: unknown, right: unknown): boolean;
 /**
  * Are two unknown values shallowly equal?
  * - If the values are both arrays/objects, see if the items/properties are **shallowly** equal with each other.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are shallowly equal.
+ * @example isShallowEqual({ a: 1 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isShallowEqual
  */
 export declare function isShallowEqual<T>(left: unknown, right: T): left is T;
-/** Are two unknown values not shallowly equal? */
+/**
+ * Are two unknown values not shallowly equal?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are not shallowly equal.
+ * @example notShallowEqual({ a: 1 }, { a: 2 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notShallowEqual
+ */
 export declare function notShallowEqual<T>(left: unknown, right: T): left is T;
 /**
  * Are two unknown values deeply equal?
  * - If the values are both arrays/objects, see if the items/properties are **deeply** equal with each other.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are deeply equal.
+ * @example isDeepEqual({ a: { b: 1 } }, { a: { b: 1 } }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isDeepEqual
  */
 export declare function isDeepEqual<T>(left: unknown, right: T): left is T;
-/** Are two unknown values not deeply equal? */
+/**
+ * Are two unknown values not deeply equal?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are not deeply equal.
+ * @example notDeepEqual({ a: { b: 1 } }, { a: { b: 2 } }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notDeepEqual
+ */
 export declare function notDeepEqual<T>(left: unknown, right: T): left is T;
 /**
- * Are two maps equal (based on their items).
+ * Are two maps equal based on their items?
+ *
+ * @param left The map to check and narrow.
+ * @param right The map to compare against.
+ * @param recursor Function that checks each value of the map (defaults to `isEqual` for strict equality; pass `isDeepEqual` for deep equality).
+ * @returns `true` if both maps have the same keys and matching values.
+ * @example isMapEqual(new Map([["a", 1]]), new Map([["a", 1]])) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isMapEqual
  */
 export declare function isMapEqual<T extends ImmutableMap>(left: ImmutableMap, right: T, recursor?: Match): left is T;
 /**
  * Are two arrays equal based on their items?
  *
+ * @param left The array to check and narrow.
+ * @param right The array to compare against.
  * @param recursor Function that checks each item of the array.
  * - Defaults to `isEqual()` to check strict equality of the items.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the items.
+ * @returns `true` if both arrays have the same length and matching items.
+ * @example isArrayEqual([1, 2], [1, 2]) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isArrayEqual
  */
 export declare function isArrayEqual<T extends ImmutableArray>(left: ImmutableArray, right: T, recursor?: Match): left is T;
-/** Is unknown value `left` in array `right`? */
+/**
+ * Is unknown value `left` in array `right`?
+ *
+ * @param left The value to look for and narrow.
+ * @param right The array to search within.
+ * @returns `true` if `left` is an item of `right`.
+ * @example isInArray(2, [1, 2, 3]) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isInArray
+ */
 export declare function isInArray<R>(left: unknown, right: ImmutableArray<R>): left is R;
-/** Is unknown value `left` not in array `right`? */
+/**
+ * Is unknown value `left` not in array `right`?
+ *
+ * @param left The value to look for.
+ * @param right The array to search within.
+ * @returns `true` if `left` is not an item of `right`.
+ * @example notInArray(9, [1, 2, 3]) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notInArray
+ */
 export declare function notInArray(left: unknown, right: ImmutableArray): boolean;
-/** Is unknown value `left` an array including `right`? */
+/**
+ * Is unknown value `left` an array that includes `right`?
+ *
+ * @param left The value to check and narrow.
+ * @param right The item the array must include.
+ * @returns `true` if `left` is an array containing `right`.
+ * @example isArrayWith([1, 2, 3], 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isArrayWith
+ */
 export declare function isArrayWith<T>(left: unknown, right: T): left is ImmutableArray<T>;
-/** Is unknown value `left` not an array or does not include `right`? */
+/**
+ * Is unknown value `left` not an array, or an array that does not include `right`?
+ *
+ * @param left The value to check.
+ * @param right The item the array must include.
+ * @returns `true` if `left` is not an array or does not include `right`.
+ * @example notArrayWith([1, 2, 3], 9) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notArrayWith
+ */
 export declare function notArrayWith(left: unknown, right: unknown): boolean;
 /**
  * Are two objects equal based on their own props?
  * - `left` must have every property present in `right`
  * - `left` must not have excess properties not present in `right`
  *
+ * @param left The object to check and narrow.
+ * @param right The object to compare against.
  * @param recursor Function that checks each prop of the object.
  * - Defaults to `isEqual()` to check strict equality of the properties.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the properties.
+ * @returns `true` if both objects have exactly the same own props and matching values.
+ * @example isObjectEqual({ a: 1 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isObjectEqual
  */
 export declare function isObjectEqual<T extends ImmutableObject>(left: ImmutableObject, right: T, recursor?: Match): left is T;
 /**
@@ -68,12 +211,33 @@ export declare function isObjectEqual<T extends ImmutableObject>(left: Immutable
  * - `left` must have every property present in `right`
  * - `left` may have have excess properties not present in `right`
  *
+ * @param left The object to check and narrow.
+ * @param right The object whose props `left` must contain.
  * @param recursor Function that checks each prop of the object.
  * - Defaults to `isEqual()` to check strict equality of the properties.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the properties.
+ * @returns `true` if `left` contains every prop of `right` with matching values.
+ * @example isObjectMatch({ a: 1, b: 2 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isObjectMatch
  */
 export declare function isObjectMatch<L extends ImmutableObject, R extends ImmutableObject>(left: L | R, right: R, recursor?: Match): left is L & R;
-/** Is unknown value `left` an object with every prop from `right`? */
+/**
+ * Is unknown value `left` an object with every prop from `right`?
+ *
+ * @param left The value to check.
+ * @param right The object whose props `left` must contain.
+ * @returns `true` if `left` is an object containing every prop of `right`.
+ * @example isObjectWith({ a: 1, b: 2 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isObjectWith
+ */
 export declare function isObjectWith(left: unknown, right: ImmutableObject): boolean;
-/** Is unknown value `left` not an object or missing one or more props from `right`? */
+/**
+ * Is unknown value `left` not an object or missing one or more props from `right`?
+ *
+ * @param left The value to check.
+ * @param right The object whose props `left` must contain.
+ * @returns `true` if `left` is not an object or is missing one or more props of `right`.
+ * @example notObjectWith({ a: 1 }, { b: 2 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notObjectWith
+ */
 export declare function notObjectWith(left: unknown, right: ImmutableObject): boolean;