@dereekb/util 13.0.7 → 13.2.0

package/src/lib/number/random.d.ts

@@ -25,10 +25,20 @@ export interface RandomNumberFactoryConfig {
 }
 export type RandomNumberFactoryInput = number | RandomNumberFactoryConfig;
 /**
- * Used to generate a RandomNumberFunction that returns a number between the input and the maximum (exclusive).
+ * Creates a factory that generates random numbers within a configured range.
  *
- * @param maxOrArgs
- * @returns
+ * Accepts either a simple max number or a full config object with min, max, and rounding options.
+ *
+ * @param maxOrArgs - Maximum value (exclusive) or full configuration object
+ * @param roundingInput - Optional rounding mode override
+ * @returns A factory function that produces random numbers within the range
  */
 export declare function randomNumberFactory(maxOrArgs: RandomNumberFactoryInput, roundingInput?: RoundingInput): RandomNumberFactory;
+/**
+ * Generates a single random number using {@link randomNumberFactory}. Convenience function for one-off usage.
+ *
+ * @param maxOrArgs - Maximum value (exclusive) or full configuration object
+ * @param roundingInput - Optional rounding mode
+ * @returns A single random number
+ */
 export declare function randomNumber(maxOrArgs: RandomNumberFactoryInput, roundingInput?: RoundingInput): number;

package/src/lib/number/round.d.ts

@@ -4,6 +4,12 @@ import { type AsNumberInput } from './number';
 export type FloorOrCeilRounding = 'floor' | 'ceil';
 export type NumberRounding = 'none' | FloorOrCeilRounding | 'round';
 export type RoundingFunction = MapFunction<number, number>;
