@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

package/types/config/listCrud.d.ts

@@ -9,8 +9,17 @@ export function getListCrud(target: import("vue").UnwrapNestedRefs<ListCrudHandl
     props?: import("vue").UnwrapNestedRefs<ListTargetOption>;
     handlers?: ListCrudHandlers;
 }): void;
+/**
+ * Signature for the handler that clears the objects held by the list.
+ */
 export type ClearObjectsFn = import("../use/listInstance.js").ClearListFn;
+/**
+ * Signature for the handler that updates the list's pagination information.
+ */
 export type SetPaginateInfo = import("../use/listInstance.js").SetPaginateInfoFn;
+/**
+ * Signature for the handler that updates the list's column totals.
+ */
 export type SetColumnTotals = import("../use/listInstance.js").SetColumnTotalsFn;
 /**
  * Additional arguments that can be passed to list crud handlers.
@@ -18,132 +27,178 @@ export type SetColumnTotals = import("../use/listInstance.js").SetColumnTotalsFn
 export type AdditionalListArgs = {
     [key: string]: any;
 };
+/**
+ * Raw arguments for a list operation before run-tracking and additional list CRUD arguments are merged in.
+ */
 export type ListArgsRaw = {
     /**
-     * - 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 key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - The arguments to be passed for list crud handlers.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: object;
     /**
-     * - The method to call with new page(s) of data received.
+     * The method to call with new page(s) of data received.
      */
     pushObjects: import("../use/listInstance.js").PushObjectsFn;
     /**
-     * - The method to call to clear the objects.
+     * The method to call to clear the objects.
      */
     clearObjects: ClearObjectsFn;
     /**
-     * - A ref to a boolean indicating whether the request has
-     * been cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
     /**
-     * - The method to update pagination information.
+     * The method to update pagination information.
      */
     setPaginateInfo: SetPaginateInfo;
     /**
-     * - The method to update column totals.
+     * The method to update column totals.
      */
     setColumnTotals: SetColumnTotals;
 };
+/**
+ * Arguments for a list operation, combining the raw arguments with run-tracking and any additional list CRUD arguments.
+ */
 export type ListArgs = ListArgsRaw & Partial<import("../use/cancellableIntent.js").CommonRunTracking> & AdditionalListArgs;
