@dereekb/util 13.0.7 → 13.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.0.7",
+  "version": "13.1.0",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -29,7 +29,6 @@
     "ts-essentials": "^10.0.0"
   },
   "devDependencies": {
-    "class-validator": "^0.15.1",
     "date-fns": "4.0.0"
   },
   "module": "./index.esm.js",

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

@@ -1,106 +1,149 @@
 import { type IterableOrValue } from '../iterable/iterable';
 import { type Maybe } from '../value/maybe.type';
+/**
+ * An array type that cannot contain any elements.
+ */
 export type EmptyArray = never[];
+/**
+ * A value that is either a single item of type T or an array of T items.
+ */
 export type ArrayOrValue<T> = T | T[];
 /**
- * Converts the input value to an array containing itself, or returns itself if it is a non-empty array. Otherwise returns undefined.
+ * Converts the input value to an array containing itself, or returns itself if it is a non-empty array. Returns undefined if the input is nullish or results in an empty array.
  *
- * @param arrayOrValue
- * @returns
+ * @param arrayOrValue - single value or array to convert
+ * @returns an array with at least one element, or undefined if the result would be empty
  */
 export declare function convertMaybeToNonEmptyArray<T>(arrayOrValue: Maybe<ArrayOrValue<T>>): Maybe<T[]>;
 /**
- * Converts the input value to an array containing itself, or returns itself if it is an array.
+ * Converts the input value to an array containing itself, or returns itself if it is an array. Returns an empty array if the input is nullish.
  *
- * @param arrayOrValue
- * @returns
+ * @param arrayOrValue - single value, array, or nullish value to convert
+ * @returns the input wrapped in an array, the input array itself, or an empty array if nullish
  */
 export declare function convertMaybeToArray<T>(arrayOrValue: Maybe<ArrayOrValue<T>>): T[];
+/**
+ * Alias for {@link convertMaybeToArray}. Converts a maybe value or array into an array, returning an empty array for nullish input.
+ */
 export declare const asArray: typeof convertMaybeToArray;
+/**
+ * Alias for {@link convertMaybeToNonEmptyArray}. Converts a maybe value or array into a non-empty array, returning undefined for nullish or empty input.
+ */
 export declare const asNonEmptyArray: typeof convertMaybeToNonEmptyArray;
 /**
- * Converts the input value to an array containing itself, or returns itself if it is an array.
+ * Converts the input value to an array containing itself, or returns itself if it is already an array.
  *
- * @param arrayOrValue
- * @returns
+ * @param arrayOrValue - single value or array to convert
+ * @returns the input array unchanged, or a new single-element array wrapping the input value
  */
 export declare function convertToArray<T>(arrayOrValue: ArrayOrValue<T>): T[];
 /**
- * Returns the first value from the array.
+ * Returns the first value from the array, or the value itself if not an array.
+ *
+ * @param input - single value or array to retrieve from
+ * @returns the first element of the array, or the input value itself
  */
 export declare function firstValue<T>(input: ArrayOrValue<T>): T;
 /**
- * Returns the last value from the array.
+ * Returns the last value from the array, or the value itself if not an array.
+ *
+ * @param input - single value or array to retrieve from
+ * @returns the last element of the array, or the input value itself
  */
 export declare function lastValue<T>(input: ArrayOrValue<T>): T;
 /**
  * Returns a tuple with the first and last value of the input.
  *
- * If the input is not an array, returns that value as the first and last value.
+ * If the input is not an array, returns that value as both the first and last value.
  *
- * @param input
- * @returns
+ * @param input - single value or array to retrieve from
+ * @returns a two-element tuple of the first and last values
  */
 export declare function firstAndLastValue<T>(input: ArrayOrValue<T>): [T, T];