+/**
+ * Returns a rounding function for the specified rounding type.
+ *
+ * @param type - The rounding strategy: 'floor', 'ceil', 'round', or 'none'
+ * @returns The corresponding Math function, or an identity function for 'none'
+ */
 export declare function roundingFunction(type: NumberRounding): RoundingFunction;
 export type RoundingInput = NumberRounding | RoundingFunction;
 /**
@@ -11,11 +17,13 @@ export type RoundingInput = NumberRounding | RoundingFunction;
  */
 export type NumberPrecision = number;
 /**
- * Same as cutToPrecision, but can take in a string or null/undefined.
+ * Truncates a number (or number string) to the specified decimal precision without rounding.
  *
- * @param input
- * @param precision
- * @returns
+ * Accepts strings and null/undefined via {@link asNumber}.
+ *
+ * @param input - Number, number string, or null/undefined
+ * @param precision - Number of decimal places to retain
+ * @returns The truncated number value
  */
 export declare function cutValueToPrecision(input: AsNumberInput, precision: NumberPrecision): number;
 /**
@@ -23,8 +31,10 @@ export declare function cutValueToPrecision(input: AsNumberInput, precision: Num
  */
 export declare const CUT_VALUE_TO_ZERO_PRECISION: CutValueToPrecisionFunction;
 /**
+ * Truncates a value to an integer by cutting to zero decimal precision.
  *
- * @returns
+ * @param input - Number, number string, or null/undefined
+ * @returns The truncated integer value
  */
 export declare function cutValueToInteger(input: AsNumberInput): number;
 /**
@@ -34,10 +44,11 @@ export type CutValueToPrecisionFunction = ((input: AsNumberInput) => number) & {
     readonly _precision: number;
 };
 /**
- * Creates a CutValueToPrecisionFunction
+ * Creates a {@link CutValueToPrecisionFunction} that truncates values to the configured precision.
  *
- * @param precision
- * @returns
+ * @param precision - Number of decimal places to retain
+ * @param roundingType - Rounding strategy; defaults to 'cut' (truncation)
+ * @returns A function that accepts a number or string and returns the truncated number
  */
 export declare function cutValueToPrecisionFunction(precision: NumberPrecision, roundingType?: RoundToPrecisionFunctionType): CutValueToPrecisionFunction;
 /**
@@ -50,27 +61,30 @@ export declare function cutValueToPrecisionFunction(precision: NumberPrecision,
 export type RoundToPrecisionFunction = MapFunction<number, number>;
 export type RoundToPrecisionFunctionType = NumberRounding | 'cut';
 /**
- * Creates a RoundToPrecisionFunction
+ * Creates a function that rounds numbers to the specified precision using a configurable rounding strategy.
  *
- * @param precision
- * @param roundFn
- * @returns
+ * @param precision - Number of decimal places
+ * @param roundFn - Rounding strategy; defaults to 'round'. Use 'cut' for truncation.
+ * @returns A function that rounds numbers to the configured precision
  */
 export declare function roundToPrecisionFunction(precision: NumberPrecision, roundFn?: RoundToPrecisionFunctionType): RoundToPrecisionFunction;
 /**
- * Rounds the input number to the given precision using a specific rounding function.
+ * Rounds a number to the specified decimal precision using `Math.round`.
  *
- * @param value
- * @param precision
- * @returns
+ * @param value - Number to round
+ * @param precision - Number of decimal places to retain
+ * @returns The rounded number
  */
 export declare function roundToPrecision(value: number, precision: NumberPrecision): number;
 /**
- * Cuts the input number to the given precision. For example, 1.25 with precision 1 will not be rounded up to 1.3, but instead be "cut" to 1.2
+ * Truncates a number to the specified decimal precision without rounding.
  *
- * @param value
- * @param precision
- * @returns
+ * Uses `Math.floor` for positive numbers and `Math.ceil` for negative numbers to truncate toward zero.
+ * For example, 1.25 with precision 1 becomes 1.2 (not 1.3).
+ *
+ * @param value - Number to truncate
+ * @param precision - Number of decimal places to retain
+ * @returns The truncated number
  */
 export declare function cutToPrecision(value: number, precision: NumberPrecision): number;
 /**
@@ -82,13 +96,11 @@ export type StepNumber = number;
  */
 export type StepOrigin = number;
 /**
- * Rounds the number up to a specific "step" that contains it.
- *
- * For example, with the value of 2, and a step size of 5, the value will be rounded up to 1.
+ * Rounds a number up to the nearest multiple of the step size using `Math.ceil`.
  *
- * @param value Input value.
- * @param step Step size.
- * @returns Step that contains the value.
+ * @param value - Input value
+ * @param step - Step size to round up to
+ * @returns The nearest multiple of step that is >= value
  */
 export declare function roundNumberUpToStep(value: number, step: number): number;
 /**
@@ -117,4 +129,13 @@ export type RoundNumberToStepFunctionInput = RoundNumberToStepFunctionConfig | S
 export type RoundNumberToStepFunction = ((input: Maybe<number>) => number) & {
     readonly _round: RoundNumberToStepFunctionConfig;
 };
+/**
+ * Creates a function that rounds numbers to the nearest step multiple using a configurable rounding strategy.
+ *
+ * Accepts either a step number (uses 'ceil' rounding) or a full config with step, rounding type, and origin.
+ *
+ * @param input - Step size or full configuration
+ * @returns A function that rounds input numbers to the nearest step
+ * @throws Error if step is 0 or undefined
+ */
 export declare function roundNumberToStepFunction(input: RoundNumberToStepFunctionInput): RoundNumberToStepFunction;

package/src/lib/number/sort.d.ts

@@ -5,7 +5,13 @@ import { type ReadNumberFunction } from './number';
  */
 export type SortByNumberFunction<T> = SortCompareFunction<T>;
 /**
- * Creates a SortByNumberFunction that sorts values in ascending order.
+ * Creates a {@link SortCompareFunction} that sorts values in ascending order by a numeric property.
+ *
+ * @param readNumberFn - Function that extracts the numeric value from each item
+ * @returns A sort comparator function for ascending numeric order
  */
 export declare function sortByNumberFunction<T>(readNumberFn: ReadNumberFunction<T>): SortByNumberFunction<T>;
