@dereekb/util 13.0.7 → 13.2.0

package/src/lib/value/map.d.ts

@@ -2,7 +2,7 @@ import { type ArrayOrValue } from '../array/array';
 import { type PromiseOrValue } from '../promise/promise.type';
 import { type Maybe, type MaybeNot } from './maybe.type';
 /**
- * Converts one value to another.
+ * Converts a value of one type to another, serving as the fundamental transformation primitive throughout the library.
  */
 export type MapFunction<I, O> = (input: I) => O;
 /**
@@ -12,45 +12,77 @@ export type MapFunction<I, O> = (input: I) => O;
  */
 export type ReadValueFunction<I, O> = MapFunction<I, O>;
 /**
- * Turns a normal MapFunction into one that passes through Maybe values without attempting to map them.
+ * Wraps a MapFunction so that null/undefined inputs are passed through without invoking the map,
+ * avoiding errors on nullable values.
  *
- * @param mapFunction
- * @returns
+ * @param mapFunction - function to apply only when the input is defined
+ * @returns a new function that short-circuits on null/undefined inputs
+ *
+ * @example
+ * ```ts
+ * const double = (x: number) => x * 2;
+ * const maybeDouble = mapMaybeFunction(double);
+ *
+ * maybeDouble(3);         // 6
+ * maybeDouble(undefined); // undefined
+ * maybeDouble(null);      // null
+ * ```
  */
 export declare function mapMaybeFunction<I, O>(mapFunction: MapFunction<I, O>): MapFunction<Maybe<I>, Maybe<O>>;
 /**
- * MapFunction with the same input as output.
+ * A MapFunction whose output type matches its input type, useful for in-place transformations or chained pipelines.
  */
 export type MapSameFunction<I> = MapFunction<I, I>;
 /**
- * Converts a MapFunction into one that returns a promise.
+ * Derives an asynchronous variant of a MapFunction, allowing the output to be either a value or a Promise.
  */
 export type AsyncMapFunction<F extends MapFunction<any, any>> = F extends MapFunction<infer I, infer O> ? MapFunction<I, PromiseOrValue<O>> : never;
 /**
- * Converts a MapFunction into one that takes in arrays and returns arrays.
+ * Derives an array variant of a MapFunction that maps each element individually, producing an array of results.
  */
 export type MapArrayFunction<F extends MapFunction<any, any>> = F extends MapFunction<infer I, infer O> ? MapFunction<I[], O[]> : never;
 /**
- * Converts values from the input, and applies them to the target if a target is supplied.
+ * Maps values from the input to the output type, optionally merging into an existing partial target object.
  */
 export type ApplyMapFunction<I, O> = (input: I, target?: Maybe<Partial<O>>) => O;
 /**
- * Converts values from the input, and applies them to the target if a target is supplied.
+ * Maps values from the input to the output type, optionally merging into a partial target and accepting additional options.
  */
 export type ApplyMapFunctionWithOptions<I, O, C> = (input: I, target?: Maybe<Partial<O>>, options?: Maybe<C>) => O;
+/**
+ * Lifts a per-element MapFunction into one that operates on arrays, applying the mapping to each element.
+ *
+ * @param mapFunction - per-element transformation
+ * @returns a function that maps entire arrays
+ */
 export declare function mapArrayFunction<I, O>(mapFunction: MapFunction<I, O>): MapArrayFunction<MapFunction<I, O>>;
+/**
+ * The canonical identity MapFunction. Returns its input unchanged.
+ *
+ * Used as a sentinel value so that {@link chainMapSameFunctions} and other combinators can detect
+ * and skip no-op mappings for efficiency.
+ */
 export declare const MAP_IDENTITY: <T>(input: T) => T;
+/**
+ * Returns the shared {@link MAP_IDENTITY} function cast to the requested type, useful for providing a typed no-op transformation.
+ */
 export declare function mapIdentityFunction<T>(): MapFunction<T, T>;
+/**
+ * Checks whether the given function is the singleton {@link MAP_IDENTITY} reference.
+ */
 export declare function isMapIdentityFunction(fn: unknown): fn is typeof MAP_IDENTITY;