+/**
+ * Returns the value at the given index from an array, or the value itself if not an array.
+ *
+ * @param input - single value or array to retrieve from
+ * @param index - zero-based index of the element to retrieve
+ * @returns the element at the specified index, or the input value itself if not an array
+ */
 export declare function valueAtIndex<T>(input: ArrayOrValue<T>, index: number): T;
 /**
- * Concatinates the input arrays and filters out falsy values.
+ * Concatenates the input arrays into a single array, filtering out nullish entries.
+ *
+ * @param arrays - arrays to concatenate; nullish entries are ignored
+ * @returns a single flattened array containing all elements from the non-nullish input arrays
  */
 export declare function concatArrays<T>(...arrays: Maybe<T[]>[]): T[];
 /**
- * Flattens a two dimensional array into a single dimensional array. Any null/undefined values from the first dimension are filtered out.
+ * Flattens a two-dimensional array into a single-dimensional array. Any null/undefined entries in the outer dimension are filtered out.
  *
- * @param array
- * @returns
+ * @param array - two-dimensional array to flatten, may contain nullish entries
+ * @returns a single-dimensional array with all elements from the non-nullish inner arrays
  */
 export declare function flattenArray<T>(array: Maybe<T[]>[]): T[];
 /**
- * Flattens an array of ArrayOrValue values into a single array.
+ * Flattens an array of {@link ArrayOrValue} entries into a single array. Nullish entries are filtered out.
  *
- * @param array
- * @returns
+ * @param array - array of single values or arrays to flatten
+ * @returns a single flat array containing all non-nullish elements
  */
 export declare function flattenArrayOrValueArray<T>(array: ArrayOrValue<Maybe<T>>[]): T[];
+/**
+ * Creates a shallow copy of the input array. Returns an empty array if the input is nullish.
+ *
+ * @param input - array to copy, or nullish
+ * @returns a new array with the same elements, or an empty array if input is nullish
+ */
 export declare function copyArray<T>(input: Maybe<T[]>): T[];
+/**
+ * Pushes the same element onto the target array a specified number of times.
+ *
+ * @param target - array to push elements into
+ * @param element - element to push
+ * @param times - number of times to push the element
+ * @returns the mutated target array
+ */
 export declare function pushElementOntoArray<T>(target: T[], element: T, times: number): T[];
 /**
- * Merges all input arrays into a single array.
+ * Merges all input arrays into a single new array. Nullish entries are ignored.
  *
- * @param arrays
- * @returns
+ * @param arrays - arrays to merge; nullish entries are skipped
+ * @returns a new array containing all elements from the provided arrays
  */
 export declare function mergeArrays<T>(arrays: Maybe<T[]>[]): T[];
 /**
- * Merges the input arrays into the target array by pushing each item from each array. Creates an empty array if the target is null/undefined.
+ * Merges the input arrays into the target array by pushing each item from each array. Creates an empty array if the target is nullish.
  *
- * @param target
- * @param arrays
- * @returns
+ * @param target - array to merge into; a new array is created if nullish
+ * @param arrays - arrays whose elements are pushed into the target; nullish entries are skipped
+ * @returns the mutated target array, or a new array if the target was nullish
  */
 export declare function mergeArraysIntoArray<T>(target: Maybe<T[]>, ...arrays: Maybe<T[]>[]): T[];
 /**
- * Pushes the input value into the target array if it is not an array. If it is an array, inserts all values from that array into the target array.
+ * Pushes the input value into the target array if it is not an array. If it is an array, pushes all of its elements into the target array.
  *
- * @param target
- * @param value
- * @returns
+ * @param target - array to push into
+ * @param value - single value or array of values to add
+ * @returns the mutated target array
  */
 export declare function pushItemOrArrayItemsIntoArray<T>(target: T[], value: ArrayOrValue<T>): T[];
 /**
- * Merges all the values from the second array into the first using push.
+ * Merges all elements from the source array into the target array using push.
  *
  * This is preferable in cases where immutability is not required.
  *
- * @param target
- * @param array
+ * @param target - array to push elements into
+ * @param array - source array whose elements are pushed into the target
+ * @returns the mutated target array
  */
 export declare function pushArrayItemsIntoArray<T>(target: T[], array: T[]): T[];
 /**
- * Copies/takes the elements from the front of the array up to the max.
+ * Copies/takes the elements from the front of the array up to the specified maximum.
  *
- * @param values
- * @param maxToTake
- * @returns
+ * @param values - source array to take from
+ * @param maxToTake - maximum number of elements to take from the front
+ * @returns a new array containing at most maxToTake elements from the front
  */
 export declare function takeFront<T>(values: T[], maxToTake: number): T[];
 /**
@@ -138,23 +181,25 @@ export declare function splitFront<T>(values: T[], maxToTake: number): SplitFron
  */
 export declare function takeLast<T>(values: T[], maxToTake: number, keepFromFront?: number): T[];
 /**
- * Performs forEach with the input array and returns the array.
+ * Performs a forEach iteration over the input and returns the resulting array. If the input is nullish, returns an empty array.
  *
- * @param array
- * @param forEach
- * @returns
+ * @param array - single value, array, or nullish value to iterate over
+ * @param forEach - callback invoked for each element
+ * @returns the array that was iterated over, or an empty array if the input was nullish
  */
 export declare function forEachWithArray<T>(array: Maybe<ArrayOrValue<T>>, forEach: (value: T) => void): T[];
 /**
- * Counts all the values in a nested array.
+ * Counts the total number of elements across all inner arrays of a nested array.
  *
- * @param array
- * @returns
+ * @param array - two-dimensional array whose elements are counted
+ * @returns the total number of elements across all inner arrays
  */
 export declare function countAllInNestedArray<T>(array: T[][]): number;
 /**
  * Creates a copy of the array with the items at the specified indexes removed.
  *
- * @param array
+ * @param array - source array to copy from
+ * @param removeIndexes - indexes of elements to exclude from the copy
+ * @returns a new array without the elements at the specified indexes
  */
 export declare function removeValuesAtIndexesFromArrayCopy<T>(array: T[], removeIndexes: IterableOrValue<number>): T[];

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

