unwrapped 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # unwrapped
 
+## 0.1.6
+
+### Patch Changes
+
+- 58d5299: Added AsyncResultList
+
+## 0.1.5
+
+### Patch Changes
+
+- 50d5178: Improved beginning of docs
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -1,10 +1,19 @@
 # Unwrapped
 
-A TypeScript library for elegant error handling and asynchronous state management, inspired by Rust's `Result` type and designed with Vue 3 integration in mind.
+A TypeScript library for handling more gracefully synchronous and asynchronous operations that can fail via Result types. Provides also utilities for caching and binding for popular web frameworks.
 
 ## Overview
 
-**Unwrapped** provides a robust alternative to `try/catch` blocks and promise chains, making error handling explicit, type-safe, and composable. It consists of two main parts:
+Error handling in TypeScript is fundamentally built around throwing exceptions and catching them with try/catch blocks. This works fine for simple scripts where an unexpected error should crash the program, but modern applications—especially frontends—need to handle errors gracefully without crashing the entire app.
+
+**Unwrapped** provides a different approach by providing Result types, with variants for both synchronous and asynchronous operations.
+While their primary and most basic use are for describing the result of operations that may fail, they can be chained to describe chains of operations, with build-in short-circuiting when encoutering an error. These chains can be described either by successively calling methods like `.chain()`, or by using a generator syntax inspired by Effect (although much simplified).
+
+Without **Unwrapped**, the traditional approach leads to scattered state management: separate variables for loading, error, and data, manual state transitions, and the ever-present risk of forgetting to set loading = false in a finally block. Error types are unknown, forcing type assertions everywhere. Chaining multiple async operations that can each fail becomes a mess of nested try/catch blocks or promise chains with multiple .catch() handlers.
+
+On the contrary, **Unwrapped**'s AsyncResult type wraps loading, error, and success states in one type allowing for a much leaner and less error prone way of writing. Unsettled asynchronous operations will always give you an AsyncResult in a loading state, and when this work finishes, the AsyncResult will always be in a settled state, being either error or success.
+
+**Unwrapped** is composed of multiple sub-modules :
 
 - **Core**: Framework-agnostic utilities for managing results and async operations
 - **Vue**: Vue 3 composables and components for reactive async state management
