shelving 1.236.0 → 1.236.2

package/util/map.d.ts

@@ -1,45 +1,170 @@
 import type { Entry } from "./entry.js";
 import type { AnyCaller } from "./function.js";
-/** `Map` that cannot be changed. */
+/**
+ * `Map` that cannot be changed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/ImmutableMap
+ */
 export type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
-/** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
+/**
+ * Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/ImmutableMap
+ */
 export declare const ImmutableMap: {
     new <K, T>(...params: ConstructorParameters<typeof Map<K, T>>): ImmutableMap<K, T>;
 };
-/** `Map` that can be changed. */
+/**
+ * `Map` that can be changed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/MutableMap
+ */
 export type MutableMap<K = unknown, T = unknown> = Map<K, T>;
-/** Extract the type for the value of a map. */
+/**
+ * Extract the type for the key of a map.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/MapKey
+ */
 export type MapKey<X> = X extends ReadonlyMap<infer Y, unknown> ? Y : never;
-/** Extract the type for the value of a map. */
+/**
+ * Extract the type for the value of a map.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/MapValue
+ */
 export type MapValue<X> = X extends ReadonlyMap<unknown, infer Y> ? Y : never;
-/** Get the type for an item of a map in entry format. */
+/**
+ * Get the type for an item of a map in entry format.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/MapItem
+ */
 export type MapItem<T extends ImmutableMap> = readonly [MapKey<T>, MapValue<T>];
-/** Things that can be converted to maps. */
+/**
+ * Things that can be converted to maps.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/PossibleMap
+ */
 export type PossibleMap<K, T> = ImmutableMap<K, T> | Iterable<Entry<K, T>>;
-/** Things that can be converted to maps with string keys. */
+/**
+ * Things that can be converted to maps with string keys.
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/PossibleStringMap
+ */
 export type PossibleStringMap<K extends string, T> = PossibleMap<K, T> | {
     readonly [KK in K]: T;
 };
-/** Is an unknown value a map? */
+/**
+ * Is an unknown value a map?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `Map` instance, otherwise `false`.
+ * @example isMap(new Map()) // true
+ * @see https://dhoulb.github.io/shelving/util/map/isMap
+ */
 export declare function isMap(value: unknown): value is ImmutableMap;
-/** Assert that a value is a `Map` instance. */
+/**
+ * Assert that a value is a `Map` instance.
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `ImmutableMap`.
+ * @throws {RequiredError} If `value` is not a `Map` instance.
+ * @example assertMap(new Map()); // passes
+ * @see https://dhoulb.github.io/shelving/util/map/assertMap
+ */
 export declare function assertMap(value: unknown, caller?: AnyCaller): asserts value is ImmutableMap;
-/** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
+/**
+ * Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged).
+ *
+ * @param input The map, object, or iterable of entries to convert.
+ * @returns An `ImmutableMap` — the input unchanged if it's already a `Map`, otherwise a new `Map`.
+ * @example getMap({ a: 1, b: 2 }) // Map { "a" => 1, "b" => 2 }
+ * @see https://dhoulb.github.io/shelving/util/map/getMap
+ */
 export declare function getMap<K extends string, T>(input: PossibleStringMap<K, T>): ImmutableMap<K, T>;
 export declare function getMap<K, T>(input: PossibleMap<K, T>): ImmutableMap<K, T>;
-/** Apply a limit to a map. */
+/**
+ * Apply a limit to a map.
+ * - Returns the input map unchanged if the limit is not smaller than its size.
+ *
+ * @param map The map to limit.
+ * @param limit The maximum number of items to keep.
+ * @returns An `ImmutableMap` with at most `limit` items (the input map unchanged if it already fits).
+ * @example limitMap(new Map([["a", 1], ["b", 2]]), 1) // Map { "a" => 1 }
+ * @see https://dhoulb.github.io/shelving/util/map/limitMap
+ */
 export declare function limitMap<T>(map: ImmutableMap<T>, limit: number): ImmutableMap<T>;
-/** Is an unknown value a key for an item in a map? */
+/**
+ * Is an unknown value a key for an item in a map?
+ *
+ * @param map The map to look in.
+ * @param key The candidate key to test.
+ * @returns `true` if `key` exists in `map`, otherwise `false`.
+ * @example isMapItem(new Map([["a", 1]]), "a") // true
+ * @see https://dhoulb.github.io/shelving/util/map/isMapItem
+ */
 export declare function isMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown): key is K;