@@ -1,33 +1,29 @@
 import { type SetIncludesMode } from '../set/set.mode';
 /**
- * A decision function used by the array find function.
- * Similar to the predicate function in Array.prototype.find() or Array.prototype.filter().
- * @template T - The type of elements in the array
+ * Predicate function that tests an individual array element, similar to the callback used by {@link Array.prototype.find} or {@link Array.prototype.filter}.
  */
 export type ArrayFindDecisionFunction<T> = (value: T, index: number, obj: T[]) => boolean;
 /**
- * Returns a decision about an array based on its input values using a preconfigured DecisionFunction and SetIncludesMode.
- *
- * @template T - The type of elements in the array
+ * Preconfigured function that evaluates an array and returns whether its elements satisfy a decision criterion based on a {@link SetIncludesMode}.
  */
 export type ArrayDecisionFunction<T> = (values: T[]) => boolean;
 /**
- * Creates an ArrayDecisionFunction based on the input decision and mode.
+ * Creates an {@link ArrayDecisionFunction} from a per-element predicate and a {@link SetIncludesMode}.
+ *
+ * When mode is `'any'`, the resulting function returns `true` if at least one element satisfies the predicate.
+ * When mode is `'all'`, it returns `true` only if every element satisfies the predicate.
  *
- * @template T - The type of elements in the array
- * @param decision - The function used to test individual elements of the array
- * @param mode - The mode determining how the decision is applied ('any' or 'all')
- * @returns A function that takes an array and returns a boolean decision based on the array elements
+ * @param decision - Predicate used to test individual elements.
+ * @param mode - Whether all or any elements must satisfy the predicate.
+ * @returns A function that evaluates an array against the configured decision criteria.
  */
 export declare function arrayDecisionFunction<T>(decision: ArrayFindDecisionFunction<T>, mode: SetIncludesMode): ArrayDecisionFunction<T>;
 /**
- * Returns true based on the input values and find decision.
- * A convenience function that creates and immediately applies an array decision function.
+ * Convenience wrapper that creates and immediately invokes an {@link ArrayDecisionFunction}.
  *
- * @template T - The type of elements in the array
- * @param values - The array to evaluate
- * @param decision - The function used to test individual elements of the array
- * @param mode - The mode determining how the decision is applied ('any' or 'all')
- * @returns A boolean indicating whether the array meets the decision criteria
+ * @param values - Array to evaluate.
+ * @param decision - Predicate used to test individual elements.
+ * @param mode - Whether all or any elements must satisfy the predicate.
+ * @returns `true` if the array satisfies the decision criteria for the given mode.
  */
 export declare function arrayDecision<T>(values: T[], decision: ArrayFindDecisionFunction<T>, mode: SetIncludesMode): boolean;

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