+/**
+ * Pre-built sort comparator for sorting plain numbers in ascending order.
+ */
 export declare const sortNumbersAscendingFunction: SortByNumberFunction<number>;

package/src/lib/number/transform.d.ts

@@ -25,5 +25,21 @@ export interface TransformNumberFunctionConfigRef<N extends number = number> {
 }
 export type TransformNumberFunction<N extends number = number> = MapFunction<N, N>;
 export type TransformNumberFunctionConfigInput<S extends number = number> = TransformNumberFunctionConfig<S> | TransformNumberFunction<S>;
+/**
+ * Normalizes a {@link TransformNumberFunctionConfigInput} to a {@link TransformNumberFunctionConfig}.
+ *
+ * If a function is provided, wraps it as the `transform` field. Returns undefined for undefined input.
+ *
+ * @param config - A config object, a transform function, or undefined
+ * @returns The normalized config, or undefined
+ */
 export declare function transformNumberFunctionConfig<S extends number = number>(config?: TransformNumberFunctionConfigInput<S>): Maybe<TransformNumberFunctionConfig<S>>;
+/**
+ * Creates a composite number transform function from a {@link TransformNumberFunctionConfig}.
+ *
+ * Chains the configured operations in order: custom transform, step rounding, precision cut, then bounds clamping.
+ *
+ * @param config - Configuration with optional transform, roundToStep, precision, and bounds
+ * @returns A single function that applies all configured transformations in sequence
+ */
 export declare function transformNumberFunction<N extends number = number>(config: TransformNumberFunctionConfig<N>): TransformNumberFunction<N>;

package/src/lib/object/object.array.d.ts

@@ -1,9 +1,23 @@
 import { type ArrayOrValue } from '../array';
 /**
- * Convenience function for objectMergeMatrix that returns a flat array.
+ * Creates a flattened array of merged objects by computing the cross-product of arrays a and b,
+ * merging each pair with spread syntax.
+ *
+ * Convenience wrapper around {@link objectMergeMatrix} that flattens the result.
+ *
+ * @param a - First array (or single value) of partial objects
+ * @param b - Second array (or single value) of partial objects
+ * @returns Flat array of merged objects
  */
 export declare function objectFlatMergeMatrix<A extends object = object, B extends object = object>(a: ArrayOrValue<Partial<A>>, b: ArrayOrValue<Partial<B>>): (Partial<A> & Partial<B>)[];
 /**
- * Creates a matrix of results by merging the input. If either a or b is null/undefined, the result is returned as an array of the other value.
+ * Creates a 2D matrix of merged objects from the cross-product of arrays a and b.
+ *
+ * Each element in the matrix is the spread merge of one item from a with one item from b.
+ * If either input is null/undefined, returns the other as a single-row matrix.
+ *
+ * @param a - First array (or single value) of partial objects
+ * @param b - Second array (or single value) of partial objects
+ * @returns 2D array where result[i][j] is `{ ...a[i], ...b[j] }`
  */
 export declare function objectMergeMatrix<A extends object = object, B extends object = object>(a: ArrayOrValue<Partial<A>>, b: ArrayOrValue<Partial<B>>): (Partial<A> & Partial<B>)[][];

package/src/lib/object/object.array.delta.d.ts

@@ -40,8 +40,12 @@ export interface ObjectDeltaArrayCompressor<T extends object> {
     readonly expand: ObjectDeltaArrayCompressorExpandFunction<T>;
 }
 /**
- * Creates an object delta array compressor.
+ * Creates an {@link ObjectDeltaArrayCompressor} that can compress and expand arrays of objects using delta encoding.
  *
- * @param compressor
+ * The first object is stored fully. Subsequent objects store only fields that changed from the previous entry.
+ * Null in a delta entry means the field was cleared. Undefined (missing key) means no change.
+ *
+ * @param config - Configuration with the equality checker that defines which fields to track
+ * @returns A compressor with `compress` and `expand` methods
  */
 export declare function objectDeltaArrayCompressor<T extends object>(config: ObjectDeltaArrayCompressorConfig<T>): ObjectDeltaArrayCompressor<T>;

package/src/lib/object/object.d.ts

@@ -10,22 +10,50 @@ export type POJOKey = PrimativeKey | symbol;
  */
 export type ObjectKey = string;
 export type EmptyObject = Record<string, never>;
+/**
+ * Checks whether the object has no own enumerable keys.
+ *
+ * @param obj - Object to check
+ * @returns `true` if the object has zero keys
+ */
 export declare function objectHasNoKeys(obj: object): obj is EmptyObject;
+/**
+ * Checks whether the object has the specified own property using `Object.prototype.hasOwnProperty`.
+ *
+ * @param obj - Object to check
+ * @param key - Property key to test for
+ * @returns `true` if the object has the key as an own property
+ */
 export declare function objectHasKey<T>(obj: T, key: KeyAsString<keyof T>): boolean;
 export declare function objectHasKey(obj: unknown, key: string): boolean;
 export declare function objectHasKey<T, K extends keyof T>(obj: T, key: K): boolean;
 /**
- * Returns true if the object has all or any of the keys, based on the input mode. Defaults to all.
+ * Checks whether the object has all or any of the specified keys, based on the mode.
  *
- * @param obj
- * @param keys
+ * @param obj - Object to check
+ * @param keys - Keys to test for
+ * @param mode - Whether to require 'all' keys or just 'any'; defaults to 'all'
+ * @returns `true` if the keys match the mode criteria
  */
 export declare function objectHasKeys<T>(obj: T, keys: KeyAsString<keyof T>[], mode?: SetIncludesMode): boolean;
 export declare function objectHasKeys(obj: unknown, keys: ObjectKey[], mode?: SetIncludesMode): boolean;
 export declare function objectHasKeys<T, K extends keyof T>(obj: T, keys: K[], mode?: SetIncludesMode): boolean;
+/**
+ * Creates a partial object with the same value assigned to each of the specified fields.
+ *
+ * @param value - The value to assign to each field
+ * @param fields - Array of field names to set
+ * @returns A partial object with the value set on each specified field
+ */
 export declare function applyToMultipleFields<T extends object, X = unknown>(value: X, fields: FieldOfType<T>[]): Partial<{
     [K in keyof T]: X;
 }>;
+/**
+ * Converts a Map to a plain object by iterating entries and assigning key-value pairs.
+ *
+ * @param map - Map to convert
+ * @returns A plain object with the same key-value pairs
+ */
 export declare function mapToObject<T, K extends PropertyKey>(map: Map<K, T>): {
     [key: PropertyKey]: T;
 };
@@ -36,7 +64,7 @@ export type CopyObjectFunction<T> = (input: T) => T;
 /**
  * Creates a shallow copy of an object using the spread operator.
  *
- * @param input
- * @returns
+ * @param input - Object to copy
+ * @returns A new object with the same properties
  */
 export declare function copyObject<T extends object>(input: T): T;

package/src/lib/object/object.empty.d.ts

@@ -1,7 +1,9 @@
 import { type Maybe } from '../value/maybe.type';
 /**
- * Recursively function that returns true if the input is not an object or if every key on the object is empty.
+ * Recursively checks whether an object is "empty" — meaning it is null/undefined, has no keys,
+ * or all of its values are themselves empty (recursively for nested objects, or falsy for primitives).
  *
- * @param obj
+ * @param obj - Object to check
+ * @returns `true` if the object is considered empty
  */
 export declare function objectIsEmpty<T extends object>(obj: Maybe<T>): boolean;

package/src/lib/object/object.equal.d.ts

@@ -2,15 +2,24 @@ import { type FieldOfType } from '../key';
 import { type EqualityComparatorFunction } from '../value/comparator';
 import { type FilterFromPOJOFunction } from './object.filter.pojo';
 /**
- * Performs a deep comparison to check if all values on the input filters are equal.
+ * Performs a deep equality comparison between two values.
  *
- * Recursively compares Arrays, Objects, Maps, Sets, Primatives, and Dates.
+ * Recursively compares arrays, objects, Maps, Sets, primitives, and Dates.
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns `true` if the values are deeply equal
  */
 export declare function areEqualPOJOValues<F>(a: F, b: F): boolean;
 /**
- * Performs a deep comparison to check if all values on the input filters are equal. Each input is run through the pojo filter
+ * Performs a deep equality comparison with a POJO filter applied to each value before comparison.
+ *
+ * Recursively compares arrays, objects, Maps, Sets, primitives, and Dates.
  *
- * Recursively compares Arrays, Objects, Maps, Sets, Primatives, and Dates.
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @param pojoFilter - Filter function applied to each value before comparison
+ * @returns `true` if the filtered values are deeply equal
  */
 export declare function areEqualPOJOValuesUsingPojoFilter<F>(a: F, b: F, pojoFilter: FilterFromPOJOFunction<F>): boolean;
 /**
@@ -70,4 +79,12 @@ export interface ObjectFieldEqualityCheckResults<T extends object> {
 export type ObjectFieldEqualityChecker<T extends object> = ((a: Partial<T>, b: Partial<T>) => ObjectFieldEqualityCheckResults<T>) & {
     readonly _fields: Map<keyof T, ObjectFieldEqualityCheckerFieldConfig<T, any>>;
 };
+/**
+ * Creates an {@link ObjectFieldEqualityChecker} that compares two objects field-by-field using configured equality functions.
+ *
+ * Fields can be specified as simple field names (using the default `===` comparator) or as config objects with custom comparators.
+ *
+ * @param config - Configuration with the fields to compare and an optional default equality function
+ * @returns A function that compares two objects and reports which fields are equal/unequal
+ */
 export declare function objectFieldEqualityChecker<T extends object>(config: ObjectFieldEqualityCheckerConfig<T>): ObjectFieldEqualityChecker<T>;

package/src/lib/object/object.filter.tuple.d.ts

@@ -1,19 +1,88 @@
 import { type FilterFunction } from '../filter/filter';
 import { type KeyAsString } from '../type';
+/**
+ * Callback invoked for each key/value tuple during iteration.
+ */
 export type ForEachKeyValueTupleFunction<T extends object = object, K extends keyof T = keyof T> = (tuple: KeyValueTuple<T, K>, index: number) => void;
+/**
+ * Configuration for {@link forEachKeyValue} specifying a filter and a forEach callback.
+ */
 export interface ForEachKeyValue<T extends object = object, K extends keyof T = keyof T> {
     readonly filter?: FilterKeyValueTuplesInput<T, K>;
     readonly forEach: ForEachKeyValueTupleFunction<T, K>;
 }
+/**
+ * Iterates over filtered key/value tuples of an object and invokes a callback for each.
+ *
+ * @param obj - Object to iterate
+ * @param config - Configuration with a forEach callback and optional filter
+ *
+ * @example
+ * ```ts
+ * const keys: string[] = [];
+ * forEachKeyValue({ a: 1, b: undefined, c: 3 }, {
+ *   filter: KeyValueTypleValueFilter.UNDEFINED,
+ *   forEach: ([key]) => keys.push(key as string)
+ * });
+ * // keys: ['a', 'c']
+ * ```
+ */
 export declare function forEachKeyValue<T extends object = object, K extends keyof T = keyof T>(obj: T, { forEach, filter }: ForEachKeyValue<T, K>): void;
