@dereekb/util 13.0.7 → 13.2.0

package/src/lib/page/page.d.ts

@@ -11,6 +11,9 @@ export declare const FIRST_PAGE = 0;
  * Page value used when there are no elements left to load.
  */
 export declare const FINAL_PAGE = -2;
+/**
+ * Numeric page identifier.
+ */
 export type PageNumber = number;
 /**
  * Represents a page number.
@@ -21,6 +24,24 @@ export interface Page {
      */
     page: PageNumber;
 }
+/**
+ * Extracts the page number from a {@link Page} object, returning {@link UNLOADED_PAGE} if the input is nullish.
+ *
+ * @param page - Page object to read from
+ * @returns The page number, or {@link UNLOADED_PAGE} (-1) if not provided
+ */
 export declare function getPageNumber(page: Maybe<Partial<Page>>): number;
+/**
+ * Returns the next sequential page number after the given page.
+ *
+ * @param page - Current page object
+ * @returns The current page number plus one
+ */
 export declare function getNextPageNumber(page: Maybe<Partial<Page>>): number;
+/**
+ * Checks whether the given page represents the final page of results.
+ *
+ * @param page - Page object to check
+ * @returns `true` if the page number equals {@link FINAL_PAGE}
+ */
 export declare function isFinalPage(page: Maybe<Partial<Page>>): boolean;

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