@@ -2,41 +2,70 @@ import { type AscendingSortCompareFunction } from '../sort';
 import { type IndexNumber, type IndexRef, type IndexRangeInput } from '../value/indexed';
 import { type Maybe } from '../value/maybe.type';
 /**
- * A set of number corresponding to items in an array.
+ * A set of index numbers corresponding to items in an array.
  *
- * This is useful for cases where you need the items in their index in the array.
+ * This is useful for cases where you need to reference items by their position in the array.
  */
 export type IndexSet = IndexNumber[];
+/**
+ * An array of {@link IndexSetPair} values, associating array items with their indices.
+ */
 export type IndexSetPairSet<T> = IndexSetPair<T>[];
+/**
+ * Pairs an array item with its index position.
+ */
 export interface IndexSetPair<T> extends IndexRef {
+    /** The item at the index, or undefined if no item exists at that position. */
     item: Maybe<T>;
 }
 /**
- * Runs a filter on an array and returns an IndexSet for values that match.
+ * Runs a filter on an array and returns an {@link IndexSet} containing the indices of values that match.
  *
- * @param input
- * @param filter
- * @returns
+ * @param input - array to search through
+ * @param filter - predicate function to test each value
+ * @returns an {@link IndexSet} of indices for matching values
  */
 export declare function findToIndexSet<T>(input: T[], filter: (value: T) => boolean): IndexSet;
+/**
+ * Expands an {@link IndexSet} into an {@link IndexSetPairSet} by pairing each index with the corresponding item from the input array.
+ *
+ * @param input - source array to retrieve items from
+ * @param indexSet - set of indices to expand
+ * @returns an {@link IndexSetPairSet} pairing each index with its corresponding item
+ */
 export declare function expandIndexSet<T>(input: T[], indexSet: IndexSet): IndexSetPairSet<T>;
 /**
- * Finds the best item in the input array using the compare function, and returns an IndexSetPair value.
+ * Finds the best item in the input array using the compare function, and returns an {@link IndexSetPair} value.
  *
- * @param input
- * @param compare
+ * The comparison follows ascending sort conventions: a negative return value from the compare function
+ * indicates the second argument is "better" than the first.
+ *
+ * @param input - array of items to search through
+ * @param compare - comparison function used to determine the best item
+ * @returns an {@link IndexSetPair} containing the best item and its index
  */
 export declare function findBest<T>(input: T[], compare: (a: T, b: T) => number): IndexSetPair<T>;
 /**
- * Finds the best item in the input IndexSetPairSet, and returns it.
+ * Finds the best item in the input {@link IndexSetPairSet} using the compare function, and returns it.
+ *
+ * Pairs with null/undefined items are skipped in favor of pairs with defined items.
  *
- * @param input
- * @param compare
- * @returns
+ * @param input - set of index-item pairs to search through
+ * @param compare - ascending sort comparison function used to determine the best item
+ * @returns the {@link IndexSetPair} containing the best item
  */
 export declare function findBestIndexSetPair<T>(input: IndexSetPairSet<T>, compare: AscendingSortCompareFunction<T>): IndexSetPair<T>;
 /**
- * Slices a configured index range from the input array.
+ * A function that slices a pre-configured index range from an input array.
+ *
+ * @param input - array to slice
+ * @returns the sliced portion of the array
  */
 export type SliceIndexRangeFunction<T> = (input: T[]) => T[];
+/**
+ * Creates a {@link SliceIndexRangeFunction} that slices the specified index range from any input array.
+ *
+ * @param inputRange - the index range configuration to use for slicing
+ * @returns a function that slices the configured range from an input array
+ */
 export declare function sliceIndexRangeFunction<T>(inputRange: IndexRangeInput): SliceIndexRangeFunction<T>;

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

