unwrapped 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # unwrapped
 
+## 0.1.10
+
+### Patch Changes
+
+- 43b4f87: Added utility functions in KeyedAsyncCache
+
+## 0.1.9
+
+### Patch Changes
+
+- 07818f4: Added onSuccess and onError listeners
+
 ## 0.1.8
 
 ### Patch Changes

package/dist/core/index.d.mts

@@ -376,6 +376,30 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
      * @returns a function to remove the listener
      */
     listenUntilSettled(listener: AsyncResultListener<T, E>, immediate?: boolean): () => void;
+    /**
+     * Adds a one-time listener that is called once the AsyncResult settles on a success.
+     * @param callback callback called once the AsyncResult settled on a success
+     * @returns A function to unsubscribe early
+     */
+    onSuccessOnce(callback: (value: T) => void): () => void;
+    /**
+     * Adds a perpetual listener that is called every time the AsyncResult settles on a success.
+     * @param callback callback called every time the AsyncResult settles on a success
+     * @returns A function to unsubscribe
+     */
+    onSuccessPerpetual(callback: (value: T) => void): () => void;
+    /**
+     * Adds a one-time listener that is called once the AsyncResult settles on an error.
+     * @param callback callback called once the AsyncResult settled on an error
+     * @returns A function to unsubscribe early
+     */
+    onErrorOnce(callback: (error: E) => void): () => void;
+    /**
+     * Adds a perpetual listener that is called every time the AsyncResult settles on an error.
+     * @param callback callback called every time the AsyncResult settles on an error
+     * @returns A function to unsubscribe
+     */
+    onErrorPerpetual(callback: (error: E) => void): () => void;
     /**
      * Mirrors the state of another AsyncResult into this one.
      * Whenever the other AsyncResult changes state, this AsyncResult is updated to match.
@@ -483,23 +507,47 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
 /**
  * The possible states of an AsyncResultList.
  */
