@dereekb/util 13.0.7 → 13.2.0

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

@@ -1,39 +1,107 @@
 import { type BatchCount } from '../grouping';
 import { type Maybe } from '../value/maybe.type';
 import { type PromiseOrValue } from './promise.type';
+/**
+ * Configuration for {@link performTaskLoop} without an initial value.
+ */
 export interface PerformTaskLoopConfig<O> {
+    /** Produces the next value given the iteration index and the previous value. */
     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>;
 }
+/**
+ * Configuration for {@link performTaskLoop} with a required initial value.
+ */
 export interface PerformTaskLoopWithInitConfig<O> {
+    /** The initial value to start the loop with. */
     initValue: O;
+    /** Produces the next value given the iteration index and the previous value. */
     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>;
 }
+/**
+ * Executes an async task in a loop, calling `next` repeatedly until `checkContinue` returns false.
+ * Optionally starts with an initial value. Returns the final value produced by the loop.
+ *
+ * @param config - Loop configuration with the next-value producer and continuation check.
+ * @returns The final value produced by the last iteration.
+ */
 export declare function performTaskLoop<O>(config: PerformTaskLoopWithInitConfig<O>): Promise<O>;
 export declare function performTaskLoop<O>(config: PerformTaskLoopConfig<O>): Promise<O>;
 export declare function performTaskLoop<O>(config: PerformTaskLoopConfig<O>): Promise<Maybe<O>>;
 export declare function performTaskLoop(config: PerformTaskLoopConfig<void>): Promise<void>;
+/**
+ * Configuration for {@link performTaskCountLoop} without an initial value.
+ */
 export interface PerformTaskCountLoopConfig<O> extends Omit<PerformTaskLoopConfig<O>, 'checkContinue'> {
+    /** The number of iterations to perform. */
     count: number;
 }
+/**
+ * Configuration for {@link performTaskCountLoop} with a required initial value.
+ */
 export interface PerformTaskCountLoopWithInitConfig<O> extends Omit<PerformTaskLoopWithInitConfig<O>, 'checkContinue'> {
+    /** The number of iterations to perform. */
     count: number;
 }
+/**
+ * Performs an async task loop a fixed number of times. A convenience wrapper around
+ * {@link performTaskLoop} that automatically checks the iteration count.
+ *
+ * @param config - Loop configuration with the iteration count and next-value producer.
+ * @returns The final value produced by the last iteration.
+ */
 export declare function performTaskCountLoop<O>(config: PerformTaskCountLoopWithInitConfig<O>): Promise<O>;
 export declare function performTaskCountLoop<O>(config: PerformTaskCountLoopConfig<O>): Promise<Maybe<O>>;
 export declare function performTaskCountLoop(config: PerformTaskCountLoopConfig<void>): Promise<void>;
+/**
+ * A function that creates a single item in a {@link performMakeLoop} iteration.
+ *
+ * @param i - The current iteration index.
+ * @param made - The array of items created so far.
+ */
 export type PerformMakeLoopFunction<O> = (i: number, made: O[]) => Promise<O>;
