@dereekb/util 13.11.14 → 13.11.15

package/src/lib/getter/getter.d.ts

@@ -47,13 +47,13 @@ export type StringOrGetter = GetterOrValue<string>;
 /**
  * Returns true if the input value is a non-class function (i.e., likely a Getter).
  *
+ * @param value - The value to check.
+ * @returns True if the value is a non-class function.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilTags getter, type-guard, function, callable, check
  * @dbxUtilRelated as-getter, get-value-from-getter
- *
- * @param value - The value to check
- * @returns True if the value is a non-class function
  */
 export declare function isGetter<T = unknown>(value: unknown): value is Getter<T>;
 /**
@@ -75,13 +75,13 @@ export declare function getValueFromGetter<T extends GetterDistinctValue, A>(thi
 /**
  * Wraps the input as a Getter function. If it's already a function, returns it directly.
  *
+ * @param input - A value or getter function.
+ * @returns A Getter function that returns the value.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilTags getter, factory, wrap, ensure, normalize
  * @dbxUtilRelated get-value-from-getter, is-getter
- *
- * @param input - A value or getter function
- * @returns A Getter function that returns the value
  */
 export declare function asGetter<T>(input: GetterOrValue<T>): Getter<T>;
 /**
@@ -91,15 +91,16 @@ export type ObjectCopyFactory<T> = Factory<T>;
 /**
  * Creates a factory that returns a shallow copy of the input value on each call.
  *
+ * @param value - Source whose contents the factory should reproduce.
+ * @param copyFunction - Override for the per-call copy behavior; defaults to `copyObject`.
+ * @returns Stable producer that yields a fresh copy of `value` per invocation.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilKind factory
  * @dbxUtilTags getter, factory, copy, clone, object
  * @dbxUtilRelated as-object-copy-factory, copy-object
  *
- * @param value - The object to copy
- * @param copyFunction - Optional custom copy function (defaults to copyObject)
- * @returns A factory that produces copies of the value
  * @__NO_SIDE_EFFECTS__
  */
 export declare function objectCopyFactory<T extends object>(value: T, copyFunction?: CopyObjectFunction<T>): ObjectCopyFactory<T>;