@@ -2,59 +2,108 @@ import { type IndexNumber, type IndexRange, type ReadIndexRangeFunction } from '
 import { type Maybe } from '../value/maybe.type';
 import { type ArrayFindDecisionFunction } from './array.find';
 /**
- * Creates an IndexRange for the input array.
+ * Creates an IndexRange for the input array, spanning from index 0 to the array's length.
  *
- * @param array
- * @returns
+ * @param array - The array to create an index range for.
+ * @returns An IndexRange covering the full extent of the array.
  */
 export declare function indexRangeForArray<T>(array: T[]): IndexRange;
 /**
- * Finds a value, then returns the next value, if applicable.
+ * Finds a value in the array using the provided decision function, then returns the value at the next index.
  *
- * @param array array to look in
- * @param find find function
- * @param wrapAround Whether or not to loop around to the front of the array if the value fonud is at the last index.
- * @param steps
+ * @param array - The array to search through, or undefined/null.
+ * @param find - Decision function used to locate the target element.
+ * @param wrapAround - Whether to wrap around to the beginning of the array if the found value is at or near the last index.
+ * @param steps - Number of steps forward from the found index. Defaults to 1.
+ * @returns The value at the next index, or undefined if no match is found or no next value exists.
  */
 export declare function findNext<T>(array: Maybe<T[]>, find: ArrayFindDecisionFunction<T>, wrapAround?: boolean, steps?: number): Maybe<T>;
 /**
- * Returns the next index of an element in the input array based in the input index.
+ * Returns the next index of an element in the input array based on the input index.
  *
  * Indexes less than 0 are considered to not exist.
  *
  * When wrapAround is true, indexes that are larger than the entire array will be used to find an index that is that many steps into the array.
- *
  * For instance, an index of 5 on an array of length 3 will return the index 1.
  *
- * @param array
- * @param index
- * @param wrapAround
- * @param steps
+ * @param array - The array to compute the next index within.
+ * @param index - The current index to step from.
+ * @param wrapAround - Whether to wrap around when stepping past the end of the array.
+ * @param steps - Number of steps forward from the current index.
+ * @returns The computed next index, or undefined if the input index is out of bounds.
  */
 export declare function getArrayNextIndex<T>(array: T[], index: number, wrapAround?: boolean, steps?: number): Maybe<number>;
 /**
- * Returns a value given the input index if any value responds to the index.
+ * Accessor function that returns a value for the given index if any value's range contains that index.
  */
 export type RangedIndexedValuesArrayAccessor<T> = (index: IndexNumber) => Maybe<T>;
+/**
+ * Factory function that creates a {@link RangedIndexedValuesArrayAccessor} from an array of values.
+ */
 export type RangedIndexedValuesArrayAccessorFactory<T> = (values: T[]) => RangedIndexedValuesArrayAccessor<T>;
+/**
+ * Creates a factory that produces {@link RangedIndexedValuesArrayAccessor} instances.
+ *
+ * Each accessor maps an index to the value whose range contains that index, or undefined if no range matches.
+ *
+ * @param readIndexRange - Function that reads the index range from each value.
+ * @returns A factory that creates ranged accessors from arrays of values.
+ */
 export declare function rangedIndexedValuesArrayAccessorFactory<T>(readIndexRange: ReadIndexRangeFunction<T>): RangedIndexedValuesArrayAccessorFactory<T>;
 /**
- * Returns a value given the input index. Always returns a value.
+ * Accessor function that returns a value for the given index. Always returns a value by falling back to the nearest neighbor.
  */
 export type IndexedValuesArrayAccessor<T> = (index: IndexNumber) => T;
+/**
+ * Factory function that creates an {@link IndexedValuesArrayAccessor} from an array of values.
+ */
 export type IndexedValuesArrayAccessorFactory<T> = (values: T[]) => IndexedValuesArrayAccessor<T>;
