unwrapped 0.1.5 → 0.1.7

package/dist/vue/index.d.mts

@@ -1,6 +1,7 @@
+import * as unwrapped_core from 'unwrapped/core';
+import { ErrorBase, AsyncResult, Result, FlatChainStep, Action, AsyncResultGenerator, AsyncResultList } from 'unwrapped/core';
 import * as vue from 'vue';
-import { Ref, WatchSource, VNode } from 'vue';
-import { ErrorBase, AsyncResult, Result, FlatChainStep, Action, AsyncResultGenerator } from 'unwrapped/core';
+import { Ref, WatchSource, VNode, SlotsType } from 'vue';
 
 interface ReactiveProcessOptions {
     immediate: boolean;
@@ -12,7 +13,7 @@ interface ReactiveProcessOptions {
  * @param asyncResult the result to make reactive
  * @returns the ref to the result
  */
-declare function useAsyncResultRef<T, E extends ErrorBase = ErrorBase>(asyncResult: AsyncResult<T, E>): Ref<AsyncResult<T, E>, AsyncResult<T, E>>;
+declare function useAsyncResultRef<T, E extends ErrorBase = ErrorBase>(asyncResult?: AsyncResult<T, E>): Ref<AsyncResult<T, E>, AsyncResult<T, E>>;
 /**
  * Creates an AsyncResult ref from a promise returning a Result.
  * @param promise the promise returning a Result
@@ -78,68 +79,280 @@ declare function useLazyGenerator<T>(generatorFunc: () => AsyncResultGenerator<T
  * @returns ref to the result
  */
 declare function useReactiveGenerator<Inputs, T, E extends ErrorBase = ErrorBase>(source: WatchSource<Inputs>, generatorFunc: (args: Inputs) => AsyncResultGenerator<T>, options?: ReactiveProcessOptions): Ref<AsyncResult<T, E>>;
-
 /**
- * A Vue component that displays different content based on the state of an AsyncResult.
- * It supports slots for 'loading', 'error', 'success' (default), and 'idle' states.
+ * Creates a reactive AsyncResultList wrapped in a Vue ref.
+ * The AsyncResultList notifies Vue's reactivity system whenever its state changes.
  *
- * @example
- * <AsyncResultLoader :result="myAsyncResult">
- *   <template #loading>
- *     <div>Loading data...</div>
- *   </template>
- *   <template #error="{ error }">
- *     <div>Error occurred: {{ error.message }}</div>
- *   </template>
- *   <template #default="{ value }">
- *     <div>Data loaded: {{ value }}</div>
- *   </template>
- *   <template #idle>
- *     <div>Waiting to start...</div>
- *   </template>
- * </AsyncResultLoader>
+ * @template T - The type of the values in the AsyncResultList.
+ * @template E - The type of the error, extending ErrorBase (default is ErrorBase).
+ * @returns a ref to the AsyncResultList
  */
-declare const AsyncResultLoader: vue.DefineComponent<vue.ExtractPropTypes<{
-    result: {
-        type: () => AsyncResult<unknown>;
-        required: true;
-    };
-}>, () => VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}> | VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    result: {
-        type: () => AsyncResult<unknown>;
-        required: true;
-    };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+declare function useAsyncResultList<T = any, E extends ErrorBase = ErrorBase>(): Ref<{
+    readonly tasks: Map<string, {
+        key: string;
+        result: {
+            state: {
+                status: "idle";
+            } | {
+                status: "loading";
+                promise: {
+                    then: <TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined) => Promise<TResult1 | TResult2>;
+                    catch: <TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined) => Promise<Result<T, E> | TResult>;
+                    finally: (onfinally?: (() => void) | null | undefined) => Promise<Result<T, E>>;
+                    readonly [Symbol.toStringTag]: string;
+                };
+            } | {
+                status: "success";
+                value: vue.UnwrapRef<T>;
+            } | {
+                status: "error";
+                error: vue.UnwrapRef<E>;
+            };
+            isSuccess: () => boolean;
+            isError: () => boolean;
+            isIdle: () => boolean;
+            isLoading: () => boolean;
+            unwrapOrNull: () => T | null;
+            unwrapOrThrow: () => T;
+            unwrapErrorOrNull: () => E | null;
+            updateFromValue: (value: T) => AsyncResult<T, E>;
+            updateFromError: (error: E) => AsyncResult<T, E>;
+            updateFromValuePromise: (promise: Promise<T>) => AsyncResult<T, E>;
+            waitForSettled: () => Promise<AsyncResult<T, E>>;
+            toResultPromise: () => Promise<Result<T, E>>;
+            toValueOrThrowPromise: () => Promise<T>;
+            toValueOrNullPromise: () => Promise<T | null>;
+            updateFromResultPromise: (promise: Promise<Result<T, E>>) => AsyncResult<T, E>;
+            listen: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+            listenUntilSettled: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+            mirror: (other: AsyncResult<T, E>) => () => void;
+            mirrorUntilSettled: (other: AsyncResult<T, E>) => () => void;
+            chain: <O, E2 extends ErrorBase = ErrorBase>(fn: unwrapped_core.ChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+            flatChain: <O, E2 extends ErrorBase = ErrorBase>(fn: FlatChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+            runInPlace: (generatorFunc: () => AsyncResultGenerator<T>) => AsyncResult<T, E>;
+            log: (name?: string) => void;
+            debug: (name?: string) => () => void;
+            [Symbol.iterator]: () => Generator<AsyncResult<T, E>, T, any>;
+        };
+        unsub: () => void;
+    }> & Omit<Map<string, unwrapped_core.AsyncResultListItem<T, E>>, keyof Map<any, any>>;
+    readonly length: number;
+    readonly items: {
+        state: {
+            status: "idle";
+        } | {
+            status: "loading";
+            promise: {
+                then: <TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined) => Promise<TResult1 | TResult2>;
+                catch: <TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined) => Promise<Result<T, E> | TResult>;
+                finally: (onfinally?: (() => void) | null | undefined) => Promise<Result<T, E>>;
+                readonly [Symbol.toStringTag]: string;
+            };
+        } | {
+            status: "success";
+            value: vue.UnwrapRef<T>;
+        } | {
+            status: "error";
+            error: vue.UnwrapRef<E>;
+        };
+        isSuccess: () => boolean;
+        isError: () => boolean;
+        isIdle: () => boolean;
+        isLoading: () => boolean;
+        unwrapOrNull: () => T | null;
+        unwrapOrThrow: () => T;
+        unwrapErrorOrNull: () => E | null;
+        updateFromValue: (value: T) => AsyncResult<T, E>;
+        updateFromError: (error: E) => AsyncResult<T, E>;
+        updateFromValuePromise: (promise: Promise<T>) => AsyncResult<T, E>;
+        waitForSettled: () => Promise<AsyncResult<T, E>>;
+        toResultPromise: () => Promise<Result<T, E>>;
+        toValueOrThrowPromise: () => Promise<T>;
+        toValueOrNullPromise: () => Promise<T | null>;
+        updateFromResultPromise: (promise: Promise<Result<T, E>>) => AsyncResult<T, E>;
+        listen: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+        listenUntilSettled: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+        mirror: (other: AsyncResult<T, E>) => () => void;
+        mirrorUntilSettled: (other: AsyncResult<T, E>) => () => void;
+        chain: <O, E2 extends ErrorBase = ErrorBase>(fn: unwrapped_core.ChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+        flatChain: <O, E2 extends ErrorBase = ErrorBase>(fn: FlatChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+        runInPlace: (generatorFunc: () => AsyncResultGenerator<T>) => AsyncResult<T, E>;
+        log: (name?: string) => void;
+        debug: (name?: string) => () => void;
+        [Symbol.iterator]: () => Generator<AsyncResult<T, E>, T, any>;
+    }[];
+    state: unwrapped_core.AsyncResultListState;
+    listen: (listener: (taskQueue: AsyncResultList<T, E>) => void) => () => void;
+    add: (key: string, task: AsyncResult<T, E>, removeOnSettle?: boolean) => AsyncResult<T, E>;
+    clear: () => void;
+    anyLoading: () => boolean;
+    getAllFiltered: (predicate: (task: AsyncResult<T, E>) => boolean) => AsyncResult<T, E>[];
+    getAllFilteredAndMap: <U>(filterPredicate: (task: AsyncResult<T, E>) => boolean, mapFunc: (task: AsyncResult<T, E>) => U) => U[];
+    getAllSuccess: () => AsyncResult<T, E>[];
+    getAllSuccessValues: () => T[];
+    getAllErrors: () => AsyncResult<T, E>[];
+    getAllErrorValues: () => E[];
+    getAllLoading: () => AsyncResult<T, E>[];
+    getAllLoadingPromises: () => Promise<Result<T, E>>[];
+    log: (name?: string) => void;
+    debug: (name?: string) => () => void;
+}, AsyncResultList<T, E> | {
+    readonly tasks: Map<string, {
+        key: string;
+        result: {
+            state: {
+                status: "idle";
+            } | {
+                status: "loading";
+                promise: {
+                    then: <TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined) => Promise<TResult1 | TResult2>;
+                    catch: <TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined) => Promise<Result<T, E> | TResult>;
+                    finally: (onfinally?: (() => void) | null | undefined) => Promise<Result<T, E>>;
+                    readonly [Symbol.toStringTag]: string;
+                };
+            } | {
+                status: "success";
+                value: vue.UnwrapRef<T>;
+            } | {
+                status: "error";
+                error: vue.UnwrapRef<E>;
+            };
+            isSuccess: () => boolean;
+            isError: () => boolean;
+            isIdle: () => boolean;
+            isLoading: () => boolean;
+            unwrapOrNull: () => T | null;
+            unwrapOrThrow: () => T;
+            unwrapErrorOrNull: () => E | null;
+            updateFromValue: (value: T) => AsyncResult<T, E>;
+            updateFromError: (error: E) => AsyncResult<T, E>;
+            updateFromValuePromise: (promise: Promise<T>) => AsyncResult<T, E>;
+            waitForSettled: () => Promise<AsyncResult<T, E>>;
+            toResultPromise: () => Promise<Result<T, E>>;
+            toValueOrThrowPromise: () => Promise<T>;
+            toValueOrNullPromise: () => Promise<T | null>;
+            updateFromResultPromise: (promise: Promise<Result<T, E>>) => AsyncResult<T, E>;
+            listen: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+            listenUntilSettled: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+            mirror: (other: AsyncResult<T, E>) => () => void;
+            mirrorUntilSettled: (other: AsyncResult<T, E>) => () => void;
+            chain: <O, E2 extends ErrorBase = ErrorBase>(fn: unwrapped_core.ChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+            flatChain: <O, E2 extends ErrorBase = ErrorBase>(fn: FlatChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+            runInPlace: (generatorFunc: () => AsyncResultGenerator<T>) => AsyncResult<T, E>;
+            log: (name?: string) => void;
+            debug: (name?: string) => () => void;
+            [Symbol.iterator]: () => Generator<AsyncResult<T, E>, T, any>;
+        };
+        unsub: () => void;
+    }> & Omit<Map<string, unwrapped_core.AsyncResultListItem<T, E>>, keyof Map<any, any>>;
+    readonly length: number;
+    readonly items: {
+        state: {
+            status: "idle";
+        } | {
+            status: "loading";
+            promise: {
+                then: <TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined) => Promise<TResult1 | TResult2>;
+                catch: <TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined) => Promise<Result<T, E> | TResult>;
+                finally: (onfinally?: (() => void) | null | undefined) => Promise<Result<T, E>>;
+                readonly [Symbol.toStringTag]: string;
+            };
+        } | {
+            status: "success";
+            value: vue.UnwrapRef<T>;
+        } | {
+            status: "error";
+            error: vue.UnwrapRef<E>;
+        };
+        isSuccess: () => boolean;
+        isError: () => boolean;
+        isIdle: () => boolean;
+        isLoading: () => boolean;
+        unwrapOrNull: () => T | null;
+        unwrapOrThrow: () => T;
+        unwrapErrorOrNull: () => E | null;
+        updateFromValue: (value: T) => AsyncResult<T, E>;
+        updateFromError: (error: E) => AsyncResult<T, E>;
+        updateFromValuePromise: (promise: Promise<T>) => AsyncResult<T, E>;
+        waitForSettled: () => Promise<AsyncResult<T, E>>;
+        toResultPromise: () => Promise<Result<T, E>>;
+        toValueOrThrowPromise: () => Promise<T>;
+        toValueOrNullPromise: () => Promise<T | null>;
+        updateFromResultPromise: (promise: Promise<Result<T, E>>) => AsyncResult<T, E>;
+        listen: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+        listenUntilSettled: (listener: unwrapped_core.AsyncResultListener<T, E>, immediate?: boolean) => () => void;
+        mirror: (other: AsyncResult<T, E>) => () => void;
+        mirrorUntilSettled: (other: AsyncResult<T, E>) => () => void;
+        chain: <O, E2 extends ErrorBase = ErrorBase>(fn: unwrapped_core.ChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+        flatChain: <O, E2 extends ErrorBase = ErrorBase>(fn: FlatChainStep<T, O, E | E2>) => AsyncResult<O, E | E2>;
+        runInPlace: (generatorFunc: () => AsyncResultGenerator<T>) => AsyncResult<T, E>;
+        log: (name?: string) => void;
+        debug: (name?: string) => () => void;
+        [Symbol.iterator]: () => Generator<AsyncResult<T, E>, T, any>;
+    }[];
+    state: unwrapped_core.AsyncResultListState;
+    listen: (listener: (taskQueue: AsyncResultList<T, E>) => void) => () => void;
+    add: (key: string, task: AsyncResult<T, E>, removeOnSettle?: boolean) => AsyncResult<T, E>;
+    clear: () => void;
+    anyLoading: () => boolean;
+    getAllFiltered: (predicate: (task: AsyncResult<T, E>) => boolean) => AsyncResult<T, E>[];
+    getAllFilteredAndMap: <U>(filterPredicate: (task: AsyncResult<T, E>) => boolean, mapFunc: (task: AsyncResult<T, E>) => U) => U[];
+    getAllSuccess: () => AsyncResult<T, E>[];
+    getAllSuccessValues: () => T[];
+    getAllErrors: () => AsyncResult<T, E>[];
+    getAllErrorValues: () => E[];
+    getAllLoading: () => AsyncResult<T, E>[];
+    getAllLoadingPromises: () => Promise<Result<T, E>>[];
+    log: (name?: string) => void;
+    debug: (name?: string) => () => void;
+}>;
+
 interface CustomSlots<E extends ErrorBase = ErrorBase> {
     loading?: () => VNode;
     error?: (props: {
         error: E;
     }) => VNode;
+    idle?: () => VNode;
 }
 /**
- * Builds a custom AsyncResultLoader component with predefined slots for loading and error states.
+ * Factory function to create a component that displays different content based on an AsyncResult's state. Provides slots for loading, error, idle, and success states and passes the relevant data to each slot, and are typed appropriately.
+ * @param slots predefined slots for loading, error, and idle states. Useful for not having to repeat the same template for displaying a framework-specific spinner while in loading state, or a custom error message.
+ * @param name Optional internal name for the component
+ * @returns An instantiable component that accepts an AsyncResult prop and a default slot for the success state.
  *
- * Useful for creating reusable components with consistent loading and error handling UI (eg. framework-specific spinners, etc...).
+ * @example
+ * // loaders.ts - Create reusable loader with default loading/error UI
+ * const MyLoader = makeAsyncResultLoader({
+ *   loading: () => h(Spinner),
+ *   error: ({ error }) => h(ErrorDisplay, { error }),
+ *   idle: () => h('div', 'Ready')
+ * });
  *
- * @param slots the custom slots for loading and error states
- * @returns a Vue component that uses the provided slots
+ * // MyPage.vue - Use the loader with custom success content
+ * <MyLoader :result="myAsyncResult">
+ *   <template #default="{ value }">
+ *     <UserProfile :user="value" />
+ *   </template>
+ * </MyLoader>
  */
-declare function buildCustomAsyncResultLoader<T, E extends ErrorBase = ErrorBase>(slots: CustomSlots<E>): vue.DefineComponent<vue.ExtractPropTypes<{
+declare function makeAsyncResultLoader<T, E extends ErrorBase = ErrorBase>(slots: CustomSlots<E>, name?: string): vue.DefineComponent<vue.ExtractPropTypes<{
     result: {
         type: () => AsyncResult<T, E>;
         required: true;
     };
 }>, () => VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
-}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+}> | VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[], {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     result: {
         type: () => AsyncResult<T, E>;
         required: true;
     };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+}>> & Readonly<{}>, {}, SlotsType<CustomSlots<E> & {
+    default: {
+        value: T;
+    };
+}>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
-export { AsyncResultLoader, type LazyActionRef, buildCustomAsyncResultLoader, useAction, useAsyncResultRef, useAsyncResultRefFromPromise, useGenerator, useLazyAction, useLazyGenerator, useReactiveChain, useReactiveGenerator };
+export { type LazyActionRef, makeAsyncResultLoader, useAction, useAsyncResultList, useAsyncResultRef, useAsyncResultRefFromPromise, useGenerator, useLazyAction, useLazyGenerator, useReactiveChain, useReactiveGenerator };