@dereekb/util 13.11.14 → 13.11.15

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

@@ -16,7 +16,7 @@ export type UsePromiseCallback = (cb: PromiseCallback) => void;
  * Node.js-style error-first callback; calling it with an error rejects the promise, and
  * calling it without an error resolves it.
  *
- * @param use - A function that performs an async operation and signals completion via the provided callback.
- * @returns A Promise that resolves when the callback is invoked without an error, or rejects with the provided error.
+ * @param use - Performs an async operation and signals completion via the provided callback.
+ * @returns Resolves when the callback is invoked without an error, or rejects with the provided error.
  */
 export declare function useCallback(use: UsePromiseCallback): Promise<void>;

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

@@ -1,25 +1,25 @@
 /**
  * Checks whether the input value is a native Promise by testing for a `.then` method.
  *
+ * @param obj - The value to test.
+ * @returns `true` if the value is a Promise, `false` otherwise.
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, type-guard, async, then, check
  * @dbxUtilRelated is-promise-like, as-promise
- *
- * @param obj - The value to test.
- * @returns `true` if the value is a Promise, `false` otherwise.
  */
 export declare function isPromise<T, S>(obj: Promise<T> | S): obj is Promise<T>;
 /**
  * Checks whether the input value is PromiseLike (i.e., has a `.then` method), which
  * includes both native Promises and custom thenables.
  *
+ * @param obj - The value to test.
+ * @returns `true` if the value is PromiseLike, `false` otherwise.
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, type-guard, async, then, thenable, check
  * @dbxUtilRelated is-promise, as-promise
- *
- * @param obj - The value to test.
- * @returns `true` if the value is PromiseLike, `false` otherwise.
  */
 export declare function isPromiseLike<T, S>(obj: PromiseLike<T> | S): obj is PromiseLike<T>;

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

@@ -7,30 +7,30 @@ export interface PollConfig {
      *
      * Defaults to 250.
      */
-    wait?: number;
+    readonly wait?: number;
     /**
      * Predicate function that returns `true` when the polling condition has been met.
      */
-    check: () => boolean;
+    readonly check: () => boolean;
     /**
      * Maximum number of polling iterations before giving up.
      *
      * Defaults to `Number.MAX_SAFE_INTEGER`.
      */
-    timesToGiveup?: number;
+    readonly timesToGiveup?: number;
 }
 /**
  * Polls at a regular interval until a condition is met or the maximum number of attempts is reached.
  *
+ * @param config - Polling configuration including check function, wait interval, and max attempts.
+ * @param config.check - Predicate function that returns true when the polling condition has been satisfied.
+ * @param config.wait - Milliseconds to wait between polling iterations; defaults to 250.
+ * @param config.timesToGiveup - Maximum number of polling iterations before giving up; defaults to `Number.MAX_SAFE_INTEGER`
+ * @returns Resolves when the check condition returns `true` or the max attempts are exhausted.
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, poll, wait, retry, condition, async, interval
  * @dbxUtilRelated wait-for-ms, perform-task-loop
- *
- * @param config - Polling configuration including check function, wait interval, and max attempts.
- * @param config.check - predicate function that returns true when the polling condition has been satisfied
- * @param config.wait - milliseconds to wait between polling iterations; defaults to 250
- * @param config.timesToGiveup - maximum number of polling iterations before giving up; defaults to `Number.MAX_SAFE_INTEGER`
- * @returns A Promise that resolves when the check condition returns `true` or the max attempts are exhausted.
  */
 export declare function poll({ check, wait, timesToGiveup }: PollConfig): Promise<void>;

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

