@dereekb/util 13.11.2 → 13.11.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.11.2",
+  "version": "13.11.4",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -15,6 +15,12 @@
       "import": "./fetch/index.cjs.mjs",
       "default": "./fetch/index.cjs.js"
     },
+    "./eslint": {
+      "module": "./eslint/index.esm.js",
+      "types": "./eslint/index.d.ts",
+      "import": "./eslint/index.cjs.mjs",
+      "default": "./eslint/index.cjs.js"
+    },
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",

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

@@ -29,6 +29,7 @@ export type AsyncArrayInputFactory<I, O> = AsyncMapFunction<ArrayInputFactory<I,
  *
  * @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>;
 /**
@@ -42,6 +43,7 @@ export declare function arrayFactory<T>(factory: Factory<T> | FactoryWithIndex<T
  *
  * @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>;
 /**

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

@@ -5,14 +5,16 @@ import { type AscendingSortCompareFunction } from '../sort';
  * Filters the input values by distance while maintaining the original order of elements.
  * Values that are too close to each other (based on the minDistance parameter) will be filtered out.
  *
+ * Items whose extracted value is null are excluded from the result.
+ *
  * If order is irrelevant, use filterValuesByDistanceNoOrder() instead.
  *
- * @param _input - The array of values to filter
- * @param _minDistance - The minimum distance required between values
- * @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
+ * @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
  */
-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) => number | null): T[];
 /**
  * Filters the input values by an arbitrary "distance"/difference from each other and returns the values sorted by their determined distance.
  *
@@ -25,29 +27,53 @@ export declare function filterValuesByDistance<T>(_input: T[], _minDistance: num
  * @returns A filtered array with only values that are at least minDistance apart, sorted by the extracted value
  */
 export declare function filterValuesByDistanceNoOrder<T>(input: T[], minDistance: number, getValue: (value: T) => number | null): T[];
+/**
+ * Strategy used by {@link applyBestFit} and {@link makeBestFit} to pick the best-fit item and transform the rest.
+ */
+export interface BestFitConfig<T> {
+    /**
+     * Function that determines which items are candidates for the best fit.
+     */
+    readonly filter: (value: T) => boolean;
+    /**
+     * AscendingSortCompareFunction to compare two values to determine which is the best fit.
+     */
+    readonly compare: AscendingSortCompareFunction<T>;
+    /**
+     * Function that transforms non-best-fit items.
+     */
+    readonly updateNonBestFit: (value: T) => T;
+}
 /**
  * Same as applyBestFit, but returns a new array, rather than modifying the existing array.
  *
- * @param input - The array to filter for the best fit
- * @param filter - Function that determines which items are candidates for the best fit
- * @param compare - AscendingSortCompareFunction to compare two values to determine which is the best fit
- * @param updateNonBestFit - Function that transforms non-best-fit items
- * @returns A new array with only the best fit item and transformed non-best-fit items
+ * @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[], filter: (value: T) => boolean, compare: AscendingSortCompareFunction<T>, updateNonBestFit: (value: T) => T): T[];
+export declare function makeBestFit<T>(input: T[], config: BestFitConfig<T>): T[];
 /**
  * Used for updating an array so that a single element becomes the "best fit" in whatever context is provided.
  *
  * 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 - The array to modify in-place
- * @param filter - Function that determines which items are candidates for the best fit
- * @param compare - AscendingSortCompareFunction to compare two values to determine which is the best fit
- * @param updateNonBestFit - Function that transforms non-best-fit items
- * @returns The modified input array with only the best fit item and transformed non-best-fit items
+ * @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[], filter: (value: T) => boolean, compare: AscendingSortCompareFunction<T>, updateNonBestFit: (value: T) => T): T[];
+export declare function applyBestFit<T>(input: T[], config: BestFitConfig<T>): T[];
 /**
  * Filters and maps the input values to an array.
  * Combines filtering and mapping operations into a single pass over the data.
@@ -57,8 +83,15 @@ 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.
  *
+ * @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

@@ -22,6 +22,7 @@ export type ArrayDecisionFunction<T> = (values: T[]) => boolean;
  * @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>;
 /**

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

@@ -67,7 +67,14 @@ export type SliceIndexRangeFunction<T> = (input: T[]) => T[];
 /**
  * Creates a {@link SliceIndexRangeFunction} that slices the specified index range from any input array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, slice, index, range, factory
+ * @dbxUtilRelated index-range, find-to-index-set
+ *
  * @param inputRange - the index range configuration to use for slicing
  * @returns a function that slices the configured range from an input array
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function sliceIndexRangeFunction<T>(inputRange: IndexRangeInput): SliceIndexRangeFunction<T>;

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

@@ -46,8 +46,15 @@ export type RangedIndexedValuesArrayAccessorFactory<T> = (values: T[]) => Ranged
  *
  * Each accessor maps an index to the value whose range contains that index, or undefined if no range matches.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, indexed, range, accessor, factory, lookup
+ * @dbxUtilRelated indexed-values-array-accessor-factory, ranged-indexed-values-array-accessor-info-factory
+ *
  * @param readIndexRange - Function that reads the index range from each value.
  * @returns A factory that creates ranged accessors from arrays of values.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function rangedIndexedValuesArrayAccessorFactory<T>(readIndexRange: ReadIndexRangeFunction<T>): RangedIndexedValuesArrayAccessorFactory<T>;
 /**
@@ -64,9 +71,16 @@ export type IndexedValuesArrayAccessorFactory<T> = (values: T[]) => IndexedValue
  * 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.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, indexed, range, accessor, factory, fallback
+ * @dbxUtilRelated ranged-indexed-values-array-accessor-factory, ranged-indexed-values-array-accessor-info-factory
+ *
  * @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.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function indexedValuesArrayAccessorFactory<T>(readIndexRange: ReadIndexRangeFunction<T>): IndexedValuesArrayAccessorFactory<T>;
 /**
@@ -109,7 +123,14 @@ export interface RangedIndexedValuesArrayInfoAccessorFactoryConfig<T> {
  * 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.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, indexed, range, accessor, info, factory, neighbors
+ * @dbxUtilRelated ranged-indexed-values-array-accessor-factory, indexed-values-array-accessor-factory
+ *
  * @param config - Configuration containing the index range reader function.
  * @returns A factory that creates ranged info accessors from arrays of values.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function rangedIndexedValuesArrayAccessorInfoFactory<T>(config: RangedIndexedValuesArrayInfoAccessorFactoryConfig<T>): RangedIndexedValuesArrayInfoAccessorFactory<T>;

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

@@ -23,7 +23,14 @@ export type RandomArrayFactory<T> = FactoryWithInput<T[], number>;
 /**
  * Creates a factory function that generates arrays of a random length populated with items from a make function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, random, factory, generate, make
+ * @dbxUtilRelated array-factory, random-number-factory
+ *
  * @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
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function randomArrayFactory<T>(config: RandomArrayFactoryConfig<T>): RandomArrayFactory<T>;

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

@@ -20,6 +20,7 @@ export type RandomPickFactory<T> = (() => T) & {
  * @param values - array of values to randomly pick from
  * @returns a callable factory that returns a random value from the array on each invocation
  * @throws Error if the input array is empty
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function randomPickFactory<T>(values: T[]): RandomPickFactory<T>;
 /**

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

@@ -87,6 +87,7 @@ export declare function readKeysFromFilterUniqueFunctionAdditionalKeys<T, K exte
  * @param readKey - Function to extract a unique key from each item.
  * @param additionalKeysInput - Optional keys or values to pre-seed as already seen, causing them to be excluded.
  * @returns A reusable filter function that removes duplicate items from arrays.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function filterUniqueFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>, additionalKeysInput?: FilterUniqueFunctionAdditionalKeysInput<T, K>): FilterUniqueFunction<T, K>;
 /**
@@ -118,6 +119,7 @@ export type IsUniqueKeyedFunction<T> = DecisionFunction<T[]>;
  *
  * @param readKey - Function to extract a unique key from each item.
  * @returns A decision function that returns true if all items have distinct keys.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isUniqueKeyedFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>): IsUniqueKeyedFunction<T>;
 /**
@@ -144,6 +146,7 @@ export type AllowValueOnceFilter<T, K extends PrimativeKey = PrimativeKey> = Dec
  *
  * @param inputReadKey - Optional function to extract a key from each value. Defaults to identity.
  * @returns A stateful filter function that returns true only for the first occurrence of each key.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function allowValueOnceFilter<T extends PrimativeKey = PrimativeKey>(): AllowValueOnceFilter<T, T>;
 export declare function allowValueOnceFilter<T, K extends PrimativeKey = PrimativeKey>(readKey?: ReadKeyFunction<T, K>): AllowValueOnceFilter<T, K>;

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

@@ -10,8 +10,15 @@ export type UniversalFilterMaybeArrayFunction = <T>(values: Maybe<Maybe<T>[]>) =
 /**
  * Creates a {@link FilterMaybeArrayFunction} that filters maybe values from an array using the provided filter function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, filter, maybe, factory, predicate
+ * @dbxUtilRelated filter-maybe-array-values
+ *
  * @param filterFn - Filter predicate used to determine which values to keep.
  * @returns A function that filters maybe values from an optional input array.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function filterMaybeArrayFunction<T>(filterFn: Parameters<Array<Maybe<T>>['filter']>[0]): FilterMaybeArrayFunction<T>;
 /**

package/src/lib/auth/auth.role.claims.d.ts

@@ -127,9 +127,16 @@ export declare const AUTH_ROLE_CLAIMS_DEFAULT_EMPTY_VALUE: null;
  * Each key in the config maps a claim key to role(s). Simple entries map a claim value to one or more roles,
  * while encode/decode entries allow custom bidirectional conversion logic.
  *
+ * @dbxUtil
+ * @dbxUtilCategory auth
+ * @dbxUtilKind factory
+ * @dbxUtilTags auth, role, claims, jwt, factory, bidirectional
+ * @dbxUtilRelated auth-role
+ *
  * @param config - Mapping of claim keys to their role configuration entries (or null to ignore)
  * @param defaults - Optional default values for claim presence and absence
  * @returns A service with `toClaims` and `toRoles` conversion functions
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function authRoleClaimsService<T extends AuthClaimsObject>(config: AuthRoleClaimsFactoryConfig<T>, defaults?: AuthRoleClaimsFactoryDefaults): AuthRoleClaimsService<T>;
 /**

package/src/lib/boolean.d.ts

@@ -154,6 +154,7 @@ export interface BooleanFactoryConfig {
  * const coinFlip = booleanFactory({ chance: 50 });
  * coinFlip(); // true or false with equal probability
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function booleanFactory(config: BooleanFactoryConfig): BooleanFactory;
 /**

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

@@ -29,8 +29,15 @@ export type RandomEmailFactory = Factory<EmailAddress>;
 /**
  * Creates a factory that generates random email addresses using configurable prefixes, domains, and number generators.
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilKind factory
+ * @dbxUtilTags contact, email, random, factory, generate
+ * @dbxUtilRelated random-phone-number-factory, incrementing-number-factory
+ *
  * @param inputConfig - Optional configuration overrides
  * @returns A factory function that produces random email address strings
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function randomEmailFactory(inputConfig?: RandomEmailFactoryConfig): RandomEmailFactory;
 /**
@@ -54,7 +61,14 @@ export type RandomPhoneNumberFactory = Factory<E164PhoneNumber>;
 /**
  * Creates a factory that generates random E.164 phone numbers using configurable area codes and number generators.
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilKind factory
+ * @dbxUtilTags contact, phone, e164, random, factory, generate
+ * @dbxUtilRelated random-email-factory, random-number-factory
+ *
  * @param inputConfig - Optional configuration overrides
  * @returns A factory function that produces random E.164 phone number strings
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function randomPhoneNumberFactory(inputConfig?: RandomPhoneNumberFactoryConfig): RandomPhoneNumberFactory;