+/**
+ * Creates a factory that produces {@link IndexedValuesArrayAccessor} instances.
+ *
+ * Each accessor maps an index to the matching value, falling back to the previous value, then the next value.
+ * This guarantees a value is always returned.
+ *
+ * @param readIndexRange - Function that reads the index range from each value.
+ * @returns A factory that creates indexed accessors from arrays of values.
+ * @throws Error if the provided values array is empty.
+ */
 export declare function indexedValuesArrayAccessorFactory<T>(readIndexRange: ReadIndexRangeFunction<T>): IndexedValuesArrayAccessorFactory<T>;
+/**
+ * Contains the match result for a ranged index lookup, including the matched value and its neighbors.
+ */
 export interface RangedIndexValuesArrayAccessorInfo<T> {
+    /** The value from the range immediately before the matched or queried range. */
     readonly prev?: Maybe<T>;
+    /** The value whose range contains the queried index, or undefined if no range matched. */
     readonly match?: Maybe<T>;
+    /** The value from the range immediately after the matched or queried range. */
     readonly next?: Maybe<T>;
 }
+/**
+ * Accessor function that returns detailed match info (match, previous, and next values) for the given index.
+ */
 export type RangedIndexedValuesArrayInfoAccessor<T> = (index: IndexNumber) => RangedIndexValuesArrayAccessorInfo<T>;
+/**
+ * Factory function that creates a {@link RangedIndexedValuesArrayInfoAccessor} from an array of values.
+ */
 export type RangedIndexedValuesArrayInfoAccessorFactory<T> = (values: T[]) => RangedIndexedValuesArrayInfoAccessor<T>;
+/**
+ * Configuration for {@link rangedIndexedValuesArrayAccessorInfoFactory}.
+ */
 export interface RangedIndexedValuesArrayInfoAccessorFactoryConfig<T> {
     /**
-     * Reads the index range. The IndexRange is treated as exclusive.
+     * Reads the index range from a value. The IndexRange is treated as exclusive.
      */
     readonly readIndexRange: ReadIndexRangeFunction<T>;
 }
+/**
+ * Creates a factory that produces {@link RangedIndexedValuesArrayInfoAccessor} instances.
+ *
+ * Each accessor sorts the values by their index ranges in ascending order, then for a given index
+ * returns the matching value along with its previous and next neighbors.
+ *
+ * @param config - Configuration containing the index range reader function.
+ * @returns A factory that creates ranged info accessors from arrays of values.
+ */
 export declare function rangedIndexedValuesArrayAccessorInfoFactory<T>(config: RangedIndexedValuesArrayInfoAccessorFactoryConfig<T>): RangedIndexedValuesArrayInfoAccessorFactory<T>;

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

@@ -1,4 +1,7 @@
 import { type Maybe } from '../value/maybe.type';
+/**
+ * Configuration for limiting the number of items returned from an array.
+ */
 export interface LimitArrayConfig {
     /**
      * Number of items in the list to limit in the result.
@@ -9,6 +12,14 @@ export interface LimitArrayConfig {
      */
     readonly limitFromEnd?: boolean;
 }
+/**
+ * Limits the number of items in an array based on the provided configuration.
+ * Items are taken from the front of the array by default, or from the end if configured.
+ *
+ * @param array - source array to limit
+ * @param inputConfig - configuration controlling the limit count and direction
+ * @returns a new array with at most the configured number of items, or the original array if no limit is specified
+ */
 export declare function limitArray<T>(array: T[], { limit, limitFromEnd }: Partial<LimitArrayConfig>): T[];
 export declare function limitArray<T>(array: Maybe<T[]>, { limit, limitFromEnd }: Partial<LimitArrayConfig>): Maybe<T[]>;
 export declare function limitArray<T>(array: Maybe<T[]>, config: Maybe<Partial<LimitArrayConfig>>): Maybe<T[]>;

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

@@ -1,5 +1,8 @@
 import { type FactoryWithInput } from '../getter';
 import { type RandomNumberFactoryInput, type RandomNumberFactory } from '../number/random';