+/**
+ * Configuration for {@link performMakeLoop}.
+ */
 export interface PerformMakeLoopConfig<O> {
+    /** The factory function to create each item. */
     make: PerformMakeLoopFunction<O>;
+    /** The total number of items to create. */
     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.
+ */
 export declare function performMakeLoop<O>(config: PerformMakeLoopConfig<O>): Promise<O[]>;
+/**
+ * A function that creates a batch of items in a {@link performBatchLoop} iteration.
+ *
+ * @param itemsToMake - The number of items to create in this batch.
+ * @param i - The current batch index.
+ * @param made - The array of batches created so far.
+ */
 export type PerformBatchLoopFunction<O> = (itemsToMake: number, i: number, made: O[][]) => Promise<O[]>;
+/**
+ * Configuration for {@link performBatchLoop}.
+ */
 export interface PerformBatchLoopConfig<O> extends BatchCount {
     /**
-     * Makes a certain number of items.
+     * Factory function that creates a batch of items given the requested count.
      */
     make: PerformBatchLoopFunction<O>;
 }
+/**
+ * Creates items in batches by dividing a total count into batch-sized chunks and
+ * invoking the make function for each batch.
+ *
+ * @param config - Configuration with the make function and batch count parameters.
+ * @returns A two-dimensional array where each inner array is a batch of created items.
+ */
 export declare function performBatchLoop<O>(config: PerformBatchLoopConfig<O>): Promise<O[][]>;

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

@@ -1,13 +1,25 @@
 /**
- * A reference to a Promise and its resolve/reject functions.
+ * A deconstructed Promise exposing its `resolve` and `reject` functions alongside the Promise itself.
+ * Useful for controlling Promise resolution from outside the executor.
  */
 export type PromiseReference<O = unknown> = {
     readonly promise: Promise<O>;
     readonly resolve: (value: O | PromiseLike<O>) => void;
     readonly reject: (reason?: unknown) => void;
 };
+/**
+ * An executor function for a Promise, matching the signature of the native Promise constructor callback.
+ *
+ * @param resolve - Resolves the Promise with a value.
+ * @param reject - Rejects the Promise with a reason.
+ */
 export type PromiseExecutor<O> = (resolve: (value: O | PromiseLike<O>) => void, reject: (reason?: unknown) => void) => void;
 /**
- * Creates a new promise and returns the full ref for it.
+ * Creates a new {@link PromiseReference} containing a Promise and its externally accessible
+ * `resolve` and `reject` functions. An optional executor can be provided to run initialization
+ * logic inside the Promise constructor.
+ *
+ * @param executor - An optional executor function invoked inside the Promise constructor.
+ * @returns A PromiseReference with the created Promise and its control functions.
  */
 export declare function promiseReference<O>(executor?: PromiseExecutor<O>): PromiseReference<O>;

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

@@ -12,6 +12,9 @@ export type NamedAsyncTask<T = void> = {
     readonly name: string;
     readonly run: AsyncTask<T>;
 };
+/**
+ * A record of named async tasks, keyed by name.
+ */
 export type NamedAsyncTaskRecord<T = void> = Record<string, AsyncTask<T>>;
 /**
  * A function that runs an array of named async tasks.
@@ -54,10 +57,11 @@ export interface RunNamedAsyncTasksResult<T = void> {
  */
 export declare function runNamedAsyncTasksFunction<T = void>(config?: RunNamedAsyncTasksFunctionConfig<T>): RunNamedAsyncTasksFunction<T>;
 /**
- * Runs the input named tasks and returns the results.
+ * Convenience function that creates a {@link RunNamedAsyncTasksFunction} and immediately
+ * executes it with the given tasks.
  *
- * @param inputTasks
- * @param options
- * @returns
+ * @param inputTasks - An array of 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.
  */
 export declare function runNamedAsyncTasks<T = void>(inputTasks: RunNamedAsyncTasksInput<T>, config?: RunNamedAsyncTasksFunctionConfig<T>): Promise<RunNamedAsyncTasksResult<T>>;

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

@@ -1,11 +1,11 @@
 /**
- * A promise or a value.
+ * A value that may be either a Promise resolving to T, or a synchronous value of type T.
  */
 export type PromiseOrValue<T> = Promise<T> | T;
 /**
- * Convenience function for calling Promise.resolve
+ * Wraps the input in a resolved Promise if it is not already a Promise.
  *
- * @param input
- * @returns
+ * @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,13 +1,15 @@
 import { type GetterOrValue } from '../getter';
 import { type UseAsync } from '../value';
 /**
- * Uses a cached promise value.
+ * A function that 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>;
 /**
- * Creates a UsePromiseFunction.
+ * Creates a {@link UsePromiseFunction} that resolves the input promise and passes the result
+ * to any consumer function provided at call time.
  *
- * @param input
- * @returns
+ * @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.
  */
 export declare function usePromise<I>(input: GetterOrValue<Promise<I>>): UsePromiseFunction<I>;

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

@@ -1,6 +1,9 @@
 /**
- * Waits a certain number of ms before resolving the promise.
+ * Returns a Promise that resolves after the specified number of milliseconds.
+ * Optionally resolves with the provided value.
  *
- * @param ms
+ * @param ms - The number of milliseconds to wait before resolving.
+ * @param value - An optional value to resolve the Promise with.
+ * @returns A Promise that resolves after the specified delay.
  */
 export declare function waitForMs(ms: number): Promise<void>;

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

@@ -34,12 +34,33 @@ export declare const RelationChange: {
      */
     readonly INSERT: "insert";
 };
+/**
+ * Union of all valid {@link RelationChange} values.
+ */
 export type RelationChangeType = (typeof RelationChange)[keyof typeof RelationChange];
+/**
+ * A string-based relation identifier.
+ */
 export type RelationString = string;
+/**
+ * A relation target that is either a string key or an object containing relation data.
+ */
 export type RelationObject = RelationString | object;
+/**
+ * A string identifying the type/category of a relation model.
+ */
 export type RelationModelType = string;
+/**
+ * A unique key identifying a relation model, either a string or number.
+ */
 export type RelationKey = string | number;
+/**
+ * Extracts the unique key from a relation model.
+ */
 export type ReadRelationKeyFn<T> = (model: T) => RelationKey;
+/**
+ * Extracts the model type string from a relation model.
+ */
 export type ReadRelationModelTypeFn<T> = (model: T) => RelationModelType;
 /**
  * Merges the two input values. The "a" value is usually the existing/incumbent value, while "b" is the new value.
@@ -49,6 +70,9 @@ export type MergeRelationObjectsFn<T> = (a: T, b: T) => T;
  * Whether or not the object is changable as part of this request.
  */
 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>;
@@ -64,6 +88,9 @@ export interface UpdateRelationConfig<T> {
      */
     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>;
 }
@@ -73,7 +100,25 @@ export interface UpdateMiltiTypeRelationConfig<T> extends UpdateRelationConfig<T
  * For instance, a string collection of keys.
  */
 export declare class ModelRelationUtility {
+    /**
+     * Convenience method that modifies a collection of plain string relations.
+     *
+     * @param current - The current string collection.
+     * @param change - The type of relation change to perform.
+     * @param mods - The string values to apply as modifications.
+     * @returns The modified string collection.
+     */
     static modifyStringCollection(current: Maybe<RelationString[]>, change: RelationChangeType, mods: RelationString[]): RelationString[];
+    /**
+     * Applies a {@link RelationChangeType} operation to a typed collection of relation objects.
+     * Supports single-type and multi-type collections depending on the config.
+     *
+     * @param current - The current collection of relation objects.
+     * @param change - The relation change operation to perform.
+     * @param mods - The modification objects to apply.
+     * @param config - Configuration providing key/type readers, merge function, and optional mask.
+     * @returns The modified collection.
+     */
     static modifyCollection<T extends RelationObject>(current: Maybe<T[]>, change: RelationChangeType, mods: T[], config: UpdateMiltiTypeRelationConfig<T>): T[];
     static modifyCollection<T extends RelationObject>(current: Maybe<T[]>, change: RelationChangeType, mods: T[], config: UpdateRelationConfig<T>): T[];
     /**
@@ -83,7 +128,24 @@ export declare class ModelRelationUtility {
      */
     private static _mergeMaskResults;
     private static _modifyCollectionWithoutMask;
+    /**
+     * Merges update objects into matching existing items in the collection. Items without a match are ignored.
+     *
+     * @param current - The current collection.
+     * @param update - The objects to merge into matching items.
+     * @param config - Configuration with key/type readers and merge function.
+     * @returns The updated collection.
+     */
     static updateCollection<T extends RelationObject>(current: T[], update: T[], config: UpdateRelationConfig<T> | UpdateMiltiTypeRelationConfig<T>): T[];
+    /**
+     * Inserts objects into the collection: merges with existing items that share a key,
+     * and adds new items that have no match.
+     *
+     * @param current - The current collection.
+     * @param update - The objects to insert or merge.
+     * @param config - Configuration with key/type readers and merge function.
+     * @returns The collection with insertions and merges applied.
+     */
     static insertCollection<T extends RelationObject>(current: T[], update: T[], config: UpdateRelationConfig<T> | UpdateMiltiTypeRelationConfig<T>): T[];
     /**
      * Used to modify a collection which may be multi-type. If readType is provided, the collection is handled as a multi-type map.
@@ -92,9 +154,45 @@ export declare class ModelRelationUtility {
     private static _modifyMultiTypeCollection;
     private static _insertSingleTypeCollection;
     private static _updateSingleTypeCollection;
+    /**
+     * Adds items to the collection, replacing any existing items with the same key.
+     * New items take precedence over existing ones with duplicate keys.
+     *
+     * @param current - The current collection.
+     * @param add - The items to add.
+     * @param readKey - Function to extract the unique key from each item.
+     * @returns The collection with added items.
+     */
     static addToCollection<T extends RelationObject>(current: Maybe<T[]>, add: T[], readKey: ReadRelationKeyFn<T>): T[];
+    /**
+     * Removes items from the collection by matching keys. Optionally uses a `shouldRemove`
+     * predicate to conditionally skip removal of matched items.
+     *
+     * @param current - The current collection.
+     * @param remove - The items whose keys identify which items to remove.
+     * @param readKey - Function to extract the unique key from each item.
+     * @param shouldRemove - Optional predicate that must return true for a matched item to actually be removed.
+     * @returns The collection with matching items removed.
+     */
     static removeFromCollection<T extends RelationObject>(current: Maybe<T[]>, remove: T[], readKey: ReadRelationKeyFn<T>, shouldRemove?: (x: T) => boolean): T[];
+    /**
+     * Removes items from the collection whose keys match any of the given keys to remove.
+     *
+     * @param current - The current collection.
+     * @param keysToRemove - The keys identifying items to remove.
+     * @param readKey - Function to extract the unique key from each item.
+     * @returns The collection with matching items removed.
+     */
     static removeKeysFromCollection<T extends RelationObject>(current: Maybe<T[]>, keysToRemove: RelationKey[], readKey: ReadRelationKeyFn<T>): T[];
+    /**
+     * Removes duplicate items from the collection by key, keeping the first occurrence.
+     * Optionally excludes items whose keys appear in an additional keys list.
+     *
+     * @param relations - The collection to deduplicate.
+     * @param readKey - Function to extract the unique key from each item.
+     * @param additionalKeys - Extra keys to treat as already seen (items with these keys are excluded).
+     * @returns The deduplicated collection.
+     */
     static removeDuplicates<T>(relations: Maybe<T[]>, readKey: ReadRelationKeyFn<T>, additionalKeys?: RelationKey[]): T[];
     private static _assertMergeProvided;
 }

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

@@ -10,11 +10,12 @@ export interface HandlerBindAccessor<T, K extends PrimativeKey = string, R = Han
     readonly boundTo: unknown;
 }
 /**
- * Creates a HandlerBindAccessor<T, K> for the input values.
+ * Creates a {@link HandlerBindAccessor} that automatically binds handler functions to the given object
+ * when registering them via `set`.
  *
- * @param bindTo
- * @param accessor
- * @returns
+ * @param boundTo - The object to bind handler functions to.
+ * @param accessor - The underlying handler accessor to delegate to.
+ * @returns A HandlerBindAccessor wrapping the accessor with automatic binding.
  */
 export declare function handlerBindAccessor<T, K extends PrimativeKey = string, R = HandleResult>(boundTo: unknown, accessor: HandlerAccessor<T, K, R>): HandlerBindAccessor<T, K, R>;
 /**
@@ -22,27 +23,64 @@ export declare function handlerBindAccessor<T, K extends PrimativeKey = string,
  */
 export type HandlerSetFunction<T, R = HandleResult> = (handlerFunction: InternalHandlerFunction<T, R>) => void;
 /**
- * Creates a HandlerSetFunction.
+ * Creates a {@link HandlerSetFunction} that registers a handler function on a pre-defined key.
  *
- * @param accessor
- * @param key
- * @returns
+ * @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.
  */
 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,