@@ -16,31 +16,31 @@ export type RunAsyncTasksForValuesConfig<T = unknown> = Omit<PerformAsyncTasksCo
 /**
  * Runs a single async task and returns the resulting value. Always configured to throw on failure.
  *
+ * @param taskFn - The async task to execute.
+ * @param config - Optional configuration for retries and retry behavior.
+ * @returns The value produced by the task, or undefined if the task produced no value.
+ * @throws {Error} Rethrows any error thrown by the task function.
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, async, task, retry, run, value
  * @dbxUtilRelated perform-async-task, run-async-tasks-for-values, perform-async-tasks
- *
- * @param taskFn - The async task to execute.
- * @param config - Optional configuration for retries and retry behavior.
- * @returns The value produced by the task, or undefined if the task produced no value.
- * @throws Rethrows any error thrown by the task function.
  */
 export declare function runAsyncTaskForValue<O>(taskFn: () => Promise<O>, config?: RunAsyncTaskForValueConfig<0>): Promise<Maybe<O>>;
 /**
  * Runs an async task for each input value and returns an array of the resulting values.
  * Always configured to throw on failure.
  *
+ * @param input - The array of input values to process.
+ * @param taskFn - The async task function to run for each input value.
+ * @param config - Optional configuration for parallelism and retries.
+ * @returns The results produced by the task function for each input.
+ * @throws {Error} Rethrows any error thrown by a task function.
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, async, tasks, parallel, batch, retry, run, values
  * @dbxUtilRelated perform-async-tasks, run-async-task-for-value
- *
- * @param input - The array of input values to process.
- * @param taskFn - The async task function to run for each input value.
- * @param config - Optional configuration for parallelism and retries.
- * @returns An array of results produced by the task function for each input.
- * @throws Rethrows any error thrown by a task function.
  */
 export declare function runAsyncTasksForValues<T, K = unknown>(input: T[], taskFn: PerformAsyncTaskFn<T, K>, config?: RunAsyncTasksForValuesConfig<T>): Promise<K[]>;
 /**
@@ -116,30 +116,30 @@ export interface PerformAsyncTasksConfig<I = unknown, K extends PrimativeKey = P
  * Performs async tasks for each input value with configurable retry and parallelism behavior.
  * Useful for operations that may experience optimistic concurrency collisions.
  *
- * @dbxUtil
- * @dbxUtilCategory promise
- * @dbxUtilTags async, promise, parallel, retry, task, batch, concurrency, throttle
- * @dbxUtilRelated perform-tasks-in-parallel, perform-async-task
- *
  * @param input - The array of input values to process.
  * @param taskFn - The async function to execute for each input.
  * @param config - Configuration for retries, parallelism, and error handling.
  * @returns An aggregated result with succeeded/failed items and their outputs/errors.
- * @throws Rethrows the last error from retries if `throwError` is true (default).
+ * @throws {Error} Rethrows the last error from retries if `throwError` is true (default).
+ *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags async, promise, parallel, retry, task, batch, concurrency, throttle
+ * @dbxUtilRelated perform-tasks-in-parallel, perform-async-task
  */
 export declare function performAsyncTasks<I, O = unknown, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(input: I[], taskFn: PerformAsyncTaskFn<I, O>, config?: PerformAsyncTasksConfig<I, K>): Promise<PerformAsyncTasksResult<I, O>>;
 /**
  * Performs a single async task with configurable retry behavior and returns the result with success status.
  *
+ * @param taskFn - The async task to execute.
+ * @param config - Optional configuration for retries and error handling.
+ * @returns A result object containing the value (if successful) and a success flag.
+ * @throws {Error} Rethrows the last error from retries if `throwError` is true (default).
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, async, task, retry, run, success
  * @dbxUtilRelated perform-async-tasks, run-async-task-for-value
- *
- * @param taskFn - The async task to execute.
- * @param config - Optional configuration for retries and error handling.
- * @returns A result object containing the value (if successful) and a success flag.
- * @throws Rethrows the last error from retries if `throwError` is true (default).
  */
 export declare function performAsyncTask<O>(taskFn: () => Promise<O>, config?: PerformAsyncTaskConfig<0>): Promise<PerformAsyncTaskResult<O>>;
 /**
@@ -166,22 +166,23 @@ export type PerformTasksInParallelFunction<I> = (input: I[]) => Promise<void>;
  *
  * @param input - The array of items to process.
  * @param config - Configuration for task execution, parallelism, and concurrency constraints.
- * @returns A Promise that resolves when all tasks complete.
- * @throws Rethrows the first error encountered during task execution.
+ * @returns Resolves when all tasks complete.
+ * @throws {Error} Rethrows the first error encountered during task execution.
  */
 export declare function performTasksInParallel<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(input: I[], config: PerformTasksInParallelFunctionConfig<I, K>): Promise<void>;
 /**
  * Creates a reusable function that performs tasks in parallel with optional concurrency limits
  * and non-concurrent task key constraints.
  *
+ * @param config - Configuration for task factory, parallelism limits, and concurrency keys.
+ * @returns Accepts an array of inputs and returns a Promise resolving when all tasks complete.
+ *
  * @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>;
@@ -223,7 +224,7 @@ export interface PerformTasksFromFactoryInParallelFunctionConfig<I, K extends Pr
  * A factory function that produces the next batch of task inputs. Returns `null` to signal
  * that no more inputs are available.
  */
