@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

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

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

package/types/use/cancellableIntent.d.ts

@@ -22,9 +22,7 @@
  * @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
+ * @typedef {object} CommonRunTracking - The common run tracking arguments.
  * @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.
  */
@@ -42,9 +40,7 @@
  * @property {boolean} [clearActiveOnResolved=true] - Whether to clear the active state when the promise resolves.
  */
 /**
- * Cancel function signature for cancellable intent.
- *
- * @typedef {Function} CancelFn
+ * @typedef {Function} CancelFn - Cancel function signature for cancellable intent.
  * @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.
@@ -61,12 +57,19 @@
 /**
  * Calls your awaitable function with the arguments you pass in when the watch arguments change and are all truthy.
  * Watch arguments should be a reactive object.
- * If the promise is not resolved before the watch arguments change again, the previous promise is cancelled.
+ *
+ * If the watch arguments change again before the promise resolves, the in-flight promise is cancelled only when it
+ * carries a `cancel` method (a `MaybeCancellablePromise`); a plain promise is left to run to completion. That
+ * distinction is visible through the composables built on this one. `useObjectSubscription` calls
+ * `objectInstance.retrieve()` again for the new key, and that call returns the promise already in flight for the
+ * previous key, so the stale record is assigned and the new key is never fetched. `useListSubscription` guards its
+ * list intent on the list's own loading state, so the superseded run is left to finish and the list is then listed
+ * again with the current arguments.
  *
  * @example
  * ```vue
  * <script setup>
- * import { useCancellableIntent } from "@vueda/use/cancellableIntent.js";
+ * import { useCancellableIntent } from "@arrai-innovations/reactive-helpers";
  * import { ref, computed, onMounted, onUnmounted } from "vue";
  *
  * const myValue = ref(0);
@@ -114,50 +117,50 @@ export class CancellableIntentError extends Error {
     code: string;
 }
 /**
- * - A unique identifier for a single execution ("run") of an intent.
+ * 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.
+ * The raw state of the cancellable intent.
  */
 export type CancellableIntentMyState = {
     /**
-     * - Whether there are active intents.
+     * Whether there are active intents.
      */
     active: import("vue").ComputedRef<boolean> | undefined;
     /**
-     * - Whether there are resolving intents.
+     * Whether there are resolving intents.
      */
     resolving: import("vue").ComputedRef<boolean> | undefined;
     /**
-     * - Whether to clear the active state when the promise resolves.
+     * Whether to clear the active state when the promise resolves.
      */
     clearActiveOnResolved: boolean;
     /**
-     * - The most recent run ID issued for a triggered intent. Useful for associating async results with their originating trigger.
+     * The most recent run ID issued for a triggered intent. Useful for associating async results with their originating trigger.
      */
     lastRunId: RunId | null;
     /**
-     * - The watch arguments.
+     * The watch arguments.
      */
     watchArguments: import("vue").DeepReadonly<object>;
     /**
-     * - The guard arguments.
+     * The guard arguments.
      */
     guardArguments: import("vue").DeepReadonly<object>;
 };
 /**
- * - The raw state of the cancellable intent.
+ * The raw state of the cancellable intent.
  */
 export type CancellableIntentRawState = CancellableIntentMyState & import("./error.js").ErrorProperties;
 /**
- * - The state of the cancellable intent.
+ * The state of the cancellable intent.
  */
 export type CancellableIntentState = import("vue").Reactive<CancellableIntentRawState>;
 /**
- * - A function that checks if the current run ID matches the last run ID.
+ * A function that checks if the current run ID matches the last run ID.
  */
 export type IsCurrentRunFn = () => boolean;
 /**
@@ -165,42 +168,42 @@ export type IsCurrentRunFn = () => boolean;
  */
 export type CommonRunTracking = {
     /**
-     * - The unique identifier for your run.
+     * The unique identifier for your run.
      */
     runId: RunId;
     /**
-     * - A function that checks if the current run ID matches your run ID.
+     * 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. The return value of the promise is not used.
+ * A function that returns a promise that can be cancelled. The return value of the promise is not used.
  */
 export type AwaitableWithCancel = (runTracking: CommonRunTracking) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<unknown>;
 /**
- * - The reactive object to watch for changes.
+ * 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.
+ * The options for the cancellable intent.
  */
 export type CancellableIntentOptions = {
     /**
-     * - The function that returns a promise that can be cancelled. Receives the run ID as an argument.
+     * The function that returns a promise that can be cancelled. Receives the run ID as an argument.
      */
     awaitableWithCancel: AwaitableWithCancel;
     /**
-     * - The reactive object to watch for changes.
+     * The reactive object to watch for changes.
      */
     watchArguments?: WatchGuardArguments;
     /**
-     * - The reactive object to watch for truthiness before running the intent.
+     * The reactive object to watch for truthiness before running the intent.
      */
     guardArguments?: WatchGuardArguments;
     /**
-     * - Whether to clear the active state when the promise resolves.
+     * Whether to clear the active state when the promise resolves.
      */
     clearActiveOnResolved?: boolean;
 };
@@ -209,23 +212,23 @@ export type CancellableIntentOptions = {
  */
 export type CancelFn = Function;
 /**
- * - The instance of the cancellable intent.
+ * The instance of the cancellable intent.
  */
 export type MyCancellableIntent = {
     /**
-     * - The state of the cancellable intent.
+     * The state of the cancellable intent.
      */
     state: CancellableIntentState;
     /**
-     * - Stop the cancellable intent.
+     * Stop the cancellable intent.
      */
     stop: () => void;
     /**
-     * - Cancel the cancellable intent.
+     * Cancel the cancellable intent.
      */
     cancel: CancelFn;
 };
 /**
- * - The instance of the cancellable intent.
+ * The instance of the cancellable intent.
  */
 export type CancellableIntent = MyCancellableIntent & import("./error.js").ErrorReadOnlyFunctions;

package/types/use/combineClasses.d.ts

@@ -4,7 +4,7 @@
  *     string[] |
  *     { [key: string]: boolean | import("vue").Ref<boolean> } |
  *     import("vue").Ref<string | string[]>
- * )} CSSClasses
+ * )} CSSClasses - The accepted ways of specifying CSS classes to useCombineClasses (a string, array, class-map, or ref thereof).
  */
 /**
  * Normalize various ways of specifying CSS classes into an object for use in Vue.js with reactivity. If refs are
@@ -14,7 +14,7 @@
  * @example
  * ```vue
  * <script setup>
- * import { useCombineClasses } from "@vueda/use/combineClasses.js";
+ * import { useCombineClasses } from "@arrai-innovations/reactive-helpers";
  * import { ref } from "vue";
  * const myClasses = useCombineClasses(
  *     "class1",
@@ -37,6 +37,9 @@
  *  preserve order of operations in reactive contexts.
  */
 export function useCombineClasses(...classes: (CSSClasses)[]): import("vue").Ref<import("../utils/classes.js").CombinedClasses>;
