@arrai-innovations/reactive-helpers 21.1.2 → 22.0.0

package/types/config/objectCrud.d.ts

@@ -9,6 +9,9 @@ export function getObjectCrud(target: import("vue").UnwrapNestedRefs<ObjectTarge
     props?: import("vue").UnwrapNestedRefs<ObjectTargetOption>;
     handlers?: ObjectCrudHandlers;
 }): void;
+/**
+ * Implementation-specific arguments passed through to the CRUD handlers, such as endpoint identifiers.
+ */
 export type TargetArgs = {
     [key: string]: any;
 };
@@ -23,230 +26,306 @@ export type AdditionalCrudArgs = {
  */
 export type ObjectTargetProperties = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     args: TargetArgs;
 };
+/**
+ * Optional target arguments passed through to the object CRUD handlers.
+ */
 export type ObjectTargetOption = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target?: TargetArgs;
 };
+/**
+ * Raw arguments for an object create operation before additional CRUD arguments are merged in.
+ */
 export type CreateArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: TargetArgs;
     /**
-     * - The data to be acted upon.
+     * The data to be acted upon.
      */
     object: {
         [key: string]: any;
     };
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A ref to indicate if the request was cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for an object create operation, combining the raw arguments with any additional CRUD arguments.
+ */
 export type CreateArgs = CreateArgsRaw & AdditionalCrudArgs;
+/**
+ * Raw arguments for an object retrieve operation before run-tracking and additional CRUD arguments are merged in.
+ */
 export type RetrieveArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: TargetArgs;
     /**
-     * - The pk of the object to be acted upon.
+     * The pk of the object to be acted upon.
      */
     pk: import("./commonCrud.js").Pk;
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A ref to indicate if the request was cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for an object retrieve operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
+ */
 export type RetrieveArgs = RetrieveArgsRaw & Partial<import("../use/cancellableIntent.js").CommonRunTracking> & AdditionalCrudArgs;
+/**
+ * Raw arguments for an object update operation before additional CRUD arguments are merged in.
+ */
 export type UpdateArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: TargetArgs;
     /**
-     * - The data to be acted upon.
+     * The data to be acted upon.
      */
     object: import("../use/objectInstance.js").ExistingCrudObject;
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A ref to indicate if the request was cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for an object update operation, combining the raw arguments with any additional CRUD arguments.
+ */
 export type UpdateArgs = UpdateArgsRaw & AdditionalCrudArgs;
+/**
+ * Raw arguments for an object delete operation before additional CRUD arguments are merged in.
+ */
 export type DeleteArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: TargetArgs;
     /**
-     * - The pk of the object to be acted upon.
+     * The pk of the object to be acted upon.
      */
     pk: import("./commonCrud.js").Pk;
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
+    /**
+     * A ref to indicate if the request was cancelled.
+     */
+    isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for an object delete operation, combining the raw arguments with any additional CRUD arguments.
+ */
 export type DeleteArgs = DeleteArgsRaw & AdditionalCrudArgs;
+/**
+ * Raw arguments for an object patch (partial update) operation before additional CRUD arguments are merged in.
+ */
 export type PartialArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: TargetArgs;
     /**
-     * - The pk of the object to be acted upon.
+     * The pk of the object to be acted upon.
      */
     pk: import("./commonCrud.js").Pk;
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - The data to be acted upon.
+     * The data to be acted upon.
      */
     partialObject: {
         [key: string]: any;
     };
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A ref to indicate if the request was cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for an object patch (partial update) operation, combining the raw arguments with any additional CRUD arguments.
+ */
 export type PartialArgs = PartialArgsRaw & AdditionalCrudArgs;
+/**
+ * Raw arguments for a single-object execute-action operation before additional CRUD arguments are merged in.
+ */
 export type ObjectExecuteActionArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: import("../config/objectCrud.js").TargetArgs;
     /**
-     * - The id of the objects to be acted upon.
+     * The id of the objects to be acted upon.
      */
     pk: string;
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - The action to execute.
+     * The action to execute.
      */
     action: string;
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A ref to indicate if the request was cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for a single-object execute-action operation, combining the raw arguments with any additional CRUD arguments.
+ */
 export type ObjectExecuteActionArgs = ObjectExecuteActionArgsRaw & AdditionalCrudArgs;