-export type PerformTaskFactoryTasksInParallelFunctionTaskInputFactory<I> = () => PromiseOrValue<ArrayOrValue<I> | null>;
+export type PerformTaskFactoryTasksInParallelFunctionTaskInputFactory<I> = () => PromiseOrValue<Maybe<ArrayOrValue<I>>>;
 /**
  * Function that awaits all promises generated from the task factory until the factory returns null.
  *
@@ -236,27 +237,29 @@ 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.
  *
+ * @param config - Configuration for the task factory, parallelism, and concurrency behavior.
+ * @returns Accepts a task input factory and returns a Promise that resolves when all tasks complete.
+ *
  * @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.
  *
+ * @returns A {@link StringFactory} that produces unique keys for identifying non-concurrent tasks.
+ *
  * @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

@@ -1,7 +1,7 @@
 import { type FactoryWithRequiredInput } from '../getter/getter';
 import { type Maybe } from '../value/maybe.type';
 /**
- * A function that tries an array of Promise factories one after another until one
+ * Tries an array of Promise factories one after another until one
  * produces a successful result. Returns `undefined` if none succeed.
  *
  * @param input - The input to pass to each factory.
@@ -43,14 +43,15 @@ 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).
  *
+ * @param config - Configuration including the array of promise factories and default behavior options.
+ * @returns Tries each factory in order for a given input.
+ *
  * @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.loop.d.ts

@@ -8,11 +8,11 @@ export interface PerformTaskLoopConfig<O> {
     /**
      * Produces the next value given the iteration index and the previous value.
      */
-    next: (i: number, prev: Maybe<O>) => Promise<O>;
+    readonly next: (i: number, prev: Maybe<O>) => Promise<O>;
     /**
      * Returns whether to continue looping. Called after each iteration with the current value and next index.
      */
-    checkContinue: (prev: Maybe<O>, i: number) => PromiseOrValue<boolean>;
+    readonly checkContinue: (prev: Maybe<O>, i: number) => PromiseOrValue<boolean>;
 }
 /**
  * Configuration for {@link performTaskLoop} with a required initial value.
@@ -21,15 +21,15 @@ export interface PerformTaskLoopWithInitConfig<O> {
     /**
      * The initial value to start the loop with.
      */
-    initValue: O;
+    readonly initValue: O;
     /**
      * Produces the next value given the iteration index and the previous value.
      */
-    next: (i: number, prev: O) => Promise<O>;
+    readonly next: (i: number, prev: O) => Promise<O>;
     /**
      * Returns whether to continue looping. Called after each iteration with the current value and next index.
      */
-    checkContinue: (prev: O, i: number) => PromiseOrValue<boolean>;
+    readonly checkContinue: (prev: O, i: number) => PromiseOrValue<boolean>;
 }
 /**
  * Executes an async task in a loop, calling `next` repeatedly until `checkContinue` returns false.
@@ -49,7 +49,7 @@ export interface PerformTaskCountLoopConfig<O> extends Omit<PerformTaskLoopConfi
     /**
      * The number of iterations to perform.
      */