+/**
+ * Extracts key/value tuples from an object, optionally filtering them.
+ *
+ * @param obj - Object to extract tuples from
+ * @param filter - Optional filter to apply to the tuples
+ * @returns Array of matching key/value tuples
+ *
+ * @example
+ * ```ts
+ * const tuples = filterKeyValueTuples({ a: 1, b: null, c: 3 }, KeyValueTypleValueFilter.NULL);
+ * // tuples: [['a', 1], ['c', 3]]
+ * ```
+ */
 export declare function filterKeyValueTuples<T extends object = object, K extends keyof T = keyof T>(obj: T, filter?: FilterKeyValueTuplesInput<T, K>): KeyValueTuple<T, K>[];
 /**
  * A Key-Value pair within an Tuple array value.
  */
 export type KeyValueTuple<T extends object = object, K extends keyof T = keyof T> = [K, T[K]];
+/**
+ * Function that extracts key/value tuples from an object, optionally filtering them based on a pre-configured filter.
+ */
 export type FilterKeyValueTuplesFunction<T extends object = object, K extends keyof T = keyof T> = (obj: T) => KeyValueTuple<T, K>[];
+/**
+ * Creates a reusable function that extracts and filters key/value tuples from objects.
+ *
+ * When no filter is provided, returns all key/value tuples.
+ *
+ * @param filter - Optional filter configuration
+ * @returns A function that extracts filtered tuples from any input object
+ *
+ * @example
+ * ```ts
+ * const getDefinedTuples = filterKeyValueTuplesFunction(KeyValueTypleValueFilter.UNDEFINED);
+ * const tuples = getDefinedTuples({ a: 1, b: undefined, c: 'hello' });
+ * // tuples: [['a', 1], ['c', 'hello']]
+ * ```
+ */
 export declare function filterKeyValueTuplesFunction<T extends object = object, K extends keyof T = keyof T>(filter?: FilterKeyValueTuplesInput<T, K>): FilterKeyValueTuplesFunction<T, K>;
+/**
+ * Returns all key/value pairs from the object as tuples using `Object.entries`.
+ *
+ * @param obj - Object to extract tuples from
+ * @returns Array of `[key, value]` tuples
+ *
+ * @example
+ * ```ts
+ * const tuples = allKeyValueTuples({ x: 10, y: 20 });
+ * // tuples: [['x', 10], ['y', 20]]
+ * ```
+ */
 export declare function allKeyValueTuples<T extends object = object, K extends keyof T = keyof T>(obj: T): KeyValueTuple<T, K>[];
+/**
+ * Input for configuring key/value tuple filtering. Can be a {@link KeyValueTypleValueFilter} enum for simple cases
+ * or a {@link KeyValueTupleFilter} object for more complex filtering (value type + key restriction + inversion).
+ */
 export type FilterKeyValueTuplesInput<T extends object = object, K extends keyof T = keyof T> = KeyValueTypleValueFilter | KeyValueTupleFilter<T, K>;
 /**
  * Value filter options for filterKeyValueTupleFunction()
@@ -52,17 +121,50 @@ export declare enum KeyValueTypleValueFilter {
      */
     FALSY_AND_EMPTY_STRICT = 7
 }
+/**
+ * Full configuration for filtering key/value tuples, supporting value type filtering, key restriction, and inversion.
+ */
 export interface KeyValueTupleFilter<T extends object = object, K extends keyof T = keyof T> {
+    /**
+     * Type of value filtering to apply.
+     */
     valueFilter?: KeyValueTypleValueFilter;
+    /**
+     * When `true`, inverts the filter so that only non-matching tuples are retained.
+     */
     invertFilter?: boolean;
+    /**
+     * Restricts filtering to only these keys. Other keys are excluded from the result.
+     */
     keysFilter?: (K | KeyAsString<K>)[];
 }
 /**
- * Converts an input FilterKeyValueTuplesInput to a KeyValueTupleFilter.
+ * Normalizes a {@link FilterKeyValueTuplesInput} to a {@link KeyValueTupleFilter} object.
+ *
+ * If the input is already an object, returns it as-is. If it's an enum value, wraps it in a filter object.
  *
- * @param input
- * @returns
+ * @param input - Enum value or filter object
+ * @returns Normalized filter object
  */
 export declare function filterKeyValueTuplesInputToFilter<T extends object = object, K extends keyof T = keyof T>(input: FilterKeyValueTuplesInput<T, K>): KeyValueTupleFilter<T, K>;