@@ -107,29 +108,31 @@ export declare function objectCopyFactory<T extends object>(value: T, copyFuncti
  * Converts the input to an ObjectCopyFactory. If the input is an object, wraps it with objectCopyFactory.
  * If it's already a function (Getter), it's returned directly.
  *
+ * @param input - An object value or a getter function.
+ * @param copyFunction - Optional custom copy function.
+ * @returns An ObjectCopyFactory for the input.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilKind factory
  * @dbxUtilTags getter, factory, copy, clone, object, normalize
  * @dbxUtilRelated object-copy-factory, as-getter
  *
- * @param input - An object value or a getter function
- * @param copyFunction - Optional custom copy function
- * @returns An ObjectCopyFactory for the input
  * @__NO_SIDE_EFFECTS__
  */
 export declare function asObjectCopyFactory<T>(input: T | ObjectCopyFactory<T>, copyFunction?: CopyObjectFunction<T>): ObjectCopyFactory<T>;
 /**
  * Wraps the input value in a Getter function that always returns it.
  *
+ * @param input - The value to wrap.
+ * @returns A Getter that returns the input value.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilKind factory
  * @dbxUtilTags getter, factory, wrap, constant
  * @dbxUtilRelated as-getter, get-value-from-getter
  *
- * @param input - The value to wrap
- * @returns A Getter that returns the input value
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeGetter<T>(input: T): Getter<T>;
@@ -140,14 +143,15 @@ export type FactoryWithIndex<T> = FactoryWithInput<T, number> | FactoryWithRequi
 /**
  * Calls a factory function the specified number of times and returns the results as an array.
  *
+ * @param factory - Per-item producer invoked with the running index.
+ * @param count - Total number of items to materialize.
+ * @returns Materialized output collected from each `factory` call.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilTags getter, factory, generate, array, count
  * @dbxUtilRelated make-with-factory-input, array-factory
  *
- * @param factory - The factory function to call (receives the current index as argument)
- * @param count - The number of items to create
- * @returns An array of produced values
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeWithFactory<T>(factory: Factory<T> | FactoryWithIndex<T>, count: number): T[];
@@ -170,14 +174,15 @@ export declare function makeWithFactoryInput<T, A>(factory: FactoryWithRequiredI
  * Wraps a factory so that no arguments are forwarded when it's called.
  * Useful for protecting a factory from accidentally receiving arguments.
  *
+ * @param factory - The factory to wrap.
+ * @returns A new factory that calls the original with no arguments.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilKind factory
  * @dbxUtilTags getter, factory, protect, wrap, no-args
  * @dbxUtilRelated as-getter, make-getter
  *
- * @param factory - The factory to wrap
- * @returns A new factory that calls the original with no arguments
  * @__NO_SIDE_EFFECTS__
  */
 export declare function protectedFactory<T>(factory: Factory<T>): Factory<T>;

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

@@ -7,22 +7,23 @@ export type MapGetterFactory<I, O> = (input: Getter<I>) => Getter<O>;
 /**
  * Creates a new Getter that applies a mapping function to the result of the input Getter.
  *
- * @param input - The source Getter
- * @param mapFn - The mapping function to apply to the getter's value
- * @returns A new Getter that returns the mapped value
+ * @param input - The source Getter.
+ * @param mapFn - The mapping function to apply to the getter's value.
+ * @returns A new Getter that returns the mapped value.
  */
 export declare function mapGetter<I, O>(input: Getter<I>, mapFn: MapFunction<I, O>): Getter<O>;
 /**
  * Creates a factory that wraps Getters with a mapping function.
  *
+ * @param mapFn - The mapping function to apply.
+ * @returns A factory that transforms Getters of type I to Getters of type O.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilKind factory
  * @dbxUtilTags getter, map, transform, factory
  * @dbxUtilRelated map-getter
  *
- * @param mapFn - The mapping function to apply
- * @returns A factory that transforms Getters of type I to Getters of type O
  * @__NO_SIDE_EFFECTS__
  */
 export declare function mapGetterFactory<I, O>(mapFn: MapFunction<I, O>): MapGetterFactory<I, O>;

package/src/lib/getter/getter.util.d.ts

@@ -6,14 +6,15 @@ export type RandomFromArrayFactory<T> = Factory<T>;
 /**
  * Creates a factory that returns a random element from the given array on each call.
  *
+ * @param values - Candidate pool the factory picks from on each call.
+ * @returns Stable producer that yields a uniformly random pick from `values`.
+ *
  * @dbxUtil
  * @dbxUtilCategory getter
  * @dbxUtilKind factory
  * @dbxUtilTags getter, factory, random, array, sample
  * @dbxUtilRelated random-number-factory, random-array-factory
  *
- * @param values - The array of values to randomly select from
- * @returns A factory that returns a random element from the array
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomFromArrayFactory<T>(values: T[]): RandomFromArrayFactory<T>;

package/src/lib/grouping.d.ts

@@ -36,27 +36,27 @@ export interface ArrayContentsDifferentParams<T, K extends PrimativeKey = Primat
     /**
      * Extracts a unique key from each item for pairing items across arrays.
      */
-    groupKeyFn: ReadKeyFunction<T, K>;
+    readonly groupKeyFn: ReadKeyFunction<T, K>;
     /**
      * Compares two paired items for equality.
      */
-    isEqual: EqualityComparatorFunction<T>;
+    readonly isEqual: EqualityComparatorFunction<T>;
 }
 /**
  * Configuration for RestoreOrderParams.
  */
 export interface RestoreOrderParams<T, K extends number | string = number | string> {
-    readKey: ReadKeyFunction<T, K>;
+    readonly readKey: ReadKeyFunction<T, K>;
     /**
      * Optional function used to decide which value should be retained.
      */
-    chooseRetainedValue?: (values: T[]) => T;
+    readonly chooseRetainedValue?: (values: T[]) => T;
     /**
      * Whether or not new items should be excluded. If false, the new items are appended to the end of the result in the order they are accessed.
      *
      * By default this is false.
      */
-    excludeNewItems?: boolean;
+    readonly excludeNewItems?: boolean;
 }
 /**
  * An array batch that carries its zero-based batch index via {@link IndexRef}.
@@ -65,9 +65,9 @@ export type IndexedBatch<T> = T[] & Readonly<IndexRef>;
 /**
  * Splits the input array into batches of a maximum size. Each batch carries its zero-based index as `.i`.
  *
- * @param input - The array to split into batches.
- * @param batchSize - Maximum number of items per batch.
- * @returns An array of {@link IndexedBatch} arrays.
+ * @param input - Source items to partition into consecutive runs.
+ * @param batchSize - Upper bound on items per batch.
+ * @returns Consecutive batches tagged with their zero-based index.
  *
  * @dbxUtil
  * @dbxUtilCategory grouping
@@ -106,13 +106,13 @@ export interface BatchCalc extends BatchCount {
 /**
  * Calculates batch metrics (count, full batches, remainder) from a {@link BatchCount} configuration.
  *
+ * @param input - The total items and items-per-batch configuration.
+ * @returns A {@link BatchCalc} with computed batch counts and remainder.
+ *
  * @dbxUtil
  * @dbxUtilCategory grouping
  * @dbxUtilTags batch, calculate, count, remainder, math
  * @dbxUtilRelated batch, item-count-for-batch-index
- *
- * @param input - The total items and items-per-batch configuration.
- * @returns A {@link BatchCalc} with computed batch counts and remainder.
  */
 export declare function batchCalc(input: BatchCount): BatchCalc;
 /**
@@ -120,7 +120,7 @@ export declare function batchCalc(input: BatchCount): BatchCalc;
  *
  * @param index - Zero-based batch index.
  * @param calc - Pre-computed batch calculation from {@link batchCalc}.
- * @returns The number of items in that batch.
+ * @returns Item count for the requested batch, accounting for a smaller trailing remainder.
  */
 export declare function itemCountForBatchIndex(index: number, calc: BatchCalc): number;
 /**
@@ -141,9 +141,9 @@ export declare function restoreOrderWithValues<T, K extends PrimativeKey = Prima
  * @param orderKeys - Keys defining the desired order.
  * @param values - Values to reorder.
  * @param params - Configuration including key reader, duplicate handling, and new-item behavior.
- * @param params.readKey - function that extracts the grouping key from each value
- * @param params.chooseRetainedValue - function that selects which value to keep when duplicates share the same key; defaults to keeping the first
- * @param params.excludeNewItems - when true, values whose keys are not in `orderKeys` are omitted from the result; defaults to false
+ * @param params.readKey - Function that extracts the grouping key from each value.
+ * @param params.chooseRetainedValue - Function that selects which value to keep when duplicates share the same key; defaults to keeping the first.
+ * @param params.excludeNewItems - When true, values whose keys are not in `orderKeys` are omitted from the result; defaults to false.
  * @returns The reordered values array.
  *
  * @dbxUtil
@@ -167,8 +167,8 @@ export declare function restoreOrder<T, K extends PrimativeKey = PrimativeKey>(o
  * @param a - First array to compare.
  * @param b - Second array to compare.
  * @param params - Key extraction and equality functions.
- * @param params.groupKeyFn - function that extracts a grouping key from each element for pairing
- * @param params.isEqual - predicate that returns true when two paired elements are considered equal
+ * @param params.groupKeyFn - Function that extracts a grouping key from each element for pairing.
+ * @param params.isEqual - Predicate that returns true when two paired elements are considered equal.
  * @returns `true` if the array contents differ.
  */
 export declare function arrayContentsDiffer<T, K extends PrimativeKey = PrimativeKey>(a: T[] | undefined, b: T[] | undefined, { groupKeyFn, isEqual }: ArrayContentsDifferentParams<T, K>): boolean;
