@arrai-innovations/reactive-helpers 21.1.2 → 22.0.0

package/types/use/loadingError.d.ts

@@ -1,7 +1,7 @@
 /**
- * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ErrorProperties} LoadingErrorProperties
- * @typedef {import('./loading.js').LoadingFunctions & import('./error.js').ErrorFunctions} LoadingErrorFunctions
- * @typedef {LoadingErrorProperties & LoadingErrorFunctions} LoadingErrorStatus
+ * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ErrorProperties} LoadingErrorProperties - The combined reactive loading and error state members contributed by the useLoadingError composable.
+ * @typedef {import('./loading.js').LoadingFunctions & import('./error.js').ErrorFunctions} LoadingErrorFunctions - The combined loading and error state actions contributed by the useLoadingError composable.
+ * @typedef {LoadingErrorProperties & LoadingErrorFunctions} LoadingErrorStatus - The combined loading and error state API (properties plus actions) returned by useLoadingError.
  */
 /**
  * A composable function combining loading and error state management.
@@ -9,6 +9,15 @@
  * @returns {LoadingErrorStatus} - An object containing reactive fields and actions for both loading and error state.
  */
 export function useLoadingError(): LoadingErrorStatus;
+/**
+ * The combined reactive loading and error state members contributed by the useLoadingError composable.
+ */
 export type LoadingErrorProperties = import("./loading.js").LoadingProperties & import("./error.js").ErrorProperties;
+/**
+ * The combined loading and error state actions contributed by the useLoadingError composable.
+ */
 export type LoadingErrorFunctions = import("./loading.js").LoadingFunctions & import("./error.js").ErrorFunctions;
+/**
+ * The combined loading and error state API (properties plus actions) returned by useLoadingError.
+ */
 export type LoadingErrorStatus = LoadingErrorProperties & LoadingErrorFunctions;

package/types/use/object.d.ts

@@ -17,11 +17,11 @@ export type ObjectManagerProps = import("vue").UnwrapNestedRefs<ObjectManagerRaw
  */
 export type ObjectManagerOptions = {
     /**
-     * - The reactive properties to be passed to the object instance.
+     * The reactive properties to be passed to the object instance.
      */
     props: ObjectManagerProps;
     /**
-     * - The non-reactive handlers to be passed to the object instance.
+     * The non-reactive handlers to be passed to the object instance.
      */
     handlers: import("../config/objectCrud.js").ObjectCrudHandlers;
 };