-type AsyncResultListState = "any-loading" | "all-settled";
-interface AsyncResultListItem<T = any, E extends ErrorBase = ErrorBase> {
+type AsyncResultCollectionState = "any-loading" | "all-settled";
+interface AsyncResultCollectionItem<T = any, E extends ErrorBase = ErrorBase> {
     key: string;
     result: AsyncResult<T, E>;
     unsub: () => void;
 }
 /**
- * A list that manages multiple AsyncResult instances, tracking their states and providing utilities to monitor them.
+ * Manages a collection of AsyncResult tasks with state tracking and listener support.
+ *
+ * This class provides a way to group multiple async operations, track their overall state
+ * (whether any are loading or all have settled), and react to state changes through listeners.
+ *
+ * @template T - The success value type for all AsyncResult tasks in this collection
+ * @template E - The error type for all AsyncResult tasks, defaults to ErrorBase
+ *
+ * @example
+ * ```typescript
+ * const collection = new AsyncResultCollection<User>();
+ * const userTask = new AsyncResult<User>();
+ *
+ * collection.add('user-1', userTask);
+ *
+ * collection.listen((taskQueue) => {
+ *   console.log('Collection state changed:', taskQueue.state);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Tasks can be automatically removed when they settle or kept in the collection
+ * - The collection state is either "any-loading" (at least one task is loading) or "all-settled" (no tasks loading)
+ * - Listeners are notified whenever the collection state changes
+ * - Use filtering methods to query tasks by their state (success, error, loading)
  */
-declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
+declare class AsyncResultCollection<T = any, E extends ErrorBase = ErrorBase> {
     private _list;
     private _listeners;
     private _state;
     /**
      * Gets the current tasks in the AsyncResultList.
      */
-    get tasks(): Map<string, AsyncResultListItem<T, E>>;
+    get tasks(): Map<string, AsyncResultCollectionItem<T, E>>;
     /**
      * Gets the number of tasks in the list.
      */
@@ -516,7 +564,7 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
     /**
      * Gets the current state of the AsyncResultList.
      */
-    get state(): AsyncResultListState;
+    get state(): AsyncResultCollectionState;
     private set state(value);
     private _onTaskFinished;
     /**
@@ -524,7 +572,19 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
      * @param listener the function to call when the state changes
      * @returns a function to unsubscribe the listener
      */
-    listen(listener: (taskQueue: AsyncResultList<T, E>) => void): () => void;
+    listen(listener: (taskQueue: AsyncResultCollection<T, E>) => void): () => void;
+    /**
+     * Adds a listener that gets called whenever any item in the AsyncResultList succeeds.
+     * @param listener the function to call when an item succeeds
+     * @returns a function to unsubscribe the listener
+     */
+    onItemSuccess(listener: (task: AsyncResult<T, E>, key: string) => void): () => void;
+    /**
+     * Adds a listener that gets called whenever any item in the AsyncResultList errors.
+     * @param listener the function to call when an item errors
+     * @returns a function to unsubscribe the listener
+     */
+    onItemError(listener: (task: AsyncResult<T, E>, key: string) => void): () => void;
     /**
      * Adds an AsyncResult task to the list.
      * @param key the unique key for the task
@@ -607,6 +667,13 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
 type KeyedAsyncCacheRefetchOptions = {
     policy: 'refetch' | 'if-error' | 'no-refetch';
 };
+type CacheItem<P, V, E extends ErrorBase = ErrorBase> = {
+    result: AsyncResult<V, E>;
+    fetcherParams: P;
+    valid: boolean;
+    lastFetched?: number;
+    ttl?: number;
+};
 /**
  * A cache for asynchronous operations that maps parameter sets to their corresponding AsyncResult.
  * Supports automatic refetching based on specified policies.
@@ -668,8 +735,23 @@ declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
      * Invalidates all cache entries.
      */
     invalidateAll(): void;
+    /**
+     * Gets all cache items.
+     * @returns an array of all cache items
+     */
+    get items(): CacheItem<P, V, E>[];
+    /**
+     * Gets the number of cache items.
+     * @returns the number of cache items
+     */
+    get size(): number;
+    /**
+     * Gets all cache items with successful results.
+     * @returns an array of cache items with successful results
+     */
+    get successfulItems(): CacheItem<P, V, E>[];
 }
 
 declare function delay(ms: number): AsyncResult<true>;
 
-export { type Action, AsyncResult, type AsyncResultGenerator, AsyncResultList, type AsyncResultListItem, type AsyncResultListState, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState, delay };
+export { type Action, AsyncResult, AsyncResultCollection, type AsyncResultCollectionItem, type AsyncResultCollectionState, type AsyncResultGenerator, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState, delay };

package/dist/core/index.d.ts

@@ -376,6 +376,30 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
      * @returns a function to remove the listener
      */
     listenUntilSettled(listener: AsyncResultListener<T, E>, immediate?: boolean): () => void;
+    /**
+     * Adds a one-time listener that is called once the AsyncResult settles on a success.
+     * @param callback callback called once the AsyncResult settled on a success
+     * @returns A function to unsubscribe early
+     */
+    onSuccessOnce(callback: (value: T) => void): () => void;
+    /**
+     * Adds a perpetual listener that is called every time the AsyncResult settles on a success.
+     * @param callback callback called every time the AsyncResult settles on a success
+     * @returns A function to unsubscribe
+     */
+    onSuccessPerpetual(callback: (value: T) => void): () => void;
+    /**
+     * Adds a one-time listener that is called once the AsyncResult settles on an error.
+     * @param callback callback called once the AsyncResult settled on an error
+     * @returns A function to unsubscribe early
+     */
+    onErrorOnce(callback: (error: E) => void): () => void;
+    /**
+     * Adds a perpetual listener that is called every time the AsyncResult settles on an error.
+     * @param callback callback called every time the AsyncResult settles on an error
+     * @returns A function to unsubscribe
+     */
+    onErrorPerpetual(callback: (error: E) => void): () => void;
     /**
      * Mirrors the state of another AsyncResult into this one.
      * Whenever the other AsyncResult changes state, this AsyncResult is updated to match.
@@ -483,23 +507,47 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
 /**
  * The possible states of an AsyncResultList.
  */
-type AsyncResultListState = "any-loading" | "all-settled";
-interface AsyncResultListItem<T = any, E extends ErrorBase = ErrorBase> {
+type AsyncResultCollectionState = "any-loading" | "all-settled";
+interface AsyncResultCollectionItem<T = any, E extends ErrorBase = ErrorBase> {
     key: string;
     result: AsyncResult<T, E>;
     unsub: () => void;
 }
 /**
- * A list that manages multiple AsyncResult instances, tracking their states and providing utilities to monitor them.
+ * Manages a collection of AsyncResult tasks with state tracking and listener support.
+ *
+ * This class provides a way to group multiple async operations, track their overall state
+ * (whether any are loading or all have settled), and react to state changes through listeners.
+ *
+ * @template T - The success value type for all AsyncResult tasks in this collection
+ * @template E - The error type for all AsyncResult tasks, defaults to ErrorBase
+ *
+ * @example
+ * ```typescript
+ * const collection = new AsyncResultCollection<User>();
+ * const userTask = new AsyncResult<User>();
+ *
+ * collection.add('user-1', userTask);
+ *
+ * collection.listen((taskQueue) => {
+ *   console.log('Collection state changed:', taskQueue.state);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Tasks can be automatically removed when they settle or kept in the collection
+ * - The collection state is either "any-loading" (at least one task is loading) or "all-settled" (no tasks loading)
+ * - Listeners are notified whenever the collection state changes
+ * - Use filtering methods to query tasks by their state (success, error, loading)
  */
-declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
+declare class AsyncResultCollection<T = any, E extends ErrorBase = ErrorBase> {
     private _list;
     private _listeners;
     private _state;
     /**
      * Gets the current tasks in the AsyncResultList.
      */
-    get tasks(): Map<string, AsyncResultListItem<T, E>>;
+    get tasks(): Map<string, AsyncResultCollectionItem<T, E>>;
     /**
      * Gets the number of tasks in the list.
      */
@@ -516,7 +564,7 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
     /**
      * Gets the current state of the AsyncResultList.
      */
-    get state(): AsyncResultListState;
+    get state(): AsyncResultCollectionState;
     private set state(value);
     private _onTaskFinished;
     /**
@@ -524,7 +572,19 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
      * @param listener the function to call when the state changes
      * @returns a function to unsubscribe the listener
      */
-    listen(listener: (taskQueue: AsyncResultList<T, E>) => void): () => void;
+    listen(listener: (taskQueue: AsyncResultCollection<T, E>) => void): () => void;
+    /**
+     * Adds a listener that gets called whenever any item in the AsyncResultList succeeds.
+     * @param listener the function to call when an item succeeds
+     * @returns a function to unsubscribe the listener
+     */
+    onItemSuccess(listener: (task: AsyncResult<T, E>, key: string) => void): () => void;
+    /**
+     * Adds a listener that gets called whenever any item in the AsyncResultList errors.
+     * @param listener the function to call when an item errors
+     * @returns a function to unsubscribe the listener
+     */
+    onItemError(listener: (task: AsyncResult<T, E>, key: string) => void): () => void;
     /**
      * Adds an AsyncResult task to the list.
      * @param key the unique key for the task
@@ -607,6 +667,13 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
 type KeyedAsyncCacheRefetchOptions = {
     policy: 'refetch' | 'if-error' | 'no-refetch';
 };
+type CacheItem<P, V, E extends ErrorBase = ErrorBase> = {
+    result: AsyncResult<V, E>;
+    fetcherParams: P;
+    valid: boolean;
+    lastFetched?: number;
+    ttl?: number;
+};
 /**
  * A cache for asynchronous operations that maps parameter sets to their corresponding AsyncResult.
  * Supports automatic refetching based on specified policies.
@@ -668,8 +735,23 @@ declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
      * Invalidates all cache entries.
      */
     invalidateAll(): void;
+    /**
+     * Gets all cache items.
+     * @returns an array of all cache items
+     */
+    get items(): CacheItem<P, V, E>[];
+    /**
+     * Gets the number of cache items.
+     * @returns the number of cache items
+     */
+    get size(): number;
+    /**
+     * Gets all cache items with successful results.
+     * @returns an array of cache items with successful results
+     */
+    get successfulItems(): CacheItem<P, V, E>[];
 }
 
 declare function delay(ms: number): AsyncResult<true>;
 
-export { type Action, AsyncResult, type AsyncResultGenerator, AsyncResultList, type AsyncResultListItem, type AsyncResultListState, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState, delay };
+export { type Action, AsyncResult, AsyncResultCollection, type AsyncResultCollectionItem, type AsyncResultCollectionState, type AsyncResultGenerator, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState, delay };

package/dist/core/index.js

@@ -21,7 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AsyncResult: () => AsyncResult,
-  AsyncResultList: () => AsyncResultList,
+  AsyncResultCollection: () => AsyncResultCollection,
   ErrorBase: () => ErrorBase,
   KeyedAsyncCache: () => KeyedAsyncCache,
   Result: () => Result,
@@ -519,6 +519,54 @@ var AsyncResult = class _AsyncResult {
     }, immediate);
     return unsub;
   }