@@ -183,28 +183,29 @@ export declare function pairGroupValues<T, K extends PrimativeKey = PrimativeKey
 /**
  * Creates an array of `[key, value]` tuples by extracting a key from each value.
  *
+ * @param values - Values to create key pairs from.
+ * @param keyFn - Extracts the key from each value.
+ * @returns Tuples pairing each derived key with its source value.
+ *
  * @dbxUtil
  * @dbxUtilCategory grouping
  * @dbxUtilTags grouping, key, pairs, tuple, array
  * @dbxUtilRelated group-values, make-values-group-map
  *
- * @param values - Values to create key pairs from.
- * @param keyFn - Extracts the key from each value.
- * @returns An array of `[key, value]` tuples.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeKeyPairs<T, K extends string | number = string | number>(values: T[], keyFn: ReadKeyFunction<T, K>): [Maybe<K>, T][];
 /**
  * Separates values into included and excluded groups based on a decision function.
  *
+ * @param values - Values to separate.
+ * @param checkInclusion - Returns `true` for values that should be included.
+ * @returns A {@link SeparateResult} with included and excluded arrays.
+ *
  * @dbxUtil
  * @dbxUtilCategory grouping
  * @dbxUtilTags array, separate, partition, split, filter, group
  * @dbxUtilRelated group-values, pair-group-values
- *
- * @param values - Values to separate.
- * @param checkInclusion - Returns `true` for values that should be included.
- * @returns A {@link SeparateResult} with included and excluded arrays.
  */
 export declare function separateValues<T>(values: T[], checkInclusion: DecisionFunction<T>): SeparateResult<T>;
 /**

package/src/lib/hash.d.ts

@@ -16,10 +16,10 @@ export type HashDecodeMap<H extends string = string, V extends string = string>
 /**
  * Decodes a list of hashed string values using a provided list of potential original values and a hash function.
  *
- * @param hashedValues - An array of hashed strings to decode.
- * @param decodeValues - An array of potential original string values.
- * @param hashFn - A function that takes a string and returns its hashed representation.
- * @returns An array of decoded strings. Values that cannot be decoded are filtered out.
+ * @param hashedValues - Hashed inputs awaiting reverse lookup.
+ * @param decodeValues - Plaintext candidates that may match one of the hashes.
+ * @param hashFn - Deterministic hashing used to align the candidate set with the input hashes.
+ * @returns Plaintext recovered from `decodeValues`, dropping any hash that lacks a match.
  *
  * @dbxUtil
  * @dbxUtilCategory hash
@@ -38,22 +38,23 @@ export declare function decodeHashedValues(hashedValues: string[], decodeValues:
  * Creates a `HashDecodeMap` from a list of potential original string values and a hash function.
  * The map's keys are the hashed versions of the `decodeValues`, and the values are the original `decodeValues`.
  *
+ * @param decodeValues - Plaintext candidates whose hashes the map should index.
+ * @param hashFn - Deterministic hashing used to compute each key.
+ * @returns Hash-to-plaintext lookup ready for reverse decoding.
+ *
  * @dbxUtil
  * @dbxUtilCategory hash
  * @dbxUtilTags hash, decode, map, lookup, reverse, factory
  * @dbxUtilRelated decode-hashed-values, decode-hashed-values-with-decode-map
  *
- * @param decodeValues - An array of potential original string values.
- * @param hashFn - A function that takes a string and returns its hashed representation.
- * @returns A {@link HashDecodeMap} for decoding hashed values.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeHashDecodeMap(decodeValues: string[], hashFn: (value: string) => string): HashDecodeMap;
 /**
  * Decodes a list of hashed string values using a pre-built `HashDecodeMap`.
  *
- * @param hashedValues - An array of hashed strings to decode.
- * @param decodeMap - A {@link HashDecodeMap} to use for looking up original values.
- * @returns An array of decoded strings. Values that cannot be decoded are filtered out.
+ * @param hashedValues - Hashed inputs awaiting reverse lookup.
+ * @param decodeMap - Pre-built hash-to-plaintext lookup.
+ * @returns Plaintext recovered via `decodeMap`, dropping any hash missing from it.
  */
 export declare function decodeHashedValuesWithDecodeMap(hashedValues: string[], decodeMap: HashDecodeMap): string[];

