unwrapped 0.1.2 → 0.1.3

package/dist/core/index.d.ts

@@ -1,105 +1,544 @@
+/**
+ * Base class for error handling, providing structured error information and logging.
+ * @class ErrorBase
+ * @property {string} code - The error code.
+ * @property {string | undefined} message - The error message (optional).
+ * @property {unknown} thrownError - The original error object, if any (optional).
+ *
+ * @constructor
+ * @param {string} code - The error code.
+ * @param {string} [message] - The error message.
+ * @param {unknown} [thrownError] - The original error object, if any.
+ * @param {boolean} [log=true] - Whether to log the error upon creation.
+ */
 declare class ErrorBase {
     code: string;
     message?: string | undefined;
-    thrownError?: any;
-    constructor(code: string, message?: string, thrownError?: any, log?: boolean);
+    thrownError?: unknown;
+    constructor(code: string, message?: string, thrownError?: unknown, log?: boolean);
+    /**
+     * Converts the error to a string representation, on the format "Error {code}: {message}".
+     * @returns a string representation of the error
+     */
     toString(): string;
+    /**
+     * Logs the error to the console, uses console.error and ErrorBase.toString() internally.
+     * Logs thrownError if it was provided on creation.
+     */
     logError(): void;
 }
 
-type ResultState<T, E = ErrorBase> = {
+/**
+ * Type representing the state of a Result, either success with a value of type T,
+ * or error with an error of type E (defaulting to ErrorBase).
+ */
+type ResultState<T, E extends ErrorBase = ErrorBase> = {
     status: 'success';
     value: T;
 } | {
     status: 'error';
     error: E;
 };
-declare class Result<T, E = ErrorBase> {
+/**
+ * Class representing the result of an operation that can either succeed with a value of type T,
+ * or fail with an error of type E (defaulting to ErrorBase).
+ * Provides methods for unwrapping the result, chaining operations, and handling errors.
+ * @class Result
+ * @template T - The type of the successful result value.
+ * @template E - The type of the error, extending ErrorBase (default is ErrorBase).
+ */
+declare class Result<T, E extends ErrorBase = ErrorBase> {
     private _state;
+    /**
+     * Creates a new Result instance with the given state.
+     * @param state the state of the created Result
+     */
     constructor(state: ResultState<T, E>);
+    /** Returns the internal state of the Result. */
     get state(): ResultState<T, E>;
-    static ok<T, E = ErrorBase>(value: T): Result<T, E>;
-    static err<E>(error: E): Result<never, E>;
-    static errTag(code: string, message?: string): Result<never, ErrorBase>;
+    /**
+     * Checks if the Result is successful.
+     * @returns whether or not the result is successful
+     */
+    isSuccess(): boolean;
+    /**
+     * Checks if the Result is an error.
+     * @returns whether or not the result is an error
+     */
+    isError(): boolean;
+    /**
+     * Creates a successful Result with the given value.
+     * @param value the result of the successful operation
+     * @returns a successful Result
+     */
+    static ok<T, E extends ErrorBase = ErrorBase>(value: T): Result<T, E>;
+    /**
+     * Creates an error Result with the given error.
+     * @param error the error of the failed operation
+     * @returns an error Result
+     */
+    static err<E extends ErrorBase = ErrorBase>(error: E): Result<never, E>;
+    /**
+     * Creates an error Result (containing an ErrorBase) with the given error code and optional message.
+     * @param code the error code
+     * @param message an optional error message
+     * @returns an error Result
+     */
+    static errTag(code: string, message?: string, thrownError?: unknown): Result<never, ErrorBase>;
+    /**
+     * Returns the successful value (if the Result is successful) or null (if it is an error).
+     * @returns either the successful value or null
+     */
     unwrapOrNull(): T | null;
+    /**
+     * Returns the successful value (if the Result is successful) or throws an error (if it is an error).
+     * @returns the successful value
+     * @throws an normal JS Error if the result is not successful
+     */
     unwrapOrThrow(): T;
+    /**
+     * Returns the successful value (if the Result is successful) or a default value (if it is an error).
+     * @param defaultValue the default value to return if the Result is an error
+     * @returns either the successful value or the default value
+     */
     unwrapOr<O>(defaultValue: O): T | O;
-    isSuccess(): boolean;
-    isError(): boolean;
-    static tryPromise<T, E>(promise: Promise<T>, errorMapper: (error: unknown) => E): Promise<Result<T, E>>;
+    /**
+     * Transforms a Promise of a successful value into a Promise of a Result,
+     * catching any thrown errors and mapping them using the provided errorMapper function.
+     * @param promise the promise to execute
+     * @param errorMapper a function that maps a thrown error to a Result error
+     * @returns a Promise resolving to a Result containing either the successful value or the mapped error
+     */
+    static tryPromise<T, E extends ErrorBase = ErrorBase>(promise: Promise<T>, errorMapper: (error: unknown) => E): Promise<Result<T, E>>;
+    /**
+     * Executes an asynchronous function and transforms its result into a Result,
+     * catching any thrown errors and mapping them using the provided errorMapper function.
+     * Same as Result.tryPromise(fn(), errorMapper).
+     * @param fn the asynchronous function to execute
+     * @param errorMapper a function that maps a thrown error to a Result error
+     * @returns a Promise resolving to a Result containing either the successful value or the mapped error
+     */
     static tryFunction<T, E extends ErrorBase = ErrorBase>(fn: () => Promise<T>, errorMapper: (error: unknown) => E): Promise<Result<T, E>>;
-    chain<O, E2>(fn: (input: T) => ResultState<O, E | E2>): Result<O, E | E2>;
+    /**
+     * Chains the current Result with another operation that returns a ResultState.
+     * If the current Result is successful, applies the provided function to its value.
+     * Otherwise, returns the current error.
+     * Useful to describe a sequence of operations that can each fail, and short-circuit on the first failure.
+     * @param fn a function taking as input the successful value of the result, and returning a ResultState describing the result of its own operation
+     * @returns a new Result that has either the successful value of the operation, or either the error of the current result or the error returned by fn
+     */
+    chain<O, E2 extends ErrorBase = ErrorBase>(fn: (input: T) => ResultState<O, E | E2>): Result<O, E | E2>;
+    /**
+     * Chains the current Result with another operation that returns a Result.
+     * If the current Result is successful, applies the provided function to its value.
+     * Otherwise, returns the current error.
+     * Useful to describe a sequence of operations that can each fail, and short-circuit on the first failure.
+     * Same as chain, but the function returns a Result directly instead of a ResultState.
+     * @param fn a function taking as input the successful value of the result, and returning a Result describing the result of its own operation
+     * @returns a new Result that has either the successful value of the operation, or either the error of the current result or the error returned by fn
+     */
+    flatChain<O, E2 extends ErrorBase = ErrorBase>(fn: (input: T) => Result<O, E | E2>): Result<O, E | E2>;
+    /**
+     * @yields the current Result, and if it is successful, returns its value.
+     * This allows using Result instances in generator functions to simplify error handling and propagation.
+     * @example
+     * function* example(): Generator<Result<number>, number, any> {
+     *     const result1 = yield* Result.ok(5);
+     *     const result2 = yield* Result.ok(10);
+     *     return result1 + result2;
+     * }
+     */
     [Symbol.iterator](): Generator<Result<T, E>, T, any>;
-    static run<T, E>(generator: () => Generator<Result<any, E>, T, any>): Result<T, E>;
+    /**
+     * Runs a generator function that yields Result instances, propagating errors automatically.
+     * If any yielded Result is an error, the execution stops and the error is returned.
+     * If all yielded Results are successful, returns a successful Result with the final returned value.
+     *
+     * This serves the same purpose as chain/flatChain, but allows for a more linear and readable style of coding.
+     * Think of it as "async/await" but for Result handling in generator functions.
+     *
+     * @param generator a generator function that yields Result instances
+     * @returns a Result containing either the final successful value or the first encountered error
+     *
+     * @example
+     * const result = Result.run(function* () {
+     *     const value1 = yield* Result.ok(5);
+     *     const value2 = yield* Result.ok(10);
+     *     return value1 + value2;
+     * });
+     */
+    static run<T, E extends ErrorBase = ErrorBase>(generator: () => Generator<Result<any, E>, T, any>): Result<T, E>;
 }
 
-type AsyncResultState<T, E> = {
+/**
+ * Type representing the state of an AsyncResult.
+ * It can be 'idle', 'loading' with a promise, or a settled ResultState (success or error).
+ */
+type AsyncResultState<T, E extends ErrorBase = ErrorBase> = {
     status: 'idle';
 } | {
     status: 'loading';
     promise: Promise<Result<T, E>>;
 } | ResultState<T, E>;
-type ChainFunction<I, O, E> = (input: I) => Result<O, E> | Promise<Result<O, E>>;
-type FlatChainFunction<I, O, E> = (input: I) => AsyncResult<O, E>;
-type AsyncResultListener<T, E> = (result: AsyncResult<T, E>) => any;
-declare class AsyncResult<T, E = ErrorBase> {
+/**
+ * An Action is a function returning a Promise of a Result.
+ */
+type Action<T, E extends ErrorBase = ErrorBase> = () => Promise<Result<T, E>>;
+/**
+ * A LazyAction is an object containing a trigger function to start the action, and the AsyncResult representing the action's state.
+ */
+type LazyAction<T, E extends ErrorBase = ErrorBase> = {
+    trigger: () => void;
+    result: AsyncResult<T, E>;
+};
+/**
+ * A ChainStep is a function that takes an arbitrary input and returns a Result or a Promise of a Result.
+ * It takes an input of type I and returns either a Result<O, E> or a Promise<Result<O, E>>.
+ *
+ * Used for chaining operations on AsyncResult.
+ */
+type ChainStep<I, O, E extends ErrorBase = ErrorBase> = (input: I) => Result<O, E> | Promise<Result<O, E>>;
+/**
+ * A FlatChainStep is a function that takes an arbitrary input and returns an AsyncResult.
+ * It takes an input of type I and returns an AsyncResult<O, E>.
+ *
+ * Used for flat-chaining operations on AsyncResult.
+ */
+type FlatChainStep<I, O, E extends ErrorBase = ErrorBase> = (input: I) => AsyncResult<O, E>;
+/**
+ * Type representing a generator function that yields AsyncResult instances and returns a final value of type T.
+ *
+ * Used for running generators with AsyncResult.run().
+ */
+type AsyncResultGenerator<T> = Generator<AsyncResult<any, any>, T, any>;
+/**
+ * Type representing a listener function for AsyncResult state changes.
+ */
+type AsyncResultListener<T, E extends ErrorBase = ErrorBase> = (result: AsyncResult<T, E>) => any;
+/**
+ * Class representing the asynchronous result of an operation that can be idle, loading, successful, or failed.
+ * Provides methods for listening to state changes, updating state, chaining operations, and converting to and from promises.
+ * @class AsyncResult
+ * @template T - The type of the successful result value.
+ * @template E - The type of the error, extending ErrorBase (default is ErrorBase).
+ */
+declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
     private _state;
     private _listeners;
     constructor(state?: AsyncResultState<T, E>);
+    /**
+     * Returns the internal state of the AsyncResult.
+     */
     get state(): AsyncResultState<T, E>;
-    private set state(value);
-    static ok<T>(value: T): AsyncResult<T, never>;
-    static err<E>(error: E): AsyncResult<never, E>;
+    /**
+     * Checks if the AsyncResult is successful.
+     * @returns whether or not the result is successful
+     */
     isSuccess(): boolean;
+    /**
+     * Checks if the AsyncResult is an error.
+     * @returns whether or not the result is an error
+     */
     isError(): boolean;
+    /**
+     * Checks if the AsyncResult is idle.
+     * @returns whether or not the result is idle
+     */
+    isIdle(): boolean;
+    /**
+     * Checks if the AsyncResult is loading.
+     * @returns whether or not the result is loading
+     */
     isLoading(): boolean;
-    listen(listener: AsyncResultListener<T, E>, immediate?: boolean): () => void;
-    listenUntilSettled(listener: AsyncResultListener<T, E>, immediate?: boolean): () => void;
-    setState(newState: AsyncResultState<T, E>): void;
-    copyOnceSettled(other: AsyncResult<T, E>): void;
-    update(newState: AsyncResultState<T, E>): void;
-    updateToValue(value: T): void;
-    updateToError(error: E): void;
-    updateFromResultPromise(promise: Promise<Result<T, E>>): void;
-    static fromResultPromise<T, E>(promise: Promise<Result<T, E>>): AsyncResult<T, E>;
-    updateFromValuePromise(promise: Promise<T>): void;
-    static fromValuePromise<T, E>(promise: Promise<T>): AsyncResult<T, E>;
+    /**
+     * Returns the successful value if the AsyncResult is in a success state, otherwise returns null.
+     * @returns the successful value or null
+     */
+    unwrapOrNull(): T | null;
+    /**
+     * Returns the successful value if the AsyncResult is in a success state, otherwise throws an error.
+     * @returns the successful value
+     * @throws an normal JS Error if the result is not successful
+     */
+    unwrapOrThrow(): T;
+    private set state(value);
+    private setState;
+    /**
+     * Creates a successful AsyncResult with the given value.
+     * @param value the result of the successful operation
+     * @returns a successful AsyncResult
+     */
+    static ok<T>(value: T): AsyncResult<T, never>;
+    /**
+     * Creates an error AsyncResult with the given error.
+     * @param error the error of the failed operation
+     * @returns an error AsyncResult
+     */
+    static err<E extends ErrorBase = ErrorBase>(error: E): AsyncResult<never, E>;
+    /**
+     * Creates an error AsyncResult with a new ErrorBase constructed from the given parameters.
+     * @param code the error code
+     * @param message the error message (optional)
+     * @param thrownError the original error object, if any (optional)
+     * @param log whether to log the error upon creation (default is true)
+     * @returns an error AsyncResult
+     */
+    static errTag(code: string, message?: string, thrownError?: unknown, log?: boolean): AsyncResult<never, ErrorBase>;
+    /**
+     * Updates the AsyncResult to a successful state with the given value.
+     * Like AsyncResult.ok, but in place.
+     * @param value the successful value
+     */
+    updateFromValue(value: T): this;
+    /**
+     * Updates the AsyncResult to an error state with the given error.
+     * Like AsyncResult.err, but in place.
+     * @param error the error
+     */
+    updateFromError(error: E): this;
+    /**
+     * Creates an AsyncResult from a promise that resolves to a value.
+     * The AsyncResult is initially in a loading state, and updates to a successful state once the promise resolves.
+     * If the promise rejects, the AsyncResult is updated to an error state with the caught error.
+     *
+     * Like AsyncResult.fromResultPromise, but for promise that only resolves to a successful value and not a Result.
+     *
+     * @param promise the promise that resolves to a value
+     * @returns an AsyncResult representing the state of the promise
+     */
+    static fromValuePromise<T, E extends ErrorBase = ErrorBase>(promise: Promise<T>): AsyncResult<T, E>;
+    /**
+     * Updates the AsyncResult to a loading state with the given promise.
+     * The AsyncResult is initially in a loading state, and updates to a successful state once the promise resolves.
+     * If the promise rejects, the AsyncResult is updated to an error state with the caught error.
+     *
+     * Like AsyncResult.fromValuePromise, but in place.
+     *
+     * @param promise the promise that resolves to a value
+     */
+    updateFromValuePromise(promise: Promise<T>): this;
+    /**
+     * Waits for the AsyncResult to settle (either success or error) if it is currently loading.
+     * @returns itself once settled
+     */
     waitForSettled(): Promise<AsyncResult<T, E>>;
-    waitForSettledResult(): Promise<Result<T, E>>;
+    /**
+     * Waits for the AsyncResult to settle (either success or error) if it is currently loading, and returns a Result representing the settled state.
+     * @returns a Result representing the settled state
+     */
     toResultPromise(): Promise<Result<T, E>>;
-    toValuePromiseThrow(): Promise<T>;
+    /**
+     * Waits for the AsyncResult to settle (either success or error) if it is currently loading, and returns the successful value or throws an error.
+     * @returns the successful value
+     * @throws an normal JS Error if the result is not successful
+     */
+    toValueOrThrowPromise(): Promise<T>;
+    /**
+     * Waits for the AsyncResult to settle (either success or error) if it is currently loading, and returns the successful value or null.
+     * @returns either the successful value or null
+     */
     toValueOrNullPromise(): Promise<T | null>;
-    unwrapOrNull(): T | null;
-    unwrapOrNullOnceSettled(): Promise<T | null>;
-    unwrapOrThrow(): T;
-    unwrapOrThrowOnceSettled(): Promise<T>;
-    chain<O, E2>(fn: ChainFunction<T, O, E | E2>): AsyncResult<O, E | E2>;
-    flatChain<O, E2>(fn: FlatChainFunction<T, O, E | E2>): AsyncResult<O, E | E2>;
+    /**
+     * Creates an AsyncResult from a promise that resolves to a Result.
+     * The AsyncResult is initially in a loading state, and updates to the settled state once the promise resolves.
+     * If the promise rejects, the AsyncResult is updated to an error state with a default ErrorBase.
+     *
+     * @param promise the promise that resolves to a Result
+     * @returns an AsyncResult representing the state of the promise
+     */
+    static fromResultPromise<T, E extends ErrorBase = ErrorBase>(promise: Promise<Result<T, E>>): AsyncResult<T, E>;
+    /**
+     * Updates the AsyncResult to a loading state with the given promise.
+     * The promise must produce a Result once settled (meaning it should return the error in the result when possible).
+     * If the promise rejects, the AsyncResult is updated to an error state with a default ErrorBase.
+     *
+     * Like AsyncResult.fromResultPromise, but in place.
+     *
+     * @param promise the promise that resolves to a Result
+     */
+    updateFromResultPromise(promise: Promise<Result<T, E>>): this;
+    /**
+     * Adds a listener that is called whenever the AsyncResult state changes.
+     * @param listener the listener function to add
+     * @param immediate whether to call the listener immediately with the current state (default is true)
+     * @returns a function to remove the listener
+     */
+    listen(listener: AsyncResultListener<T, E>, immediate?: boolean): () => void;
+    /**
+     * Adds a listener that is called whenever the AsyncResult state changes, and automatically unsubscribes once it is settled (success or error).
+     * @param listener the listener function to add
+     * @param immediate whether to call the listener immediately with the current state (default is true)
+     * @returns a function to remove the listener
+     */
+    listenUntilSettled(listener: AsyncResultListener<T, E>, immediate?: boolean): () => void;
+    /**
+     * Mirrors the state of another AsyncResult into this one.
+     * Whenever the other AsyncResult changes state, this AsyncResult is updated to match.
+     * @param other the AsyncResult to mirror
+     * @returns a function to stop mirroring
+     */
     mirror(other: AsyncResult<T, E>): () => void;
+    /**
+     * Mirrors the state of another AsyncResult into this one, until the other AsyncResult is settled (success or error).
+     * Whenever the other AsyncResult changes state, this AsyncResult is updated to match, until the other AsyncResult is settled.
+     * @param other the AsyncResult to mirror
+     * @returns a function to stop mirroring
+     */
     mirrorUntilSettled(other: AsyncResult<T, E>): () => void;
+    /**
+     * Creates a LazyAction that can be triggered to run the given Action.
+     * @param action the Action to run when triggered
+     * @returns an object containing the trigger function and the associated AsyncResult
+     */
+    static makeLazyAction<T, E extends ErrorBase = ErrorBase>(action: Action<T, E>): LazyAction<T, E>;
+    /**
+     * Chains the current AsyncResult with another operation that returns a Result or a Promise of a Result.
+     *
+     * If the current AsyncResult is loading, waits for it to settle first, then applies the provided function to its value.
+     * If the current AsyncResult is successful, applies the provided function to its value.
+     * Otherwise, returns the current error.
+     *
+     * Useful to describe a sequence of operations that can each fail, and short-circuit on the first failure.
+     *
+     * @param fn a function taking as input the successful value of the result, and returning a Result or a Promise of a Result describing the result of its own operation
+     * @returns a new AsyncResult that has either the successful value of the operation, or either the error of the current result or the error returned by fn
+     */
+    chain<O, E2 extends ErrorBase = ErrorBase>(fn: ChainStep<T, O, E | E2>): AsyncResult<O, E | E2>;
+    /**
+     * Chains the current AsyncResult with another operation that returns an AsyncResult.
+     *
+     * If the current AsyncResult is loading, waits for it to settle first, then applies the provided function to its value.
+     * If the current AsyncResult is successful, applies the provided function to its value.
+     * Otherwise, returns the current error.
+     *
+     * Useful to describe a sequence of operations that can each fail, and short-circuit on the first failure.
+     *
+     * Like chain, but for functions returning AsyncResult instead of Result.
+     *
+     * @param fn a function taking as input the successful value of the result, and returning an AsyncResult describing the result of its own operation
+     * @returns a new AsyncResult that has either the successful value of the operation, or either the error of the current result or the error returned by fn
+     */
+    flatChain<O, E2 extends ErrorBase = ErrorBase>(fn: FlatChainStep<T, O, E | E2>): AsyncResult<O, E | E2>;
+    /**
+     * Ensures that all provided AsyncResults are successful.
+     * If all are successful, returns an AsyncResult containing an array of their values.
+     * If any AsyncResult is an error, returns an AsyncResult with the first encountered error.
+     * @param results an array of AsyncResults to check
+     * @returns an AsyncResult containing either an array of successful values or the first encountered error
+     */
     static ensureAvailable<R extends readonly AsyncResult<any, any>[]>(results: R): AsyncResult<{
         [K in keyof R]: R[K] extends AsyncResult<infer T, any> ? T : never;
     }, R[number] extends AsyncResult<any, infer E> ? E : never>;
+    /**
+     * Yields the current AsyncResult, and if it is successful, returns its value.
+     * This allows using AsyncResult instances in generator functions to simplify error handling and propagation.
+     * @example
+     * function* example(): Generator<AsyncResult<number>, number, any> {
+     *     const result1 = yield* AsyncResult.ok(5);
+     *     const result2 = yield* AsyncResult.ok(10);
+     *     return result1 + result2;
+     * }
+     */
     [Symbol.iterator](): Generator<AsyncResult<T, E>, T, any>;
     private static _runGeneratorProcessor;
-    static run<T, E = ErrorBase>(generatorFunc: () => Generator<AsyncResult<any, any>, T, any>): AsyncResult<T, E>;
-    runInPlace(generatorFunc: () => Generator<AsyncResult<any, any>, T, any>): void;
+    /**
+     * Runs a generator function that yields AsyncResult instances, propagating errors automatically.
+     * If any yielded AsyncResult is an error, the execution stops and the error is returned.
+     * If all yielded AsyncResults are successful, returns a successful AsyncResult with the final returned value.
+     *
+     * This serves the same purpose as chain/flatChain, but allows for a more linear and readable style of coding.
+     * Think of it as "async/await" but for AsyncResult handling in generator functions.
+     *
+     * @param generatorFunc a generator function that yields AsyncResult instances
+     * @returns a AsyncResult containing either the final successful value or the first encountered error
+     *
+     * @example
+     * const result = AsyncResult.run(function* () {
+     *     const value1 = yield* AsyncResult.ok(5);
+     *     const value2 = yield* AsyncResult.ok(10);
+     *     return value1 + value2;
+     * }
+     */
+    static run<T, E extends ErrorBase = ErrorBase>(generatorFunc: () => AsyncResultGenerator<T>): AsyncResult<T, E>;
+    /**
+     * Runs a generator function that yields AsyncResult instances, propagating errors automatically, and updates this AsyncResult in place.
+     * If any yielded AsyncResult is an error, the execution stops and this AsyncResult is updated to that error.
+     * If all yielded AsyncResults are successful, this AsyncResult is updated to a successful state with the final returned value.
+     *
+     * This serves the same purpose as chain/flatChain, but allows for a more linear and readable style of coding.
+     * Think of it as "async/await" but for AsyncResult handling in generator functions.
+     *
+     * @param generatorFunc a generator function that yields AsyncResult instances
+     */
+    runInPlace(generatorFunc: () => AsyncResultGenerator<T>): this;
+    log(name?: string): void;
+    debug(name?: string): () => void;
 }
 
 type KeyedAsyncCacheRefetchOptions = {
     policy: 'refetch' | 'if-error' | 'no-refetch';
 };
-declare class KeyedAsyncCache<P, V, E = ErrorBase> {
+/**
+ * A cache for asynchronous operations that maps parameter sets to their corresponding AsyncResult.
+ * Supports automatic refetching based on specified policies.
+ *
+ * @template P - The type of the parameters used to fetch values.
+ * @template V - The type of the values being fetched.
+ * @template E - The type of the error, extending ErrorBase (default is ErrorBase).
+ */
+declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
     private _cache;
     private _fetcher;
     private _paramsToKey;
-    constructor(fetcher: ChainFunction<P, V, E>, paramsToKey?: (params: P) => string);
+    private _cacheTTL?;
+    /**
+     * Creates a new KeyedAsyncCache instance.
+     * @param fetcher the function used to fetch values based on parameters
+     * @param paramsToKey a function that converts parameters to a unique string key (default uses JSON.stringify for objects)
+     * @param cacheTTL optional time-to-live for cache entries in milliseconds
+     */
+    constructor(fetcher: ChainStep<P, V, E>, paramsToKey?: (params: P) => string, cacheTTL?: number);
     private makeCacheItem;
     private shouldRefetch;
+    private updateOrCreateCacheItemFromParams;
+    /**
+     * Gets the AsyncResult for the given parameters, fetching it if not cached or if refetching is required.
+     * @param params the parameters to fetch the value
+     * @param refetch options determining whether to refetch the value
+     * @returns the AsyncResult corresponding to the given parameters
+     */
     get(params: P, refetch?: KeyedAsyncCacheRefetchOptions): AsyncResult<V, E>;
+    /**
+     * Gets the settled state of the AsyncResult for the given parameters, fetching it if not cached or if refetching is required.
+     * Waits for the AsyncResult to settle before returning its state.
+     * @param params the parameters to fetch the value
+     * @param refetch options determining whether to refetch the value
+     * @returns a promise resolving to the settled state of the AsyncResult
+     */
     getSettledState(params: P, refetch?: KeyedAsyncCacheRefetchOptions): Promise<AsyncResultState<V, E>>;
+    /**
+     * Checks if any cached AsyncResult is currently loading.
+     * @returns whether any cached AsyncResult is loading
+     */
     anyLoading(): boolean;
+    /**
+     * Clears the entire cache.
+     */
     clear(): void;
+    /**
+     * Invalidates the cache entry for the given key.
+     * @param key the key of the cache entry to invalidate
+     */
+    invalidateKey(key: string): void;
+    /**
+     * Invalidates the cache entry for the given parameters.
+     * @param params the parameters of the cache entry to invalidate
+     */
+    invalidateParams(params: P): void;
+    /**
+     * Invalidates all cache entries.
+     */
+    invalidateAll(): void;
 }
 
-export { AsyncResult, type AsyncResultListener, type AsyncResultState, type ChainFunction, ErrorBase, type FlatChainFunction, KeyedAsyncCache, Result, type ResultState };
+export { type Action, AsyncResult, type AsyncResultGenerator, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState };