unwrapped 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # unwrapped
 
+## 0.1.9
+
+### Patch Changes
+
+- 07818f4: Added onSuccess and onError listeners
+
+## 0.1.8
+
+### Patch Changes
+
+- ba3d98f: Tweaks to AsyncResultList
+
 ## 0.1.7
 
 ### 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.
      */
@@ -508,10 +556,15 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
      * Gets all tasks in the list as an array.
      */
     get items(): AsyncResult<T, E>[];
+    /**
+     * Gets all tasks in the list as an array of key-value pairs.
+     * Each pair contains the key and the corresponding AsyncResult.
+     */
+    get entries(): [string, AsyncResult<T, E>][];
     /**
      * Gets the current state of the AsyncResultList.
      */
-    get state(): AsyncResultListState;
+    get state(): AsyncResultCollectionState;
     private set state(value);
     private _onTaskFinished;
     /**
@@ -519,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
@@ -528,6 +593,15 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
      * @returns the added AsyncResult task
      */
     add(key: string, task: AsyncResult<T, E>, removeOnSettle?: boolean): AsyncResult<T, E>;
+    /**
+     * Removes a task from the list by its key.
+     * @param key the unique key of the task to remove
+     * @returns true if the task was removed, false if it was not found
+     */
+    remove(key: string): boolean;
+    /**
+     * Clears all tasks from the list and sets the state to "all-settled".
+     */
     clear(): void;
     /**
      * Checks if any task in the list is currently loading.
@@ -658,4 +732,4 @@ declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
 
 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.
      */
@@ -508,10 +556,15 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
      * Gets all tasks in the list as an array.
      */
     get items(): AsyncResult<T, E>[];
+    /**
+     * Gets all tasks in the list as an array of key-value pairs.
+     * Each pair contains the key and the corresponding AsyncResult.
+     */
+    get entries(): [string, AsyncResult<T, E>][];
     /**
      * Gets the current state of the AsyncResultList.
      */
-    get state(): AsyncResultListState;
+    get state(): AsyncResultCollectionState;
     private set state(value);
     private _onTaskFinished;
     /**
@@ -519,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
@@ -528,6 +593,15 @@ declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
      * @returns the added AsyncResult task
      */
     add(key: string, task: AsyncResult<T, E>, removeOnSettle?: boolean): AsyncResult<T, E>;
+    /**
+     * Removes a task from the list by its key.
+     * @param key the unique key of the task to remove
+     * @returns true if the task was removed, false if it was not found
+     */
+    remove(key: string): boolean;
+    /**
+     * Clears all tasks from the list and sets the state to "all-settled".
+     */
     clear(): void;
     /**
      * Checks if any task in the list is currently loading.
@@ -658,4 +732,4 @@ declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
 
 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";
@@ -735,6 +783,13 @@ var AsyncResultList = class {
   get items() {
     return Array.from(this._list.values()).map((i) => i.result);
   }
+  /**
+   * Gets all tasks in the list as an array of key-value pairs.
+   * Each pair contains the key and the corresponding AsyncResult.
+   */
+  get entries() {
+    return Array.from(this._list.entries()).map(([key, item]) => [key, item.result]);
+  }
   /**
    * Gets the current state of the AsyncResultList.
    */
@@ -760,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.
@@ -786,6 +869,22 @@ var AsyncResultList = class {
     this.state = "any-loading";
     return task;
   }
+  /**
+   * Removes a task from the list by its key.
+   * @param key the unique key of the task to remove
+   * @returns true if the task was removed, false if it was not found
+   */
+  remove(key) {
+    const item = this._list.get(key);
+    if (!item) return false;
+    item.unsub();
+    this._list.delete(key);
+    this._onTaskFinished();
+    return true;
+  }
+  /**
+   * Clears all tasks from the list and sets the state to "all-settled".
+   */
   clear() {
     this._list.forEach(({ unsub }) => unsub());
     this._list.clear();
@@ -1043,7 +1142,7 @@ function delay(ms) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AsyncResult,
-  AsyncResultList,
+  AsyncResultCollection,
   ErrorBase,
   KeyedAsyncCache,
   Result,