@arrai-innovations/reactive-helpers 20.1.2 → 21.0.0

package/types/tests/unit/crudPromise.d.ts

@@ -1,25 +1,52 @@
 /**
  * A class that wraps a promise and its resolve and reject functions
+ *
+ * @template T
  */
-export class Resolvable {
+export class Resolvable<T> {
     /**
-     * @type {Promise}
+     * @type {Promise<T>}
      */
-    promise: Promise<any>;
-    /** @type {Function} */
-    resolve: Function;
-    /** @type {Function} */
-    reject: Function;
+    promise: Promise<T>;
+    /**
+     * @type {(value: T) => void}
+     */
+    resolve: (value: T) => void;
+    /**
+     * @type {(reason?: any) => void}
+     */
+    reject: (reason?: any) => void;
 }
 /**
  * A Resolvable with a cancel function.
+ *
+ * @template T
  */
-export class CancellableResolvable {
-    promise: Promise<any>;
-    /** @type {Function} */
-    resolve: Function;
-    /** @type {Function} */
-    reject: Function;
-    cancel: Resolvable;
+export class CancellableResolvable<T> {
+    /**
+     * @type {import("../../utils/cancellablePromise.js").CancellablePromise<T>}
+     */
+    promise: import("../../utils/cancellablePromise.js").CancellablePromise<T>;
+    /**
+     * @type {(value: T) => void}
+     */
+    resolve: (value: T) => void;
+    /**
+     * @type {(reason?: any) => void}
+     */
+    reject: (reason?: any) => void;
+    /**
+     * Cancel-related resolvable.
+     *
+     * @type {{ promise: Promise<void>, resolve: () => void }}
+     */
+    cancel: {
+        promise: Promise<void>;
+        resolve: () => void;
+    };
+    /**
+     * @private
+     * @type {(value?: any) => void}
+     */
+    private _cancelResolve;
 }
-//# sourceMappingURL=crudPromise.d.ts.map

package/types/tests/unit/mockOnUnmounted.d.ts

@@ -1,2 +1 @@
 export function getMockOnUnmounted(): {};
-//# sourceMappingURL=mockOnUnmounted.d.ts.map

package/types/tests/unit/poll.d.ts

@@ -1,2 +1 @@
 export function poll(condition: any, interval?: number, timeout?: number): Promise<any>;
-//# sourceMappingURL=poll.d.ts.map

package/types/tests/unit/scopedIt.d.ts

@@ -0,0 +1,15 @@
+export function scopedIt(name: string, fn: () => Promise<void> | void, timeout?: number): void;
+export namespace scopedIt {
+    /**
+     * Mark a scoped test as TODO.
+     * @param {string} name - The name of the test.
+     */
+    export function todo(name: string): void;
+    export function each(cases: any): (name: any, optionsOrFn: any, maybeFn: any) => any;
+    /**
+     * Run a test in a Vue effect scope with multiple cases, using `it.for`.
+     * @param {Array} cases - The cases to run the test with.
+     */
+    function _for(cases: any[]): (name: any, maybeOptionsOrFn: any, maybeFnOrNothing: any) => void;
+    export { _for as for };
+}

package/types/tests/unit/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/types/tests/unit/use/cancellableIntent.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=cancellableIntent.spec.d.ts.map

package/types/tests/unit/use/combineClasses.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/list.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listCalculated.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listCalculated.spec.d.ts.map

package/types/tests/unit/use/listFilter.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listFilter.spec.d.ts.map

package/types/tests/unit/use/listInstance.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listInstance.spec.d.ts.map

package/types/tests/unit/use/listRelated.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listRelated.spec.d.ts.map

package/types/tests/unit/use/listSearch.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listSearch.spec.d.ts.map

package/types/tests/unit/use/listSort.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listSort.spec.d.ts.map

package/types/tests/unit/use/listSubscription.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=listSubscription.spec.d.ts.map

package/types/tests/unit/use/loadingError.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=loadingError.spec.d.ts.map

package/types/tests/unit/use/object.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/objectCalculated.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/objectInstance.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=objectInstance.spec.d.ts.map

package/types/tests/unit/use/objectRelated.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/objectSubscription.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=objectSubscription.spec.d.ts.map

package/types/tests/unit/use/proxyLoadingError.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=proxyLoadingError.spec.d.ts.map

package/types/tests/unit/use/search.error.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/search.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=search.spec.d.ts.map

package/types/tests/unit/utils/assignReactiveObject.extra.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/assignReactiveObject.refs.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/assignReactiveObject.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=assignReactiveObject.spec.d.ts.map

package/types/tests/unit/utils/cancellableFetch.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/classes.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=classes.spec.d.ts.map

package/types/tests/unit/utils/compact.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/deepUnref.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/deleteKey.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=deleteKey.spec.d.ts.map

package/types/tests/unit/utils/flattenPaths.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=flattenPaths.spec.d.ts.map

package/types/tests/unit/utils/flattenPathsWithValues.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/getFakePk.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/keepAliveTry.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/keyDiff.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=keyDiff.spec.d.ts.map

package/types/tests/unit/utils/set.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=set.spec.d.ts.map

package/types/tests/unit/utils/transformWalk.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/unwrapNested.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/utils/watches.spec.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=watches.spec.d.ts.map

package/types/use/cancellableIntent.d.ts

@@ -1,33 +1,62 @@
 /**
- * @module use/cancellableIntent.js - A composable function for handling cancellable intents.
+ * @typedef {number} RunId - A unique identifier for a single execution ("run") of an intent.
+ * This is incremented each time `watchArguments` change and the intent re-triggers.
+ * Enables distinguishing results or effects from overlapping async runs.
  */
 /**
  * @typedef {object} CancellableIntentRawState - The raw state of the cancellable intent.
- * @property {number|undefined} activeCount - The number of active intents.
- * @property {boolean|undefined} active - Whether there are active intents.
- * @property {number|undefined} resolvingCount - The number of resolving intents.
- * @property {boolean|undefined} resolving - Whether there are resolving intents.
- * @property {boolean} errored - Whether there was an error.
- * @property {Error|null} error - The error that occurred.
+ * @property {import('vue').ComputedRef<boolean>|undefined} active - Whether there are active intents.
+ * @property {import('vue').ComputedRef<boolean>|undefined} resolving - Whether there are resolving intents.
  * @property {boolean} clearActiveOnResolved - Whether to clear the active state when the promise resolves.
+ * @property {RunId|null} lastRunId - The most recent run ID issued for a triggered intent. Useful for associating async results with their originating trigger.
+ * @property {import('vue').DeepReadonly<object>} watchArguments - The watch arguments.
+ * @property {import('vue').DeepReadonly<object>} guardArguments - The guard arguments.
+ */
+/**
+ * @typedef {import("vue").Reactive<
+ *     CancellableIntentRawState &
+ *     Pick<import('./error.js').ErrorStatus, 'error' | 'errored'>
+ * >} CancellableIntentState - The state of the cancellable intent.
+ */
+/**
+ * @typedef {() => boolean} IsCurrentRunFn - A function that checks if the current run ID matches the last run ID.
+ */
+/**
+ * The common run tracking arguments.
+ *
+ * @typedef {object} CommonRunTracking
+ * @property {RunId} runId - The unique identifier for your run.
+ * @property {IsCurrentRunFn} isCurrentRun - A function that checks if the current run ID matches your run ID.
  */
 /**
- * @typedef {import("vue").UnwrapNestedRefs<CancellableIntentRawState>} CancellableIntentState - The state of the cancellable intent.
+ * @typedef {(runTracking: CommonRunTracking) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} AwaitableWithCancel - A function that returns a promise that can be cancelled.
+ */
+/**
+ * @typedef {import("vue").UnwrapNestedRefs<object>|{[key: string]: import('vue').Ref<any>}} WatchGuardArguments - The reactive object to watch for changes.
  */
 /**
  * @typedef {object} CancellableIntentOptions - The options for the cancellable intent.
- * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} awaitableWithCancel - The function that returns a promise that can be cancelled.
- * @property {import("vue").UnwrapNestedRefs<object>} [watchArguments={}] - The reactive object to watch for changes.
- * @property {import("vue").UnwrapNestedRefs<object>} [guardArguments={}] - The reactive object to watch for truthiness before running the intent.
+ * @property {AwaitableWithCancel} awaitableWithCancel - The function that returns a promise that can be cancelled. Receives the run ID as an argument.
+ * @property {WatchGuardArguments} [watchArguments={}] - The reactive object to watch for changes.
+ * @property {WatchGuardArguments} [guardArguments={}] - The reactive object to watch for truthiness before running the intent.
  * @property {boolean} [clearActiveOnResolved=true] - Whether to clear the active state when the promise resolves.
  */
 /**
- * @typedef {object} CancellableIntent - The instance of the cancellable intent.
+ * Cancel function signature for cancellable intent.
+ *
+ * @typedef {Function} CancelFn
+ * @param {any} reason - The reason for cancellation.
+ * @param {boolean} [forceClearActive=false] - Whether to force clear the active state.
+ * @returns {Promise<void>} - A promise that resolves when the cancellation is complete.
+ */
+/**
+ * @typedef {object} MyCancellableIntent - The instance of the cancellable intent.
  * @property {CancellableIntentState} state - The state of the cancellable intent.
- * @property {import('vue').UnwrapNestedRefs<object>} watchArguments - The watch arguments.
- * @property {import('vue').UnwrapNestedRefs<object>} guardArguments - The guard arguments.
- * @property {Function} stop - Stop the cancellable intent.
- * @property {Function} cancel - Cancel the cancellable intent.
+ * @property {() => void} stop - Stop the cancellable intent.
+ * @property {CancelFn} cancel - Cancel the cancellable intent.
+ */
+/**
+ * @typedef {MyCancellableIntent & Pick<import('./error.js').ErrorStatus, "clearError">} CancellableIntent - The instance of the cancellable intent.
  */
 /**
  * Calls your awaitable function with the arguments you pass in when the watch arguments change and are all truthy.
@@ -69,86 +98,130 @@
  */
 export function useCancellableIntent({ awaitableWithCancel, watchArguments, guardArguments, clearActiveOnResolved, }: CancellableIntentOptions): CancellableIntent;
 /**
- * - The raw state of the cancellable intent.
+ * @module use/cancellableIntent.js - A composable function for handling cancellable intents.
  */
-export type CancellableIntentRawState = {
+/**
+ * Custom error class for list subscription errors.
+ */
+export class CancellableIntentError extends Error {
     /**
-     * - The number of active intents.
+     * Creates a new CancellableIntentError.
+     *
+     * @param {string} message - The error message.
+     * @param {string} code - The error code.
      */
-    activeCount: number | undefined;
+    constructor(message: string, code: string);
+    code: string;
+}
+/**
+ * - A unique identifier for a single execution ("run") of an intent.
+ * This is incremented each time `watchArguments` change and the intent re-triggers.
+ * Enables distinguishing results or effects from overlapping async runs.
+ */
+export type RunId = number;
+/**
+ * - The raw state of the cancellable intent.
+ */
+export type CancellableIntentRawState = {
     /**
      * - Whether there are active intents.
      */
-    active: boolean | undefined;
+    active: import("vue").ComputedRef<boolean> | undefined;
     /**
-     * - The number of resolving intents.
+     * - Whether there are resolving intents.
      */
-    resolvingCount: number | undefined;
+    resolving: import("vue").ComputedRef<boolean> | undefined;
     /**
-     * - Whether there are resolving intents.
+     * - Whether to clear the active state when the promise resolves.
      */
-    resolving: boolean | undefined;
+    clearActiveOnResolved: boolean;
     /**
-     * - Whether there was an error.
+     * - The most recent run ID issued for a triggered intent. Useful for associating async results with their originating trigger.
      */
-    errored: boolean;
+    lastRunId: RunId | null;
     /**
-     * - The error that occurred.
+     * - The watch arguments.
      */
-    error: Error | null;
+    watchArguments: import("vue").DeepReadonly<object>;
     /**
-     * - Whether to clear the active state when the promise resolves.
+     * - The guard arguments.
      */
-    clearActiveOnResolved: boolean;
+    guardArguments: import("vue").DeepReadonly<object>;
 };
 /**
  * - The state of the cancellable intent.
  */
-export type CancellableIntentState = import("vue").UnwrapNestedRefs<CancellableIntentRawState>;
+export type CancellableIntentState = import("vue").Reactive<CancellableIntentRawState & Pick<import("./error.js").ErrorStatus, "error" | "errored">>;
+/**
+ * - A function that checks if the current run ID matches the last run ID.
+ */
+export type IsCurrentRunFn = () => boolean;
+/**
+ * The common run tracking arguments.
+ */
+export type CommonRunTracking = {
+    /**
+     * - The unique identifier for your run.
+     */
+    runId: RunId;
+    /**
+     * - A function that checks if the current run ID matches your run ID.
+     */
+    isCurrentRun: IsCurrentRunFn;
+};
+/**
+ * - A function that returns a promise that can be cancelled.
+ */
+export type AwaitableWithCancel = (runTracking: CommonRunTracking) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<void>;
+/**
+ * - The reactive object to watch for changes.
+ */
+export type WatchGuardArguments = import("vue").UnwrapNestedRefs<object> | {
+    [key: string]: import("vue").Ref<any>;
+};
 /**
  * - The options for the cancellable intent.
  */
 export type CancellableIntentOptions = {
     /**
-     * - The function that returns a promise that can be cancelled.
+     * - The function that returns a promise that can be cancelled. Receives the run ID as an argument.
      */
-    awaitableWithCancel: () => import("../utils/cancellablePromise.js").MaybeCancellablePromise<void>;
+    awaitableWithCancel: AwaitableWithCancel;
     /**
      * - The reactive object to watch for changes.
      */
-    watchArguments?: import("vue").UnwrapNestedRefs<object>;
+    watchArguments?: WatchGuardArguments;
     /**
      * - The reactive object to watch for truthiness before running the intent.
      */
-    guardArguments?: import("vue").UnwrapNestedRefs<object>;
+    guardArguments?: WatchGuardArguments;
     /**
      * - Whether to clear the active state when the promise resolves.
      */
     clearActiveOnResolved?: boolean;
 };
+/**
+ * Cancel function signature for cancellable intent.
+ */
+export type CancelFn = Function;
 /**
  * - The instance of the cancellable intent.
  */
-export type CancellableIntent = {
+export type MyCancellableIntent = {
     /**
      * - The state of the cancellable intent.
      */
     state: CancellableIntentState;
-    /**
-     * - The watch arguments.
-     */
-    watchArguments: import("vue").UnwrapNestedRefs<object>;
-    /**
-     * - The guard arguments.
-     */
-    guardArguments: import("vue").UnwrapNestedRefs<object>;
     /**
      * - Stop the cancellable intent.
      */
-    stop: Function;
+    stop: () => void;
     /**
      * - Cancel the cancellable intent.
      */
-    cancel: Function;
+    cancel: CancelFn;
 };
-//# sourceMappingURL=cancellableIntent.d.ts.map
+/**
+ * - The instance of the cancellable intent.
+ */
+export type CancellableIntent = MyCancellableIntent & Pick<import("./error.js").ErrorStatus, "clearError">;

package/types/use/combineClasses.d.ts

@@ -40,4 +40,3 @@ export function useCombineClasses(...classes: (CSSClasses)[]): import("vue").Ref
 export type CSSClasses = (string | string[] | {
     [key: string]: boolean | import("vue").Ref<boolean>;
 } | import("vue").Ref<string | string[]>);
-//# sourceMappingURL=combineClasses.d.ts.map

package/types/use/error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @typedef {() => void} ClearErrorFn
+ * @typedef {import("vue").Ref<Error|null>} ErrorRef
+ * @typedef {import("vue").Ref<boolean>} ErroredRef
+ * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef
+ * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef
+ */
+/**
+ * The error state API.
+ *
+ * @typedef {object} ErrorStatus
+ * @property {ErrorReadonlyRef} error - The error that occurred.
+ * @property {ErroredReadonlyRef} errored - Whether an error has occurred.
+ * @property {(error: Error) => void} setError - Set the error state.
+ * @property {ClearErrorFn} clearError - Clear the error state.
+ */
+/**
+ * A composable function for managing error state.
+ *
+ * @returns {ErrorStatus} - An object containing reactive fields and actions for error state.
+ */
+export function useError(): ErrorStatus;
+export type ClearErrorFn = () => void;
+export type ErrorRef = import("vue").Ref<Error | null>;
+export type ErroredRef = import("vue").Ref<boolean>;
+export type ErrorReadonlyRef = Readonly<ErrorRef>;
+export type ErroredReadonlyRef = Readonly<ErroredRef>;
+/**
+ * The error state API.
+ */
+export type ErrorStatus = {
+    /**
+     * - The error that occurred.
+     */
+    error: ErrorReadonlyRef;
+    /**
+     * - Whether an error has occurred.
+     */
+    errored: ErroredReadonlyRef;
+    /**
+     * - Set the error state.
+     */
+    setError: (error: Error) => void;
+    /**
+     * - Clear the error state.
+     */
+    clearError: ClearErrorFn;
+};

package/types/use/list.d.ts

@@ -24,7 +24,7 @@ export function useLists(listOptions: {
 }): {
     [key: string]: ListManager;
 };
-export function useList({ props, handlers, paged, keepOldPages, clearListOnListIntentTriggered, searchThrottle, sortThrottleWait, searchShowAllWhenEmpty, }: ListOptions): ListManager;
+export function useList({ props, handlers, searchThrottle, sortThrottleWait, searchShowAllWhenEmpty }: ListOptions): ListManager;
 /**
  * Defines properties for configuring the list management system.
  */
@@ -94,47 +94,25 @@ export type ListOptions = {
     /**
      * - Additional handlers to be included in the list manager.
      */
-    handlers: import("../config/listCrud.js").ListCrudHandlers;
-    /**
-     * - Indicates whether the list should be paginated.
-     */
-    paged: boolean;
-    /**
-     * - Indicates whether old pages should be kept when paginating.
-     */
-    keepOldPages: import("vue").Ref<boolean> | boolean;
-    /**
-     * - Indicates whether the list should be cleared when the list intent is triggered.
-     */
-    clearListOnListIntentTriggered: boolean;
+    handlers?: import("../config/listCrud.js").ListCrudHandlers;
     /**
      * - The throttle time for text search.
      */
-    searchThrottle: number;
+    searchThrottle?: number;
     /**
      * - The throttle time for sorting.
      */
-    sortThrottleWait: number;
+    sortThrottleWait?: number;
     /**
      * - Indicates whether all items should be shown when the search query is empty.
      */
-    searchShowAllWhenEmpty: boolean;
+    searchShowAllWhenEmpty?: boolean;
 };
-/**
- * Represents the combined state definitions for all list-related components.
- * This interface aggregates the raw state from multiple list management functionalities.
- */
-export type ListRawState = ((import("./listInstance.js").ListInstanceRawState | import("./paginatedListInstance.js").PagedListInstanceRawState) & import("./listSubscription.js").ListSubscriptionRawState & import("./listRelated.js").ListRelatedRawState & import("./listCalculated.js").ListCalculatedRawState & import("./listFilter.js").ListFilterRawState & import("./listSearch.js").ListSearchRawState & import("./listSort.js").ListSortRawState);
-/**
- * Represents the reactive state derived from aggregating states of various list-related components.
- * This state is typically used within Vue components for reactivity and access to updated list properties.
- */
-export type ListState = import("vue").UnwrapNestedRefs<ListRawState>;
 /**
  * Holds references to instances of all list-related composables, facilitating direct access and management.
  */
 export type ListManaged = {
-    listInstance: import("./listInstance.js").ListInstance | import("./paginatedListInstance.js").PagedListInstance;
+    listInstance: import("./listInstance.js").ListInstance;
     listSubscription: import("./listSubscription.js").ListSubscription;
     listRelated: import("./listRelated.js").ListRelated;
     listCalculated: import("./listCalculated.js").ListCalculated;
@@ -158,15 +136,14 @@ export type ListManagerProperties = {
     /**
      * - Represents the final reactive state in the list processing chain.
      */
-    state: ListState;
+    state: import("./listSort.js").ListSortState;
     /**
-     * - Encapsulates all reactive effects related to the list hooks.
+     * - A function to stop the effect scope and clean up resources.
      */
-    effectScope: import("vue").EffectScope;
+    stop: () => void;
 };
 /**
  * Combines functionality and properties to represent a fully managed list instance,
  * orchestrating various functionalities such as sorting, searching, filtering, and state management.
  */
 export type ListManager = ListFunctions & ListManagerProperties;
-//# sourceMappingURL=list.d.ts.map