+/**
+ * Predicate function that tests a single key/value tuple, returning `true` if it passes the filter.
+ */
 export type FilterKeyValueTupleFunction<T extends object = object, K extends keyof T = keyof T> = FilterFunction<KeyValueTuple<T, K>>;
+/**
+ * Creates a filter predicate function for key/value tuples based on the provided filter configuration.
+ *
+ * The predicate returns `true` for tuples whose values pass the configured filter. Supports value type filtering
+ * (undefined, null, falsy, empty), key filtering, and inversion.
+ *
+ * @param inputFilter - Filter configuration (enum value or full config object)
+ * @returns A predicate function that tests individual key/value tuples
+ *
+ * @example
+ * ```ts
+ * const isNotNull = filterKeyValueTupleFunction(KeyValueTypleValueFilter.NULL);
+ * isNotNull(['a', 1], 0);    // true
+ * isNotNull(['b', null], 0); // false
+ * ```
+ */
 export declare function filterKeyValueTupleFunction<T extends object = object, K extends keyof T = keyof T>(inputFilter: FilterKeyValueTuplesInput<T, K>): FilterKeyValueTupleFunction<T, K>;

package/src/lib/object/object.key.d.ts

@@ -2,16 +2,23 @@ import { type PrimativeKey, type ReadKeyFunction, type ReadMultipleKeysFunction
 import { type Maybe } from '../value/maybe.type';
 import { type EqualityComparatorFunction } from '../value/comparator';
 /**
- * Creates a EqualityComparatorFunction that compares the two input values
+ * Creates an {@link EqualityComparatorFunction} that compares two arrays of objects by extracting keys
+ * and checking that both arrays contain the same set of keys (order-independent).
  *
- * @param readKey
- * @returns
+ * Returns `true` if both arrays have the same length and produce identical key sets.
+ * Handles `null`/`undefined` inputs via {@link safeEqualityComparatorFunction}.
+ *
+ * @param readKey - Function to extract one or more keys from each object
+ * @returns An equality comparator for arrays of keyed objects
  */
 export declare function objectKeysEqualityComparatorFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): EqualityComparatorFunction<Maybe<T[]>>;
 /**
- * Creates a EqualityComparatorFunction that compares the two input values
+ * Creates an {@link EqualityComparatorFunction} that compares two objects by extracting a single key
+ * from each and checking strict equality.
+ *
+ * Handles `null`/`undefined` inputs via {@link safeEqualityComparatorFunction}.
  *
- * @param readKey
- * @returns
+ * @param readKey - Function to extract the key from an object
+ * @returns An equality comparator for keyed objects
  */
 export declare function objectKeyEqualityComparatorFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>): EqualityComparatorFunction<Maybe<T>>;

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

@@ -12,14 +12,17 @@ export type StringObjectMap<T> = {
     [key: number]: never;
     [key: symbol]: never;
 };