+/**
+ * Callback invoked with the changed object and the action (create, update, or delete) when a subscribed object changes.
+ */
 export type CrudSubscribeCallback = (data: import("../use/objectInstance.js").ExistingCrudObject, action: "delete" | "update" | "create") => any;
+/**
+ * Raw arguments for a single-object subscribe operation before run-tracking and additional CRUD arguments are merged in.
+ */
 export type ObjectSubscribeArgsRaw = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: TargetArgs;
     /**
-     * - The pk of the object to be acted upon.
+     * The pk of the object to be acted upon.
      */
     pk: import("./commonCrud.js").Pk;
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - The callback to be called when the object is updated.
+     * The callback to be called when the object is updated.
      */
     callback: CrudSubscribeCallback;
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A ref to indicate if the request was cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for a single-object subscribe operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
+ */
 export type ObjectSubscribeArgs = ObjectSubscribeArgsRaw & import("../use/cancellableIntent.js").CommonRunTracking & AdditionalCrudArgs;
+/**
+ * The value returned by an object CRUD handler, a possibly-cancellable promise resolving to an object or string.
+ */
 export type CrudResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string>;
+/**
+ * Signature for the handler that creates an object in the backing store.
+ */
 export type CrudCreateFn = (args: CreateArgs) => CrudResponse;
+/**
+ * Signature for the handler that retrieves an object from the backing store.
+ */
 export type CrudRetrieveFn = (args: RetrieveArgs) => CrudResponse;
+/**
+ * Signature for the handler that updates an object in the backing store.
+ */
 export type CrudUpdateFn = (args: UpdateArgs) => CrudResponse;
+/**
+ * Signature for the handler that partially updates (patches) an object in the backing store.
+ */
 export type CrudPatchFn = (args: PartialArgs) => CrudResponse;
+/**
+ * Signature for the handler that deletes an object from the backing store.
+ */
 export type CrudDeleteFn = (args: DeleteArgs) => CrudResponse;
+/**
+ * Signature for the handler that executes an action on a single object in the backing store.
+ */
 export type CrudObjectExecuteActionFn = (args: ObjectExecuteActionArgs) => CrudResponse;
+/**
+ * Signature for the handler that subscribes to changes on a single object in the backing store.
+ */
 export type CrudObjectSubscribeFn = (args: ObjectSubscribeArgs) => import("../utils/cancellablePromise.js").CancellablePromise<void>;
 /**
  * Defines the CRUD-related handlers and additional utilities provided by the object instance.
  */
 export type ObjectCrudHandlers = {
     /**
-     * - A function to be used instead of the default crud create function.
+     * A function to be used instead of the default crud create function.
      */
     create?: CrudCreateFn;
     /**
-     * - A function to be used instead of the default crud retrieve function.
+     * A function to be used instead of the default crud retrieve function.
      */
     retrieve?: CrudRetrieveFn;
     /**
-     * - A function to be used instead of the default crud update function.
+     * A function to be used instead of the default crud update function.
      */
     update?: CrudUpdateFn;
     /**
-     * - A function to be used instead of the default crud delete function.
+     * A function to be used instead of the default crud delete function.
      */
     delete?: CrudDeleteFn;
     /**
-     * - A function to be used instead of the default crud patch function.
+     * A function to be used instead of the default crud patch function.
      */
     patch?: CrudPatchFn;
     /**
-     * - A function to be used instead of the default crud subscribe function.
+     * A function to be used instead of the default crud subscribe function.
      */
     subscribe?: CrudObjectSubscribeFn;
     /**
-     * - The  function to execute a certain action on an object.
+     * The  function to execute a certain action on an object.
      */
     executeAction?: CrudObjectExecuteActionFn;
 };

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.
@@ -114,50 +110,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 +161,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 +205,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
@@ -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.