@@ -12,6 +12,9 @@ export interface FilteredPage<F> extends Page, OptionalFilter<F> {
 export interface PageAndFilter<F> extends OptionalFilter<F> {
     page: Page;
 }
+/**
+ * Callbacks for iterating over paged results. Provide either `use` (per-item) or `usePage` (per-page).
+ */
 export interface FilteredPageIterateFn<T> {
     /**
      * Uses each value one-by-one.
@@ -23,19 +26,23 @@ export interface FilteredPageIterateFn<T> {
     usePage?: IteratePageFn<T>;
 }
 /**
- * Creates a FilteredPage.
+ * Creates a {@link FilteredPage} combining a page number with an optional filter copied from the request.
  *
- * @param page
- * @param request
- * @returns
+ * @param page - The page number
+ * @param request - Optional filter to copy into the result
+ * @returns A new filtered page object
  */
 export declare function filteredPage<F = unknown>(page: PageNumber, request?: Filter<F>): FilteredPage<F>;
 /**
- * Iterates using a delegate function sequentially.
+ * Sequentially loads and iterates through pages of results until an empty page is returned.
+ *
+ * Starts from the given page and increments the page number after each load. Stops when
+ * `loadFn` returns an empty array. Either `iterFn.use` or `iterFn.usePage` must be provided.
  *
- * @param inputPage
- * @param loadFn
- * @param iterFn
- * @returns
+ * @param inputPage - Starting page with optional filter
+ * @param loadFn - Async function that loads a page of results
+ * @param iterFn - Callbacks for processing each item or page
+ * @returns The total number of items processed across all pages
+ * @throws Error if neither `use` nor `usePage` is specified in `iterFn`
  */
 export declare function iterateFilteredPages<T, F>(inputPage: FilteredPage<F>, loadFn: (page: FilteredPage<F>) => Promise<T[]>, iterFn: FilteredPageIterateFn<T>): Promise<number>;

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

@@ -81,27 +81,52 @@ export type SlashPathFunction = MapSameFunction<SlashPath>;
  */
 export type SlashPathType = 'folder' | 'file' | 'typedfile' | 'invalid';
 /**
- * Returns the SlashPathType for the input.
+ * Determines the type of a slash path string.
  *
- * @param input
- * @returns
+ * @param input - The slash path to classify.
+ * @returns The path type classification.
  */
 export declare function slashPathType(input: SlashPath): SlashPathType;
+/**
+ * Type guard that checks if the input is a file path (typed or untyped).
+ *
+ * @param input - The string to check.
+ * @returns Whether the input is a file path.
+ */
 export declare function isSlashPathFile(input: string): input is SlashPathFile;
+/**
+ * Type guard that checks if the input is a typed file path (contains a file extension).
+ *
+ * @param input - The string to check.
+ * @returns Whether the input is a typed file path.
+ */
 export declare function isSlashPathTypedFile(input: string): input is SlashPathTypedFile;
+/**
+ * Type guard that checks if the input is a folder path (ends with a slash).
+ *
+ * @param input - The string to check.
+ * @returns Whether the input is a folder path.
+ */
 export declare function isSlashPathFolder(input: string): input is SlashPathFolder;
+/**
+ * Type guard that checks if the input is a valid slash path (not 'invalid' type).
+ *
+ * @param input - The string to check.
+ * @returns Whether the input is a valid slash path.
+ */
 export declare function isValidSlashPath(input: string): input is SlashPath;
 /**
  * Returns the last part of the slash path.
  *
- * @param slashPath
+ * @param slashPath - The path to extract the name from.
+ * @returns The last part of the path (file name or folder name).
  */
 export declare function slashPathName(slashPath: SlashPath): SlashPathPart;
 /**
- * Returns each section of a SlashPath
+ * Returns each section of a SlashPath.
  *
- * @param slashPath
- * @returns
+ * @param slashPath - The path to split.
+ * @returns Array of non-empty path segments.
  */
 export declare function slashPathParts(slashPath: SlashPath): SlashPathPart[];
 /**
@@ -115,6 +140,12 @@ export type SlashPathStartType = 'relative' | 'absolute' | 'any';
  * Factory use to set the slash path type of the input.
  */
 export type SlashPathStartTypeFactory = SlashPathFunction;
+/**
+ * Creates a function that enforces the specified start type on a slash path.
+ *
+ * @param type - The start type to enforce.
+ * @returns A function that transforms paths to the specified start type.
+ */
 export declare function slashPathStartTypeFactory(type: SlashPathStartType): SlashPathStartTypeFactory;
 export declare const LEADING_SLASHES_REGEX: RegExp;
 export declare const TRAILING_SLASHES_REGEX: RegExp;
@@ -122,6 +153,12 @@ export declare const TRAILING_FILE_TYPE_SEPARATORS_REGEX: RegExp;
 export declare const ALL_SLASHES_REGEX: RegExp;
 export declare const ALL_DOUBLE_SLASHES_REGEX: RegExp;
 export declare const ALL_SLASH_PATH_FILE_TYPE_SEPARATORS_REGEX: RegExp;
+/**
+ * Converts a slash path to a relative path by removing all leading slashes.
+ *
+ * @param input - The slash path to convert.
+ * @returns A relative path without leading slashes.
+ */
 export declare function toRelativeSlashPathStartType(input: SlashPath): SlashPath;
 /**
  * Factory function that creates a SlashPathFolder from a string.
@@ -167,14 +204,39 @@ export declare function slashPathFolderFactory(config?: SlashPathFolderFactoryCo
  */
 export declare function slashPathFolder(input: string, config?: SlashPathFolderFactoryConfig): InferredSlashPathFolder;
 /**
+ * Converts a slash path to an absolute path by ensuring exactly one leading slash.
  *
- * @param input
- * @returns
+ * @param input - The slash path to convert.
+ * @returns An absolute path starting with a single slash.
  */
 export declare function toAbsoluteSlashPathStartType(input: SlashPath): SlashPath;
+/**
+ * Replaces consecutive double slashes with single slashes.
+ *
+ * @param input - The slash path to fix.
+ * @returns The path with double slashes collapsed.
+ */
 export declare function fixMultiSlashesInSlashPath(input: SlashPath): SlashPath;
+/**
+ * Replaces consecutive double slashes with single slashes. Alias for {@link fixMultiSlashesInSlashPath}.
+ *
+ * @param input - The slash path to fix.
+ * @returns The path with double slashes collapsed.
+ */
 export declare function replaceMultipleFilePathsInSlashPath(input: SlashPath): SlashPath;
+/**
+ * Removes all trailing slashes from a slash path.
+ *
+ * @param input - The slash path to trim.
+ * @returns The path without trailing slashes.
+ */
 export declare function removeTrailingSlashes(input: SlashPath): SlashPath;
+/**
+ * Removes all trailing dots from a slash path.
+ *
+ * @param input - The slash path to trim.
+ * @returns The path without trailing dots.
+ */
 export declare function removeTrailingFileTypeSeparators(input: SlashPath): SlashPath;
 /**
  * Adds a trailing slash to the input if it does not already have one.
@@ -227,6 +289,12 @@ export interface SlashPathValidationFactoryConfig {
      */
     readonly throwError?: boolean;
 }
+/**
+ * Creates a validation/fixup function for slash paths that replaces illegal characters and extra dots.
+ *
+ * @param config - Configuration for validation behavior.
+ * @returns A function that validates and fixes a slash path.
+ */
 export declare function slashPathValidationFactory(config?: SlashPathValidationFactoryConfig): SlashPathValidationFactory;
 /**
  * Factory use to generate/merge file paths together.
@@ -246,13 +314,32 @@ export interface SlashPathFactoryConfig {
      */
     readonly validate?: boolean | SlashPathValidationFactoryConfig;
 }