-/** Assert that an unknown value is a key for an item in a map. */
+/**
+ * Assert that an unknown value is a key for an item in a map.
+ *
+ * @param map The map to look in.
+ * @param key The candidate key to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `key` to the map's key type.
+ * @throws {RequiredError} If `key` does not exist in `map`.
+ * @example assertMapItem(new Map([["a", 1]]), "a"); // passes
+ * @see https://dhoulb.github.io/shelving/util/map/assertMapItem
+ */
 export declare function assertMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown, caller?: AnyCaller): asserts key is K;
-/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
+/**
+ * Set an item in a map (by reference) and return the value that was set.
+ *
+ * @param map The mutable map to set the item on.
+ * @param key The key to set.
+ * @param value The value to set.
+ * @returns The `value` that was set.
+ * @example setMapItem(map, "a", 1) // 1
+ * @see https://dhoulb.github.io/shelving/util/map/setMapItem
+ */
 export declare function setMapItem<K, T>(map: MutableMap<K, T>, key: K, value: T): T;
-/** Add multiple items to a set (by reference). */
+/**
+ * Add multiple items to a map (by reference).
+ *
+ * @param map The mutable map to set the items on.
+ * @param items Iterable of key/value entries to set.
+ * @returns Nothing; mutates `map` in place.
+ * @example setMapItems(map, [["a", 1], ["b", 2]]);
+ * @see https://dhoulb.github.io/shelving/util/map/setMapItems
+ */
 export declare function setMapItems<K, T>(map: MutableMap<K, T>, items: Iterable<MapItem<ImmutableMap<K, T>>>): void;
-/** Remove multiple items from a set (by reference). */
+/**
+ * Remove multiple items from a map (by reference).
+ *
+ * @param map The mutable map to remove the items from.
+ * @param keys The keys to delete.
+ * @returns Nothing; mutates `map` in place.
+ * @example removeMapItems(map, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/map/removeMapItems
+ */
 export declare function removeMapItems<K, T>(map: MutableMap<K, T>, ...keys: K[]): void;
-/** Get an item in a map, or `undefined` if it doesn't exist. */
+/**
+ * Get an item in a map, or `undefined` if it doesn't exist.
+ *
+ * @param map The map to read from.
+ * @param key The key to look up.
+ * @returns The value for `key`, or `undefined` if it doesn't exist.
+ * @example getMapItem(new Map([["a", 1]]), "a") // 1
+ * @see https://dhoulb.github.io/shelving/util/map/getMapItem
+ */
 export declare function getMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T | undefined;
-/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
+/**
+ * Get an item in a map, or throw `RequiredError` if it doesn't exist.
+ *
+ * @param map The map to read from.
+ * @param key The key to look up.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The value for `key`.
+ * @throws {RequiredError} If `key` does not exist in `map`.
+ * @example requireMapItem(new Map([["a", 1]]), "a") // 1
+ * @see https://dhoulb.github.io/shelving/util/map/requireMapItem
+ */
 export declare function requireMapItem<K, T>(map: ImmutableMap<K, T>, key: K, caller?: AnyCaller): T;

package/util/map.js

@@ -1,12 +1,32 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isIterable, limitItems } from "./iterate.js";
-/** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
+/**
+ * Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/map/ImmutableMap
+ */
 export const ImmutableMap = Map;
-/** Is an unknown value a map? */
+/**
+ * Is an unknown value a map?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `Map` instance, otherwise `false`.
+ * @example isMap(new Map()) // true
+ * @see https://dhoulb.github.io/shelving/util/map/isMap
+ */
 export function isMap(value) {
     return value instanceof Map;
 }