@@ -19,6 +28,20 @@ A brief comparison with other libraries can be found at the "Why Unwrapped ?" se
 npm install unwrapped
 ```
 
+## API Reference
+
+### Core Module (`unwrapped/core`)
+
+- **`Result<T, E>`**: Synchronous result type
+- **`AsyncResult<T, E>`**: Asynchronous result with state tracking
+- **`ErrorBase`**: Base error class with structured logging
+- **`KeyedAsyncCache<P, V, E>`**: Cache for async operations
+
+### Vue Module (`unwrapped/vue`)
+
+- **Composables**: `useAsyncResultRef`, `useAction`, `useLazyAction`, `useReactiveChain`, `useGenerator`, `useLazyGenerator`, `useReactiveGenerator`
+- **Components**: `AsyncResultLoader`, `buildCustomAsyncResultLoader`
+
 
 ## Core Concepts
 
@@ -825,20 +848,6 @@ Unwrapped is in very active development and a lot of features are still planned,
 - Debounce on relevant utilities
 
 
-## API Reference
-
-### Core Module (`unwrapped/core`)
-
-- **`Result<T, E>`**: Synchronous result type
-- **`AsyncResult<T, E>`**: Asynchronous result with state tracking
-- **`ErrorBase`**: Base error class with structured logging
-- **`KeyedAsyncCache<P, V, E>`**: Cache for async operations
-
-### Vue Module (`unwrapped/vue`)
-
-- **Composables**: `useAsyncResultRef`, `useAction`, `useLazyAction`, `useReactiveChain`, `useGenerator`, `useLazyGenerator`, `useReactiveGenerator`
-- **Components**: `AsyncResultLoader`, `buildCustomAsyncResultLoader`
-
 ## License
 
 LGPL-3.0-or-later

package/dist/core/index.d.mts

@@ -261,6 +261,11 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
      * @throws an normal JS Error if the result is not successful
      */
     unwrapOrThrow(): T;
+    /**
+     * Returns the error value if the AsyncResult is in an error state, otherwise returns null.
+     * @returns the error value or null
+     */
+    unwrapErrorOrNull(): E | null;
     private set state(value);
     private setState;
     /**
@@ -475,6 +480,110 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
     debug(name?: string): () => void;
 }
 
+/**
+ * The possible states of an AsyncResultList.
+ */
+type AsyncResultListState = "any-loading" | "all-settled";
+/**
+ * A list that manages multiple AsyncResult instances, tracking their states and providing utilities to monitor them.
+ */
+declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
+    private _list;
+    private _listeners;
+    private _state;
+    /**
+     * Gets the current tasks in the AsyncResultList.
+     */
+    get tasks(): Map<string, AsyncResult<T, E>>;
+    /**
+     * Gets the number of tasks in the list.
+     */
+    get length(): number;
+    /**
+     * Gets all tasks in the list as an array.
+     */
+    get items(): AsyncResult<T, E>[];
+    /**
+     * Gets the current state of the AsyncResultList.
+     */
+    get state(): AsyncResultListState;
+    private set state(value);
+    private _onTaskFinished;
+    /**
+     * Adds a listener that gets called whenever the state of the AsyncResultList changes.
+     * @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;
+    /**
+     * Adds an AsyncResult task to the list.
+     * @param key the unique key for the task
+     * @param task the AsyncResult task to add
+     * @param removeOnSettle whether to remove the task from the list once it settles (defaults to true)
+     * @returns the added AsyncResult task
+     */
+    add(key: string, task: AsyncResult<T, E>, removeOnSettle?: boolean): AsyncResult<T, E>;
+    /**
+     * Checks if any task in the list is currently loading.
+     * @returns true if any task is loading, false otherwise
+     */
+    anyLoading(): boolean;
+    /**
+     * Gets all tasks that satisfy the given predicate.
+     * @param predicate the function to test each task
+     * @returns an array of tasks that satisfy the predicate
+     */
+    getAllFiltered(predicate: (task: AsyncResult<T, E>) => boolean): AsyncResult<T, E>[];
+    /**
+     * Gets all tasks that satisfy the given predicate and maps them using the provided function.
+     * @param filterPredicate the function to test each task
+     * @param mapFunc the function to map each task
+     * @returns an array of mapped values
+     */
+    getAllFilteredAndMap<U>(filterPredicate: (task: AsyncResult<T, E>) => boolean, mapFunc: (task: AsyncResult<T, E>) => U): U[];
+    /**
+     * Gets all tasks that have succeeded.
+     * @returns an array of successful AsyncResult tasks
+     */
+    getAllSuccess(): AsyncResult<T, E>[];
+    /**
+     * Gets the success values of all tasks that have succeeded.
+     * @returns an array of successful values
+     */
+    getAllSuccessValues(): T[];
+    /**
+     * Gets all tasks that have errored.
+     * @returns an array of error AsyncResult tasks
+     */
+    getAllErrors(): AsyncResult<T, E>[];
+    /**
+     * Gets the error values of all tasks that have errored.
+     * @returns an array of error values
+     */
+    getAllErrorValues(): E[];
+    /**
+     * Gets all tasks that are currently loading.
+     * @returns an array of loading AsyncResult tasks
+     */
+    getAllLoading(): AsyncResult<T, E>[];
+    /**
+     * Gets the promises of all tasks that are currently loading.
+     * @returns an array of promises for loading tasks
+     */
+    getAllLoadingPromises(): Promise<Result<T, E>>[];
+    /**
+     * Logs the current state and tasks of the AsyncResultList to the console.
+     * @param name an optional name to identify the log
+     */
+    log(name?: string): void;
+    /**
+     * Sets up a listener to log the state and tasks of the AsyncResultList whenever it changes.
+     * @param name an optional name to identify the log
+     * @returns a function to unsubscribe the debug listener
+     */
+    debug(name?: string): () => void;
+}
+
 type KeyedAsyncCacheRefetchOptions = {
     policy: 'refetch' | 'if-error' | 'no-refetch';
 };
@@ -541,4 +650,6 @@ declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
     invalidateAll(): void;
 }
 
-export { type Action, AsyncResult, type AsyncResultGenerator, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState };
+declare function delay(ms: number): AsyncResult<true>;
+
+export { type Action, AsyncResult, type AsyncResultGenerator, AsyncResultList, type AsyncResultListState, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState, delay };

package/dist/core/index.d.ts

@@ -261,6 +261,11 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
      * @throws an normal JS Error if the result is not successful
      */
     unwrapOrThrow(): T;
+    /**
+     * Returns the error value if the AsyncResult is in an error state, otherwise returns null.
+     * @returns the error value or null
+     */
+    unwrapErrorOrNull(): E | null;
     private set state(value);
     private setState;
     /**
@@ -475,6 +480,110 @@ declare class AsyncResult<T, E extends ErrorBase = ErrorBase> {
     debug(name?: string): () => void;
 }
 
+/**
+ * The possible states of an AsyncResultList.
+ */
+type AsyncResultListState = "any-loading" | "all-settled";
+/**
+ * A list that manages multiple AsyncResult instances, tracking their states and providing utilities to monitor them.
+ */
+declare class AsyncResultList<T = any, E extends ErrorBase = ErrorBase> {
+    private _list;
+    private _listeners;
+    private _state;
+    /**
+     * Gets the current tasks in the AsyncResultList.
+     */
+    get tasks(): Map<string, AsyncResult<T, E>>;
+    /**
+     * Gets the number of tasks in the list.
+     */
+    get length(): number;
+    /**
+     * Gets all tasks in the list as an array.
+     */
+    get items(): AsyncResult<T, E>[];
+    /**
+     * Gets the current state of the AsyncResultList.
+     */
+    get state(): AsyncResultListState;
+    private set state(value);
+    private _onTaskFinished;
+    /**
+     * Adds a listener that gets called whenever the state of the AsyncResultList changes.
+     * @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;
+    /**
+     * Adds an AsyncResult task to the list.
+     * @param key the unique key for the task
+     * @param task the AsyncResult task to add
+     * @param removeOnSettle whether to remove the task from the list once it settles (defaults to true)
+     * @returns the added AsyncResult task
+     */
+    add(key: string, task: AsyncResult<T, E>, removeOnSettle?: boolean): AsyncResult<T, E>;
+    /**
+     * Checks if any task in the list is currently loading.
+     * @returns true if any task is loading, false otherwise
+     */
+    anyLoading(): boolean;
+    /**
+     * Gets all tasks that satisfy the given predicate.
+     * @param predicate the function to test each task
+     * @returns an array of tasks that satisfy the predicate
+     */
+    getAllFiltered(predicate: (task: AsyncResult<T, E>) => boolean): AsyncResult<T, E>[];
+    /**
+     * Gets all tasks that satisfy the given predicate and maps them using the provided function.
+     * @param filterPredicate the function to test each task
+     * @param mapFunc the function to map each task
+     * @returns an array of mapped values
+     */
+    getAllFilteredAndMap<U>(filterPredicate: (task: AsyncResult<T, E>) => boolean, mapFunc: (task: AsyncResult<T, E>) => U): U[];
+    /**
+     * Gets all tasks that have succeeded.
+     * @returns an array of successful AsyncResult tasks
+     */
+    getAllSuccess(): AsyncResult<T, E>[];
+    /**
+     * Gets the success values of all tasks that have succeeded.
+     * @returns an array of successful values
+     */
+    getAllSuccessValues(): T[];
+    /**
+     * Gets all tasks that have errored.
+     * @returns an array of error AsyncResult tasks
+     */
+    getAllErrors(): AsyncResult<T, E>[];
+    /**
+     * Gets the error values of all tasks that have errored.
+     * @returns an array of error values
+     */
+    getAllErrorValues(): E[];
+    /**
+     * Gets all tasks that are currently loading.
+     * @returns an array of loading AsyncResult tasks
+     */
+    getAllLoading(): AsyncResult<T, E>[];
+    /**
+     * Gets the promises of all tasks that are currently loading.
+     * @returns an array of promises for loading tasks
+     */
+    getAllLoadingPromises(): Promise<Result<T, E>>[];
+    /**
+     * Logs the current state and tasks of the AsyncResultList to the console.
+     * @param name an optional name to identify the log
+     */
+    log(name?: string): void;
+    /**
+     * Sets up a listener to log the state and tasks of the AsyncResultList whenever it changes.
+     * @param name an optional name to identify the log
+     * @returns a function to unsubscribe the debug listener
+     */
+    debug(name?: string): () => void;
+}
+
 type KeyedAsyncCacheRefetchOptions = {
     policy: 'refetch' | 'if-error' | 'no-refetch';
 };
@@ -541,4 +650,6 @@ declare class KeyedAsyncCache<P, V, E extends ErrorBase = ErrorBase> {
     invalidateAll(): void;
 }
 
-export { type Action, AsyncResult, type AsyncResultGenerator, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState };
+declare function delay(ms: number): AsyncResult<true>;
+
+export { type Action, AsyncResult, type AsyncResultGenerator, AsyncResultList, type AsyncResultListState, type AsyncResultListener, type AsyncResultState, type ChainStep, ErrorBase, type FlatChainStep, KeyedAsyncCache, type LazyAction, Result, type ResultState, delay };

package/dist/core/index.js

@@ -21,9 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AsyncResult: () => AsyncResult,
+  AsyncResultList: () => AsyncResultList,
   ErrorBase: () => ErrorBase,
   KeyedAsyncCache: () => KeyedAsyncCache,
-  Result: () => Result
+  Result: () => Result,
+  delay: () => delay
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -308,6 +310,16 @@ var AsyncResult = class _AsyncResult {
     }
     throw new Error("Tried to unwrap an AsyncResult that is not successful");
   }
+  /**
+   * Returns the error value if the AsyncResult is in an error state, otherwise returns null.
+   * @returns the error value or null
+   */
+  unwrapErrorOrNull() {
+    if (this._state.status === "error") {
+      return this._state.error;
+    }
+    return null;
+  }
   // === Creating/updating from settled values ===
   set state(newState) {
     this._state = newState;
@@ -691,7 +703,7 @@ var AsyncResult = class _AsyncResult {
   }
   // === Debuging ===
   log(name) {
-    const time = (/* @__PURE__ */ new Date()).toTimeString().slice(0, 7);
+    const time = (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
     console.log(`${name ?? "<Anonymous AsyncResult>"} ; State at ${time} :`, this.state);
   }
   debug(name) {
@@ -699,6 +711,185 @@ var AsyncResult = class _AsyncResult {
   }
 };
 
+// src/core/asyncResultList.ts
+var AsyncResultList = class {
+  _list = /* @__PURE__ */ new Map();
+  _listeners = /* @__PURE__ */ new Set();
+  _state = "all-settled";
+  // === Getters ===
+  /**
+   * Gets the current tasks in the AsyncResultList.
+   */
+  get tasks() {
+    return this._list;
+  }
+  /**
+   * Gets the number of tasks in the list.
+   */
+  get length() {
+    return this._list.size;
+  }
+  /**
+   * Gets all tasks in the list as an array.
+   */
+  get items() {
+    return Array.from(this._list.values());
+  }
+  /**
+   * Gets the current state of the AsyncResultList.
+   */
+  get state() {
+    return this._state;
+  }
+  set state(s) {
+    this._state = s;
+    this._listeners.forEach((f) => f(this));
+  }
+  _onTaskFinished() {
+    this.state = this.anyLoading() ? "any-loading" : "all-settled";
+  }
+  // === Listeners ===
+  /**
+   * Adds a listener that gets called whenever the state of the AsyncResultList changes.
+   * @param listener the function to call when the state changes
+   * @returns a function to unsubscribe the listener
+   */
+  listen(listener) {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+  // === Managing tasks ===
+  /**
+   * Adds an AsyncResult task to the list.
+   * @param key the unique key for the task
+   * @param task the AsyncResult task to add
+   * @param removeOnSettle whether to remove the task from the list once it settles (defaults to true)
+   * @returns the added AsyncResult task
+   */
+  add(key, task, removeOnSettle = true) {
+    this._list.set(key, task);
+    this.state = "any-loading";
+    if (removeOnSettle) {
+      task.listenUntilSettled((r) => {
+        if (r.isLoading() || r.isIdle()) return;
+        this._onTaskFinished();
+        this._list.delete(key);
+      }, true);
+    } else {
+      task.listen((r) => {
+        if (r.isLoading() || r.isIdle()) return;
+        this._onTaskFinished();
+      }, true);
+    }
+    return task;
+  }
+  // === Querying tasks ===
+  /**
+   * Checks if any task in the list is currently loading.
+   * @returns true if any task is loading, false otherwise
+   */
+  anyLoading() {
+    for (const task of this._list.values()) {
+      if (task.isLoading()) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Gets all tasks that satisfy the given predicate.
+   * @param predicate the function to test each task
+   * @returns an array of tasks that satisfy the predicate
+   */
+  getAllFiltered(predicate) {
+    const filtered = [];
+    for (const task of this._list.values()) {
+      if (predicate(task)) {
+        filtered.push(task);
+      }
+    }
+    return filtered;
+  }
+  /**
+   * Gets all tasks that satisfy the given predicate and maps them using the provided function.
+   * @param filterPredicate the function to test each task
+   * @param mapFunc the function to map each task
+   * @returns an array of mapped values
+   */
+  getAllFilteredAndMap(filterPredicate, mapFunc) {
+    const results = [];
+    for (const task of this._list.values()) {
+      if (filterPredicate(task)) {
+        results.push(mapFunc(task));
+      }
+    }
+    return results;
+  }
+  /**
+   * Gets all tasks that have succeeded.
+   * @returns an array of successful AsyncResult tasks
+   */
+  getAllSuccess() {
+    return this.getAllFiltered((task) => task.isSuccess());
+  }
+  /**
+   * Gets the success values of all tasks that have succeeded.
+   * @returns an array of successful values
+   */
+  getAllSuccessValues() {
+    return this.getAllFilteredAndMap((task) => task.isSuccess(), (task) => task.unwrapOrThrow());
+  }
+  /**
+   * Gets all tasks that have errored.
+   * @returns an array of error AsyncResult tasks
+   */
+  getAllErrors() {
+    return this.getAllFiltered((task) => task.isError());
+  }
+  /**
+   * Gets the error values of all tasks that have errored.
+   * @returns an array of error values
+   */
+  getAllErrorValues() {
+    return this.getAllFilteredAndMap((task) => task.isError(), (task) => task.unwrapErrorOrNull());
+  }
+  /**
+   * Gets all tasks that are currently loading.
+   * @returns an array of loading AsyncResult tasks
+   */
+  getAllLoading() {
+    return this.getAllFiltered((task) => task.isLoading());
+  }
+  /**
+   * Gets the promises of all tasks that are currently loading.
+   * @returns an array of promises for loading tasks
+   */
+  getAllLoadingPromises() {
+    return this.getAllFilteredAndMap((task) => task.isLoading(), (task) => task.toResultPromise());
+  }
+  // === Debugging utilities ===
+  /**
+   * Logs the current state and tasks of the AsyncResultList to the console.
+   * @param name an optional name to identify the log
+   */
+  log(name) {
+    const time = (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+    console.log(`${name ?? "<Anonymous TaskQueue>"} ; State at ${time} :`, this.state, this._list);
+  }
+  /**
+   * Sets up a listener to log the state and tasks of the AsyncResultList whenever it changes.
+   * @param name an optional name to identify the log
+   * @returns a function to unsubscribe the debug listener
+   */
+  debug(name) {
+    return this.listen(() => {
+      this.log(name);
+    });
+  }
+};
+
 // src/core/cache.ts
 var _defaultRefetchOptions = { policy: "no-refetch" };
 function defaultParamsToKey(params) {
@@ -836,11 +1027,20 @@ var KeyedAsyncCache = class {
     }
   }
 };
+
+// src/core/utils.ts
+function delay(ms) {
+  return AsyncResult.fromValuePromise(new Promise((resolve) => {
+    setTimeout(() => resolve(true), ms);
+  }));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AsyncResult,
+  AsyncResultList,
   ErrorBase,
   KeyedAsyncCache,
-  Result
+  Result,
+  delay
 });
 //# sourceMappingURL=index.js.map