+/**
+ * Creates a factory function that merges path segments together with optional base path, start type enforcement, and validation.
+ *
+ * @param config - Configuration for path generation.
+ * @returns A factory function that merges input paths into a single validated slash path.
+ */
 export declare function slashPathFactory(config?: SlashPathFactoryConfig): SlashPathFactory;
+/**
+ * Merges an array of path segments into a single slash path, filtering nullish values and collapsing double slashes.
+ *
+ * @param paths - Array of path segments to merge.
+ * @returns The merged slash path.
+ */
 export declare function mergeSlashPaths(paths: Maybe<SlashPath>[]): SlashPath;
+/**
+ * Creates an Error indicating that a slash path is invalid.
+ *
+ * @returns A new Error with a descriptive message.
+ */
 export declare function slashPathInvalidError(): Error;
 /**
  * Splits the path and returns the items at the given ranges.
  *
- * @param path
+ * @param path - The path to isolate parts from.
+ * @param range - Index range defining which path segments to extract.
+ * @returns A new slash path containing only the segments within the range.
  */
 export declare function isolateSlashPath(path: SlashPath, range: IndexRangeInput): SlashPath;
 /**
@@ -281,8 +368,8 @@ export type IsolateSlashPathFunction = (path: SlashPath) => SlashPath;
 /**
  * Creates an IsolateSlashPathFunction.
  *
- * @param config
- * @returns
+ * @param config - Configuration with range, optional start type, and file mode.
+ * @returns A function that isolates path segments within the configured range.
  */
 export declare function isolateSlashPathFunction(config: IsolateSlashPathFunctionConfig): IsolateSlashPathFunction;
 export interface SlashPathDetails {
@@ -382,8 +469,8 @@ export type SlashPathPathMatcherPath = ArrayOrValue<SlashPathPathMatcherPart>;
 /**
  * Expands the input matcher path into decision functions.
  *
- * @param path The path to expand.
- * @returns An array of decision functions.
+ * @param path - Matcher path parts to expand into decision functions.
+ * @returns Array of decision functions for each path part.
  */
 export declare function expandSlashPathPathMatcherPartToDecisionFunctions(path: SlashPathPathMatcherPath): SlashPathPathMatcherFunction[];
 /**

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

@@ -8,7 +8,13 @@ export type SlashPathDirectoryTreeNodeValue<T> = {
     readonly value: T;
     readonly slashPathDetails: SlashPathDetails;
 };
+/**
+ * A tree node containing a value with slash path details.
+ */
 export type SlashPathDirectoryTreeNode<T, V extends SlashPathDirectoryTreeNodeValue<T> = SlashPathDirectoryTreeNodeValue<T>> = TreeNode<V>;
+/**
+ * Root of a slash path directory tree. Has children but no value of its own.
+ */
 export type SlashPathDirectoryTreeRoot<T, V extends SlashPathDirectoryTreeNodeValue<T> = SlashPathDirectoryTreeNodeValue<T>> = Omit<SlashPathDirectoryTreeNode<T, V>, 'value'>;
 export interface SlashPathDirectoryTreeOptions {
     /**
@@ -20,4 +26,14 @@ export interface SlashPathDirectoryTreeOptions {
      */
     readonly includeChildrenWithMissingParentFolder?: Maybe<boolean>;
 }
+/**
+ * Builds a directory tree structure from a flat list of node values based on their slash path hierarchy.
+ *
+ * Nodes are organized by their path parts, with each part becoming a level in the tree.
+ * Typed files (files with extensions) are added as children but cannot serve as parent folders.
+ *
+ * @param nodeValues - Flat list of values with associated slash path details.
+ * @param options - Optional configuration for tree building behavior.
+ * @returns The root node of the constructed directory tree.
+ */
 export declare function slashPathDirectoryTree<T, V extends SlashPathDirectoryTreeNodeValue<T> = SlashPathDirectoryTreeNodeValue<T>>(nodeValues: V[], options?: SlashPathDirectoryTreeOptions): SlashPathDirectoryTreeRoot<T, V>;

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

@@ -1,4 +1,22 @@
 import { type Maybe } from '../value/maybe.type';
+/**
+ * A Node.js-style error-first callback function.
+ *
+ * @param err - An optional error. If provided, indicates failure.
+ */
 export type PromiseCallback = (err?: Maybe<Error>) => void;
+/**
+ * A function that receives a {@link PromiseCallback} and invokes it to signal completion or failure.
+ *
+ * @param cb - The callback to invoke when the async operation completes.
+ */
 export type UsePromiseCallback = (cb: PromiseCallback) => void;
+/**
+ * Wraps a callback-based async operation as a Promise. The provided function receives a
+ * 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.
+ */
 export declare function useCallback(use: UsePromiseCallback): Promise<void>;

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

@@ -1,8 +1,15 @@
 /**
- * Whether or not the input is function-like.
+ * Checks whether the input value is a native Promise by testing for a `.then` method.
  *
- * @param obj
- * @returns
+ * @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.
+ */
 export declare function isPromiseLike<T, S>(obj: PromiseLike<T> | S): obj is PromiseLike<T>;

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

@@ -1,9 +1,11 @@
 import { type PromiseOrValue } from './promise.type';
 /**
- * Performs a mapping function on the input PromiseOrValue value.
+ * Applies a mapping function to a {@link PromiseOrValue}. If the input is a Promise, the
+ * mapping is applied via `.then()`; if it is a synchronous value, the mapping is applied directly.
  *
- * @param input
- * @param mapFn
+ * @param input - A value or Promise to map over.
+ * @param mapFn - The transformation function to apply.
+ * @returns The mapped result, as a Promise if the input was a Promise, or synchronously otherwise.
  */
 export declare function mapPromiseOrValue<I, O>(input: Promise<I>, mapFn: (input: I) => O): Promise<O>;
 export declare function mapPromiseOrValue<I, O>(input: I, mapFn: (input: I) => O): O;

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

@@ -1,18 +1,28 @@
+/**
+ * Configuration for the {@link poll} function.
+ */
 export interface PollConfig {
     /**
-     * How long to wait between polling checks in ms.
+     * How long to wait between polling checks in milliseconds.
+     *
+     * Defaults to 250.
      */
     wait?: number;
     /**
-     * Checks to see the poll has been met.
+     * Predicate function that returns `true` when the polling condition has been met.
      */
     check: () => boolean;
     /**
-     * Max number of times to poll before giving up.
+     * Maximum number of polling iterations before giving up.
+     *
+     * Defaults to `Number.MAX_SAFE_INTEGER`.
      */
     timesToGiveup?: number;
 }
 /**
- * Polls every number of ms to check that a condition has been met.
+ * 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.
+ * @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

@@ -5,32 +5,66 @@ import { type StringFactory } from '../string/factory';
 import { type IndexNumber } from '../value';
 import { type Maybe } from '../value/maybe.type';
 import { type PromiseOrValue } from './promise.type';
+/**
+ * Configuration for {@link runAsyncTaskForValue}, which omits `throwError` since it always throws on failure.
+ */
 export type RunAsyncTaskForValueConfig<T = unknown> = Omit<PerformAsyncTaskConfig<T>, 'throwError'>;
+/**
+ * Configuration for {@link runAsyncTasksForValues}, which omits `throwError` since it always throws on failure.
+ */
 export type RunAsyncTasksForValuesConfig<T = unknown> = Omit<PerformAsyncTasksConfig<T>, 'throwError'>;
 /**
- * Runs the task using the input config, and returns the value. Is always configured to throw the error if it fails.
+ * 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 Rethrows any error thrown by the task function.
  */
 export declare function runAsyncTaskForValue<O>(taskFn: () => Promise<O>, config?: RunAsyncTaskForValueConfig<0>): Promise<Maybe<O>>;
 /**
- * Returns the task for each input value, and returns the values. Is always configured to throw the error if it fails.
+ * Runs an async task for each input value and returns an array of the resulting values.
+ * Always configured to throw on failure.
  *
- * @param input
- * @param taskFn
- * @param config
- * @returns
+ * @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[]>;
+/**
+ * An async function that processes a value and returns a result. Receives the current retry/try number.
+ *
+ * @param value - The input value to process.
+ * @param tryNumber - The current attempt number (0-based).
+ */
 export type PerformAsyncTaskFn<T, K = unknown> = (value: T, tryNumber?: number) => Promise<K>;
+/**
+ * The result of executing a single async task via {@link performAsyncTask}.
+ */
 export interface PerformAsyncTaskResult<O> {
+    /** The resulting value if the task succeeded, or undefined on failure. */
     readonly value: Maybe<O>;
+    /** Whether the task completed successfully. */
     readonly success: boolean;
 }
+/**
+ * The aggregated result of executing multiple async tasks via {@link performAsyncTasks}.
+ */
 export interface PerformAsyncTasksResult<I, O> {
+    /** Input values whose tasks succeeded. */
     readonly succeded: I[];
+    /** Input values whose tasks failed. */
     readonly failed: I[];
+    /** Tuples of [input, output] for each successful task. */
     readonly results: [I, O][];
+    /** Tuples of [input, error] for each failed task. */
     readonly errors: [I, unknown][];
 }
+/**
+ * Configuration for retry behavior when performing async tasks.
+ */
 export interface PerformAsyncTaskConfig<I = unknown> {
     /**
      * Whether or not to throw an error if the task fails. Defaults to true.
@@ -51,19 +85,38 @@ export interface PerformAsyncTaskConfig<I = unknown> {
      */
     readonly beforeRetry?: (value: I, tryNumber?: number) => void | Promise<void>;
 }
+/**
+ * Configuration for {@link performAsyncTasks}, combining retry behavior with parallel execution options.
+ */
 export interface PerformAsyncTasksConfig<I = unknown, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey> extends PerformAsyncTaskConfig<I>, Omit<PerformTasksInParallelFunctionConfig<I, K>, 'taskFactory'> {
 }
 /**
- * Performs the input tasks, and will retry tasks if they fail, up to a certain point.
+ * Performs async tasks for each input value with configurable retry and parallelism behavior.
+ * Useful for operations that may experience optimistic concurrency collisions.
  *
- * This is useful for retrying sections that may experience optimistic concurrency collisions.
+ * @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).
  */
 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 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>>;
 /**
  * Used as a key to identify the "group" that a task belongs to to prevent other concurrent tasks from that group from running in parallel when parallel execution is desired.
  */
 export type PerformTasksInParallelTaskUniqueKey = string;
+/**
+ * Configuration for {@link performTasksInParallelFunction}, excluding `waitBetweenTaskInputRequests`.
+ */
 export type PerformTasksInParallelFunctionConfig<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey> = Omit<PerformTasksFromFactoryInParallelFunctionConfig<I, K>, 'waitBetweenTaskInputRequests'>;
 /**
  * Function that awaits a promise generated from each of the input values.
@@ -72,19 +125,26 @@ export type PerformTasksInParallelFunctionConfig<I, K extends PrimativeKey = Per
  */
 export type PerformTasksInParallelFunction<I> = (input: I[]) => Promise<void>;
 /**
- * Convenience function for calling performTasksInParallelFunction() with the given input.
+ * Convenience function that creates a parallel task executor and immediately runs it with the given input.
  *
- * @param input
- * @param config
- * @returns
+ * @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.
  */
 export declare function performTasksInParallel<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(input: I[], config: PerformTasksInParallelFunctionConfig<I, K>): Promise<void>;
 /**
- * Creates a function that performs tasks in parallel.
+ * Creates a reusable function that performs tasks in parallel with optional concurrency limits
+ * and non-concurrent task key constraints.
  *
- * @param config
+ * @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.
  */
 export declare function performTasksInParallelFunction<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(config: PerformTasksInParallelFunctionConfig<I, K>): PerformTasksInParallelFunction<I>;
+/**
+ * Configuration for {@link performTasksFromFactoryInParallelFunction}, controlling task execution,
+ * parallelism limits, and non-concurrent key constraints.
+ */
 export interface PerformTasksFromFactoryInParallelFunctionConfig<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey> {
     /**
      * Creates a promise from the input.
@@ -115,6 +175,10 @@ export interface PerformTasksFromFactoryInParallelFunctionConfig<I, K extends Pr
      */
     readonly waitBetweenTaskInputRequests?: Milliseconds;
 }
+/**
+ * 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>;
 /**
  * Function that awaits all promises generated from the task factory until the factory returns null.
@@ -125,14 +189,16 @@ export type PerformTaskFactoryTasksInParallelFunctionTaskInputFactory<I> = () =>
  */
 export type PerformTaskFactoryTasksInParallelFunction<I> = (taskInputFactory: PerformTaskFactoryTasksInParallelFunctionTaskInputFactory<I>) => Promise<void>;
 /**
- * Creates a function that performs tasks from the task factory in parallel.
+ * 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
+ * @param config - Configuration for the task factory, parallelism, and concurrency behavior.
+ * @returns A function that accepts a task input factory and returns a Promise resolving when all tasks complete.
  */
 export declare function performTasksFromFactoryInParallelFunction<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(config: PerformTasksFromFactoryInParallelFunctionConfig<I, K>): PerformTaskFactoryTasksInParallelFunction<I>;
 /**
- * Creates a default non-concurrent task key factory that simply creates increasing number strings.
+ * Creates a default non-concurrent task key factory that generates unique incrementing number strings.
  *
- * @returns A string factory that generates unique keys for non-concurrent tasks.
+ * @returns A {@link StringFactory} that produces unique keys for identifying non-concurrent tasks.
  */
 export declare function makeDefaultNonConcurrentTaskKeyFactory(): StringFactory<any>;

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

@@ -1,11 +1,17 @@
 import { type FactoryWithRequiredInput } from '../getter/getter';
 import { type Maybe } from '../value/maybe.type';
 /**
- * Function that uses an array of Factories to produce Promises, one after the other, to attempt to return the value.
+ * A function that tries an array of Promise factories one after another until one
+ * produces a successful result. Returns `undefined` if none succeed.
  *
- * Returns a Maybe value of the expected output, and returns null if no factory/promise returns the intended value.
+ * @param input - The input to pass to each factory.
+ * @param config - Optional per-call configuration overrides.
+ * @returns The first successful value, or `undefined` if no factory succeeds.
  */
 export type TryWithPromiseFactoriesFunction<I, O> = (input: I, config?: TryWithPromiseFactoriesFunctionOptionalConfig<I, O>) => Promise<Maybe<O>>;
+/**
+ * Optional per-call configuration for {@link TryWithPromiseFactoriesFunction}.
+ */
 export interface TryWithPromiseFactoriesFunctionOptionalConfig<I, O> {
     /**
      * Whether or not to return a Maybe value if it is returned by one of the created promises.
@@ -20,6 +26,9 @@ export interface TryWithPromiseFactoriesFunctionOptionalConfig<I, O> {
      */
     readonly throwErrors?: boolean;
 }
+/**
+ * Configuration for creating a {@link TryWithPromiseFactoriesFunction} via {@link tryWithPromiseFactoriesFunction}.
+ */
 export interface TryWithPromiseFactoriesFunctionConfig<I, O> extends TryWithPromiseFactoriesFunctionOptionalConfig<I, O> {
     /**
      * Factories used to create new Promise valeus to test.
@@ -30,4 +39,11 @@ export interface TryWithPromiseFactoriesFunctionConfig<I, O> extends TryWithProm
      */
     readonly promiseFactories: FactoryWithRequiredInput<Promise<Maybe<O>>, I>[];
 }
+/**
+ * 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 A function that tries each factory in order for a given input.
+ */
 export declare function tryWithPromiseFactoriesFunction<I, O>(config: TryWithPromiseFactoriesFunctionConfig<I, O>): TryWithPromiseFactoriesFunction<I, O>;

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

@@ -56,7 +56,14 @@ export interface ExponentialPromiseRateLimiterConfig {
      */
     readonly exponentRate?: number;
 }
+/**
+ * A fully resolved {@link ExponentialPromiseRateLimiterConfig} with all fields required.
+ */
 export type FullExponentialPromiseRateLimiterConfig = Required<ExponentialPromiseRateLimiterConfig>;
+/**
+ * An exponential backoff rate limiter that increases wait times exponentially based on usage,
+ * with a configurable cooldown that reduces the effective count over time.
+ */
 export interface ExponentialPromiseRateLimiter extends EnableTogglePromiseRateLimiter {
     /**
      * Returns the current config.
@@ -71,7 +78,18 @@ export interface ExponentialPromiseRateLimiter extends EnableTogglePromiseRateLi
      */
     reset(): void;
 }
+/**
+ * Creates an {@link ExponentialPromiseRateLimiter} that computes wait times using exponential
+ * growth with a configurable cooldown that reduces the effective count over time.
+ *
+ * @param initialConfig - Optional initial configuration. Defaults are applied for any omitted fields.
+ * @returns An ExponentialPromiseRateLimiter instance.
+ */
 export declare function exponentialPromiseRateLimiter(initialConfig?: Maybe<ExponentialPromiseRateLimiterConfig>): ExponentialPromiseRateLimiter;
+/**
+ * Configuration for a {@link ResetPeriodPromiseRateLimiter} that resets its remaining count
+ * periodically and applies exponential backoff when the limit is exhausted.
+ */
 export interface ResetPeriodPromiseRateLimiterConfig extends Partial<ExponentialPromiseRateLimiterConfig> {
     /**
      * The number of times the rate limiter can be used before it needs to be reset.
@@ -124,8 +142,10 @@ export interface ResetPeriodPromiseRateLimiter extends EnableTogglePromiseRateLi
     reset(): void;
 }
 /**
- * Creates a ResetPeriodPromiseRateLimiter.
+ * Creates a {@link ResetPeriodPromiseRateLimiter} that limits the number of operations per time period,
+ * resetting the count at regular intervals and applying exponential backoff when the limit is exceeded.
  *
- * @param limit
+ * @param initialConfig - Configuration specifying the limit count, reset period, and optional exponential backoff settings.
+ * @returns A ResetPeriodPromiseRateLimiter instance.
  */
 export declare function resetPeriodPromiseRateLimiter(initialConfig: ResetPeriodPromiseRateLimiterConfig): ResetPeriodPromiseRateLimiter;