+/**
+ * The accepted ways of specifying CSS classes to useCombineClasses (a string, array, class-map, or ref thereof).
+ */
 export type CSSClasses = (string | string[] | {
     [key: string]: boolean | import("vue").Ref<boolean>;
 } | import("vue").Ref<string | string[]>);

package/types/use/error.d.ts

@@ -1,33 +1,29 @@
 /**
- * @typedef {() => void} ClearErrorFn
- * @typedef {import("vue").Ref<Error|null>} ErrorRef
- * @typedef {import("vue").Ref<boolean>} ErroredRef
- * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef
- * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef
+ * @typedef {() => void} ClearErrorFn - Signature for the function that clears the current error state.
+ * @typedef {import("vue").Ref<Error|null>} ErrorRef - A Vue ref holding the current error, or null when there is none.
+ * @typedef {import("vue").Ref<boolean>} ErroredRef - A Vue ref to the boolean indicating whether an error has occurred.
+ * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef - A readonly Vue ref holding the current error, or null when there is none.
+ * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef - A readonly Vue ref to the boolean indicating whether an error has occurred.
  */
 /**
- * @typedef {object} ErrorProperties
+ * @typedef {object} ErrorProperties - The reactive error-state members (error and errored) contributed by the useError composable.
  * @property {ErrorReadonlyRef} error - The error that occurred.
  * @property {ErroredReadonlyRef} errored - Whether an error has occurred.
  */
 /**
- * @typedef {object} ErrorFunctions
+ * @typedef {object} ErrorFunctions - The error-state actions (setError, clearError) contributed by the useError composable.
  * @property {(error: Error) => void} setError - Set the error state.
  * @property {ClearErrorFn} clearError - Clear the error state.
  */
 /**
- * Proxies can still clear errors but cannot set them directly.
- *
- * @typedef {object} ErrorReadOnlyFunctions
+ * @typedef {object} ErrorReadOnlyFunctions - Proxies can still clear errors but cannot set them directly.
  * @property {ClearErrorFn} clearError - Clear the error state.
  */
 /**
- * @typedef {ErrorProperties & ErrorReadOnlyFunctions} ReadonlyErrorStatus
+ * @typedef {ErrorProperties & ErrorReadOnlyFunctions} ReadonlyErrorStatus - The readonly error-state API (error and errored plus clearError) exposed to consumers and proxies.
  */
 /**
- * The error state API.
- *
- * @typedef {ErrorProperties & ErrorFunctions} ErrorStatus
+ * @typedef {ErrorProperties & ErrorFunctions} ErrorStatus - The error state API.
  */
 /**
  * A composable function for managing error state.
@@ -35,28 +31,49 @@
  * @returns {ErrorStatus} - An object containing reactive fields and actions for error state.
  */
 export function useError(): ErrorStatus;