+/**
+ * Mapped type that preserves the keys of `M` but replaces all value types with `O`.
+ */
 export type MappedObjectMap<M extends object, O> = {
     [key in keyof M]: O;
 };
 /**
- * Converts an ObjectMap into a Map.
+ * Converts an {@link ObjectMap} into a `Map` using `Object.entries`.
  *
- * @param object
- * @returns
+ * @param object - The object map to convert
+ * @returns A `Map` with the same key-value pairs
  */
 export declare function objectToMap<T>(object: ObjectMap<T>): Map<string, T>;
 /**
@@ -27,26 +30,31 @@ export declare function objectToMap<T>(object: ObjectMap<T>): Map<string, T>;
  */
 export type MapObjectMapFunction<M extends ObjectMap<I>, I = unknown, O = unknown> = MapFunction<M, MappedObjectMap<M, O>>;
 /**
- * Creates a MapObjectMapFunction that calls mapObjectMap().
+ * Creates a reusable {@link MapObjectMapFunction} that applies {@link mapObjectMap} with the given mapping function.
  *
- * @param mapFn
- * @returns
+ * @param mapFn - Function that transforms each value (receives value and key)
+ * @returns A function that maps all values in an input object map
  */
 export declare function mapObjectMapFunction<M extends ObjectMap<I>, I = unknown, O = unknown>(mapFn: MapObjectMapValueFunction<M, I, O>): MapObjectMapFunction<M, I, O>;
+/**
+ * Mapping function that transforms a single value from an {@link ObjectMap}, receiving both the value and its key.
+ */
 export type MapObjectMapValueFunction<M extends ObjectMap<I>, I = unknown, O = unknown> = <K extends keyof M>(value: M[K], key: K) => O;
 /**
- * Maps the values of an ObjectMap from one type to another and returns an ObjectMap containing that type.
+ * Maps all values of an {@link ObjectMap} from one type to another, returning a new object with the same keys.
  *
- * @param object
+ * @param object - The source object map
+ * @param mapFn - Function that transforms each value
+ * @returns A new object with mapped values
  */
 export declare function mapObjectMap<M extends ObjectMap<I>, I = unknown, O = unknown>(object: M, mapFn: MapObjectMapValueFunction<M, I, O>): MappedObjectMap<M, O>;
 /**
- * Maps the values of an ObjectMap from one type to the target and return the target.
+ * Maps the values of a source {@link ObjectMap} and assigns the results onto the target object, returning the target.
  *
- * @param object
- * @param target
- * @param mapFn
- * @returns
+ * @param object - The source object map
+ * @param target - The target object to assign mapped values onto
+ * @param mapFn - Function that transforms each value
+ * @returns The target object with mapped values assigned
  */
 export declare function mapObjectToTargetObject<M extends ObjectMap<I>, I = unknown, O = unknown>(object: M, target: MappedObjectMap<M, O>, mapFn: MapObjectMapValueFunction<M, I, O>): MappedObjectMap<M, O>;
 /**
@@ -58,19 +66,22 @@ export type MapObjectKeysFunction<M> = (object: M) => any;
  */
 export type MapObjectKeyFunction<M> = <K extends keyof M>(key: K, value: M[K]) => POJOKey;
 /**
- * Maps the keys of the input object to a new object with the mapped keys.
+ * Creates a reusable {@link MapObjectKeysFunction} that transforms the keys of an input object using the given mapping function.
  *
- * @param object
+ * @param mapKeyFn - Function that computes the new key from the old key and its value
+ * @returns A function that remaps keys on any input object
  */
 export declare function mapObjectKeysFunction<M extends object>(mapKeyFn: MapObjectKeyFunction<M>): MapObjectKeysFunction<M>;
+/**
+ * Mapped type that converts all string keys of `M` to lowercase while preserving their value types.
+ */
 export type MappedKeysToLowercaseObjectMap<M extends object> = {
     [K in keyof M as K extends string ? Lowercase<K> : K]: M[K];
 };
 /**
- * Maps all the keys of an object to a new object with keys of the object mapped to lowercase.
+ * Pre-built function that maps all string keys of an object to lowercase, returning a new object.
  *
- * @param object
- * @param target
- * @param mapFn
+ * Non-string keys (e.g., numbers) are passed through unchanged.
+ * When multiple keys map to the same lowercase key, the last one wins (order is undefined).
  */
 export declare const mapObjectKeysToLowercase: <M extends object>(object: M) => MappedKeysToLowercaseObjectMap<M>;