-/** Assert that a value is a `Map` instance. */
+/**
+ * Assert that a value is a `Map` instance.
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `ImmutableMap`.
+ * @throws {RequiredError} If `value` is not a `Map` instance.
+ * @example assertMap(new Map()); // passes
+ * @see https://dhoulb.github.io/shelving/util/map/assertMap
+ */
 export function assertMap(value, caller = assertMap) {
     if (!isMap(value))
         throw new RequiredError("Must be map", { received: value, caller });
@@ -14,39 +34,109 @@ export function assertMap(value, caller = assertMap) {
 export function getMap(input) {
     return isMap(input) ? input : new Map(isIterable(input) ? input : Object.entries(input));
 }
-/** Apply a limit to a map. */
+/**
+ * Apply a limit to a map.
+ * - Returns the input map unchanged if the limit is not smaller than its size.
+ *
+ * @param map The map to limit.
+ * @param limit The maximum number of items to keep.
+ * @returns An `ImmutableMap` with at most `limit` items (the input map unchanged if it already fits).
+ * @example limitMap(new Map([["a", 1], ["b", 2]]), 1) // Map { "a" => 1 }
+ * @see https://dhoulb.github.io/shelving/util/map/limitMap
+ */
 export function limitMap(map, limit) {
     return limit > map.size ? map : new Map(limitItems(map, limit));
 }
-/** Is an unknown value a key for an item in a map? */
+/**
+ * Is an unknown value a key for an item in a map?
+ *
+ * @param map The map to look in.
+ * @param key The candidate key to test.
+ * @returns `true` if `key` exists in `map`, otherwise `false`.
+ * @example isMapItem(new Map([["a", 1]]), "a") // true
+ * @see https://dhoulb.github.io/shelving/util/map/isMapItem
+ */
 export function isMapItem(map, key) {
     return map.has(key);
 }
-/** Assert that an unknown value is a key for an item in a map. */
+/**
+ * Assert that an unknown value is a key for an item in a map.
+ *
+ * @param map The map to look in.
+ * @param key The candidate key to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `key` to the map's key type.
+ * @throws {RequiredError} If `key` does not exist in `map`.
+ * @example assertMapItem(new Map([["a", 1]]), "a"); // passes
+ * @see https://dhoulb.github.io/shelving/util/map/assertMapItem
+ */
 export function assertMapItem(map, key, caller = assertMapItem) {
     if (!isMapItem(map, key))
         throw new RequiredError("Key must exist in map", { key, map, caller });
 }
-/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
+/**
+ * Set an item in a map (by reference) and return the value that was set.
+ *
+ * @param map The mutable map to set the item on.
+ * @param key The key to set.
+ * @param value The value to set.
+ * @returns The `value` that was set.
+ * @example setMapItem(map, "a", 1) // 1
+ * @see https://dhoulb.github.io/shelving/util/map/setMapItem
+ */
 export function setMapItem(map, key, value) {
     map.set(key, value);
     return value;
 }
-/** Add multiple items to a set (by reference). */
+/**
+ * Add multiple items to a map (by reference).
+ *
+ * @param map The mutable map to set the items on.
+ * @param items Iterable of key/value entries to set.
+ * @returns Nothing; mutates `map` in place.
+ * @example setMapItems(map, [["a", 1], ["b", 2]]);
+ * @see https://dhoulb.github.io/shelving/util/map/setMapItems
+ */
 export function setMapItems(map, items) {
     for (const [k, v] of items)
         map.set(k, v);
 }
-/** Remove multiple items from a set (by reference). */
+/**
+ * Remove multiple items from a map (by reference).
+ *
+ * @param map The mutable map to remove the items from.
+ * @param keys The keys to delete.
+ * @returns Nothing; mutates `map` in place.
+ * @example removeMapItems(map, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/map/removeMapItems
+ */
 export function removeMapItems(map, ...keys) {
     for (const key of keys)
         map.delete(key);
 }
-/** Get an item in a map, or `undefined` if it doesn't exist. */
+/**
+ * Get an item in a map, or `undefined` if it doesn't exist.
+ *
+ * @param map The map to read from.
+ * @param key The key to look up.
+ * @returns The value for `key`, or `undefined` if it doesn't exist.
+ * @example getMapItem(new Map([["a", 1]]), "a") // 1
+ * @see https://dhoulb.github.io/shelving/util/map/getMapItem
+ */
 export function getMapItem(map, key) {
     return map.get(key);
 }
-/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
+/**
+ * Get an item in a map, or throw `RequiredError` if it doesn't exist.
+ *
+ * @param map The map to read from.
+ * @param key The key to look up.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The value for `key`.
+ * @throws {RequiredError} If `key` does not exist in `map`.
+ * @example requireMapItem(new Map([["a", 1]]), "a") // 1
+ * @see https://dhoulb.github.io/shelving/util/map/requireMapItem
+ */
 export function requireMapItem(map, key, caller = requireMapItem) {
     if (!map.has(key))
         throw new RequiredError("Key must exist in map", { key, map, caller });

package/util/merge.d.ts

@@ -4,6 +4,12 @@ type MergeRecursor = (left: unknown, right: unknown) => unknown;
 /**
  * Exact merge two unknown values.
  * - Always returns `right`.
+ *
+ * @param _left The left value (ignored).
+ * @param right The right value.
+ * @returns The `right` value, always.
+ * @example exactMerge(1, 2) // 2
+ * @see https://dhoulb.github.io/shelving/util/merge/exactMerge
  */
 export declare function exactMerge(_left: unknown, right: unknown): unknown;
 /**
@@ -13,9 +19,13 @@ export declare function exactMerge(_left: unknown, right: unknown): unknown;
  * - Two arrays: unique items are merged together (shallowly).
  * - Any other value: right value is returned.
  *
+ * @param left The left value to merge into.
+ * @param right The right value to merge in.
  * @returns Merged value.
  * - Will be `left` instance if no properties/items changed.
  * - Will be merged instance otherwise.
+ * @example shallowMerge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/merge/shallowMerge
  */
 export declare function shallowMerge<L extends ImmutableObject, R extends ImmutableObject>(left: L, right: R): L & R;
 export declare function shallowMerge<L, R>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
@@ -27,9 +37,13 @@ export declare function shallowMerge<R>(left: unknown, right: R): R;
  * - Two arrays: unique items are merged together (shallowly — arrays have no way to deep merge because array keys are not stable).
  * - Any other value: right value is returned.
  *
+ * @param left The left value to merge into.
+ * @param right The right value to merge in.
  * @returns Merged value.
  * - Will be `left` instance if no properties/items changed.
  * - Will be a new merged instance otherwise.
+ * @example deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: 1, c: 2 } }
+ * @see https://dhoulb.github.io/shelving/util/merge/deepMerge
  */
 export declare function deepMerge<L extends ImmutableObject, R extends ImmutableObject>(left: L, right: R): L & R;
 export declare function deepMerge<L, R>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
@@ -40,10 +54,14 @@ export declare function deepMerge<R>(left: unknown, right: R): R;
  * - Arrays have no concept of `deep merge` because array keys are not stable.
  * - Use an map/object data structure instead for values that need to be deeply mergeable (only use arrays for primitive values).
  *
+ * @param left The left array to merge into.
+ * @param right The right array whose unique items are merged in.
  * @returns Merged array.
  * - Values that appear in both arrays will not be added twice.
  * - Will be `left` instance if no items were added.
  * - Will be a new merged array otherwise.
+ * @example mergeArray([1, 2], [2, 3]) // [1, 2, 3]
+ * @see https://dhoulb.github.io/shelving/util/merge/mergeArray
  */
 export declare function mergeArray<L, R>(left: ImmutableArray<L>, right: ImmutableArray<R> | ImmutableArray<L>): ImmutableArray<L | R>;
 /**
@@ -54,14 +72,18 @@ export declare function mergeArray<L, R>(left: ImmutableArray<L>, right: Immutab
  * - Always returns a new object (or the `left` object if no changes were made).
  * - Resulting object is `cleaned`, i.e. properties in `left` or `right` that are `undefined` will be removed from the merged object.
  *
+ * @param left The left object to merge into.
+ * @param right The right object whose props replace or merge with `left`.
  * @param recursor Function that merges each property of the object.
  * - Defaults to `exactMerge()` to just swap the property for a newer one if it exists.
  * - Use `deepMerge()` as the recursor to merge objects deeply.
  *
- * @return Merged object.
+ * @returns Merged object.
  * - Returned instances will be the same if no changes were made.
  * - Will be `left` instance if no properties changed.
  * - Will be a new merged object otherwise.
+ * @example mergeObject({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/merge/mergeObject
  */
 export declare function mergeObject<L extends ImmutableObject, R extends ImmutableObject>(left: L, right: R, recursor?: MergeRecursor): L & R;
 export {};

package/util/merge.js

@@ -13,6 +13,12 @@ function _merge(left, right, recursor) {
 /**
  * Exact merge two unknown values.
  * - Always returns `right`.
+ *
+ * @param _left The left value (ignored).
+ * @param right The right value.
+ * @returns The `right` value, always.
+ * @example exactMerge(1, 2) // 2
+ * @see https://dhoulb.github.io/shelving/util/merge/exactMerge
  */
 export function exactMerge(_left, right) {
     return right;

package/util/null.d.ts

@@ -1,27 +1,116 @@
 import type { AnyCaller } from "./function.js";
-/** Function that always returns null. */
+/**
+ * Function that always returns `null`.
+ * - Useful as a default callback or placeholder.
+ *
+ * @returns `null`, always.
+ * @example getNull() // null
+ * @see https://dhoulb.github.io/shelving/util/null/getNull
+ */
 export declare function getNull(): null;
-/** Nullable is the value or `null` */
+/**
+ * Nullable is the value or `null`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/null/Nullable
+ */
 export type Nullable<T> = T | null;
-/** Is a value null? */
+/**
+ * Is a value `null`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is `null`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/isNull
+ */
 export declare function isNull(value: unknown): value is null;
-/** Assert that a value is not null. */
+/**
+ * Assert that a value is `null`.
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is not `null`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNull
+ */
 export declare function assertNull<T>(value: Nullable<T>, caller?: AnyCaller): asserts value is T;
-/** Is a value not null? */
+/**
+ * Is a value not `null`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is not `null`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/notNull
+ */
 export declare function notNull<T>(value: Nullable<T>): value is T;
-/** Assert that a value is not null. */
+/**
+ * Assert that a value is not `null`.
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is `null`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNotNull
+ */
 export declare function assertNotNull<T>(value: Nullable<T>, caller?: AnyCaller): asserts value is T;
-/** Get the not-nullish version of value. */
+/**
+ * Get the not-null version of a value, or throw `RequiredError` if it is `null`.
+ *
+ * @param value The value to require.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The value, narrowed to `T`.
+ * @throws RequiredError if `value` is `null`.
+ * @example requireNotNull("a") // "a"
+ * @see https://dhoulb.github.io/shelving/util/null/requireNotNull
+ */
 export declare function requireNotNull<T>(value: Nullable<T>, caller?: AnyCaller): T;
-/** Nullish is the value or `null` or `undefined` */
+/**
+ * Nullish is the value or `null` or `undefined`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/null/Nullish
+ */
 export type Nullish<T> = T | null | undefined;
-/** Is a value nullish? */
+/**
+ * Is a value nullish (`null` or `undefined`)?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is `null` or `undefined`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/isNullish
+ */
 export declare function isNullish<T>(value: Nullish<T>): value is null | undefined;
-/** Assert that a value is not nullish. */
+/**
+ * Assert that a value is nullish (`null` or `undefined`).
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is not `null` or `undefined`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNullish
+ */
 export declare function assertNullish<T>(value: Nullish<T>, caller?: AnyCaller): asserts value is T;
-/** Is a value not nullish? */
+/**
+ * Is a value not nullish (not `null` and not `undefined`)?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is not `null` and not `undefined`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/notNullish
+ */
 export declare function notNullish<T>(value: Nullish<T>): value is T;
-/** Assert that a value is not nullish. */
+/**
+ * Assert that a value is not nullish (not `null` and not `undefined`).
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is `null` or `undefined`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNotNullish
+ */
 export declare function assertNotNullish<T>(value: Nullish<T>, caller?: AnyCaller): asserts value is T;
-/** Get the not-nullish version of value. */
+/**
+ * Get the not-nullish version of a value, or throw `RequiredError` if it is `null` or `undefined`.
+ *
+ * @param value The value to require.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The value, narrowed to `T`.
+ * @throws RequiredError if `value` is `null` or `undefined`.
+ * @example requireNotNullish("a") // "a"
+ * @see https://dhoulb.github.io/shelving/util/null/requireNotNullish
+ */
 export declare function requireNotNullish<T>(value: Nullish<T>, caller?: AnyCaller): T;