-    count: number;
+    readonly count: number;
 }
 /**
  * Configuration for {@link performTaskCountLoop} with a required initial value.
@@ -58,7 +58,7 @@ export interface PerformTaskCountLoopWithInitConfig<O> extends Omit<PerformTaskL
     /**
      * The number of iterations to perform.
      */
-    count: number;
+    readonly count: number;
 }
 /**
  * Performs an async task loop a fixed number of times. A convenience wrapper around
@@ -84,18 +84,18 @@ export interface PerformMakeLoopConfig<O> {
     /**
      * The factory function to create each item.
      */
-    make: PerformMakeLoopFunction<O>;
+    readonly make: PerformMakeLoopFunction<O>;
     /**
      * The total number of items to create.
      */
-    count: number;
+    readonly count: number;
 }
 /**
  * Creates an array of items by invoking a make function in a loop a specified number of times.
  * Each iteration receives the current index and the array of items created so far.
  *
  * @param config - Configuration with the make function and count.
- * @returns An array of all created items.
+ * @returns The all created items.
  */
 export declare function performMakeLoop<O>(config: PerformMakeLoopConfig<O>): Promise<O[]>;
 /**
@@ -113,7 +113,7 @@ export interface PerformBatchLoopConfig<O> extends BatchCount {
     /**
      * Factory function that creates a batch of items given the requested count.
      */
-    make: PerformBatchLoopFunction<O>;
+    readonly make: PerformBatchLoopFunction<O>;
 }
 /**
  * Creates items in batches by dividing a total count into batch-sized chunks and

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

@@ -2,7 +2,7 @@ import { type AsyncFactory } from '../getter/getter';
 import { type Maybe } from '../value';
 import { type RunAsyncTasksForValuesConfig } from './promise';
 /**
- * A function that returns a Promise, typically returning void/no value.
+ * Returns a Promise, typically returning void/no value.
  */
 export type AsyncTask<T = void> = AsyncFactory<T>;
 /**
@@ -17,7 +17,7 @@ export type NamedAsyncTask<T = void> = {
  */
 export type NamedAsyncTaskRecord<T = void> = Record<string, AsyncTask<T>>;
 /**
- * A function that runs an array of named async tasks.
+ * Runs an array of named async tasks.
  */
 export type RunNamedAsyncTasksFunction<T = void> = (inputTasks: RunNamedAsyncTasksInput<T>, options?: Maybe<RunNamedAsyncTasksFunctionOptions<T>>) => Promise<RunNamedAsyncTasksResult<T>>;
 /**
@@ -52,14 +52,15 @@ export interface RunNamedAsyncTasksResult<T = void> {
 /**
  * Creates a new RunNamedAsyncTasksFunction.
  *
+ * @param config - Optional configuration.
+ * @returns 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>;
@@ -67,7 +68,7 @@ export declare function runNamedAsyncTasksFunction<T = void>(config?: RunNamedAs
  * Convenience function that creates a {@link RunNamedAsyncTasksFunction} and immediately
  * executes it with the given tasks.
  *
- * @param inputTasks - An array of named tasks or a record of task functions keyed by name.
+ * @param inputTasks - The named tasks or a record of task functions keyed by name.
  * @param config - Optional configuration for callbacks and default execution options.
  * @returns The result containing successful and failed tasks.
  */

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

@@ -5,11 +5,11 @@ export type PromiseOrValue<T> = Promise<T> | T;
 /**
  * Wraps the input in a resolved Promise if it is not already a Promise.
  *
+ * @param input - A value or Promise to normalize into a Promise.
+ * @returns Resolves to the input value.
+ *
  * @dbxUtil
  * @dbxUtilCategory promise
  * @dbxUtilTags promise, async, normalize, resolve, ensure
- *
- * @param input - A value or Promise to normalize into a Promise.
- * @returns A Promise that resolves to the input value.
  */
 export declare function asPromise<T>(input: PromiseOrValue<T>): Promise<T>;

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

