@dereekb/util 13.11.1 → 13.11.3

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

@@ -66,6 +66,14 @@ export type FilterKeyValueTuplesFunction<T extends object = object, K extends ke
  * const tuples = getDefinedTuples({ a: 1, b: undefined, c: 'hello' });
  * // tuples: [['a', 1], ['c', 'hello']]
  * ```
+ *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, tuples, filter, factory, key-value
+ * @dbxUtilRelated filter-key-value-tuple-function, for-each-key-value
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function filterKeyValueTuplesFunction<T extends object = object, K extends keyof T = keyof T>(filter?: FilterKeyValueTuplesInput<T, K>): FilterKeyValueTuplesFunction<T, K>;
 /**
@@ -168,5 +176,13 @@ export type FilterKeyValueTupleFunction<T extends object = object, K extends key
  * isNotNull(['a', 1], 0);    // true
  * isNotNull(['b', null], 0); // false
  * ```
+ *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, tuple, filter, predicate, factory, key-value
+ * @dbxUtilRelated filter-key-value-tuples-function
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function filterKeyValueTupleFunction<T extends object = object, K extends keyof T = keyof T>(inputFilter: FilterKeyValueTuplesInput<T, K>): FilterKeyValueTupleFunction<T, K>;

package/src/lib/object/object.key.d.ts

@@ -8,8 +8,15 @@ import { type EqualityComparatorFunction } from '../value/comparator';
  * Returns `true` if both arrays have the same length and produce identical key sets.
  * Handles `null`/`undefined` inputs via {@link safeEqualityComparatorFunction}.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, key, equality, comparator, factory, array