+/**
+ * Signature for the function that clears the current error state.
+ */
 export type ClearErrorFn = () => void;
+/**
+ * A Vue ref holding the current error, or null when there is none.
+ */
 export type ErrorRef = import("vue").Ref<Error | null>;
+/**
+ * A Vue ref to the boolean indicating whether an error has occurred.
+ */
 export type ErroredRef = import("vue").Ref<boolean>;
+/**
+ * A readonly Vue ref holding the current error, or null when there is none.
+ */
 export type ErrorReadonlyRef = Readonly<ErrorRef>;
+/**
+ * A readonly Vue ref to the boolean indicating whether an error has occurred.
+ */
 export type ErroredReadonlyRef = Readonly<ErroredRef>;
+/**
+ * The reactive error-state members (error and errored) contributed by the useError composable.
+ */
 export type ErrorProperties = {
     /**
-     * - The error that occurred.
+     * The error that occurred.
      */
     error: ErrorReadonlyRef;
     /**
-     * - Whether an error has occurred.
+     * Whether an error has occurred.
      */
     errored: ErroredReadonlyRef;
 };
+/**
+ * The error-state actions (setError, clearError) contributed by the useError composable.
+ */
 export type ErrorFunctions = {
     /**
-     * - Set the error state.
+     * Set the error state.
      */
     setError: (error: Error) => void;
     /**
-     * - Clear the error state.
+     * Clear the error state.
      */
     clearError: ClearErrorFn;
 };