+/**
+ * Captures both the input and output of a MapFunction invocation, useful for debugging or auditing transformations.
+ */
 export type MapFunctionOutputPair<O, I = unknown> = {
     input: I;
     output: O;
 };
 /**
- * Wraps a MapFunction to instead provide the input and output values.
+ * Wraps a MapFunction so that each invocation returns a {@link MapFunctionOutputPair} containing both the original input and the computed output.
  *
- * @param fn
- * @returns
+ * @param fn - the map function to wrap
+ * @returns a new function that returns input/output pairs
  */
 export declare function mapFunctionOutputPair<O, I = unknown>(fn: MapFunction<I, O>): MapFunction<I, MapFunctionOutputPair<O, I>>;
 /**
@@ -60,25 +92,50 @@ export type MapFunctionOutput<O extends object, I = unknown> = O & {
     readonly _input: I;
 };
 /**
+ * Wraps a MapFunction so that its object output is augmented with a readonly `_input` property referencing the original input.
+ * Useful for retaining provenance through a transformation pipeline.
  *
- * @param fn
- * @returns
+ * @param fn - the map function whose output will be augmented
+ * @returns a new function that returns a {@link MapFunctionOutput} with the `_input` reference attached
  */
 export declare function wrapMapFunctionOutput<O extends object, I = unknown>(fn: MapFunction<I, O>): MapFunction<I, MapFunctionOutput<O, I>>;
+/**
+ * Attaches a readonly `_input` property to the given output object, creating a {@link MapFunctionOutput}.
+ *
+ * @param output - the computed output object
+ * @param input - the original input value to attach
+ * @returns the output augmented with `_input`
+ */
 export declare function mapFunctionOutput<O extends object, I = unknown>(output: O, input: I): MapFunctionOutput<O, I>;
 /**
- * Chains together multiple MapSameFunctions in the same order. Functions that are not defined are ignored.
+ * Chains together multiple MapSameFunctions into a single pipeline executed left-to-right.
+ * Null/undefined entries and identity functions are automatically removed for efficiency.
+ * Returns the identity function if no meaningful functions remain.
+ *
+ * @param input - one or more optional same-type map functions to chain
+ * @returns a single composed function that runs all provided functions in order
+ *
+ * @example
+ * ```ts
+ * const fnChain = chainMapSameFunctions([
+ *   (x: string) => x,
+ *   (x: string) => x,
+ * ]);
  *
- * @param fns
+ * const result = fnChain('aaaab');
+ * // result === 'aaaab'
+ * ```
  */
 export declare function chainMapSameFunctions<I>(input: ArrayOrValue<Maybe<MapSameFunction<I>>>): MapSameFunction<I>;
 /**
- * Creates a single function that chains the two map functions together, if apply is true or undefined.
+ * Creates a single function that pipes the output of `a` into `b`.
  *
- * If apply is false, or the second map function is not defined, returns the first map function.
+ * If `apply` is false, or `b` is null/undefined, returns `a` unchanged. This conditional chaining
+ * is useful when a second transform step is optional.
  *
- * @param a
- * @param b
+ * @param a - the first map function
+ * @param b - the optional second map function to chain after `a`
+ * @param apply - when false, skips chaining and returns `a` directly
  */
 export declare function chainMapFunction<I>(a: MapSameFunction<I>, b: Maybe<MapSameFunction<I>>): MapSameFunction<I>;
 export declare function chainMapFunction<I>(a: MapSameFunction<I>, b: Maybe<MapSameFunction<I>>, apply?: boolean): MapSameFunction<I>;

package/src/lib/value/maybe.d.ts

@@ -1,107 +1,105 @@
 import { type Maybe, type MaybeNot, type MaybeSo } from './maybe.type';
 /**
- * Returns true if the value is not null or undefined.
+ * Type guard that returns `true` if the value is not `null` or `undefined`.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function hasNonNullValue<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
- * Whether or not the input has any value.
+ * Type guard that checks whether the input has a meaningful value.
  *
- * Will return false for:
- * - empty iterables
- * - empty strings
- * - null/undefined values.
+ * Returns `false` for empty iterables (arrays, Sets, Maps), empty strings, and nullish values.
+ * Non-iterable objects (e.g. `{}`) are considered non-empty by this function;
+ * use {@link hasValueOrNotEmptyObject} to also reject empty objects.
  *
  * NaN has undefined behavior.
+ *
+ * @param value - the value to check
  */
 export declare function hasValueOrNotEmpty<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
- * Whether or not the input has any value.
+ * Type guard that checks whether the input has a meaningful value, including checking for empty objects.
  *
- * Will return false for:
- * - empty iterables
- * - empty strings
- * - empty objects (no keys)
- * - null/undefined values.
+ * Returns `false` for empty iterables, empty strings, objects with no own keys (`{}`), and nullish values.
+ * This is stricter than {@link hasValueOrNotEmpty}, which considers `{}` as having a value.
  *
  * NaN has undefined behavior.
+ *
+ * @param value - the value to check
  */
 export declare function hasValueOrNotEmptyObject<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