package/src/lib/iterable/iterable.d.ts

@@ -10,7 +10,7 @@ export type IterableOrValue<T> = T | Iterable<T>;
 /**
  * Converts an IterableOrValue to an Iterable. Non-iterable values are wrapped in an array.
  *
- * @param values - The value or iterable to convert
+ * @param values - The value or iterable to convert.
  * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
  * @returns An Iterable containing the value(s)
  */
@@ -20,14 +20,14 @@ export declare function asIterable<T = unknown>(values: IterableOrValue<T>, trea
  *
  * By default treats strings as a non-iterable value, using the string as a single value.
  *
+ * @param values - The value or iterable to convert.
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns An array containing the value(s)
+ *
  * @dbxUtil
  * @dbxUtilCategory iterable
  * @dbxUtilTags iterable, array, convert, normalize, ensure
  * @dbxUtilRelated iterable-to-set, iterable-to-map, as-iterable
- *
- * @param values - The value or iterable to convert
- * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
- * @returns An array containing the value(s)
  */
 export declare function iterableToArray<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): T[];
 /**
@@ -35,103 +35,103 @@ export declare function iterableToArray<T = unknown>(values: IterableOrValue<T>,
  *
  * By default treats strings as a non-iterable value, using the string as a single value.
  *
+ * @param values - The value or iterable to convert.
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns Deduped membership view collected from `values`.
+ *
  * @dbxUtil
  * @dbxUtilCategory iterable
  * @dbxUtilTags iterable, set, convert, normalize, unique, dedupe
  * @dbxUtilRelated iterable-to-array, iterable-to-map
- *
- * @param values - The value or iterable to convert
- * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
- * @returns A Set containing the value(s)
  */
 export declare function iterableToSet<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): Set<T>;
 /**
  * Converts an IterableOrValue to a Map using a key extraction function.
  *
- * @param values - The value or iterable to convert
- * @param readKey - Function to extract the key from each value
- * @returns A Map with the extracted keys and their corresponding values
+ * @param values - The value or iterable to convert.
+ * @param readKey - Function to extract the key from each value.
+ * @returns Lookup keyed by `readKey` results; the last entry per key wins.
  */
 export declare function iterableToMap<T, K extends PrimativeKey = PrimativeKey>(values: IterableOrValue<T>, readKey: ReadKeyFunction<T, K>): Map<Maybe<K>, T>;
 /**
  * Type guard that returns true if the input is an Iterable.
  * By default, strings are not treated as iterable.
  *
+ * @param values - The value to check.
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns True if the value is iterable.
+ *
  * @dbxUtil
  * @dbxUtilCategory iterable
  * @dbxUtilTags iterable, type-guard, check, symbol-iterator
  * @dbxUtilRelated is-empty-iterable, as-iterable
- *
- * @param values - The value to check
- * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
- * @returns True if the value is iterable
  */
 export declare function isIterable<T = unknown>(values: unknown, treatStringAsIterable?: boolean): values is Iterable<T>;
 /**
  * Returns true if the iterable has no values.
  *
+ * @param values - The iterable to check.
+ * @returns True if the iterable is empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory iterable
  * @dbxUtilTags iterable, empty, check, length
  * @dbxUtilRelated is-iterable, first-value-from-iterable
- *
- * @param values - The iterable to check
- * @returns True if the iterable is empty
  */
 export declare function isEmptyIterable<T = unknown>(values: Iterable<T>): boolean;
 /**
  * Returns the first value from the Iterable, or undefined if empty. Order is not guaranteed.
  *
- * @param values - The iterable to read from
- * @returns The first value, or undefined if empty
+ * @param values - The iterable to read from.
+ * @returns The first value, or undefined if empty.
  */
 export declare function firstValueFromIterable<T>(values: Iterable<T>): Maybe<T>;
 /**
  * Takes up to `count` items from the iterable. Order is not guaranteed.
  *
- * @param values - The iterable to take from
- * @param count - Maximum number of items to take
- * @returns An array of taken values
+ * @param values - Source iterable feeding the take operation.
+ * @param count - Upper bound on items to consume from the iterator.
+ * @returns Consumed items, capped at `count`.
  */
 export declare function takeValuesFromIterable<T>(values: Iterable<T>, count: number): T[];
 /**
  * Iterates over iterable values, calling the function for each one.
  *
- * @param values - The iterable to iterate over
- * @param fn - The function to call for each value
+ * @param values - The iterable to iterate over.
+ * @param fn - The function to call for each value.
  */
 export declare function forEachInIterable<T>(values: Iterable<T>, fn: (value: T) => void): void;
 /**
  * Calls the function for each value if the input is iterable, or once with the value if it's a single value.
  * Does nothing if the input is null/undefined.
  *
- * @param values - The value or iterable to process
- * @param fn - The function to call for each value
+ * @param values - The value or iterable to process.
+ * @param fn - The function to call for each value.
  * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
  */
 export declare function useIterableOrValue<T>(values: Maybe<IterableOrValue<T>>, fn: (value: T) => void, treatStringAsIterable?: boolean): void;
 /**
  * Finds and returns the first value in the iterable that matches the decision function.
  *
- * @param values - The iterable to search
- * @param fn - Decision function that returns true for the desired value
- * @returns The first matching value, or undefined
+ * @param values - The iterable to search.
+ * @param fn - Decision function that returns true for the desired value.
+ * @returns The first matching value, or undefined.
  */
 export declare function findInIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): Maybe<T>;
 /**
  * Returns true if any value in the iterable matches the decision function.
  *
- * @param values - The iterable to search
- * @param fn - Decision function to test each value
- * @returns True if at least one value matches
+ * @param values - The iterable to search.
+ * @param fn - Decision function to test each value.
+ * @returns True if at least one value matches.
  */
 export declare function existsInIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): boolean;
 /**
  * Filters values from the iterable, keeping those that pass the decision function.
  *
- * @param values - The iterable to filter
- * @param fn - Decision function that returns true for values to keep
- * @returns An array of matching values
+ * @param values - Source iterable feeding the filter.
+ * @param fn - Predicate that decides whether each value flows through.
+ * @returns Items for which the predicate returned true, in iteration order.
  */
 export declare function filterFromIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): T[];
 /**
@@ -140,8 +140,8 @@ export declare function filterFromIterable<T>(values: Iterable<T>, fn: DecisionF
  *
  * Used to prevent functions from incorrectly treating a tuple as an array of values.
  *
- * @param input - The tuple or array of tuples to wrap
+ * @param input - The tuple or array of tuples to wrap.
  * @returns An array containing the tuple(s)
- * @throws Error if input is not an array
+ * @throws {Error} If input is not an array.
  */
 export declare function wrapTuples<T>(input: IterableOrValue<T>): T[];

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