@@ -1,7 +1,7 @@
 import { type GetterOrValue } from '../getter';
 import { type UseAsync } from '../value';
 /**
- * A function that resolves a cached Promise value and passes it to the given async consumer,
+ * Resolves a cached Promise value and passes it to the given async consumer,
  * returning the consumer's result.
  */
 export type UsePromiseFunction<I> = <O>(useFn: UseAsync<I, O>) => Promise<O>;
@@ -9,7 +9,7 @@ export type UsePromiseFunction<I> = <O>(useFn: UseAsync<I, O>) => Promise<O>;
  * Creates a {@link UsePromiseFunction} that resolves the input promise and passes the result
  * to any consumer function provided at call time.
  *
- * @param input - A Promise or a getter that returns a Promise, whose resolved value will be passed to consumers.
- * @returns A function that accepts an async consumer and returns the consumer's result.
+ * @param input - Promise or a getter that returns a Promise, whose resolved value will be passed to consumers.
+ * @returns Accepts an async consumer and returns the consumer's result.
  */
 export declare function usePromise<I>(input: GetterOrValue<Promise<I>>): UsePromiseFunction<I>;

package/src/lib/relation/relation.d.ts

@@ -84,25 +84,25 @@ export type ChangeRelationObjectsMaskFn<T> = (x: T) => boolean;
  * Configuration for modifying a single-type relation collection via {@link ModelRelationUtility}.
  */
 export interface UpdateRelationConfig<T> {
-    readKey: ReadRelationKeyFn<T>;
-    merge: MergeRelationObjectsFn<T>;
+    readonly readKey: ReadRelationKeyFn<T>;
+    readonly merge: MergeRelationObjectsFn<T>;
     /**
      * Whether or not an item should be removed when remove is called.
      */
-    shouldRemove?: (x: T) => boolean;
+    readonly shouldRemove?: (x: T) => boolean;
     /**
      * Whether or not the item should be considered when performing a change.
      *
      * For instance, existing items that are passed to this function and it returns false are unable to be changed,
      * and new/target items that are passed to this function and it returns false are ignored.
      */
-    mask?: ChangeRelationObjectsMaskFn<T>;
+    readonly mask?: ChangeRelationObjectsMaskFn<T>;
 }
 /**
  * Extends {@link UpdateRelationConfig} with a type reader for multi-type relation collections.
  */
 export interface UpdateMiltiTypeRelationConfig<T> extends UpdateRelationConfig<T> {
-    readType: ReadRelationModelTypeFn<T>;
+    readonly readType: ReadRelationModelTypeFn<T>;
 }
 /**
  * Utility class for modifying a collection of relational objects.
@@ -136,11 +136,11 @@ export declare class ModelRelationUtility {
      *
      * Order from the "current" is retained. Anything in currentRetain overrides modifiedResults.
      *
-     * @param current - the original array whose ordering is preserved
-     * @param currentRetain - items from `current` that were excluded from modification and take precedence in the merge
-     * @param modifiedResults - items that were modified or added during the relation change
-     * @param readKey - function that extracts the relation key from each item for ordering
-     * @returns the merged array with original ordering restored
+     * @param current - The original array whose ordering is preserved.
+     * @param currentRetain - Items from `current` that were excluded from modification and take precedence in the merge.
+     * @param modifiedResults - Items that were modified or added during the relation change.
+     * @param readKey - Function that extracts the relation key from each item for ordering.
+     * @returns The merged array with original ordering restored.
      */
     private static _mergeMaskResults;
     private static _modifyCollectionWithoutMask;
