unwrapped 0.1.1 → 0.1.3

package/dist/core/index.js

@@ -40,68 +40,171 @@ var ErrorBase = class {
       this.logError();
     }
   }
+  /**
+   * Converts the error to a string representation, on the format "Error {code}: {message}".
+   * @returns a string representation of the error
+   */
   toString() {
     return `Error ${this.code}: ${this.message ?? ""}`;
   }
+  /**
+   * Logs the error to the console, uses console.error and ErrorBase.toString() internally.
+   * Logs thrownError if it was provided on creation.
+   */
   logError() {
-    console.error(this.toString(), this.thrownError);
+    if (this.thrownError) {
+      console.error(this.toString(), this.thrownError);
+    } else {
+      console.error(this.toString());
+    }
   }
 };
 
 // src/core/result.ts
 var Result = class _Result {
   _state;
+  /**
+   * Creates a new Result instance with the given state.
+   * @param state the state of the created Result
+   */
   constructor(state) {
     this._state = state;
   }
+  /** Returns the internal state of the Result. */
   get state() {
     return this._state;
   }
+  /**
+   * Checks if the Result is successful.
+   * @returns whether or not the result is successful
+   */
+  isSuccess() {
+    return this._state.status === "success";
+  }
+  /**
+   * Checks if the Result is an error.
+   * @returns whether or not the result is an error
+   */
+  isError() {
+    return this._state.status === "error";
+  }
+  /**
+   * Creates a successful Result with the given value.
+   * @param value the result of the successful operation
+   * @returns a successful Result
+   */
   static ok(value) {
     return new _Result({ status: "success", value });
   }
+  /**
+   * Creates an error Result with the given error.
+   * @param error the error of the failed operation
+   * @returns an error Result
+   */
   static err(error) {
     return new _Result({ status: "error", error });
   }
-  static errTag(code, message) {
-    return _Result.err(new ErrorBase(code, message));
-  }
+  /**
+   * 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, message, thrownError) {
+    return _Result.err(new ErrorBase(code, message, thrownError));
+  }
+  /**
+   * Returns the successful value (if the Result is successful) or null (if it is an error).
+   * @returns either the successful value or null
+   */
   unwrapOrNull() {
     if (this._state.status === "success") {
       return this._state.value;
     }
     return 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() {
     if (this._state.status === "success") {
       return this._state.value;
     }
     throw new Error("Tried to unwrap a Result that is not successful");
   }
+  /**
+   * 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(defaultValue) {
     if (this._state.status === "success") {
       return this._state.value;
     }
     return defaultValue;
   }
-  isSuccess() {
-    return this._state.status === "success";
-  }
-  isError() {
-    return this._state.status === "error";
-  }
+  /**
+   * 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(promise, errorMapper) {
     return promise.then((value) => _Result.ok(value)).catch((error) => _Result.err(errorMapper(error)));
   }
+  /**
+   * 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(fn, errorMapper) {
     return _Result.tryPromise(fn(), errorMapper);
   }
+  /**
+   * 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(fn) {
     if (this._state.status === "success") {
       return new _Result(fn(this._state.value));
     }
     return _Result.err(this._state.error);
   }
+  /**
+   * 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(fn) {
+    if (this._state.status === "success") {
+      return fn(this._state.value);
+    }
+    return _Result.err(this._state.error);
+  }
+  /**
+   * @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]() {
     yield this;
     if (this._state.status === "success") {
@@ -109,7 +212,24 @@ var Result = class _Result {
     }
     return void 0;
   }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  /**
+   * 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(generator) {
     const iterator = generator();
     let result = iterator.next();
@@ -131,74 +251,142 @@ var AsyncResult = class _AsyncResult {
   constructor(state) {
     this._state = state || { status: "idle" };
   }
+  // === Getting current state ===
+  /**
+   * Returns the internal state of the AsyncResult.
+   */
   get state() {
     return this._state;
   }
-  set state(newState) {
-    this._state = newState;
-    this._listeners.forEach((listener) => listener(this));
-  }
-  static ok(value) {
-    return new _AsyncResult({ status: "success", value });
-  }
-  static err(error) {
-    return new _AsyncResult({ status: "error", error });
-  }
+  /**
+   * Checks if the AsyncResult is successful.
+   * @returns whether or not the result is successful
+   */
   isSuccess() {
     return this._state.status === "success";
   }
+  /**
+   * Checks if the AsyncResult is an error.
+   * @returns whether or not the result is an error
+   */
   isError() {
     return this._state.status === "error";
   }
+  /**
+   * Checks if the AsyncResult is idle.
+   * @returns whether or not the result is idle
+   */
+  isIdle() {
+    return this._state.status === "idle";
+  }
+  /**
+   * Checks if the AsyncResult is loading.
+   * @returns whether or not the result is loading
+   */
   isLoading() {
     return this._state.status === "loading";
   }
-  listen(listener, immediate = true) {
-    this._listeners.add(listener);
-    if (immediate) {
-      listener(this);
+  // === Unwrapping values ===
+  /**
+   * Returns the successful value if the AsyncResult is in a success state, otherwise returns null.
+   * @returns the successful value or null
+   */
+  unwrapOrNull() {
+    if (this._state.status === "success") {
+      return this._state.value;
     }
-    return () => {
-      this._listeners.delete(listener);
-    };
+    return null;
   }
-  listenUntilSettled(listener, immediate = true) {
-    const unsub = this.listen((result) => {
-      listener(result);
-      if (result.state.status === "success" || result.state.status === "error") {
-        unsub();
-      }
-    }, immediate);
-    return unsub;
+  /**
+   * 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() {
+    if (this._state.status === "success") {
+      return this._state.value;
+    }
+    throw new Error("Tried to unwrap an AsyncResult that is not successful");
+  }
+  // === Creating/updating from settled values ===
+  set state(newState) {
+    this._state = newState;
+    this._listeners.forEach((listener) => listener(this));
   }
   setState(newState) {
     this.state = newState;
   }
-  copyOnceSettled(other) {
-    this.updateFromResultPromise(other.toResultPromise());
+  /**
+   * Creates a successful AsyncResult with the given value.
+   * @param value the result of the successful operation
+   * @returns a successful AsyncResult
+   */
+  static ok(value) {
+    return new _AsyncResult({ status: "success", value });
   }
-  update(newState) {
-    this.state = newState;
+  /**
+   * Creates an error AsyncResult with the given error.
+   * @param error the error of the failed operation
+   * @returns an error AsyncResult
+   */
+  static err(error) {
+    return new _AsyncResult({ status: "error", error });
   }
-  updateToValue(value) {
+  /**
+   * 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, message, thrownError, log = true) {
+    const error = new ErrorBase(code, message, thrownError, log);
+    return _AsyncResult.err(error);
+  }
+  /**
+   * Updates the AsyncResult to a successful state with the given value.
+   * Like AsyncResult.ok, but in place.
+   * @param value the successful value
+   */
+  updateFromValue(value) {
     this.state = { status: "success", value };
+    return this;
   }
-  updateToError(error) {
+  /**
+   * Updates the AsyncResult to an error state with the given error.
+   * Like AsyncResult.err, but in place.
+   * @param error the error
+   */
+  updateFromError(error) {
     this.state = { status: "error", error };
+    return this;
   }
-  updateFromResultPromise(promise) {
-    this.state = { status: "loading", promise };
-    promise.then((res) => {
-      this.state = res.state;
-    }).catch((error) => {
-      this.state = { status: "error", error };
-    });
-  }
-  static fromResultPromise(promise) {
+  // === Creating/updating from promises ===
+  /**
+   * 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(promise) {
     const result = new _AsyncResult();
-    result.updateFromResultPromise(promise);
+    result.updateFromValuePromise(promise);
     return result;
   }
+  /**
+   * 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) {
     const resultStatePromise = async () => {
       try {
@@ -208,13 +396,13 @@ var AsyncResult = class _AsyncResult {
         return Result.err(error);
       }
     };
-    this.updateFromResultPromise(resultStatePromise());
-  }
-  static fromValuePromise(promise) {
-    const result = new _AsyncResult();
-    result.updateFromValuePromise(promise);
-    return result;
+    return this.updateFromResultPromise(resultStatePromise());
   }
+  // === Waiting for settled state and get result ===
+  /**
+   * Waits for the AsyncResult to settle (either success or error) if it is currently loading.
+   * @returns itself once settled
+   */
   async waitForSettled() {
     if (this._state.status === "loading") {
       try {
@@ -226,7 +414,11 @@ var AsyncResult = class _AsyncResult {
     }
     return this;
   }
-  async waitForSettledResult() {
+  /**
+   * 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
+   */
+  async toResultPromise() {
     const settled = await this.waitForSettled();
     if (settled.state.status === "idle" || settled.state.status === "loading") {
       throw new Error("Cannot convert idle or loading AsyncResult to ResultState");
@@ -236,46 +428,134 @@ var AsyncResult = class _AsyncResult {
     }
     return Result.ok(settled.state.value);
   }
-  async toResultPromise() {
-    if (this._state.status === "idle") {
-      throw new Error("Cannot convert idle AsyncResult to ResultState");
-    }
-    if (this._state.status === "loading") {
-      try {
-        const value = await this._state.promise;
-        this._state = value.state;
-      } catch (error) {
-        this._state = { status: "error", error };
-      }
-    }
-    return new Result(this._state);
-  }
-  async toValuePromiseThrow() {
+  /**
+   * 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
+   */
+  async toValueOrThrowPromise() {
     const settled = await this.waitForSettled();
     return settled.unwrapOrThrow();
   }
+  /**
+   * 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
+   */
   async toValueOrNullPromise() {
     const settled = await this.waitForSettled();
     return settled.unwrapOrNull();
   }
-  unwrapOrNull() {
-    if (this._state.status === "success") {
-      return this._state.value;
-    }
-    return null;
+  /**
+   * 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(promise) {
+    const result = new _AsyncResult();
+    result.updateFromResultPromise(promise);
+    return result;
   }
-  async unwrapOrNullOnceSettled() {
-    return (await this.waitForSettled()).unwrapOrNull();
+  /**
+   * 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) {
+    this.state = { status: "loading", promise };
+    promise.then((res) => {
+      this.state = res.state;
+    }).catch((error) => {
+      this.updateFromError(new ErrorBase("defect_on_updateFromResultPromise", "The promise provided to AsyncResult rejected", error));
+    });
+    return this;
   }
-  unwrapOrThrow() {
-    if (this._state.status === "success") {
-      return this._state.value;
+  // === Listeners ===
+  /**
+   * 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, immediate = true) {
+    this._listeners.add(listener);
+    if (immediate) {
+      listener(this);
     }
-    throw new Error("Tried to unwrap an AsyncResult that is not successful");
+    return () => {
+      this._listeners.delete(listener);
+    };
   }
-  async unwrapOrThrowOnceSettled() {
-    return (await this.waitForSettled()).unwrapOrThrow();
+  /**
+   * 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, immediate = true) {
+    const unsub = this.listen((result) => {
+      listener(result);
+      if (result.state.status === "success" || result.state.status === "error") {
+        unsub();
+      }
+    }, immediate);
+    return unsub;
   }
+  // === Mirroring ===
+  /**
+   * 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) {
+    return other.listen((newState) => {
+      this.setState(newState.state);
+    }, true);
+  }
+  /**
+   * 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) {
+    return other.listenUntilSettled((newState) => {
+      this.setState(newState.state);
+    }, true);
+  }
+  // === Actions ===
+  /**
+   * 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(action) {
+    const result = new _AsyncResult();
+    const trigger = () => {
+      result.updateFromResultPromise(action());
+    };
+    return { trigger, result };
+  }
+  // === Chaining ===
+  /**
+   * 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(fn) {
     const newResultBuilder = async () => {
       const settled = await this.waitForSettled();
@@ -289,31 +569,41 @@ var AsyncResult = class _AsyncResult {
     };
     return _AsyncResult.fromResultPromise(newResultBuilder());
   }
+  /**
+   * 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(fn) {
     const newResultBuilder = async () => {
-      const settled = await this.waitForSettledResult();
+      const settled = await this.toResultPromise();
       if (settled.state.status === "error") {
         return Result.err(settled.state.error);
       }
       const nextAsyncResult = fn(settled.state.value);
-      const nextSettled = await nextAsyncResult.waitForSettledResult();
+      const nextSettled = await nextAsyncResult.toResultPromise();
       return nextSettled;
     };
     return _AsyncResult.fromResultPromise(newResultBuilder());
   }
   // pipeParallel PipeFunction[] -> AsyncResult<T, E>[]
   // pipeParallelAndCollapse PipeFunction[] -> AsyncResult<T[], E>
-  mirror(other) {
-    return other.listen((newState) => {
-      this.setState(newState.state);
-    }, true);
-  }
-  mirrorUntilSettled(other) {
-    return other.listenUntilSettled((newState) => {
-      this.setState(newState.state);
-    }, true);
-  }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  /**
+   * 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(results) {
     if (results.length === 0) {
       return _AsyncResult.ok(void 0);
@@ -331,7 +621,17 @@ var AsyncResult = class _AsyncResult {
     );
     return _AsyncResult.fromResultPromise(promise);
   }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  // === Generator support ===
+  /**
+   * 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]() {
     yield this;
     if (this._state.status === "success") {
@@ -344,7 +644,7 @@ var AsyncResult = class _AsyncResult {
       let result = iterator.next();
       while (!result.done) {
         const yielded = result.value;
-        const settled = await yielded.waitForSettledResult();
+        const settled = await yielded.toResultPromise();
         if (settled.state.status === "error") {
           return Result.err(settled.state.error);
         }
@@ -353,14 +653,49 @@ var AsyncResult = class _AsyncResult {
       return Result.ok(result.value);
     };
   }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  /**
+   * 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(generatorFunc) {
     const iterator = generatorFunc();
     return _AsyncResult.fromResultPromise(_AsyncResult._runGeneratorProcessor(iterator)());
   }
+  /**
+   * 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) {
     const iterator = generatorFunc();
-    this.updateFromResultPromise(_AsyncResult._runGeneratorProcessor(iterator)());
+    return this.updateFromResultPromise(_AsyncResult._runGeneratorProcessor(iterator)());
+  }
+  // === Debuging ===
+  log(name) {
+    const time = (/* @__PURE__ */ new Date()).toTimeString().slice(0, 7);
+    console.log(`${name ?? "<Anonymous AsyncResult>"} ; State at ${time} :`, this.state);
+  }
+  debug(name) {
+    return this.listen((r) => r.log(name));
   }
 };
 
@@ -376,42 +711,90 @@ var KeyedAsyncCache = class {
   _cache = /* @__PURE__ */ new Map();
   _fetcher;
   _paramsToKey;
-  constructor(fetcher, paramsToKey = defaultParamsToKey) {
+  _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, paramsToKey = defaultParamsToKey, cacheTTL = Infinity) {
     this._fetcher = fetcher;
     this._paramsToKey = paramsToKey;
-  }
-  makeCacheItem(result, fetcherParams) {
-    return { result, fetcherParams };
+    this._cacheTTL = cacheTTL;
+  }
+  makeCacheItem(result, fetcherParams, ttl) {
+    return {
+      result,
+      fetcherParams,
+      ttl: ttl ?? this._cacheTTL,
+      valid: true
+    };
   }
   shouldRefetch(existingResult, refetch) {
+    if (!existingResult.valid) {
+      return true;
+    }
     if (refetch.policy === "refetch") {
       return true;
     }
     if (refetch.policy === "if-error") {
       return existingResult.result.state.status === "error";
     }
+    if (existingResult.ttl !== void 0 && existingResult.lastFetched !== void 0) {
+      const now = Date.now();
+      if (now - existingResult.lastFetched > existingResult.ttl) {
+        return true;
+      }
+    }
     return false;
   }
+  updateOrCreateCacheItemFromParams(params, cacheItem) {
+    const promise = Promise.resolve(this._fetcher(params));
+    let result = cacheItem?.result.updateFromResultPromise(promise) ?? AsyncResult.fromResultPromise(promise);
+    cacheItem = cacheItem ?? this.makeCacheItem(result, params);
+    promise.then(() => {
+      cacheItem.lastFetched = Date.now();
+    });
+    return cacheItem;
+  }
+  /**
+   * 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, refetch = _defaultRefetchOptions) {
     const key = this._paramsToKey(params);
     if (this._cache.has(key)) {
-      const cacheItem = this._cache.get(key);
-      if (!this.shouldRefetch(cacheItem, refetch)) {
-        return cacheItem.result;
+      const cacheItem2 = this._cache.get(key);
+      if (!this.shouldRefetch(cacheItem2, refetch)) {
+        return cacheItem2.result;
       } else {
-        cacheItem.result.updateFromResultPromise(Promise.resolve(this._fetcher(cacheItem.fetcherParams)));
-        return cacheItem.result;
+        this.updateOrCreateCacheItemFromParams(params, cacheItem2);
+        return cacheItem2.result;
       }
     }
-    const asyncResult = AsyncResult.fromResultPromise(Promise.resolve(this._fetcher(params)));
-    this._cache.set(key, this.makeCacheItem(asyncResult, params));
-    return asyncResult;
-  }
+    const cacheItem = this.updateOrCreateCacheItemFromParams(params);
+    this._cache.set(key, cacheItem);
+    return cacheItem.result;
+  }
+  /**
+   * 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
+   */
   async getSettledState(params, refetch = _defaultRefetchOptions) {
     const asyncResult = this.get(params, refetch);
     await asyncResult.waitForSettled();
     return asyncResult.state;
   }
+  /**
+   * Checks if any cached AsyncResult is currently loading.
+   * @returns whether any cached AsyncResult is loading
+   */
   anyLoading() {
     for (const cacheItem of this._cache.values()) {
       if (cacheItem.result.isLoading()) {
@@ -420,9 +803,38 @@ var KeyedAsyncCache = class {
     }
     return false;
   }
+  /**
+   * Clears the entire cache.
+   */
   clear() {
     this._cache.clear();
   }
+  /**
+   * Invalidates the cache entry for the given key.
+   * @param key the key of the cache entry to invalidate
+   */
+  invalidateKey(key) {
+    if (this._cache.has(key)) {
+      const cacheItem = this._cache.get(key);
+      cacheItem.valid = false;
+    }
+  }
+  /**
+   * Invalidates the cache entry for the given parameters.
+   * @param params the parameters of the cache entry to invalidate
+   */
+  invalidateParams(params) {
+    const key = this._paramsToKey(params);
+    this.invalidateKey(key);
+  }
+  /**
+   * Invalidates all cache entries.
+   */
+  invalidateAll() {
+    for (const cacheItem of this._cache.values()) {
+      cacheItem.valid = false;
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {