@dereekb/util 13.11.1 → 13.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.11.1",
+  "version": "13.11.3",
   "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;

package/src/lib/date/date.d.ts

@@ -419,8 +419,14 @@ export declare function monthOfYearFromDateMonth(dateMonth: DateMonth): MonthOfY
 /**
  * Converts a MonthOfYear (1-12) to a JavaScript Date month (0-11).
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags date, month, convert, javascript
+ * @dbxUtilRelated month-of-year-from-date-month
+ *
  * @param monthOfYear - Month of year (1-12)
  * @returns JavaScript Date month (0-11)
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeDateMonthForMonthOfYear(monthOfYear: MonthOfYear): DateMonth;
 /**

package/src/lib/date/time.d.ts

@@ -104,9 +104,16 @@ export declare class TimerCancelledError extends BaseError {
 /**
  * Creates a new Timer from the input duration.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilKind factory
+ * @dbxUtilTags date, time, timer, factory, duration
+ * @dbxUtilRelated timer
+ *
  * @param duration - The duration of the timer.
  * @param startImmediately - Whether the timer should start immediately. Defaults to true.
  * @returns The new Timer.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeTimer(duration: Milliseconds, startImmediately?: boolean): Timer;
 /**

package/src/lib/date/week.d.ts

@@ -118,8 +118,15 @@ export type DayOfWeekNameFunction = (dayOfWeek: DayOfWeek) => string;
 /**
  * Creates a function that returns the name for a given DayOfWeek.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilKind factory
+ * @dbxUtilTags date, week, day-of-week, name, factory, format
+ * @dbxUtilRelated days-of-week-name-map
+ *
  * @param transform - Optional configuration for abbreviation and casing
  * @returns A function that maps DayOfWeek values to name strings
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function daysOfWeekNameFunction(transform?: DayOfWeekNamesTransformConfig): DayOfWeekNameFunction;
 /**

package/src/lib/error/error.d.ts

@@ -90,8 +90,15 @@ export type ErrorMessageContainsStringFunction = (input: Maybe<ErrorInput | stri
 /**
  * Creates a function that checks if an error's message contains the target string.
  *
+ * @dbxUtil
+ * @dbxUtilCategory error
+ * @dbxUtilKind factory
+ * @dbxUtilTags error, message, contains, factory, predicate, regex
+ * @dbxUtilRelated escape-string-for-regex
+ *
  * @param target - The string to search for
  * @returns A function that checks error messages for the target string
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function errorMessageContainsStringFunction(target: string): ErrorMessageContainsStringFunction;
 /**

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

@@ -18,8 +18,15 @@ export type FilterFunction<T = unknown> = (value: T, index: number) => boolean;
  * The merged function returns true only if all individual filters pass (AND logic).
  * Null/undefined filters are ignored.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags filter, merge, compose, factory, and
+ * @dbxUtilRelated invert-filter, invert-boolean-return-function
+ *
  * @param inputFilters - The filter functions to merge
  * @returns A single FilterFunction that applies all filters
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function mergeFilterFunctions<T>(...inputFilters: Maybe<FilterFunction<T>>[]): FilterFunction<T>;
 /**

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

@@ -5,8 +5,15 @@ export type BooleanReturnFunction = (...args: any[]) => boolean;
 /**
  * Inverts the output of an arbitrary boolean-returning function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory function
+ * @dbxUtilKind factory
+ * @dbxUtilTags function, boolean, invert, predicate, factory
+ * @dbxUtilRelated decision-function, filter-function
+ *
  * @param decisionFn - The function whose boolean return value to invert
  * @param invert - Whether to apply the inversion (defaults to true)
  * @returns The inverted function, or the original if invert is false
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function invertBooleanReturnFunction<F extends BooleanReturnFunction>(decisionFn: F, invert?: boolean): F;

package/src/lib/function/function.forward.d.ts

@@ -10,8 +10,15 @@ export type ForwardFunction<I extends (...args: any[]) => O, O = unknown> = I;
  *
  * Useful for late-binding or circular dependency resolution.
  *
+ * @dbxUtil
+ * @dbxUtilCategory function
+ * @dbxUtilKind factory
+ * @dbxUtilTags function, forward, late-binding, factory, lazy
+ * @dbxUtilRelated default-forward-function-factory
+ *
  * @param getter - A Getter that provides the target function
  * @returns A forwarding function with the same signature as the target
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function forwardFunction<I extends (...args: any[]) => O, O = unknown>(getter: Getter<I>): ForwardFunction<I>;
 /**
@@ -22,7 +29,14 @@ export type DefaultForwardFunctionFactory<I extends (...args: any[]) => O, O = u
  * Creates a factory that produces forwarding functions which use the provided function
  * or fall back to the default function when not provided.
  *
+ * @dbxUtil
+ * @dbxUtilCategory function
+ * @dbxUtilKind factory
+ * @dbxUtilTags function, forward, factory, default, fallback
+ * @dbxUtilRelated forward-function
+ *
  * @param defaultFn - The default function to use as fallback
  * @returns A factory that wraps optional functions with a default fallback
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function defaultForwardFunctionFactory<I extends (...args: any[]) => O, O = unknown>(defaultFn: I): DefaultForwardFunctionFactory<I, O>;

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

@@ -39,8 +39,15 @@ export type CachedFactoryWithInput<T, A = unknown> = CachedGetter<T> & FactoryWi
  * The value is retrieved once on first call and cached permanently.
  * Use `reset()` to clear the cache and `init()` to reload.
  *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilKind factory
+ * @dbxUtilTags getter, cache, memoize, lazy, factory
+ * @dbxUtilRelated as-getter, make-getter
+ *
  * @param getter - the factory or getter function whose result will be cached
  * @returns A CachedFactoryWithInput that caches the first result
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function cachedGetter<T>(getter: Getter<T>): CachedFactoryWithInput<T>;
 export declare function cachedGetter<T, A = unknown>(factory: FactoryWithInput<T, A>): CachedFactoryWithInput<T, A>;

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

@@ -100,22 +100,37 @@ export type ObjectCopyFactory<T> = Factory<T>;
  * @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>;
 /**
  * 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.
  *
+ * @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.
  *
+ * @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>;
 /**
@@ -125,17 +140,29 @@ export type FactoryWithIndex<T> = FactoryWithInput<T, number> | FactoryWithRequi
 /**
  * Calls a factory function the specified number of times and returns the results as an array.
  *
+ * @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[];
 /**
  * Maps an array of inputs through a factory function to produce an array of outputs.
  *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilTags getter, factory, map, array, transform
+ * @dbxUtilRelated make-with-factory
+ *
  * @param factory - The factory function to call with each input
  * @param input - The array of inputs to pass to the factory
  * @returns An array of produced values
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeWithFactoryInput<T, A>(factory: FactoryWithInput<T, A>, input: Maybe<A>[]): T[];
 export declare function makeWithFactoryInput<T, A>(factory: FactoryWithRequiredInput<T, A>, input: A[]): T[];
@@ -143,7 +170,14 @@ 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.
  *
+ * @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

@@ -15,7 +15,14 @@ export declare function mapGetter<I, O>(input: Getter<I>, mapFn: MapFunction<I,
 /**
  * Creates a factory that wraps Getters with a mapping function.
  *
+ * @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,7 +6,14 @@ export type RandomFromArrayFactory<T> = Factory<T>;
 /**
  * Creates a factory that returns a random element from the given array on each call.
  *
+ * @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

@@ -183,9 +183,15 @@ export declare function pairGroupValues<T, K extends PrimativeKey = PrimativeKey
 /**
  * Creates an array of `[key, value]` tuples by extracting a key from each 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][];
 /**
@@ -235,6 +241,8 @@ export declare function groupValues<T, K extends PrimativeKey = PrimativeKey>(va
  * const map = makeValuesGroupMap(items, (x) => x.type);
  * // Map { 'a' => [{ type: 'a', v: 1 }, { type: 'a', v: 3 }], 'b' => [{ type: 'b', v: 2 }] }
  * ```
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeValuesGroupMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], groupKeyFn: ReadKeyFunction<T, K>): Map<Maybe<K>, T[]>;
 export declare function makeValuesGroupMap<T, K extends PrimativeKey = PrimativeKey>(values: Maybe<T[]>, groupKeyFn: ReadKeyFunction<T, K>): Map<Maybe<K>, T[]>;

package/src/lib/hash.d.ts

@@ -46,6 +46,7 @@ export declare function decodeHashedValues(hashedValues: string[], decodeValues:
  * @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;
 /**