+  /**
+   * Adds a one-time listener that is called once the AsyncResult settles on a success.
+   * @param callback callback called once the AsyncResult settled on a success
+   * @returns A function to unsubscribe early
+   */
+  onSuccessOnce(callback) {
+    return this.listenUntilSettled((result) => {
+      if (result.isSuccess()) {
+        callback(result.unwrapOrThrow());
+      }
+    });
+  }
+  /**
+   * Adds a perpetual listener that is called every time the AsyncResult settles on a success.
+   * @param callback callback called every time the AsyncResult settles on a success
+   * @returns A function to unsubscribe
+   */
+  onSuccessPerpetual(callback) {
+    return this.listen((result) => {
+      if (result.isSuccess()) {
+        callback(result.unwrapOrThrow());
+      }
+    });
+  }
+  /**
+   * Adds a one-time listener that is called once the AsyncResult settles on an error.
+   * @param callback callback called once the AsyncResult settled on an error
+   * @returns A function to unsubscribe early
+   */
+  onErrorOnce(callback) {
+    return this.listenUntilSettled((result) => {
+      if (result.isError()) {
+        callback(result.unwrapErrorOrNull());
+      }
+    });
+  }
+  /**
+   * Adds a perpetual listener that is called every time the AsyncResult settles on an error.
+   * @param callback callback called every time the AsyncResult settles on an error
+   * @returns A function to unsubscribe
+   */
+  onErrorPerpetual(callback) {
+    return this.listen((result) => {
+      if (result.isError()) {
+        callback(result.unwrapErrorOrNull());
+      }
+    });
+  }
   // === Mirroring ===
   /**
    * Mirrors the state of another AsyncResult into this one.
@@ -711,8 +759,8 @@ var AsyncResult = class _AsyncResult {
   }
 };
 
-// src/core/asyncResultList.ts
-var AsyncResultList = class {
+// src/core/asyncResultCollection.ts
+var AsyncResultCollection = class {
   _list = /* @__PURE__ */ new Map();
   _listeners = /* @__PURE__ */ new Set();
   _state = "all-settled";