+ * @dbxUtilRelated object-key-equality-comparator-function, safe-equality-comparator-function
+ *
  * @param readKey - Function to extract one or more keys from each object
  * @returns An equality comparator for arrays of keyed objects
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function objectKeysEqualityComparatorFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): EqualityComparatorFunction<Maybe<T[]>>;
 /**
@@ -18,7 +25,14 @@ export declare function objectKeysEqualityComparatorFunction<T, K extends Primat
  *
  * Handles `null`/`undefined` inputs via {@link safeEqualityComparatorFunction}.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, key, equality, comparator, factory
+ * @dbxUtilRelated object-keys-equality-comparator-function, safe-equality-comparator-function
+ *
  * @param readKey - Function to extract the key from an object
  * @returns An equality comparator for keyed objects
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function objectKeyEqualityComparatorFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>): EqualityComparatorFunction<Maybe<T>>;

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

@@ -32,8 +32,15 @@ export type MapObjectMapFunction<M extends ObjectMap<I>, I = unknown, O = unknow
 /**
  * Creates a reusable {@link MapObjectMapFunction} that applies {@link mapObjectMap} with the given mapping function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, map, transform, factory, values
+ * @dbxUtilRelated map-object-map, map-object-keys-function
+ *
  * @param mapFn - Function that transforms each value (receives value and key)
  * @returns A function that maps all values in an input object map
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function mapObjectMapFunction<M extends ObjectMap<I>, I = unknown, O = unknown>(mapFn: MapObjectMapValueFunction<M, I, O>): MapObjectMapFunction<M, I, O>;
 /**
@@ -68,8 +75,15 @@ export type MapObjectKeyFunction<M> = <K extends keyof M>(key: K, value: M[K]) =
 /**
  * Creates a reusable {@link MapObjectKeysFunction} that transforms the keys of an input object using the given mapping function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, map, keys, transform, factory, rename
+ * @dbxUtilRelated map-object-map-function, map-object-keys-to-lowercase
+ *
  * @param mapKeyFn - Function that computes the new key from the old key and its value
  * @returns A function that remaps keys on any input object
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function mapObjectKeysFunction<M extends object>(mapKeyFn: MapObjectKeyFunction<M>): MapObjectKeysFunction<M>;
 /**

package/src/lib/path/path.d.ts

@@ -227,6 +227,7 @@ export type SlashPathStartTypeFactory = SlashPathFunction;
  *
  * @param type - The start type to enforce.
  * @returns A function that transforms paths to the specified start type.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function slashPathStartTypeFactory(type: SlashPathStartType): SlashPathStartTypeFactory;
 export declare const LEADING_SLASHES_REGEX: RegExp;
@@ -286,6 +287,7 @@ export interface SlashPathFolderFactoryConfig {
  *
  * @param config Configuration options for the factory.
  * @returns A SlashPathFolderFactory.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function slashPathFolderFactory(config?: SlashPathFolderFactoryConfig): SlashPathFolderFactory;
 /**
@@ -400,6 +402,7 @@ export declare function replaceInvalidFilePathTypeSeparatorsInSlashPath(input: S
  * @param input
  * @param replaceWith
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function replaceInvalidFilePathTypeSeparatorsInSlashPathFunction(replaceWith?: string): SlashPathFunction;
 /**
@@ -441,6 +444,7 @@ export interface SlashPathValidationFactoryConfig {
  *
  * @param config - Configuration for validation behavior.
  * @returns A function that validates and fixes a slash path.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function slashPathValidationFactory(config?: SlashPathValidationFactoryConfig): SlashPathValidationFactory;
 /**
@@ -472,6 +476,7 @@ export interface SlashPathFactoryConfig {
  *
  * @param config - Configuration for path generation.
  * @returns A factory function that merges input paths into a single validated slash path.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function slashPathFactory(config?: SlashPathFactoryConfig): SlashPathFactory;
 /**
@@ -544,6 +549,7 @@ export type IsolateSlashPathFunction = (path: SlashPath) => SlashPath;
  *
  * @param config - Configuration with range, optional start type, and file mode.
  * @returns A function that isolates path segments within the configured range.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isolateSlashPathFunction(config: IsolateSlashPathFunctionConfig): IsolateSlashPathFunction;
 export interface SlashPathDetails {
@@ -655,6 +661,7 @@ export type SlashPathPathMatcherPath = ArrayOrValue<SlashPathPathMatcherPart>;
  *
  * @param path - Matcher path parts to expand into decision functions.
  * @returns Array of decision functions for each path part.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function expandSlashPathPathMatcherPartToDecisionFunctions(path: SlashPathPathMatcherPath): SlashPathPathMatcherFunction[];
 /**
@@ -744,6 +751,7 @@ export declare function slashPathPathMatcherConfig<N extends PrimativeValue = Pr
  *
  * @param input - the matcher configuration, which may be a target path string, an array of path parts, or a full config object
  * @returns The matcher.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function slashPathPathMatcher<N extends PrimativeValue = PrimativeValue>(input: SlashPathPathMatcherConfigInput<N>): SlashPathPathMatcher<N>;
 export interface SlashPathSubPathMatcherConfig {
@@ -808,5 +816,6 @@ export type SlashPathSubPathMatcher = (path: SlashPath) => SlashPathSubPathMatch
  *
  * @param config The configuration for the matcher.
  * @returns The matcher.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function slashPathSubPathMatcher(config: SlashPathSubPathMatcherConfig): SlashPathSubPathMatcher;

package/src/lib/promise/promise.d.ts

@@ -174,8 +174,15 @@ export declare function performTasksInParallel<I, K extends PrimativeKey = Perfo
  * Creates a reusable function that performs tasks in parallel with optional concurrency limits
  * and non-concurrent task key constraints.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilKind factory
+ * @dbxUtilTags promise, parallel, factory, concurrency, async, tasks
+ * @dbxUtilRelated perform-tasks-in-parallel, perform-async-tasks-function
+ *
  * @param config - Configuration for task factory, parallelism limits, and concurrency keys.
  * @returns A function that accepts an array of inputs and returns a Promise resolving when all tasks complete.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function performTasksInParallelFunction<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(config: PerformTasksInParallelFunctionConfig<I, K>): PerformTasksInParallelFunction<I>;
 /**
@@ -229,13 +236,27 @@ export type PerformTaskFactoryTasksInParallelFunction<I> = (taskInputFactory: Pe
  * Creates a function that pulls task inputs from a factory and executes them in parallel
  * with configurable concurrency limits and non-concurrent key constraints.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilKind factory
+ * @dbxUtilTags promise, parallel, factory, concurrency, async, pull-tasks
+ * @dbxUtilRelated perform-tasks-in-parallel-function
+ *
  * @param config - Configuration for the task factory, parallelism, and concurrency behavior.
  * @returns a function that accepts a task input factory and returns a Promise that resolves when all tasks complete
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function performTasksFromFactoryInParallelFunction<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(config: PerformTasksFromFactoryInParallelFunctionConfig<I, K>): PerformTaskFactoryTasksInParallelFunction<I>;
 /**
  * Creates a default non-concurrent task key factory that generates unique incrementing number strings.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilKind factory
+ * @dbxUtilTags promise, parallel, key, factory, unique, incrementing
+ * @dbxUtilRelated perform-tasks-in-parallel-function, incrementing-number-factory
+ *
  * @returns A {@link StringFactory} that produces unique keys for identifying non-concurrent tasks.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeDefaultNonConcurrentTaskKeyFactory(): StringFactory<any>;

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

@@ -43,7 +43,14 @@ export interface TryWithPromiseFactoriesFunctionConfig<I, O> extends TryWithProm
  * Creates a {@link TryWithPromiseFactoriesFunction} that sequentially tries each promise factory
  * until one returns a non-null value (or a Maybe value if `successOnMaybe` is true).
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilKind factory
+ * @dbxUtilTags promise, factory, try, sequential, fallback, async
+ * @dbxUtilRelated run-named-async-tasks-function
+ *
  * @param config - Configuration including the array of promise factories and default behavior options.
  * @returns A function that tries each factory in order for a given input.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function tryWithPromiseFactoriesFunction<I, O>(config: TryWithPromiseFactoriesFunctionConfig<I, O>): TryWithPromiseFactoriesFunction<I, O>;

package/src/lib/promise/promise.task.d.ts

@@ -52,8 +52,15 @@ export interface RunNamedAsyncTasksResult<T = void> {
 /**
  * Creates a new RunNamedAsyncTasksFunction.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilKind factory
+ * @dbxUtilTags promise, async, task, factory, named, parallel
+ * @dbxUtilRelated try-with-promise-factories-function
+ *
  * @param config Optional configuration.
  * @returns A new RunNamedAsyncTasksFunction.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function runNamedAsyncTasksFunction<T = void>(config?: RunNamedAsyncTasksFunctionConfig<T>): RunNamedAsyncTasksFunction<T>;
 /**

package/src/lib/service/handler.config.d.ts

@@ -25,9 +25,16 @@ export type HandlerSetFunction<T, R = HandleResult> = (handlerFunction: Internal
 /**
  * Creates a {@link HandlerSetFunction} that registers a handler function on a pre-defined key.
  *
+ * @dbxUtil
+ * @dbxUtilCategory service
+ * @dbxUtilKind factory
+ * @dbxUtilTags service, handler, set, factory, register
+ * @dbxUtilRelated handler-mapped-set-function, handler-factory
+ *
  * @param accessor - The handler set accessor to register on.
  * @param key - The key (or keys) to associate the handler with.
  * @returns A function that accepts a handler function and registers it for the given key.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function handlerSetFunction<T, K extends PrimativeKey = string, R = HandleResult>(accessor: HandlerSetAccessor<T, K, R>, key: ArrayOrValue<K>): HandlerSetFunction<T, R>;
 /**
@@ -39,10 +46,17 @@ export type HandlerMappedSetFunction<I, R = HandleResult> = (handlerFunction: In
  * Creates a {@link HandlerMappedSetFunction} that maps the handler's native input type to a different
  * type before invoking the registered handler function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory service
+ * @dbxUtilKind factory
+ * @dbxUtilTags service, handler, set, mapped, factory, transform
+ * @dbxUtilRelated handler-set-function, handler-mapped-set-function-factory
+ *
  * @param accessor - The handler set accessor to register on.
  * @param key - The key (or keys) to associate the handler with.
  * @param mapFn - Function to map from the handler's native type to the handler function's expected type.
  * @returns A function that accepts a mapped handler function and registers it.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function handlerMappedSetFunction<I, T, K extends PrimativeKey = string, R = HandleResult>(accessor: HandlerSetAccessor<T, K, R>, key: ArrayOrValue<K>, mapFn: MapFunction<T, I>): HandlerMappedSetFunction<I, R>;
 /**
@@ -52,9 +66,16 @@ export type HandlerMappedSetFunctionFactory<I, K extends PrimativeKey = string,
 /**
  * Creates a {@link HandlerMappedSetFunctionFactory} that produces mapped set functions for any given key.
  *
+ * @dbxUtil
+ * @dbxUtilCategory service
+ * @dbxUtilKind factory
+ * @dbxUtilTags service, handler, mapped, factory, dispatch
+ * @dbxUtilRelated handler-mapped-set-function, handler-set-function
+ *
  * @param accessor - The handler set accessor to register on.
  * @param mapFn - Function to map from the handler's native type to the handler function's expected type.
  * @returns A factory that creates HandlerMappedSetFunctions for specific keys.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function handlerMappedSetFunctionFactory<I, T, K extends PrimativeKey = string, R = HandleResult>(accessor: HandlerSetAccessor<T, K, R>, mapFn: MapFunction<T, I>): HandlerMappedSetFunctionFactory<I, K, R>;
 /**
@@ -82,7 +103,14 @@ export interface HandlerConfigurerFactoryConfig<C extends HandlerBindAccessor<T,
  * Creates a {@link HandlerConfigurerFactory} that produces configurers for binding handler functions
  * to a handler instance with automatic `this` binding.
  *
+ * @dbxUtil
+ * @dbxUtilCategory service
+ * @dbxUtilKind factory
+ * @dbxUtilTags service, handler, configurer, factory, bind
+ * @dbxUtilRelated handler-bind-accessor, handler-factory
+ *
  * @param config - Configuration providing the accessor-to-configurer mapping.
  * @returns A factory that creates HandlerConfigurers for specific handlers.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function handlerConfigurerFactory<C extends HandlerBindAccessor<T, K, R>, T, K extends PrimativeKey = string, R = HandleResult>(config: HandlerConfigurerFactoryConfig<C, T, K, R>): HandlerConfigurerFactory<C, T, K, R>;

package/src/lib/service/handler.d.ts

@@ -93,17 +93,31 @@ export interface HandlerFactoryOptions<R = HandleResult> {
  * Creates a {@link HandlerFactory} that produces key-based dispatch handlers.
  * Each handler routes incoming values to registered handler functions based on a key extracted from the value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory service
+ * @dbxUtilKind factory
+ * @dbxUtilTags service, handler, factory, dispatch, key
+ * @dbxUtilRelated make-handler, handler-set-function, handler-configurer-factory
+ *
  * @param readKey - Function to extract the dispatch key from an input value.
  * @param options - Optional configuration for default and negative result values.
  * @returns A factory that creates new Handler instances.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function handlerFactory<T, K extends PrimativeKey = string>(readKey: ReadKeyFunction<T, K>): HandlerFactory<T, K, HandleResult>;
 export declare function handlerFactory<T, K extends PrimativeKey = string, R = HandleResult>(readKey: ReadKeyFunction<T, K>, options: HandlerFactoryOptions<R>): HandlerFactory<T, K, R>;
 /**
  * Convenience function that creates a new {@link Handler} from the given key reader using default options.
  *
+ * @dbxUtil
+ * @dbxUtilCategory service
+ * @dbxUtilKind factory
+ * @dbxUtilTags service, handler, factory, dispatch, key, convenience
+ * @dbxUtilRelated handler-factory
+ *
  * @param readKey - Function to extract the dispatch key from an input value.
  * @returns A new Handler instance.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeHandler<T, K extends PrimativeKey = string>(readKey: ReadKeyFunction<T, K>): Handler<T, K>;
 /**

package/src/lib/set/set.d.ts

@@ -204,9 +204,16 @@ export declare function mapValuesToSet<I, O>(values: Iterable<I>, mapFn: MapFunc
 /**
  * Creates a {@link SetHasValueFunction} from an {@link IterableOrValue} by first converting it to a Set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilKind factory
+ * @dbxUtilTags set, has, decision, factory, membership, exclude
+ * @dbxUtilRelated set-has-value-function, set-includes-function
+ *
  * @param iterable - The values to create a set from.
  * @param exclude - If true, the returned function returns true for values NOT in the set.
  * @returns A function that tests membership.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function hasValueFunction<T>(iterable: IterableOrValue<T>, exclude?: boolean): SetHasValueFunction<T>;
 /**
@@ -216,9 +223,16 @@ export type SetHasValueFunction<T> = (value: T) => boolean;
 /**
  * Creates a {@link SetHasValueFunction} for the given set. When `exclude` is true, returns the inverse (true for values not in the set).
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilKind factory
+ * @dbxUtilTags set, has, decision, factory, membership, exclude
+ * @dbxUtilRelated has-value-function, set-includes-function
+ *
  * @param set - The set to check against.
  * @param exclude - If true, returns true for values NOT in the set.
  * @returns A function that tests membership.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function setHasValueFunction<T>(set: Set<T>, exclude: boolean): SetHasValueFunction<T>;
 /**
@@ -263,10 +277,17 @@ export type SetIncludesFunction<T> = (valuesToFind: IterableOrValue<T>) => boole
 /**
  * Creates a {@link SetIncludesFunction} that checks whether the set includes given values using the specified mode.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilKind factory
+ * @dbxUtilTags set, includes, decision, factory, all, any, mode
+ * @dbxUtilRelated has-value-function, set-has-value-function
+ *
  * @param valuesSet - The reference set.
  * @param mode - Whether to require 'all' values or 'any' value to be present. Defaults to 'all'.
  * @param emptyValuesToFindArrayResult - The result when the values to find are empty.
  * @returns A function that tests inclusion against the set.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function setIncludesFunction<T>(valuesSet: Set<T>, mode?: SetIncludesMode, emptyValuesToFindArrayResult?: boolean): SetIncludesFunction<T>;
 /**

package/src/lib/set/set.decision.d.ts

@@ -9,9 +9,16 @@ export type IsInSetDecisionFunction<T, V> = DecisionFunction<T> & {
 /**
  * Creates an {@link IsInSetDecisionFunction} that checks whether a value (or a derived value) is in the given set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilKind factory
+ * @dbxUtilTags set, decision, predicate, factory, membership
+ * @dbxUtilRelated has-value-function, set-has-value-function, is-selected-decision-function-factory
+ *
  * @param set - The set to check membership against.
  * @param readValue - Optional function to extract the lookup value from the input. Defaults to identity.
  * @returns A decision function that returns true for values found in the set.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isInSetDecisionFunction<T>(set: Set<T>): IsInSetDecisionFunction<T, T>;
 export declare function isInSetDecisionFunction<T, V>(set: Set<V>, readValue: (value: T) => V): IsInSetDecisionFunction<T, V>;

package/src/lib/set/set.delta.d.ts

@@ -61,8 +61,15 @@ export interface SetDeltaFunctionConfig<T, K extends PrimativeKey = PrimativeKey
  * Creates a {@link SetDeltaFunction} that computes the differences between two iterables,
  * identifying which items were added, removed, or unchanged.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilKind factory
+ * @dbxUtilTags set, delta, diff, factory, change, added, removed
+ * @dbxUtilRelated index-delta-group-function, set-has-value-function
+ *
  * @param config - Configuration with the key reader and optional modification detector.
  * @returns A function that compares two iterables and returns an array of change pairs.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function setDeltaFunction<T>(config: SetDeltaFunctionConfig<T>): SetDeltaFunction<T>;
 /**

package/src/lib/set/set.selection.d.ts

@@ -23,7 +23,14 @@ export interface IsSelectedDecisionFunctionConfig<T, K extends PrimativeKey = Pr
  * Creates an {@link IsSelectedDecisionFunctionFactory} that produces decision functions
  * checking whether a value's key is included in a set of selected values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilKind factory
+ * @dbxUtilTags set, selection, decision, predicate, factory, key
+ * @dbxUtilRelated is-in-set-decision-function
+ *
  * @param config - Configuration with the key reader and default behavior.
  * @returns A factory that creates decision functions from a set of selected keys.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isSelectedDecisionFunctionFactory<T, K extends PrimativeKey = PrimativeKey>(config: IsSelectedDecisionFunctionConfig<T, K>): IsSelectedDecisionFunctionFactory<T, K>;

package/src/lib/sort.d.ts

@@ -92,6 +92,7 @@ export declare function compareFnOrder<T>(ascendingCompareFn: AscendingSortCompa
  * [{ name: 'Bob' }, { name: 'Alice' }].sort(byName);
  * // [{ name: 'Alice' }, { name: 'Bob' }]
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function compareWithMappedValuesFunction<T, V>(mapValue: MapFunction<T, V>, comparesFunction: SortCompareFunction<V>): SortCompareFunction<T>;
 /**
@@ -167,11 +168,18 @@ export type MinAndMaxFunction<T> = (values: Iterable<T>) => MinAndMaxFunctionRes
  * @param compareFn - Ascending sort comparison function used to determine min/max.
  * @returns A function that returns `{ min, max }` or `null` for empty iterables.
  *
+ * @dbxUtil
+ * @dbxUtilCategory sort
+ * @dbxUtilKind factory
+ * @dbxUtilTags sort, min, max, factory, iterable, compare
+ * @dbxUtilRelated min-and-max-index-items-function, sort-by-number-function
+ *
  * @example
  * ```ts
  * const fn = minAndMaxFunction<number>((a, b) => a - b);
  * fn([3, 1, 4, 1, 5]); // { min: 1, max: 5 }
  * fn([]);               // null
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function minAndMaxFunction<T>(compareFn: SortCompareFunction<T>): MinAndMaxFunction<T>;

package/src/lib/string/char.d.ts

@@ -42,9 +42,16 @@ export type ReplaceLastCharacterIfIsFunction = (input: string) => string;
  * Creates a function that replaces the last character of a string with the replacement string
  * if that character matches any of the specified values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, replace, last, character, conditional, factory
+ * @dbxUtilRelated replace-last-character-if, replace-character-at-index-if
+ *
  * @param replacement - string to substitute for the last character
  * @param is - character(s) that trigger the replacement
  * @returns a function that conditionally replaces the last character
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function replaceLastCharacterIfIsFunction(replacement: string, is: ArrayOrValue<string>): ReplaceLastCharacterIfIsFunction;
 /**

package/src/lib/string/dencoder.d.ts

@@ -69,9 +69,16 @@ export declare const PRIMATIVE_KEY_DENCODER_VALUE: (_input: unknown) => null;
  * Creates a new {@link PrimativeKeyDencoderFunction} that can bidirectionally encode/decode
  * primitive key values based on the configured value pairs.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, encode, decode, dencoder, bidirectional, factory, primitive
+ * @dbxUtilRelated primative-key-dencoder-map, primative-key-string-dencoder
+ *
  * @param config - configuration with value pairs and optional default fallback
  * @returns a function that encodes or decodes single values or arrays
  * @throws Error if a single value lookup produces a null result and no default handles it
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function primativeKeyDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyDencoderConfig<D, E>): PrimativeKeyDencoderFunction<D, E>;
 /**
@@ -101,9 +108,16 @@ export type PrimativeKeyStringDencoderFunction<D extends PrimativeKey, E extends
  * When no splitter is defined, all encoded values must be exactly one character long so the string
  * can be split character-by-character.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, encode, decode, dencoder, splitter, factory, primitive
+ * @dbxUtilRelated primative-key-dencoder, primative-key-dencoder-map
+ *
  * @param config - configuration with dencoder and optional splitter
  * @returns a bidirectional function for string-to-array and array-to-string conversion
  * @throws Error if encoded values contain the splitter character, or if values exceed one character when no splitter is defined
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function primativeKeyStringDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyStringDencoderConfig<D, E>): PrimativeKeyStringDencoderFunction<D, E>;
 /**
@@ -211,23 +225,44 @@ export type NumberStringDencoderFunction = ((input: NumberStringDencoderString)
  * Creates a {@link NumberStringDencoderFunction} from the given dencoder.
  * The returned function auto-detects the input type: numbers are encoded, strings are decoded.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, number, encode, decode, dencoder, bidirectional, factory
+ * @dbxUtilRelated number-string-dencoder, number-string-dencoder-encoded-string-value-function, number-string-dencoder-decoded-number-value-function
+ *
  * @param dencoder - the NumberStringDencoder to wrap
  * @returns a bidirectional encode/decode function
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderFunction(dencoder: NumberStringDencoder): NumberStringDencoderFunction;
 /**
  * Creates a function that always returns the encoded string form of the input.
  * Numbers are encoded; strings are passed through as-is.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, number, encode, normalize, factory
+ * @dbxUtilRelated number-string-dencoder-function, number-string-dencoder-decoded-number-value-function
+ *
  * @param dencoder - the NumberStringDencoder to use for encoding
  * @returns a function that normalizes input to an encoded string
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderEncodedStringValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderString;
 /**
  * Creates a function that always returns the decoded number form of the input.
  * Strings are decoded; numbers are passed through as-is.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, number, decode, normalize, factory
+ * @dbxUtilRelated number-string-dencoder-function, number-string-dencoder-encoded-string-value-function
+ *
  * @param dencoder - the NumberStringDencoder to use for decoding
  * @returns a function that normalizes input to a decoded number
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderDecodedNumberValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderNumber;

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

@@ -12,9 +12,16 @@ export type ToStringFunction<T, K extends string = string> = FactoryWithRequired
 /**
  * Wraps an existing factory with a {@link ToStringFunction} to produce strings from the factory's output.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, factory, wrap, transform, to-string
+ * @dbxUtilRelated string-from-date-factory, string-from-time-factory
+ *
  * @param factory - the original value factory
  * @param toStringFunction - function to convert the factory's output to a string
  * @returns a new factory that produces string values
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFactoryFromFactory<T, K extends string = string>(factory: Factory<T>, toStringFunction: ToStringFunction<T, K>): StringFactory<K>;
 /**
@@ -42,15 +49,29 @@ export interface StringFromDateConfig {
 }
 /**
  * Creates a factory that returns a string based on the input date.
- 
+ *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, date, factory, transform, slice
+ * @dbxUtilRelated string-from-time-factory, string-factory-from-factory, transform-string-function
+ *
  * @param config Configuration for the factory.
  * @returns A factory that returns a string based on the input date.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFromDateFactory(config: StringFromDateConfig): StringFromDateFactory;
 /**
  * Creates a factory that returns a string based on the Unix timestamp of the input date.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, date, time, timestamp, factory, suffix
+ * @dbxUtilRelated string-from-date-factory
+ *
  * @param digitsFromEnd The number of digits to return from the end of the generated string. Defaults to 7.
  * @returns A StringFromDateFactory.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFromTimeFactory(digitsFromEnd?: number): StringFromDateFactory;