@@ -1,8 +1,8 @@
 /**
  * Maps each value in an iterable through a function and returns the results as an array.
  *
- * @param values - The iterable to map over
- * @param fn - The mapping function to apply to each value
- * @returns An array of mapped results
+ * @param values - Source items to feed through the mapper.
+ * @param fn - Per-element transform applied to every value.
+ * @returns Mapped results collected in iteration order.
  */
 export declare function mapIterable<I, O>(values: Iterable<I>, fn: (value: I) => O): O[];

package/src/lib/key.d.ts

@@ -38,13 +38,7 @@ export type ReadKeysFunction<T, K extends PrimativeKey = PrimativeKey> = MapFunc
  * filtering out null/undefined keys.
  *
  * @param readKey - Function that extracts one or more keys from a value.
- * @returns A function that reads keys from a single value or array of values.
- *
- * @example
- * ```ts
- * const fn = readKeysFunction<string>((x) => x);
- * fn(['a', 'b', 'c']); // ['a', 'b', 'c']
- * ```
+ * @returns Reusable extractor that normalizes single or batch input into a flat key list (nullish keys dropped).
  *
  * @dbxUtil
  * @dbxUtilCategory value
@@ -52,6 +46,12 @@ export type ReadKeysFunction<T, K extends PrimativeKey = PrimativeKey> = MapFunc
  * @dbxUtilTags key, read, factory, array, primitive
  * @dbxUtilRelated read-keys-set-function
  *