@@ -43,16 +43,19 @@ export type ObjectManagerFunctions = (import("./objectInstance.js").ObjectInstan
  */
 export type ObjectManagerProperties = {
     /**
-     * - The managed object.
+     * The managed object.
      */
     managed: ObjectManaged;
     /**
-     * - The state of the managed object.
+     * The state of the managed object.
      */
     state: import("./objectCalculated.js").ObjectCalculatedState;
     /**
-     * - Stop the effect scope of the managed object.
+     * Stop the effect scope of the managed object.
      */
     stop: () => void;
 };
+/**
+ * The fully managed object returned by useObject, combining its properties and functions.
+ */
 export type ObjectManager = ObjectManagerProperties & ObjectManagerFunctions;

package/types/use/objectCalculated.d.ts

@@ -63,11 +63,9 @@ export function useObjectCalculated({ parentState, calculatedObjectRules }: Obje
  * @module use/objectCalculated.js
  */
 /**
- * The object calculated state keys.
- *
  * @typedef {{
  *     [ruleKey: string]: (object: any, relatedObject: any) => any
- * }} ObjectCalculatedRules
+ * }} ObjectCalculatedRules - The object calculated state keys.
  */
 /**
  * @typedef {object} ObjectCalculatedRawState - The raw state for object calculated.
@@ -87,7 +85,7 @@ export function useObjectCalculated({ parentState, calculatedObjectRules }: Obje
  *     import('./objectInstance.js').ObjectInstanceRawState &
  *     Partial<import('./objectSubscription.js').ObjectSubscriptionRawState> &
  *     Partial<import('./objectRelated.js').ObjectRelatedRawState>
- * )} ObjectCalculatedParentRawState
+ * )} ObjectCalculatedParentRawState - The raw, pre-unwrapped parent state consumed by the object calculated mixin, aggregating the upstream object composable states.
  */
 /**
  *
@@ -97,39 +95,35 @@ export function useObjectCalculated({ parentState, calculatedObjectRules }: Obje
  * )>} ObjectCalculatedParentState - The object calculated options.
  */
 /**
- * The state for object calculated.
- *
  * @typedef {import('vue').UnwrapNestedRefs<
  *   ObjectCalculatedParentRawState &
  *   ObjectCalculatedRawState
- * >} ObjectCalculatedState
+ * >} ObjectCalculatedState - The state for object calculated.
  */
 /**
- * The properties for object calculated.
- *
- * @typedef {object} ObjectCalculatedProperties
+ * @typedef {object} ObjectCalculatedProperties - The properties for object calculated.
  * @property {ObjectCalculatedParentState} parentState - The parent state.
  * @property {ObjectCalculatedState} state - The object calculated state.
  * @property {() => void} stop - Stops composition's effects and cleans up resources.
  */
 /**
- * The object calculated instance.
- *
- * @typedef {ObjectCalculatedProperties} ObjectCalculated
+ * @typedef {ObjectCalculatedProperties} ObjectCalculated - The object calculated instance.
  */
 /**
  *
  *
- * @typedef {object} ObjectCalculatedRawProps
+ * @typedef {object} ObjectCalculatedRawProps - The consumer-supplied props for the object calculated composable, namely the calculated-object rules ref.
  * @property {import('vue').Ref<ObjectCalculatedRules>} calculatedObjectRules - The calculated object rules.
  */
 /**
  *
  * @typedef {({
  *     parentState: ObjectCalculatedParentState,
- * } & ObjectCalculatedRawProps)} ObjectCalculatedOptions
+ * } & ObjectCalculatedRawProps)} ObjectCalculatedOptions - The options used to create an object calculated instance (the parent state plus the calculated-object rules).
  */
+/** @internal */
 export const objectCalculatedStateKeys: string[];
+/** @internal */
 export const objectCalculatedFunctions: any[];
 /**
  * The object calculated state keys.
@@ -138,39 +132,42 @@ export type ObjectCalculatedRules = {
     [ruleKey: string]: (object: any, relatedObject: any) => any;
 };
 /**
- * - The raw state for object calculated.
+ * The raw state for object calculated.
  */
 export type ObjectCalculatedRawState = {
     /**
-     * - The calculated object rules.
+     * The calculated object rules.
      */
     calculatedObjectRules: ObjectCalculatedRules;
     /**
-     * - The calculated object.
+     * The calculated object.
      */
     calculatedObject: {
         [ruleKey: string]: import("vue").ComputedRef<any>;
     };
     /**
-     * - Whether the calculated object watch is running.
+     * Whether the calculated object watch is running.
      */
     calculatedObjectWatchRunning: boolean;
     /**
-     * - Whether the parent state object watch is running.
+     * Whether the parent state object watch is running.
      */
     parentStateObjectWatchRunning: boolean;
     /**
-     * - Whether the calculated is running.
+     * Whether the calculated is running.
      */
     calculatedRunning: boolean;
     /**
-     * - Whether the object calculated is running.
+     * Whether the object calculated is running.
      */
     running: import("vue").Ref<boolean>;
 };
+/**
+ * The raw, pre-unwrapped parent state consumed by the object calculated mixin, aggregating the upstream object composable states.
+ */
 export type ObjectCalculatedParentRawState = (import("./objectInstance.js").ObjectInstanceRawState & Partial<import("./objectSubscription.js").ObjectSubscriptionRawState> & Partial<import("./objectRelated.js").ObjectRelatedRawState>);
 /**
- * - The object calculated options.
+ * The object calculated options.
  */
 export type ObjectCalculatedParentState = import("vue").UnwrapNestedRefs<(ObjectCalculatedParentRawState)>;
 /**
@@ -182,15 +179,15 @@ export type ObjectCalculatedState = import("vue").UnwrapNestedRefs<ObjectCalcula
  */
 export type ObjectCalculatedProperties = {
     /**
-     * - The parent state.
+     * The parent state.
      */
     parentState: ObjectCalculatedParentState;
     /**
-     * - The object calculated state.
+     * The object calculated state.
      */
     state: ObjectCalculatedState;
     /**
-     * - Stops composition's effects and cleans up resources.
+     * Stops composition's effects and cleans up resources.
      */
     stop: () => void;
 };
@@ -198,12 +195,18 @@ export type ObjectCalculatedProperties = {
  * The object calculated instance.
  */
 export type ObjectCalculated = ObjectCalculatedProperties;
+/**
+ * The consumer-supplied props for the object calculated composable, namely the calculated-object rules ref.
+ */
 export type ObjectCalculatedRawProps = {
     /**
-     * - The calculated object rules.
+     * The calculated object rules.
      */
     calculatedObjectRules: import("vue").Ref<ObjectCalculatedRules>;
 };
+/**
+ * The options used to create an object calculated instance (the parent state plus the calculated-object rules).
+ */
 export type ObjectCalculatedOptions = ({
     parentState: ObjectCalculatedParentState;
 } & ObjectCalculatedRawProps);

package/types/use/objectInstance.d.ts

@@ -68,37 +68,28 @@ export function useObjectInstance({ props, handlers }: ObjectInstanceOptions): O
  * @module use/objectInstance.js
  */
 /**
- * The object being managed by the instance. It must include a primary key field as identifying property, matching
- * the name provided to the object/list's `pkKey` value, which is not known statically.
- *
- * @typedef {{[key: string]: any}} ExistingCrudObject
+ * @typedef {{[key: string]: any}} ExistingCrudObject - The object being managed by the instance. It must include a primary key field as identifying property, matching the name provided to the object/list's `pkKey` value, which is not known statically.
  */
 /**
- * The object you would like an object instance to create for you.
- *
- * @typedef {{[key: string]: any}} NewCrudObject
+ * @typedef {{[key: string]: any}} NewCrudObject - The object you would like an object instance to create for you.
  */
 /**
- * @typedef {ExistingCrudObject|NewCrudObject} CrudObject
+ * @typedef {ExistingCrudObject|NewCrudObject} CrudObject - An object managed by an object instance, either an existing object or a new object to be created.
  */
 /**
- * Arguments to be passed to the object instance.
- *
- * @typedef {object} ObjectInstanceOptions
+ * @typedef {object} ObjectInstanceOptions - Arguments to be passed to the object instance.
  * @property {import('vue').UnwrapNestedRefs<ObjectInstanceRawProps>} props - The reactive configuration object.
  * @property {import('../config/objectCrud.js').ObjectCrudHandlers} [handlers] - An object of custom crud handlers to use instead of the defaults.
  */
 /**
- * Reactive arguments to be passed to the object instance.
- *
- * @typedef {object} ObjectInstanceRawProps
+ * @typedef {object} ObjectInstanceRawProps - Reactive arguments to be passed to the object instance.
  * @property {import('../config/commonCrud.js').PkInput} [pk] - The pk of the object, optional to support creating new objects.
  * @property {string} pkKey - The pk key of the object.
  * @property {object} params - The arguments to be passed to the retrieve function.
  * @property {import('../config/objectCrud.js').ObjectTarget} target - The arguments to be passed to the crud handlers.
  */
 /**
- * @typedef {object} ObjectInstanceRawStateCrud
+ * @typedef {object} ObjectInstanceRawStateCrud - The raw CRUD handlers and target args stored in an object instance's reactive state.
  * @property {import('vue').Reactive<import('../config/objectCrud.js').TargetArgs|{}>} args - The arguments to be passed to the crud handlers.
  * @property {import('../config/objectCrud.js').CrudCreateFn} create - The create function.
  * @property {import('../config/objectCrud.js').CrudRetrieveFn} retrieve - The retrieve function.
@@ -109,9 +100,7 @@ export function useObjectInstance({ props, handlers }: ObjectInstanceOptions): O
  * @property {import('../config/objectCrud.js').CrudObjectExecuteActionFn} executeAction - The executeAction function.
  */
 /**
- * The raw state of the object instance.
- *
- * @typedef {object} ObjectInstanceRawMyState
+ * @typedef {object} ObjectInstanceRawMyState - The raw state of the object instance.
  * @property {import('vue').Reactive<ObjectInstanceRawStateCrud>} crud - The crud handlers.
  * @property {import('vue').Ref<import('../config/commonCrud.js').Pk|undefined>} pk - The pk of the object.
  * @property {import('vue').Ref<string|undefined>} pkKey - The pk key of the object.
@@ -120,26 +109,19 @@ export function useObjectInstance({ props, handlers }: ObjectInstanceOptions): O
  * @property {boolean} deleted - Whether the object is deleted.
  */
 /**
- * The raw state of the object instance.
- *
- * @typedef {ObjectInstanceRawMyState & import('./loadingError.js').LoadingErrorProperties} ObjectInstanceRawState
+ * @typedef {ObjectInstanceRawMyState & import('./loadingError.js').LoadingErrorProperties} ObjectInstanceRawState - The raw state of the object instance.
  */
 /**
- * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors.
- * Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
- *
- * @typedef {import('vue').Reactive<ObjectInstanceRawState>} ObjectInstanceState
+ * @typedef {import('vue').Reactive<ObjectInstanceRawState>} ObjectInstanceState - Manages a reactive state of an object including its CRUD status, loading states, and any operational errors. Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
  */
-/** @typedef {{ object: NewCrudObject }} ObjectInstanceCreateArgs */
-/** @typedef {{ object: ExistingCrudObject }} ObjectInstanceUpdateArgs */
-/** @typedef {{ partialObject: ExistingCrudObject }} ObjectInstancePatchArgs */
+/** @typedef {{ object: NewCrudObject }} ObjectInstanceCreateArgs - The argument shape for an object instance's create operation, carrying the new object to create. */
+/** @typedef {{ object: ExistingCrudObject }} ObjectInstanceUpdateArgs - The argument shape for an object instance's update operation, carrying the existing object to update. */
+/** @typedef {{ partialObject: ExistingCrudObject }} ObjectInstancePatchArgs - The argument shape for an object instance's patch operation, carrying the partial object to apply. */
 /**
- * @typedef {{[key:string]: any}} AdditionalArgs
+ * @typedef {{[key:string]: any}} AdditionalArgs - Arbitrary extra arguments forwarded through to an object instance's CRUD operations.
  */
 /**
- * The functions available on the object instance.
- *
- * @typedef {object} ObjectInstanceMyFunctions
+ * @typedef {object} ObjectInstanceMyFunctions - The functions available on the object instance.
  * @property {(args: ObjectInstanceCreateArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} create - Called to turn the current object into a new object on the server.
  * @property {(args?: Partial<import('./cancellableIntent.js').CommonRunTracking> & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} retrieve - Called to retrieve the current object by pk from the server.
  * @property {(args: ObjectInstanceUpdateArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} update - Called to update the current object on the server.
@@ -149,23 +131,17 @@ export function useObjectInstance({ props, handlers }: ObjectInstanceOptions): O
  * @property {() => void} clear - Called to clear the object state.
  */
 /**
- * The functions available on the object instance, including the ability to clear LoadingError errors.
- *
  * @typedef {(
  *     import('./error.js').ErrorReadOnlyFunctions &
  *     ObjectInstanceMyFunctions
- * )} ObjectInstanceFunctions
+ * )} ObjectInstanceFunctions - The functions available on the object instance, including the ability to clear LoadingError errors.
  */
 /**
- * The properties of the object instance.
- *
- * @typedef {object} ObjectInstanceProperties
+ * @typedef {object} ObjectInstanceProperties - The properties of the object instance.
  * @property {ObjectInstanceState} state - The state of the object instance.
  */
 /**
- * The instance of the object instance.
- *
- * @typedef {ObjectInstanceFunctions & ObjectInstanceProperties} ObjectInstance
+ * @typedef {ObjectInstanceFunctions & ObjectInstanceProperties} ObjectInstance - The instance of the object instance.
  */
 /**
  * Represents an error related to CRUD operations on an object instance. This error might be thrown
@@ -181,11 +157,12 @@ export class ObjectError extends Error {
     constructor(message: string, code: string);
     code: string;
 }
+/** @internal */
 export const objectInstanceStateKeys: string[];
+/** @internal */
 export const objectInstanceFunctions: string[];
 /**
- * The object being managed by the instance. It must include a primary key field as identifying property, matching
- * the name provided to the object/list's `pkKey` value, which is not known statically.
+ * The object being managed by the instance. It must include a primary key field as identifying property, matching the name provided to the object/list's `pkKey` value, which is not known statically.
  */
 export type ExistingCrudObject = {
     [key: string]: any;
@@ -196,17 +173,20 @@ export type ExistingCrudObject = {
 export type NewCrudObject = {
     [key: string]: any;
 };
+/**
+ * An object managed by an object instance, either an existing object or a new object to be created.
+ */
 export type CrudObject = ExistingCrudObject | NewCrudObject;
 /**
  * Arguments to be passed to the object instance.
  */
 export type ObjectInstanceOptions = {
     /**
-     * - The reactive configuration object.
+     * The reactive configuration object.
      */
     props: import("vue").UnwrapNestedRefs<ObjectInstanceRawProps>;
     /**
-     * - An object of custom crud handlers to use instead of the defaults.
+     * An object of custom crud handlers to use instead of the defaults.
      */
     handlers?: import("../config/objectCrud.js").ObjectCrudHandlers;
 };
@@ -215,53 +195,56 @@ export type ObjectInstanceOptions = {
  */
 export type ObjectInstanceRawProps = {
     /**
-     * - The pk of the object, optional to support creating new objects.
+     * The pk of the object, optional to support creating new objects.
      */
     pk?: import("../config/commonCrud.js").PkInput;
     /**
-     * - The pk key of the object.
+     * The pk key of the object.
      */
     pkKey: string;
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: object;
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     target: import("../config/objectCrud.js").ObjectTarget;
 };
+/**
+ * The raw CRUD handlers and target args stored in an object instance's reactive state.
+ */
 export type ObjectInstanceRawStateCrud = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     args: import("vue").Reactive<import("../config/objectCrud.js").TargetArgs | {}>;
     /**
-     * - The create function.
+     * The create function.
      */
     create: import("../config/objectCrud.js").CrudCreateFn;
     /**
-     * - The retrieve function.
+     * The retrieve function.
      */
     retrieve: import("../config/objectCrud.js").CrudRetrieveFn;
     /**
-     * - The update function.
+     * The update function.
      */
     update: import("../config/objectCrud.js").CrudUpdateFn;
     /**
-     * - The patch function.
+     * The patch function.
      */
     patch: import("../config/objectCrud.js").CrudPatchFn;
     /**
-     * - The delete function.
+     * The delete function.
      */
     delete: import("../config/objectCrud.js").CrudDeleteFn;
     /**
-     * - The subscribe function.
+     * The subscribe function.
      */
     subscribe: import("../config/objectCrud.js").CrudObjectSubscribeFn;
     /**
-     * - The executeAction function.
+     * The executeAction function.
      */
     executeAction: import("../config/objectCrud.js").CrudObjectExecuteActionFn;
 };
@@ -270,29 +253,29 @@ export type ObjectInstanceRawStateCrud = {
  */
 export type ObjectInstanceRawMyState = {
     /**
-     * - The crud handlers.
+     * The crud handlers.
      */
     crud: import("vue").Reactive<ObjectInstanceRawStateCrud>;
     /**
-     * - The pk of the object.
+     * The pk of the object.
      */
     pk: import("vue").Ref<import("../config/commonCrud.js").Pk | undefined>;
     /**
-     * - The pk key of the object.
+     * The pk key of the object.
      */
     pkKey: import("vue").Ref<string | undefined>;
     /**
-     * - The arguments to be passed to the retrieve function.
+     * The arguments to be passed to the retrieve function.
      */
     params: import("vue").Ref<{
         [key: string]: any;
     }>;
     /**
-     * - The object.
+     * The object.
      */
     object: import("vue").Reactive<CrudObject>;
     /**
-     * - Whether the object is deleted.
+     * Whether the object is deleted.
      */
     deleted: boolean;
 };
@@ -301,19 +284,30 @@ export type ObjectInstanceRawMyState = {
  */
 export type ObjectInstanceRawState = ObjectInstanceRawMyState & import("./loadingError.js").LoadingErrorProperties;
 /**
- * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors.
- * Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
+ * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors. Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
  */
 export type ObjectInstanceState = import("vue").Reactive<ObjectInstanceRawState>;
+/**
+ * The argument shape for an object instance's create operation, carrying the new object to create.
+ */
 export type ObjectInstanceCreateArgs = {
     object: NewCrudObject;
 };
+/**
+ * The argument shape for an object instance's update operation, carrying the existing object to update.
+ */
 export type ObjectInstanceUpdateArgs = {
     object: ExistingCrudObject;
 };
+/**
+ * The argument shape for an object instance's patch operation, carrying the partial object to apply.
+ */
 export type ObjectInstancePatchArgs = {
     partialObject: ExistingCrudObject;
 };
+/**
+ * Arbitrary extra arguments forwarded through to an object instance's CRUD operations.
+ */
 export type AdditionalArgs = {
     [key: string]: any;
 };
@@ -322,33 +316,33 @@ export type AdditionalArgs = {
  */
 export type ObjectInstanceMyFunctions = {
     /**
-     * - Called to turn the current object into a new object on the server.
+     * Called to turn the current object into a new object on the server.
      */
     create: (args: ObjectInstanceCreateArgs & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Called to retrieve the current object by pk from the server.
+     * Called to retrieve the current object by pk from the server.
      */
     retrieve: (args?: Partial<import("./cancellableIntent.js").CommonRunTracking> & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Called to update the current object on the server.
+     * Called to update the current object on the server.
      */
     update: (args: ObjectInstanceUpdateArgs & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Called to delete the current object on the server.
+     * Called to delete the current object on the server.
      */
     delete: (args?: AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Called to patch the current object on the server.
+     * Called to patch the current object on the server.
      */
     patch: (args: ObjectInstancePatchArgs & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Called to execute certain action on the current object.
+     * Called to execute certain action on the current object.
      */
     executeAction: (args: {
         action: string;
     } & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Called to clear the object state.
+     * Called to clear the object state.
      */
     clear: () => void;
 };
@@ -361,7 +355,7 @@ export type ObjectInstanceFunctions = (import("./error.js").ErrorReadOnlyFunctio
  */
 export type ObjectInstanceProperties = {
     /**
-     * - The state of the object instance.
+     * The state of the object instance.
      */
     state: ObjectInstanceState;
 };