+/**
+ * Configuration for creating an array of items using a factory function.
+ */
 export interface MakeArray<T> {
     readonly count: number;
     /**
@@ -7,6 +10,9 @@ export interface MakeArray<T> {
      */
     readonly make: FactoryWithInput<T, number>;
 }
+/**
+ * Configuration for creating a {@link RandomArrayFactory}. Combines a make function with a random number source to produce arrays of varying length.
+ */
 export interface RandomArrayFactoryConfig<T> extends Omit<MakeArray<T>, 'count'> {
     readonly random: RandomNumberFactory | RandomNumberFactoryInput;
 }
@@ -15,9 +21,9 @@ export interface RandomArrayFactoryConfig<T> extends Omit<MakeArray<T>, 'count'>
  */
 export type RandomArrayFactory<T> = FactoryWithInput<T[], number>;
 /**
- * Makes a function that generates arrays of a random length of a specific type.
+ * Creates a factory function that generates arrays of a random length populated with items from a make function.
  *
- * @param config
- * @returns
+ * @param config - configuration containing the make function and random number source
+ * @returns a factory that produces arrays of random length, optionally accepting a specific count override
  */
 export declare function randomArrayFactory<T>(config: RandomArrayFactoryConfig<T>): RandomArrayFactory<T>;

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

@@ -1,24 +1,36 @@
 import { type PrimativeKey, type ReadKeyFunction } from '../key';
 import { type Maybe } from '../value/maybe.type';
 /**
- * Maps the values of the input array to a Map. Can additionally specify a value function to map out the input value to another value for the map.
+ * Maps the values of the input array to a Map, keyed by the result of a key function.
+ * Optionally transforms each value using a value function.
+ *
+ * @param values - source array of items to map
+ * @param keyFn - function to extract a key from each item
+ * @param valueFn - optional function to transform each item into the desired map value
+ * @returns a Map of keys to values derived from the input array
  */
 export declare function arrayToMap<T, V, K extends PrimativeKey = PrimativeKey>(values: T[], keyFn: ReadKeyFunction<T, K>, valueFn: (t: T) => V): Map<Maybe<K>, V>;
 export declare function arrayToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], keyFn: ReadKeyFunction<T, K>, valueFn: (t: T) => T): Map<Maybe<K>, T>;
 export declare function arrayToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], keyFn: ReadKeyFunction<T, K>): Map<Maybe<K>, T>;
 /**
- * Maps the values of the input array to a Record object. Can additionally specify a value function to map out the input value to another value for the map.
+ * Maps the values of the input array to a Record object, keyed by the result of a key function.
+ * Items with undefined keys are omitted. Optionally transforms each value using a value function.
+ *
+ * @param values - source array of items to map
+ * @param keyFn - function to extract a key from each item
+ * @param valueFn - optional function to transform each item into the desired record value
+ * @returns a Record of keys to values derived from the input array
  */
 export declare function arrayToObject<T, V, K extends PrimativeKey = PrimativeKey>(values: T[], keyFn: ReadKeyFunction<T, K>, valueFn: (t: T) => V): Record<K, V>;
 export declare function arrayToObject<T, K extends PrimativeKey = PrimativeKey>(values: T[], keyFn: ReadKeyFunction<T, K>, valueFn: (t: T) => T): Record<K, T>;
 export declare function arrayToObject<T, K extends PrimativeKey = PrimativeKey>(values: T[], keyFn: ReadKeyFunction<T, K>): Record<K, T>;
 /**
- * Generates a value for the input
+ * Returns values for each key, reusing existing items when available and generating new ones for missing keys.
  *
- * @param keys
- * @param existing
- * @param readKey
- * @param generateFn
- * @returns
+ * @param keys - the keys to resolve values for
+ * @param existing - array of pre-existing items to check against
+ * @param readKey - function to extract a key from an existing item
+ * @param generateFn - function to create a new item for a key not found in existing items
+ * @returns an array of items corresponding to each input key, in the same order
  */
 export declare function generateIfDoesNotExist<T, K extends PrimativeKey = PrimativeKey>(keys: K[], existing: T[], readKey: ReadKeyFunction<T, K>, generateFn: (key: K) => T): T[];