@@ -767,6 +815,34 @@ var AsyncResultList = class {
       this._listeners.delete(listener);
     };
   }
+  /**
+   * Adds a listener that gets called whenever any item in the AsyncResultList succeeds.
+   * @param listener the function to call when an item succeeds
+   * @returns a function to unsubscribe the listener
+   */
+  onItemSuccess(listener) {
+    return this.listen((taskQueue) => {
+      for (const item of taskQueue._list.values()) {
+        if (item.result.isSuccess()) {
+          listener(item.result, item.key);
+        }
+      }
+    });
+  }
+  /**
+   * Adds a listener that gets called whenever any item in the AsyncResultList errors.
+   * @param listener the function to call when an item errors
+   * @returns a function to unsubscribe the listener
+   */
+  onItemError(listener) {
+    return this.listen((taskQueue) => {
+      for (const item of taskQueue._list.values()) {
+        if (item.result.isError()) {
+          listener(item.result, item.key);
+        }
+      }
+    });
+  }
   // === Managing tasks ===
   /**
    * Adds an AsyncResult task to the list.
@@ -1055,6 +1131,27 @@ var KeyedAsyncCache = class {
       cacheItem.valid = false;
     }
   }
+  /**
+   * Gets all cache items.
+   * @returns an array of all cache items
+   */
+  get items() {
+    return Array.from(this._cache.values());
+  }
+  /**
+   * Gets the number of cache items.
+   * @returns the number of cache items
+   */
+  get size() {
+    return this._cache.size;
+  }
+  /**
+   * Gets all cache items with successful results.
+   * @returns an array of cache items with successful results
+   */
+  get successfulItems() {
+    return Array.from(this._cache.values()).filter((item) => item.result.isSuccess());
+  }
 };
 
 // src/core/utils.ts
@@ -1066,7 +1163,7 @@ function delay(ms) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AsyncResult,
-  AsyncResultList,
+  AsyncResultCollection,
   ErrorBase,
   KeyedAsyncCache,
   Result,