@@ -166,11 +166,11 @@ export declare class ModelRelationUtility {
     /**
      * Used to modify a collection which may be multi-type. If readType is provided, the collection is handled as a multi-type map.
      *
-     * @param current - the current collection of relation objects
-     * @param mods - the modifications to apply to the collection
-     * @param modifyCollection - function that applies modifications to a single-type subset of the collection
-     * @param readType - optional function to read the type from each relation object, enabling multi-type handling
-     * @returns the modified collection with all changes applied
+     * @param current - The current collection of relation objects.
+     * @param mods - The modifications to apply to the collection.
+     * @param modifyCollection - Function that applies modifications to a single-type subset of the collection.
+     * @param readType - Optional function to read the type from each relation object, enabling multi-type handling.
+     * @returns The modified collection with all changes applied.
      */
     private static _modifyCollection;
     private static _modifyMultiTypeCollection;

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

@@ -25,20 +25,21 @@ export type HandlerSetFunction<T, R = HandleResult> = (handlerFunction: Internal
 /**
  * Creates a {@link HandlerSetFunction} that registers a handler function on a pre-defined key.
  *
+ * @param accessor - The handler set accessor to register on.
+ * @param key - The key (or keys) to associate the handler with.
+ * @returns Accepts a handler function and registers it for the given 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>;
 /**
- * A function that registers a handler function whose input type differs from the handler's native type,
+ * Registers a handler function whose input type differs from the handler's native type,
  * using a mapping function to convert between them.
  */
 export type HandlerMappedSetFunction<I, R = HandleResult> = (handlerFunction: InternalHandlerFunction<I, R>) => void;
@@ -46,16 +47,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.
  *
+ * @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 Accepts a mapped handler function and registers it.
+ *
  * @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>;
@@ -66,24 +68,25 @@ export type HandlerMappedSetFunctionFactory<I, K extends PrimativeKey = string,
 /**
  * Creates a {@link HandlerMappedSetFunctionFactory} that produces mapped set functions for any given key.
  *
+ * @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.
+ *
  * @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>;
 /**
- * A function that configures handler bindings via a configurer object.
+ * Configures handler bindings via a configurer object.
  */
 export type HandlerConfigurerFunction<C extends HandlerBindAccessor<T, K, R>, T, K extends PrimativeKey = string, R = HandleResult> = (configurer: C) => void;
 /**
- * A function that binds an object to a handler and invokes a configure callback.
+ * Binds an object to a handler and invokes a configure callback.
  */
 export type HandlerConfigurer<C extends HandlerBindAccessor<T, K, R>, T, K extends PrimativeKey = string, R = HandleResult> = (bindTo: unknown, configure: HandlerConfigurerFunction<C, T, K, R>) => void;
 /**
@@ -97,20 +100,21 @@ export interface HandlerConfigurerFactoryConfig<C extends HandlerBindAccessor<T,
     /**
      * Creates a typed configurer from a bind accessor.
      */
-    configurerForAccessor: (accessor: HandlerBindAccessor<T, K, R>) => C;
+    readonly configurerForAccessor: (accessor: HandlerBindAccessor<T, K, R>) => C;
 }
 /**
  * Creates a {@link HandlerConfigurerFactory} that produces configurers for binding handler functions
  * to a handler instance with automatic `this` binding.
  *
+ * @param config - Configuration providing the accessor-to-configurer mapping.
+ * @returns A factory that creates HandlerConfigurers for specific handlers.
+ *
  * @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

@@ -109,14 +109,15 @@ export declare function handlerFactory<T, K extends PrimativeKey = string, R = H
 /**
  * Convenience function that creates a new {@link Handler} from the given key reader using default options.
  *
+ * @param readKey - Function to extract the dispatch key from an input value.
+ * @returns A new Handler instance.
+ *
  * @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/service/typed.service.d.ts

@@ -27,7 +27,7 @@ export declare class TypedServiceRegistryInstance<S, T extends string = string>
      *
      * @param type - The type key to look up.
      * @returns The registered service instance.
-     * @throws Error if no service is registered for the given type.
+     * @throws {Error} If no service is registered for the given type.
      */
     serviceForType(type: T): S;
 }
@@ -38,7 +38,7 @@ export interface TypedServiceRegistrySetupConfig<S, T extends string = string> {
     /**
      * A record mapping type keys to their service instances.
      */
-    services: {
+    readonly services: {
         [K in T]: S;
     };
 }