+ * using a mapping function to convert between them.
+ */
 export type HandlerMappedSetFunction<I, R = HandleResult> = (handlerFunction: InternalHandlerFunction<I, R>) => void;
+/**
+ * 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 A function that accepts a mapped handler function and registers it.
+ */
 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>;
 /**
  * Factory for a HandlerMappedSetFunction<I>.
  */
 export type HandlerMappedSetFunctionFactory<I, K extends PrimativeKey = string, R = HandleResult> = (key: ArrayOrValue<K>) => HandlerMappedSetFunction<I, R>;
+/**
+ * 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.
+ */
 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.
+ */
 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.
+ */
 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;
+/**
+ * Factory that creates a {@link HandlerConfigurer} for a given handler.
+ */
 export type HandlerConfigurerFactory<C extends HandlerBindAccessor<T, K, R>, T, K extends PrimativeKey = string, R = HandleResult> = (handler: Handler<T, K, R>) => HandlerConfigurer<C, T, K, R>;
 /**
- * Config for handlerConfigurerFactory().
+ * Configuration for {@link handlerConfigurerFactory}.
  */
 export interface HandlerConfigurerFactoryConfig<C extends HandlerBindAccessor<T, K, R>, T, K extends PrimativeKey = string, R = HandleResult> {
+    /** Creates a typed configurer from a bind accessor. */
     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.
+ */
 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

@@ -2,7 +2,7 @@ import { type PrimativeKey, type ReadKeyFunction } from '../key';
 import { type ArrayOrValue } from '../array/array';
 import { type PromiseOrValue } from '../promise/promise.type';
 /**
- * Key used to signify
+ * Special key used to register a catch-all handler that matches any unhandled key.
  */
 export declare const CATCH_ALL_HANDLE_RESULT_KEY = "__CATCH_ALL_HANDLE_RESULT_KEY__";
 /**
@@ -15,7 +15,13 @@ export type HandleResult = boolean;
  * If void is returned, assumes true.
  */
 export type InternalHandlerFunctionHandleResult = HandleResult | void;
+/**
+ * The type of the catch-all handler key constant.
+ */
 export type HandlerCatchAllKey = typeof CATCH_ALL_HANDLE_RESULT_KEY;
+/**
+ * A handler key that is either a specific key type or the catch-all key.
+ */
 export type HandlerKey<K extends PrimativeKey = string> = K | HandlerCatchAllKey;
 /**
  * Used to perform a task on the input value.
@@ -27,6 +33,9 @@ export type HandlerFunction<T, R = HandleResult> = (value: T) => Promise<R>;
  * HandleFunction, but used only by Handler that can return undefined.
  */
 export type InternalHandlerFunction<T, R = HandleResult> = (value: T) => PromiseOrValue<R | void>;
+/**
+ * Provides methods to register handler functions for specific keys.
+ */
 export interface HandlerSetAccessor<T, K extends PrimativeKey = string, R = HandleResult> {
     /**
      * Adds a new handler function to the current handler.
@@ -42,6 +51,9 @@ export interface HandlerSetAccessor<T, K extends PrimativeKey = string, R = Hand
      */
     setCatchAll(handle: InternalHandlerFunction<T, R>): void;
 }
+/**
+ * Extends {@link HandlerSetAccessor} with a key reader and a bind-aware set method.
+ */
 export interface HandlerAccessor<T, K extends PrimativeKey = string, R = HandleResult> extends HandlerSetAccessor<T, K, R> {
     /**
      * Used to read a handler key from the input value.
@@ -56,13 +68,43 @@ export interface HandlerAccessor<T, K extends PrimativeKey = string, R = HandleR
      */
     bindSet(bindTo: unknown, key: ArrayOrValue<HandlerKey<K>>, handle: InternalHandlerFunction<T, R>): void;
 }
+/**
+ * A callable handler function combined with its accessor interface for registering sub-handlers.
+ */
 export type Handler<T, K extends PrimativeKey = string, R = HandleResult> = HandlerFunction<T, R> & HandlerAccessor<T, K, R>;
+/**
+ * Factory that creates new {@link Handler} instances.
+ */
 export type HandlerFactory<T, K extends PrimativeKey = string, R = HandleResult> = () => Handler<T, K, R>;
+/**
+ * Options for configuring default and negative results in a {@link HandlerFactory}.
+ */
 export interface HandlerFactoryOptions<R = HandleResult> {
+    /** The result returned when a handler function returns void. */
     readonly defaultResult: R;
+    /** The result returned when no handler matches the input key. */
     readonly negativeResult: R;
 }
+/**
+ * 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.
+ *
+ * @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.
+ */
 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.
+ *
+ * @param readKey - Function to extract the dispatch key from an input value.
+ * @returns A new Handler instance.
+ */
 export declare function makeHandler<T, K extends PrimativeKey = string>(readKey: ReadKeyFunction<T, K>): Handler<T, K>;
+/**
+ * Returns the {@link CATCH_ALL_HANDLE_RESULT_KEY} constant, useful for registering a catch-all handler.
+ *
+ * @returns The catch-all handler key.
+ */
 export declare function catchAllHandlerKey(): typeof CATCH_ALL_HANDLE_RESULT_KEY;

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

@@ -15,16 +15,35 @@ export interface TypedServiceRegistry<S, T extends string = string> {
  */
 export declare class TypedServiceRegistryInstance<S, T extends string = string> implements TypedServiceRegistry<S, T> {
     private _map;
+    /**
+     * Registers a service (or getter) for the given type key.
+     *
+     * @param type - The type key to register the service under.
+     * @param service - The service instance or a getter function that returns it.
+     */
     registerServiceForType(type: T, service: GetterOrValue<S>): void;
+    /**
+     * Returns the service registered for the given type. Throws if no service is registered.
+     *
+     * @param type - The type key to look up.
+     * @returns The registered service instance.
+     * @throws Error if no service is registered for the given type.
+     */
     serviceForType(type: T): S;
 }
+/**
+ * Configuration for initializing a {@link TypedServiceRegistryInstance} with a set of services.
+ */
 export interface TypedServiceRegistrySetupConfig<S, T extends string = string> {
+    /** A record mapping type keys to their service instances. */
     services: {
         [K in T]: S;
     };
 }
 /**
- * Creates a new TypedServiceRegistryInstance and registers the input types.
- * @returns
+ * Creates a new {@link TypedServiceRegistryInstance} and registers all services from the provided config.
+ *
+ * @param config - Configuration containing the services to register.
+ * @returns A new TypedServiceRegistryInstance with all services registered.
  */
 export declare function typedServiceRegistry<S, T extends string = string>(config: TypedServiceRegistrySetupConfig<S, T>): TypedServiceRegistryInstance<S, T>;

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

@@ -14,10 +14,12 @@ export interface AllowedSet<T> {
     readonly disallowed?: Maybe<Set<T>>;
 }
 /**
- * Determines whether the input values are "allowed" for the given AllowedSet.
+ * Determines whether the input values are "allowed" for the given {@link AllowedSet}.
+ * A value is allowed if it matches the `allowed` set (or `allowed` is not specified)
+ * and does not match the `disallowed` set.
  *
- * @param input
- * @param allowedSet
- * @returns
+ * @param input - The value or array of values to check.
+ * @param allowedSet - The allowed/disallowed configuration.
+ * @returns `true` if the values are allowed.
  */
 export declare function isAllowed<T>(input: ArrayOrValue<T>, allowedSet: AllowedSet<T>): boolean;