+ * @example
+ * ```ts
+ * const fn = readKeysFunction<string>((x) => x);
+ * fn(['a', 'b', 'c']); // ['a', 'b', 'c']
+ * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function readKeysFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): ReadKeysFunction<T, K>;
@@ -60,7 +60,7 @@ export declare function readKeysFunction<T, K extends PrimativeKey = PrimativeKe
  *
  * @param readKey - Function that extracts one or more keys from a value.
  * @param values - Values to read keys from.
- * @returns An array of all extracted keys.
+ * @returns Flat list of every key extracted from `values`.
  */
 export declare function readKeysFrom<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>, values: T[]): K[];
 /**
@@ -71,13 +71,7 @@ export type ReadKeysSetFunction<T, K extends PrimativeKey = PrimativeKey> = MapF
  * Creates a {@link ReadKeysSetFunction} from a key-reading function. Like {@link readKeysFunction} but returns a Set, deduplicating keys.
  *
  * @param readKey - Function that extracts one or more keys from a value.
- * @returns A function that reads keys from values into a Set.
- *
- * @example
- * ```ts
- * const fn = readKeysSetFunction<string>((x) => x);
- * fn(['a', 'b', 'a']); // Set { 'a', 'b' }
- * ```
+ * @returns Reusable extractor that collects keys into a deduped Set.
  *
  * @dbxUtil
  * @dbxUtilCategory value
@@ -85,6 +79,12 @@ export type ReadKeysSetFunction<T, K extends PrimativeKey = PrimativeKey> = MapF
  * @dbxUtilTags key, read, set, factory, dedupe, primitive
  * @dbxUtilRelated read-keys-function
  *
+ * @example
+ * ```ts
+ * const fn = readKeysSetFunction<string>((x) => x);
+ * fn(['a', 'b', 'a']); // Set { 'a', 'b' }
+ * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function readKeysSetFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): ReadKeysSetFunction<T, K>;
@@ -93,6 +93,6 @@ export declare function readKeysSetFunction<T, K extends PrimativeKey = Primativ
  *
  * @param readKey - Function that extracts one or more keys from a value.
  * @param values - Values to read keys from.
- * @returns A Set of all extracted keys.
+ * @returns Deduped key collection drawn from `values`.
  */
 export declare function readKeysSetFrom<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>, values: T[]): Set<K>;