- * Returns true if the input value is a non-empty string or is true.
+ * Returns `true` if the input value is a non-empty string or is `true`.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function isStringOrTrue(value: Maybe<string | boolean>): boolean;
 /**
- * Returns true if the input is not MaybeNot and not an empty string.
+ * Type guard that returns `true` if the input is not nullish and not an empty string.
+ *
+ * Useful for filtering out both nullish values and empty strings in a single check.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function isNotNullOrEmptyString<T>(value: Maybe<MaybeNot | '' | T>): value is MaybeSo<T>;
 /**
- * True if the input is MaybeNot.
+ * Type guard that returns `true` if the input is `null` or `undefined`.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function isMaybeNot<T = unknown>(value: Maybe<T>): value is MaybeNot;
 /**
- * True if the input is MaybeSo
+ * Type guard that returns `true` if the input is neither `null` nor `undefined`.
  *
- * @param value
- * @returns
+ * Equivalent to {@link hasNonNullValue} but with the `MaybeSo` narrowing type.
+ *
+ * @param value - the value to check
  */
 export declare function isMaybeSo<T>(value: Maybe<T>): value is MaybeSo<T>;
 /**
- * True if the input is MaybeNot and true.
+ * Type guard that returns `true` if the input is nullish or is strictly `true`.
+ *
+ * Useful for optional boolean flags where both absence and `true` indicate the same behavior.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function isMaybeNotOrTrue<T = unknown>(value: Maybe<T | true>): value is MaybeNot | true;
 /**
- * True if the input is not null/undefined/false.
+ * Returns `true` if the input is not `null`, `undefined`, or `false`.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function isDefinedAndNotFalse<T = unknown>(value: Maybe<T>): boolean;
 /**
- * True if the input is not false
+ * Returns `true` if the input is not strictly `false`. Nullish values return `true`.
  *
- * @param value
- * @returns
+ * @param value - the value to check
  */
 export declare function isNotFalse<T = unknown>(value: Maybe<T>): boolean;
 /**
- * Returns true if both the inputs are not null/undefined but the same value.
+ * Returns `true` if both inputs are non-nullish and strictly equal (`===`).
  *
- * @param a
- * @param b
- * @returns
+ * @param a - first value
+ * @param b - second value
  */
 export declare function isSameNonNullValue<T>(a: Maybe<T>, b: Maybe<T>): a is NonNullable<T>;
 /**
- * Returns true if both inputs are null/undefined, or are the same value.
+ * Returns `true` if both inputs are nullish (using loose equality `==`) or are strictly the same value.
+ *
+ * This means `null` and `undefined` are considered equivalent to each other, but `false` and `null` are not.
  *
- * @param a
- * @param b
- * @returns
+ * @param a - first value
+ * @param b - second value
  */
 export declare function valuesAreBothNullishOrEquivalent<T>(a: Maybe<T>, b: Maybe<T>): boolean;
 /**
- * Updates "a" with "b".
+ * Merges two `Maybe` values using `undefined` as the "no change" sentinel.
  *
- * - If b is defined, then returns b
- * - If b is undefined, then returns a
- * - If b is null, then returns null
+ * - If `b` is `undefined`, returns `a` (no update).
+ * - If `b` is `null`, returns `null` (explicit clear).
+ * - If `b` is defined, returns `b` (new value).
  *
- * @param a
- * @param b
+ * @param a - the current value
+ * @param b - the update value
  */
 export declare function updateMaybeValue<T>(a: Maybe<T>, b: Maybe<T>): Maybe<T>;

package/src/lib/value/modifier.d.ts