@@ -65,10 +82,13 @@ export type ErrorFunctions = {
  */
 export type ErrorReadOnlyFunctions = {
     /**
-     * - Clear the error state.
+     * Clear the error state.
      */
     clearError: ClearErrorFn;
 };
+/**
+ * The readonly error-state API (error and errored plus clearError) exposed to consumers and proxies.
+ */
 export type ReadonlyErrorStatus = ErrorProperties & ErrorReadOnlyFunctions;
 /**
  * The error state API.

package/types/use/list.d.ts

@@ -30,81 +30,84 @@ export function useList({ props, handlers, searchThrottle, sortThrottleWait, sea
  */
 export type ListRawProps = {
     /**
-     * - The arguments to pass to the registered list crud handlers, related to the list itself.
+     * The arguments to pass to the registered list crud handlers, related to the list itself.
      */
     params: object;
     /**
-     * - The primary key for the list items.
+     * The primary key for the list items.
      */
     pkKey: string;
     /**
-     * - General arguments to pass to the registered list crud handlers, often related to endpoints.
+     * General arguments to pass to the registered list crud handlers, often related to endpoints.
      */
     target: object;
     /**
-     * - Indicates whether the list should be fetched immediately.
+     * Indicates whether the list should be fetched immediately.
      */
     intendToList: boolean;
     /**
-     * - Indicates whether changes to the list should be subscribed to.
+     * Indicates whether changes to the list should be subscribed to.
      */
     intendToSubscribe: boolean;
     /**
-     * - Defines rules for associating related objects with list items.
+     * Defines rules for associating related objects with list items.
      */
     relatedObjectsRules: import("./listRelated.js").ListRelatedRules;
     /**
-     * - Defines rules for dynamically calculating properties of list items.
+     * Defines rules for dynamically calculating properties of list items.
      */
     calculatedObjectsRules: import("./listCalculated.js").ListCalculatedRules;
     /**
-     * - Function or rule to determine if an item should be included based on inclusion criteria.
+     * Function or rule to determine if an item should be included based on inclusion criteria.
      */
     allowedFilter: import("./listFilter.js").ListFilterAllowedFilter;
     /**
-     * - Function or rule to determine if an item should be excluded based on exclusion criteria.
+     * Function or rule to determine if an item should be excluded based on exclusion criteria.
      */
     excludedFilter: import("./listFilter.js").ListFilterExcludedFilter;
     /**
-     * - Defines the properties and conditions used to filter the list via text search.
+     * Defines the properties and conditions used to filter the list via text search.
      */
     textSearchRules: import("./listSearch.js").TextSearchRules;
     /**
-     * - Current text query used for filtering the list.
+     * Current text query used for filtering the list.
      */
     textSearchValue: string;
     /**
-     * - FlexSearch document configuration options for advanced searching capabilities.
+     * FlexSearch document configuration options for advanced searching capabilities.
      */
     customDocumentOptions: object;
     /**
-     * - Additional search options for FlexSearch.
+     * Additional search options for FlexSearch.
      */
     customSearchOptions: object;
     /**
-     * - Sorting rules that define the order of list items.
+     * Sorting rules that define the order of list items.
      */
     orderByRules: import("./listSort.js").OrderByRule[];
 };
+/**
+ * The configuration options used to create a fully managed list via useList.
+ */
 export type ListOptions = {
     /**
-     * - The properties for configuring the list.
+     * The properties for configuring the list.
      */
     props: ListRawProps;
     /**
-     * - Additional handlers to be included in the list manager.
+     * Additional handlers to be included in the list manager.
      */
     handlers?: import("../config/listCrud.js").ListCrudHandlers;
     /**
-     * - The throttle time for text search.
+     * The throttle time for text search.
      */
     searchThrottle?: number;
     /**
-     * - The throttle time for sorting.
+     * The throttle time for sorting.
      */
     sortThrottleWait?: number;
     /**
-     * - Indicates whether all items should be shown when the search query is empty.
+     * Indicates whether all items should be shown when the search query is empty.
      */
     searchShowAllWhenEmpty?: boolean;
 };
@@ -125,25 +128,23 @@ export type ListManaged = {
  */
 export type ListFunctions = (import("./listInstance.js").ListInstanceFunctions & import("./listSubscription.js").ListSubscriptionFunctions);
 /**
- * Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks,
- * and scoped effects.
+ * Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks, and scoped effects.
  */
 export type ListManagerProperties = {
     /**
-     * - A readonly reference to the managed list hooks.
+     * A readonly reference to the managed list hooks.
      */
     managed: ListManaged;
     /**
-     * - Represents the final reactive state in the list processing chain.
+     * Represents the final reactive state in the list processing chain.
      */
     state: import("./listSort.js").ListSortState;
     /**
-     * - A function to stop the effect scope and clean up resources.
+     * A function to stop the effect scope and clean up resources.
      */
     stop: () => void;
 };
 /**
- * Combines functionality and properties to represent a fully managed list instance,
- * orchestrating various functionalities such as sorting, searching, filtering, and state management.
+ * 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;