+/**
+ * Raw arguments for a bulk-delete operation before additional list CRUD arguments are merged in.
+ */
 export type BulkDeleteArgsRaw = {
     /**
-     * - 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 ids of the objects to be deleted.
+     * The pks of the objects to be deleted.
      */
     pks: import("./commonCrud.js").Pk[];
     /**
-     * - The key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
 };
+/**
+ * Arguments for a bulk-delete operation, combining the raw arguments with any additional list CRUD arguments.
+ */
 export type BulkDeleteArgs = BulkDeleteArgsRaw & AdditionalListArgs;
+/**
+ * Callback that applies a created, updated, or deleted object event received from a subscription to the list.
+ */
 export type applyObjectEvent = (newOrUpdatedOrDeleteObject: import("../use/objectInstance.js").ExistingCrudObject | string, action: "create" | "update" | "delete") => void;
+/**
+ * Raw arguments for a list subscribe operation before run-tracking and additional list CRUD arguments are merged in.
+ */
 export type ListSubscribeArgsRaw = {
     /**
-     * - 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 key name of the primary key.
+     * The key name of the primary key.
      */
     pkKey: string;
     /**
-     * - The arguments to be passed for list crud handlers.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: object;
     /**
-     * - The method to call when new data is received.
+     * The method to call when new data is received.
      */
     applyObjectEvent: applyObjectEvent;
     /**
-     * - A ref to a boolean indicating whether the request has
-     * been cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
+/**
+ * Arguments for a list subscribe operation, combining the raw arguments with run-tracking and any additional list CRUD arguments.
+ */
 export type ListSubscribeArgs = ListSubscribeArgsRaw & Partial<import("../use/cancellableIntent.js").CommonRunTracking> & AdditionalListArgs;
+/**
+ * Raw arguments for a list execute-action operation before additional list CRUD arguments are merged in.
+ */
 export type ExecuteActionArgsRaw = {
     /**
-     * - 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 ids of the objects to be acted upon.
+     * The pks of the objects to be acted upon.
      */
     pks: import("./commonCrud.js").Pk[];
     /**
-     * - 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;
 };
+/**
+ * Arguments for a list execute-action operation, combining the raw arguments with any additional list CRUD arguments.
+ */
 export type ExecuteActionArgs = ExecuteActionArgsRaw & AdditionalListArgs;
+/**
+ * Signature for the handler that lists objects from the backing store.
+ */
 export type CrudListFn = (args: ListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<void>;
+/**
+ * Signature for the handler that bulk-deletes objects from the backing store.
+ */
 export type CrudBulkDeleteFn = (args: BulkDeleteArgs) => Promise<boolean>;
+/**
+ * Signature for the handler that subscribes to list changes in the backing store.
+ */
 export type CrudListSubscribeFn = (args: ListSubscribeArgs) => import("../utils/cancellablePromise.js").CancellablePromise<void>;
+/**
+ * Signature for the handler that executes an action on a list of objects in the backing store.
+ */
 export type CrudExecuteActionFn = (args: ExecuteActionArgs) => Promise<object | string | null>;
+/**
+ * The set of optional CRUD handler functions (list, bulkDelete, executeAction, subscribe) for a list.
+ */
 export type ListCrudHandlers = {
     /**
-     * - The list function to get a list of items.
+     * The list function to get a list of items.
      */
     list?: CrudListFn;
     /**
-     * - The delete function to bulk delete a list of items.
+     * The delete function to bulk delete a list of items.
      */
     bulkDelete?: CrudBulkDeleteFn;
     /**
-     * - The  function to execute a certain action on a list of items.
+     * The  function to execute a certain action on a list of items.
      */
     executeAction?: CrudExecuteActionFn;
     /**
-     * - The subscribe function to get a subscription to a list of items.
+     * The subscribe function to get a subscription to a list of items.
      */
     subscribe?: CrudListSubscribeFn;
 };
+/**
+ * The default target arguments passed through to the list CRUD handlers.
+ */
 export type ListTarget = {
     /**
-     * - The default arguments for the crud handlers.
+     * The default arguments for the crud handlers.
      */
     args: object;
 };
+/**
+ * Optional target arguments passed through to the list CRUD handlers.
+ */
 export type ListTargetOption = {
     /**
-     * - The default arguments for the crud handlers.
+     * The default arguments for the crud handlers.
      */
     target?: object;
 };

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,317 @@ 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 new object to create; it carries no primary key yet.
      */
     object: {
         [key: string]: any;
     };
     /**
-     * - The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     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 readonly ref that becomes true once the request is 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.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is 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 complete object to update; its primary key rides inside it, at `object[pkKey]`.
      */
     object: import("../use/objectInstance.js").ExistingCrudObject;
     /**
-     * - The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     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 readonly ref that becomes true once the request is 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 readonly ref that becomes true once the request is 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 changed fields only.
      */
     partialObject: {
         [key: string]: any;
     };
     /**
-     * - The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * - A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is 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;
+    target: TargetArgs;
     /**
-     * - The id of the objects to be acted upon.
+     * The pk of the object to be acted upon.
      */
-    pk: string;
+    pk: import("./commonCrud.js").Pk;
     /**
-     * - 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 readonly ref that becomes true once the request is 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.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     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 readonly ref that becomes true once the request is 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;
-export type CrudResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string>;
+/**
+ * -
+ *  The value returned by an object CRUD handler whose resolved value becomes the record: create, retrieve, update, and
+ *  patch. A possibly-cancellable promise resolving to the complete record. The instance mirrors the resolved value
+ *  into `state.object`, so a partial record drops the fields it omits, and a resolved value that is not an object (a
+ *  bare primary key string, for instance) fails the assignment and is stored in `state.error`.
+ */
+export type CrudResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object>;
+/**
+ * -
+ *  The value returned by an object CRUD handler whose resolved value is ignored: delete, and executeAction. A
+ *  possibly-cancellable promise whose resolution signals success and nothing more, so it may resolve a record, a
+ *  primary key string, or nothing at all.
+ */
+export type CrudCompletionResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string | void>;
+/**
+ * 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;
-export type CrudDeleteFn = (args: DeleteArgs) => CrudResponse;
-export type CrudObjectExecuteActionFn = (args: ObjectExecuteActionArgs) => CrudResponse;
+/**
+ * Signature for the handler that deletes an object from the backing store.
+ */
+export type CrudDeleteFn = (args: DeleteArgs) => CrudCompletionResponse;
+/**
+ * Signature for the handler that executes an action on a single object in the backing store.
+ */
+export type CrudObjectExecuteActionFn = (args: ObjectExecuteActionArgs) => CrudCompletionResponse;
+/**
+ * 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/tests/benchmarks/fixtures.d.ts

@@ -0,0 +1,60 @@
+export namespace benchmarkOptions {
+    let iterations: number;
+    let time: number;
+    let warmupIterations: number;
+    let warmupTime: number;
+}
+export function makeRows(count: number, start?: number): {
+    id: number;
+    name: string;
+}[];
+export function makeRichRows(count: number, start?: number): {
+    id: number;
+    name: string;
+    organization: number;
+}[];
+/** Related objects the populated related rule resolves against. */
+export const relatedOrganizations: {
+    [k: string]: {
+        id: number;
+        name: string;
+    };
+};
+export namespace emptyRules {
+    let allowedFilter: any;
+    let calculatedObjectsRules: {};
+    let excludedFilter: any;
+    let orderByRules: any[];
+    let relatedObjectsRules: {};
+    let textSearchRules: any[];
+    let textSearchValue: string;
+}
+export namespace populatedRules {
+    export function allowedFilter_1(object: any): boolean;
+    export { allowedFilter_1 as allowedFilter };
+    export namespace calculatedObjectsRules_1 {
+        function doubled(object: any): number;
+    }
+    export { calculatedObjectsRules_1 as calculatedObjectsRules };
+    let excludedFilter_1: any;
+    export { excludedFilter_1 as excludedFilter };
+    let orderByRules_1: {
+        key: string;
+        desc: boolean;
+        localeCompare: boolean;
+    }[];
+    export { orderByRules_1 as orderByRules };
+    export namespace relatedObjectsRules_1 {
+        namespace org {
+            export let pkKey: string;
+            export { relatedOrganizations as objects };
+        }
+    }
+    export { relatedObjectsRules_1 as relatedObjectsRules };
+    let textSearchRules_1: any[];
+    export { textSearchRules_1 as textSearchRules };
+    let textSearchValue_1: string;
+    export { textSearchValue_1 as textSearchValue };
+}
+export function makeList(rules?: object): ReturnType<typeof useList>;
+import { useList } from "../../use/list.js";

package/types/tests/benchmarks/listLayers.bench.d.ts

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

package/types/tests/benchmarks/listPush.bench.d.ts

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

package/types/tests/benchmarks/listStream.bench.d.ts

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

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

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

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

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