@@ -1,78 +1,133 @@
 import { type ArrayOrValue } from '../array';
 import { type Maybe } from './maybe.type';
 /**
- * Modifier key
+ * String key that uniquely identifies a modifier within a {@link ModifierMap}.
  */
 export type ModifierKey = string;
 /**
- * Modifies the input value.
+ * Function that mutates the input value in place.
  */
 export type ModifierFunction<T> = (input: T) => void;
 /**
- * Retains a reference to a ModifierFunction
+ * Holds a reference to a {@link ModifierFunction}.
  */
 export interface ModifierFunctionRef<T> {
     readonly modify: ModifierFunction<T>;
 }
 /**
- * A modifier that has a key and modify function.
+ * A keyed modifier that pairs a unique {@link ModifierKey} with a {@link ModifierFunction}.
+ *
+ * The key allows modifiers to be added, replaced, or removed from a {@link ModifierMap} by identity.
  */
 export interface Modifier<T> extends ModifierFunctionRef<T> {
     /**
-     * Modifier key.
+     * Unique key identifying this modifier.
      */
     readonly key: ModifierKey;
 }
 /**
- * Creates a new modifier
+ * Creates a {@link Modifier} with the given key and modify function.
+ *
+ * @param key - unique identifier for the modifier
+ * @param modify - function that mutates the target value
  *
- * @param key
- * @param modify
- * @returns
+ * @example
+ * ```ts
+ * const uppercaseName = modifier<{ name: string }>('uppercase', (x) => { x.name = x.name.toUpperCase(); });
+ * const obj = { name: 'alice' };
+ * uppercaseName.modify(obj);
+ * // obj.name === 'ALICE'
+ * ```
  */
 export declare function modifier<T>(key: string, modify: ModifierFunction<T>): Modifier<T>;
 /**
- * No operation modifier.
+ * A no-operation modifier that does nothing to the input. Useful as a default/fallback.
  */
 export declare const NOOP_MODIFIER: ModifierFunction<any>;
 /**
- * Map of Modifiers keyed by the modifier key.
+ * Map of {@link Modifier} instances keyed by their {@link ModifierKey}, enabling lookup, replacement, and removal by key.
  */
 export type ModifierMap<T> = Map<ModifierKey, Modifier<T>>;
 /**
- * Adds a modifier to the modifier map and returns the map.
+ * Adds one or more modifiers to the map, creating a new map if none is provided.
+ *
+ * If a modifier with the same key already exists, it is replaced.
+ *
+ * @param modifiers - modifier(s) to add
+ * @param map - existing map to add to, or undefined to create a new one
  *
- * @param modifier
- * @param map
- * @returns
+ * @example
+ * ```ts
+ * const mod = modifier<{ x: number }>('double', (o) => { o.x *= 2; });
+ * const map = addModifiers(mod);
+ * map.has('double'); // true
+ * ```
  */
 export declare function addModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>, map?: Maybe<ModifierMap<T>>): ModifierMap<T>;
 /**
- * Removes a modifier from the modifier map and returns the map.
+ * Removes one or more modifiers from the map by key. Returns an empty map if no map is provided.
  *
- * @param modifier
- * @param map
+ * @param modifiers - modifier(s) whose keys should be removed
+ * @param map - the map to remove from
+ *
+ * @example
+ * ```ts
+ * const mod = modifier<{ x: number }>('double', (o) => { o.x *= 2; });
+ * const map = addModifiers(mod);
+ * const result = removeModifiers(mod, map);
+ * result.has('double'); // false
+ * ```
  */
 export declare function removeModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>, map: Maybe<ModifierMap<T>>): ModifierMap<T>;
+/**
+ * Converts a {@link ModifierMap} to a single {@link ModifierFunction} that applies all modifiers in sequence.
+ *
+ * Returns {@link NOOP_MODIFIER} if the map is nullish or empty.
+ *
+ * @param map - the modifier map to convert
+ *
+ * @example
+ * ```ts
+ * const mod = modifier<{ x: number }>('inc', (o) => { o.x += 1; });
+ * const map = addModifiers(mod);
+ * const fn = modifierMapToFunction(map);
+ * const obj = { x: 0 };
+ * fn(obj);
+ * // obj.x === 1
+ * ```
+ */
 export declare function modifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): ModifierFunction<T>;
 /**
- * Converts a ModifierMap to a ModifierFunction if the map is input or has functions. Otherwise returns undefined.
+ * Converts a {@link ModifierMap} to a single {@link ModifierFunction} if the map is non-null.
+ *
+ * Returns undefined if no map is provided, allowing callers to distinguish "no modifiers" from "empty modifiers".
  *
- * @param map
- * @returns
+ * @param map - the modifier map to convert
  */
 export declare function maybeModifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): Maybe<ModifierFunction<T>>;
 /**
- * Merges all modifiers into a single function.
+ * Merges an array of {@link ModifierFunction} values into a single function that applies them all in order.
  *
- * @param map
- * @returns
+ * Returns {@link NOOP_MODIFIER} if the array is empty or nullish.
+ *
+ * @param modifiers - array of modifier functions to merge
+ *
+ * @example
+ * ```ts
+ * const add1 = (o: { x: number }) => { o.x += 1; };
+ * const double = (o: { x: number }) => { o.x *= 2; };
+ * const merged = mergeModifiers([add1, double]);
+ * const obj = { x: 3 };
+ * merged(obj);
+ * // obj.x === 8 (3 + 1 = 4, then 4 * 2 = 8)
+ * ```
  */
 export declare function mergeModifiers<T>(modifiers: ModifierFunction<T>[]): ModifierFunction<T>;
 /**
- * Merges all modifiers into a single function. If not modifier functions are input, returns
+ * Merges an array of {@link ModifierFunction} values into a single function. Returns undefined if the input is nullish.
+ *
+ * If only one modifier is provided, returns it directly without wrapping.
  *
- * @param map
- * @returns
+ * @param modifiers - array of modifier functions to merge, or undefined
  */
 export declare function maybeMergeModifiers<T>(modifiers: Maybe<ModifierFunction<T>[]>): Maybe<ModifierFunction<T>>;