@dereekb/util 13.11.14 → 13.11.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.11.14",
+  "version": "13.11.15",
   "sideEffects": false,
   "exports": {
     "./test": {

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

@@ -21,49 +21,49 @@ export type BooleanKeyArray<T = string> = Maybe<T[]>;
 /**
  * Wraps a key reading function to ensure that empty string keys are not used in boolean key arrays.
  *
- * @param readKey - The key reading function to wrap
- * @returns A wrapped key reading function that throws an error if an empty string is used as a key
+ * @param readKey - The key reading function to wrap.
+ * @returns A wrapped key reading function that throws an error if an empty string is used as a key.
  */
 export declare function readBooleanKeySafetyWrap<T>(readKey: ReadModelKeyFunction<T>): ReadModelKeyFunction<T>;
 /**
  * Checks if a boolean key array evaluates to false (empty or undefined).
  *
- * @param value - The boolean key array to check
- * @returns True if the array is empty or undefined, false otherwise
+ * @param value - Boolean-key array to evaluate as a tri-state.
+ * @returns True when the array has no entries (treated as `false`); otherwise false.
  */
 export declare function isFalseBooleanKeyArray(value: BooleanKeyArray): boolean;
 /**
  * Checks if a boolean key array evaluates to true (has at least one value).
  *
- * @param value - The boolean key array to check
- * @returns True if the array has at least one value, false otherwise
+ * @param value - Boolean-key array to evaluate as a tri-state.
+ * @returns True when at least one entry exists (treated as `true`); otherwise false.
  */
 export declare function isTrueBooleanKeyArray(value: BooleanKeyArray): boolean;
 /**
  * Inserts a value into a boolean key array, removing any existing values with the same key.
  *
- * @param array - The boolean key array to insert into
- * @param value - The value to insert
- * @param readKey - Function to extract the key from a value
- * @returns A new boolean key array with the value inserted
+ * @param array - Existing boolean-key array to extend.
+ * @param value - Entry to add, displacing any prior entry with the same key.
+ * @param readKey - Resolver that derives the comparison key from an entry.
+ * @returns Resulting boolean-key array containing the inserted entry.
  */
 export declare function insertIntoBooleanKeyArray<T>(array: BooleanKeyArray<T>, value: T, readKey: ReadModelKeyFunction<T>): BooleanKeyArray<T>;
 /**
  * Removes a value from a boolean key array based on its key.
  *
- * @param array - The boolean key array to remove from
- * @param value - The value to remove
- * @param readKey - Function to extract the key from a value
- * @returns A new boolean key array with the value removed
+ * @param array - Existing boolean-key array to filter.
+ * @param value - Entry whose key identifies the row to drop.
+ * @param readKey - Resolver that derives the comparison key from an entry.
+ * @returns Boolean-key array with entries matching the value's key removed.
  */
 export declare function removeFromBooleanKeyArray<T>(array: BooleanKeyArray<T>, value: T, readKey: ReadModelKeyFunction<T>): BooleanKeyArray<T>;
 /**
  * Removes values from a boolean key array that match the specified key.
  *
- * @param array - The boolean key array to remove from
- * @param key - The key to match for removal
- * @param readKey - Function to extract the key from a value
- * @returns A new boolean key array with matching values removed
+ * @param array - Existing boolean-key array to filter.
+ * @param key - Identifier whose entries should be removed.
+ * @param readKey - Resolver that derives the comparison key from an entry.
+ * @returns Boolean-key array with entries carrying the given key removed.
  */
 export declare function removeByKeyFromBooleanKeyArray<T>(array: BooleanKeyArray<T>, key: string, readKey: ReadModelKeyFunction<T>): BooleanKeyArray<T>;
 /**
@@ -73,8 +73,8 @@ export type BooleanKeyArrayUtility<T> = ReturnType<typeof booleanKeyArrayUtility
 /**
  * Creates a utility object with functions for working with boolean key arrays.
  *
- * @param readKey - Function to extract the key from a value
- * @returns An object with utility functions for boolean key arrays
+ * @param readKey - Function to extract the key from a value.
+ * @returns An object with utility functions for boolean key arrays.
  */
 export declare function booleanKeyArrayUtility<T>(readKey: ReadModelKeyFunction<T>): {
     isFalse: (value: BooleanKeyArray) => boolean;

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

@@ -11,25 +11,25 @@ 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. Returns undefined if the input is nullish or results in an empty array.
  *
+ * @param arrayOrValue - Single value or array to convert.
+ * @returns An array with at least one element, or undefined if the result would be empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, non-empty, convert, ensure, normalize
  * @dbxUtilRelated convert-maybe-to-array, convert-to-array
- *
- * @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. Returns an empty array if the input is nullish.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, convert, ensure, normalize, maybe, nullish
  * @dbxUtilRelated convert-maybe-to-non-empty-array, convert-to-array, as-array
- *
- * @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[];
 /**
@@ -43,37 +43,37 @@ export declare const asNonEmptyArray: typeof convertMaybeToNonEmptyArray;
 /**
  * Converts the input value to an array containing itself, or returns itself if it is already an array.
  *
+ * @param arrayOrValue - Single value or array to convert.
+ * @returns The input array unchanged, or a new single-element array wrapping the input value.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, convert, ensure, wrap, normalize
  * @dbxUtilRelated convert-maybe-to-array, convert-maybe-to-non-empty-array
- *
- * @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, 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, first, head, get, value
  * @dbxUtilRelated last-value, value-at-index, first-and-last-value
- *
- * @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, 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, last, tail, get, value
  * @dbxUtilRelated first-value, value-at-index, first-and-last-value
- *
- * @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;
 /**
@@ -81,106 +81,106 @@ export declare function lastValue<T>(input: ArrayOrValue<T>): T;
  *
  * If the input is not an array, returns that value as both the first and last value.
  *
+ * @param input - Single value or array to retrieve from.
+ * @returns A two-element tuple of the first and last values.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, first, last, head, tail, tuple, endpoints
  * @dbxUtilRelated first-value, last-value, value-at-index
- *
- * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, index, get, value, at
  * @dbxUtilRelated first-value, last-value, first-and-last-value
- *
- * @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;
 /**
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, concat, concatenate, combine, flatten, merge
  * @dbxUtilRelated flatten-array, merge-arrays
- *
- * @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 entries in the outer dimension are filtered out.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, flatten, flat, nested, two-dimensional, concat
  * @dbxUtilRelated concat-arrays, flatten-array-or-value-array, merge-arrays
- *
- * @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 {@link ArrayOrValue} entries into a single array. Nullish entries are filtered out.
  *
- * @param array - array of single values or arrays to flatten
- * @returns a single flat array containing all non-nullish elements
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, copy, clone, shallow, duplicate
  * @dbxUtilRelated convert-maybe-to-array
- *
- * @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
+ * @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 new array. Nullish entries are ignored.
  *
+ * @param arrays - Arrays to merge; nullish entries are skipped.
+ * @returns A new array containing all elements from the provided arrays.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, merge, concat, flatten, combine
  * @dbxUtilRelated merge-arrays-into-array
- *
- * @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 nullish.
  *
- * @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
+ * @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, pushes all of its elements into the target array.
  *
- * @param target - array to push into
- * @param value - single value or array of values to add
- * @returns the mutated target array
+ * @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[];
 /**
@@ -188,22 +188,22 @@ export declare function pushItemOrArrayItemsIntoArray<T>(target: T[], value: Arr
  *
  * This is preferable in cases where immutability is not required.
  *
- * @param target - array to push elements into
- * @param array - source array whose elements are pushed into the target
- * @returns the mutated target 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 specified maximum.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, take, front, head, slice, limit
  * @dbxUtilRelated take-last, split-front
- *
- * @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[];
 /**
@@ -226,59 +226,60 @@ export interface SplitFrontResult<T> {
 /**
  * Splits the array into two arrays, the first being the front of the array up to the maxToTake, and the second being the remaining values.
  *
+ * @param values - Source items to partition into front + remaining halves.
+ * @param maxToTake - Upper bound on how many entries to take from the start.
+ * @returns Pair containing the leading slice plus everything left over.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, split, partition, front, slice
  * @dbxUtilRelated take-front, take-last
- *
- * @param values The array to split.
- * @param maxToTake The maximum number of values to take from the front of the array.
- * @returns The front and remaining values.
  */
 export declare function splitFront<T>(values: T[], maxToTake: number): SplitFrontResult<T>;
 /**
  * Copies/takes as many elements as possible from the end.
  *
+ * @param values - Values to take from.
+ * @param maxToTake - Max number of values to take from the end of the input array.
+ * @param keepFromFront - Number of values to retain in the front of the array. These are not taken.
+ * @returns New array with the subset of taken values.
+ * @throws {Error} When `maxToTake` is smaller than `keepFromFront`.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, take, last, tail, end, slice, limit
  * @dbxUtilRelated take-front, split-front
- *
- * @param values Values to take from.
- * @param maxToTake Max number of values to take from the end of the input array.
- * @param keepFromFront Number of values to retain in the front of the array. These are not taken.
- * @returns New array with the subset of taken values.
  */
 export declare function takeLast<T>(values: T[], maxToTake: number, keepFromFront?: number): T[];
 /**
  * Performs a forEach iteration over the input and returns the resulting array. If the input is nullish, returns an empty array.
  *
- * @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
+ * @param array - Single value, array, or nullish value to iterate over.
+ * @param forEach - Callback invoked for each element.
+ * @returns Items iterated by the callback; empty when the input was nullish.
  */
 export declare function forEachWithArray<T>(array: Maybe<ArrayOrValue<T>>, forEach: (value: T) => void): T[];
 /**
  * Counts the total number of elements across all inner arrays of a nested array.
  *
+ * @param array - Two-dimensional array whose elements are counted.
+ * @returns The total number of elements across all inner arrays.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, count, nested, total, length, two-dimensional
  * @dbxUtilRelated flatten-array
- *
- * @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 - 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, remove, exclude, indexes, filter, copy
- *
- * @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.factory.d.ts

@@ -1,3 +1,4 @@
+import { type Maybe } from '../value/maybe.type';
 import { type Factory, type FactoryWithIndex, type FactoryWithRequiredInput } from '../getter/getter';
 import { type AsyncMapFunction } from '../value/map';
 /**
@@ -21,28 +22,30 @@ export type AsyncArrayInputFactory<I, O> = AsyncMapFunction<ArrayInputFactory<I,
 /**
  * Creates a new ArrayFactory that generates multiple values.
  *
+ * @param factory - Per-item producer invoked once per requested element.
+ * @returns Count-driven generator that materializes the requested number of items.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, factory, generate, make, build, create
  * @dbxUtilRelated array-input-factory, terminating-factory-from-array
  *
- * @param factory - The factory function used to generate each item
- * @returns A function that takes a count parameter and returns an array of generated items
  * @__NO_SIDE_EFFECTS__
  */
 export declare function arrayFactory<T>(factory: Factory<T> | FactoryWithIndex<T>): ArrayFactory<T>;
 /**
  * Creates an ArrayInputFactory that transforms input values into output values.
  *
+ * @param factory - Per-element producer invoked with each input value plus its index.
+ * @returns Adapter that runs `factory` against every input element to produce the mapped output array.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, factory, transform, map, generate, build
  * @dbxUtilRelated array-factory
  *
- * @param factory - The factory function used to transform each input value
- * @returns A function that takes an array of input values and returns an array of output values
  * @__NO_SIDE_EFFECTS__
  */
 export declare function arrayInputFactory<O, I>(factory: FactoryWithRequiredInput<O, I>): ArrayInputFactory<I, O>;
@@ -54,7 +57,7 @@ export declare function arrayInputFactory<O, I>(factory: FactoryWithRequiredInpu
  * @param array - The source array to pull values from
  * @returns A factory function that returns items from the array or null when exhausted
  */
-export declare function terminatingFactoryFromArray<T>(array: T[]): Factory<T | null>;
+export declare function terminatingFactoryFromArray<T>(array: T[]): Factory<Maybe<T>>;
 /**
  * Creates a factory that returns the items from the input array and returns the specified terminating value when the array is exhausted.
  *

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

@@ -1,3 +1,4 @@
+import { type Maybe } from '../value/maybe.type';
 import { type MapFunction } from '../value/map';
 import { type DecisionFunction } from '../value/decision';
 import { type AscendingSortCompareFunction } from '../sort';
@@ -9,24 +10,24 @@ import { type AscendingSortCompareFunction } from '../sort';
  *
  * If order is irrelevant, use filterValuesByDistanceNoOrder() instead.
  *
- * @param input - The array of values to filter
- * @param minDistance - The minimum distance required between values (inclusive)
- * @param getValue - Function that extracts a numeric value from each item for distance comparison
- * @returns A filtered array with only values that are at least minDistance apart, in their original input order
+ * @param input - Candidate items to dedupe along the value axis.
+ * @param minDistance - Inclusive gap that adjacent kept values must satisfy.
+ * @param getValue - Resolver that maps each item to a numeric coordinate; null skips the item.
+ * @returns Subset of `input` preserved in original index order with min-distance enforced.
  */
-export declare function filterValuesByDistance<T>(input: T[], minDistance: number, getValue: (value: T) => number | null): T[];
+export declare function filterValuesByDistance<T>(input: T[], minDistance: number, getValue: (value: T) => Maybe<number>): T[];
 /**
  * Filters the input values by an arbitrary "distance"/difference from each other and returns the values sorted by their determined distance.
  *
  * This is useful in cases where many values are too "close" to each other (generally items that share the same time, or within seconds of each other), and
  * we are only interested in seeing one of those items.
  *
- * @param input - The array of values to filter
- * @param minDistance - The minimum distance required between values (inclusive)
- * @param getValue - Function that extracts a numeric value from each item for distance comparison
- * @returns A filtered array with only values that are at least minDistance apart, sorted by the extracted value
+ * @param input - Candidate items to dedupe along the value axis.
+ * @param minDistance - Inclusive gap that adjacent kept values must satisfy.
+ * @param getValue - Resolver that maps each item to a numeric coordinate; null skips the item.
+ * @returns Subset of `input` sorted ascending by extracted value with min-distance enforced.
  */
-export declare function filterValuesByDistanceNoOrder<T>(input: T[], minDistance: number, getValue: (value: T) => number | null): T[];
+export declare function filterValuesByDistanceNoOrder<T>(input: T[], minDistance: number, getValue: (value: T) => Maybe<number>): T[];
 /**
  * Strategy used by {@link applyBestFit} and {@link makeBestFit} to pick the best-fit item and transform the rest.
  */
@@ -47,14 +48,15 @@ export interface BestFitConfig<T> {
 /**
  * Same as applyBestFit, but returns a new array, rather than modifying the existing array.
  *
+ * @param input - Source items considered for best-fit selection; not mutated.
+ * @param config - Strategy describing eligibility, comparison, and non-winner transformation.
+ * @returns Fresh array containing the chosen winner alongside transformed runners-up.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, best-fit, filter, sort, immutable
  * @dbxUtilRelated apply-best-fit, find-best-index-set-pair
  *
- * @param input - The array to filter for the best fit.
- * @param config - The best-fit strategy ({@link BestFitConfig}).
- * @returns A new array with only the best fit item and transformed non-best-fit items.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeBestFit<T>(input: T[], config: BestFitConfig<T>): T[];
@@ -64,14 +66,14 @@ export declare function makeBestFit<T>(input: T[], config: BestFitConfig<T>): T[
  * For instance, if two items are selected but only one can be selected by design, this function can be used to
  * pick the best fit, and update the input array.
  *
+ * @param input - Mutable array whose runners-up should be rewritten in place.
+ * @param config - Strategy describing eligibility, comparison, and non-winner transformation.
+ * @returns Same `input` reference after the runner-up replacements.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, best-fit, filter, sort, mutable, in-place
  * @dbxUtilRelated make-best-fit, find-best-index-set-pair
- *
- * @param input - The array to modify in-place.
- * @param config - The best-fit strategy ({@link BestFitConfig}).
- * @returns The modified input array with only the best fit item and transformed non-best-fit items.
  */
 export declare function applyBestFit<T>(input: T[], config: BestFitConfig<T>): T[];
 /**
@@ -83,15 +85,16 @@ export type FilterAndMapFunction<I, O> = MapFunction<Iterable<I>, O[]>;
  * Creates a function that filters the input values and maps all matching values to a new value.
  * This is a higher-order function that combines filtering and mapping operations.
  *
+ * @param decisionFunction - Predicate used to decide whether each iterated item flows through.
+ * @param mapFunction - Transform applied to every included item.
+ * @returns Reusable filter-then-map operator over any iterable input.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, filter, map, transform, factory, iterable
  * @dbxUtilRelated array-decision-function
  *
- * @param decisionFunction - Function that determines which items to include in the result
- * @param mapFunction - Function that transforms each included item
- * @returns A function that takes an iterable of input values and returns an array of transformed values
  * @__NO_SIDE_EFFECTS__
  */
 export declare function filterAndMapFunction<I, O>(decisionFunction: DecisionFunction<I>, mapFunction: MapFunction<I, O>): FilterAndMapFunction<I, O>;

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

@@ -13,29 +13,30 @@ export type ArrayDecisionFunction<T> = (values: T[]) => boolean;
  * 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.
  *
+ * @param decision - Predicate used to test individual elements.
+ * @param mode - Whether all or any elements must satisfy the predicate.
+ * @returns Predicate operating on whole arrays driven by the configured aggregation mode.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, decision, predicate, find, every, some, all, any, factory
  * @dbxUtilRelated array-decision
  *
- * @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.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function arrayDecisionFunction<T>(decision: ArrayFindDecisionFunction<T>, mode: SetIncludesMode): ArrayDecisionFunction<T>;
 /**
  * Convenience wrapper that creates and immediately invokes an {@link ArrayDecisionFunction}.
  *
- * @dbxUtil
- * @dbxUtilCategory array
- * @dbxUtilTags array, decision, predicate, find, every, some, all, any
- * @dbxUtilRelated array-decision-function
- *
  * @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.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, decision, predicate, find, every, some, all, any
+ * @dbxUtilRelated array-decision-function
  */
 export declare function arrayDecision<T>(values: T[], decision: ArrayFindDecisionFunction<T>, mode: SetIncludesMode): boolean;