@arrai-innovations/reactive-helpers 23.0.2 → 24.1.0

package/config/commonCrud.js

@@ -12,6 +12,11 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  * @typedef {string} Pk - Primary key type used for storage and output (always a string).
  */
 
+/**
+ * @typedef {() => void} SetCancelledFn - Callback a CRUD handler calls to mark its current run cancelled. The instance
+ *  withholds that run's result, stores no error, and resolves the action's cancellation value.
+ */
+
 /**
  * @internal
  * @param {string} name - The name of the method.

package/config/listCrud.js

@@ -32,6 +32,7 @@ import { readonly } from "vue";
  * @property {import("../use/listInstance.js").PushObjectsFn} pushObjects - The method to call with new page(s) of data received.
  * @property {ClearObjectsFn} clearObjects - The method to call to clear the objects.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  * @property {SetPaginateInfo} setPaginateInfo - The method to update pagination information.
  * @property {SetColumnTotals} setColumnTotals - The method to update column totals.
  */
@@ -47,6 +48,7 @@ import { readonly } from "vue";
  * @property {string} pkKey - The key name of the primary key.
  * @property {{[key:string]: any}} params - Your listing arguments, passed through to the crud handlers.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**
@@ -81,6 +83,7 @@ import { readonly } from "vue";
  * @property {string} action - The action to execute.
  * @property {{[key:string]: any}} params - Your listing arguments, passed through to the crud handlers.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**
@@ -99,7 +102,8 @@ import { readonly } from "vue";
  * @callback CrudBulkDeleteFn - Signature for the handler that bulk-deletes objects from the backing store.
  * @param {BulkDeleteArgs} args - The arguments to be passed to the crud handlers.
  * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} - A promise whose resolution
- *  means the bulk delete succeeded; the resolved value is not inspected, and the instance then empties the list.
+ *  means the bulk delete succeeded; the resolved value is not inspected, and the instance then removes the named rows
+ *  from the list.
  *  Carry a `cancel` method to let the caller abandon the run.
  */
 

package/config/objectCrud.js

@@ -33,6 +33,7 @@ import { readonly } from "vue";
  * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**
@@ -46,6 +47,7 @@ import { readonly } from "vue";
  * @property {string} pkKey - The key name of the primary key.
  * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**
@@ -59,6 +61,7 @@ import { readonly } from "vue";
  * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**
@@ -71,6 +74,7 @@ import { readonly } from "vue";
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**
@@ -85,6 +89,7 @@ import { readonly } from "vue";
  * @property {{[key:string]: any}} partialObject - The changed fields only.
  * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 /**
  * @typedef {PartialArgsRaw & AdditionalCrudArgs} PartialArgs - Arguments for an object patch (partial update) operation, combining the raw arguments with any additional CRUD arguments.
@@ -97,6 +102,7 @@ import { readonly } from "vue";
  * @property {string} pkKey - The key name of the primary key.
  * @property {string} action - The action to execute.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
+ * @property {import('./commonCrud.js').SetCancelledFn} setCancelled - Marks this run cancelled from inside the handler.
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrai-innovations/reactive-helpers",
-  "version": "23.0.2",
+  "version": "24.1.0",
   "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
   "main": "index.js",
   "type": "module",
@@ -83,7 +83,7 @@
     "vue-deepunref": "^1.0.1"
   },
   "peerDependencies": {
-    "@vueuse/core": "^13.0.0",
+    "@vueuse/core": "^14.0.0",
     "lodash-es": "^4.17.23",
     "vue": "^3.5.13"
   },

package/types/config/commonCrud.d.ts

@@ -24,3 +24,8 @@ export type PkInput = string | number;
  * Primary key type used for storage and output (always a string).
  */
 export type Pk = string;
+/**
+ * Callback a CRUD handler calls to mark its current run cancelled. The instance
+ *  withholds that run's result, stores no error, and resolves the action's cancellation value.
+ */
+export type SetCancelledFn = () => void;

package/types/config/listCrud.d.ts

@@ -55,6 +55,10 @@ export type ListArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
     /**
      * The method to update pagination information.
      */
@@ -94,6 +98,10 @@ export type BulkDeleteArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for a bulk-delete operation, combining the raw arguments with any additional list CRUD arguments.
@@ -162,6 +170,10 @@ export type ExecuteActionArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for a list execute-action operation, combining the raw arguments with any additional list CRUD arguments.

package/types/config/objectCrud.d.ts

@@ -67,6 +67,10 @@ export type CreateArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for an object create operation, combining the raw arguments with any additional CRUD arguments.
@@ -98,6 +102,10 @@ export type RetrieveArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for an object retrieve operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
@@ -129,6 +137,10 @@ export type UpdateArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for an object update operation, combining the raw arguments with any additional CRUD arguments.
@@ -154,6 +166,10 @@ export type DeleteArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for an object delete operation, combining the raw arguments with any additional CRUD arguments.
@@ -191,6 +207,10 @@ export type PartialArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for an object patch (partial update) operation, combining the raw arguments with any additional CRUD arguments.
@@ -220,6 +240,10 @@ export type ObjectExecuteActionArgsRaw = {
      * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * Marks this run cancelled from inside the handler.
+     */
+    setCancelled: import("./commonCrud.js").SetCancelledFn;
 };
 /**
  * Arguments for a single-object execute-action operation, combining the raw arguments with any additional CRUD arguments.

package/types/use/listInstance.d.ts

@@ -84,6 +84,12 @@
 /**
  * @typedef {(total: ColumnTotals) => void} SetColumnTotalsFn - Signature for the handler that updates the list's column totals.
  */
+/**
+ * @typedef {object} KeepObjectsOption - Per-call control over whether the list applies its own result to `state.objects`.
+ * @property {boolean} [keepObjects=false] - When true, `bulkDelete` leaves `state.objects` untouched after a successful
+ *  handler result. The caller reconciles through `deleteListObject`, `pushObjects`, or `clearList`. The instance
+ *  consumes the option before calling the crud handler.
+ */
 /**
  * @typedef {object} ListInstanceMyFunctions - Defines the methods provided by the list instance for managing objects in the list.
  * @property {PushObjectsFn} pushObjects - Customizable callback for handling new objects per page.
@@ -94,7 +100,7 @@
  *  or error state.
  * @property {() => import('../config/commonCrud.js').Pk} getFakePk - Generates a unique fake pk for use within the list.
  * @property {(args?: import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
- * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success. The promise carries a `cancel` method when the handler's promise did.
+ * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & KeepObjectsOption & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success. Omitting `pks` names every row the list holds. On success, the list removes named loaded rows unless `keepObjects` is true. Missing loaded rows are ignored. The promise carries a `cancel` method when the handler's promise did.
  * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
  * @property {(info: PaginateInfo) => void} setPaginateInfo - The method to update pagination information.
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
@@ -383,6 +389,17 @@ export type SetPaginateInfoFn = (info: PaginateInfo) => void;
  * Signature for the handler that updates the list's column totals.
  */
 export type SetColumnTotalsFn = (total: ColumnTotals) => void;
+/**
+ * Per-call control over whether the list applies its own result to `state.objects`.
+ */
+export type KeepObjectsOption = {
+    /**
+     * When true, `bulkDelete` leaves `state.objects` untouched after a successful
+     * handler result. The caller reconciles through `deleteListObject`, `pushObjects`, or `clearList`. The instance
+     * consumes the option before calling the crud handler.
+     */
+    keepObjects?: boolean;
+};
 /**
  * Defines the methods provided by the list instance for managing objects in the list.
  */
@@ -417,11 +434,11 @@ export type ListInstanceMyFunctions = {
      */
     list: (args?: import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * Deletes objects from the list by pk, returning a promise to a boolean indicating success. The promise carries a `cancel` method when the handler's promise did.
+     * Deletes objects from the list by pk, returning a promise to a boolean indicating success. Omitting `pks` names every row the list holds. On success, the list removes named loaded rows unless `keepObjects` is true. Missing loaded rows are ignored. The promise carries a `cancel` method when the handler's promise did.
      */
     bulkDelete: (args?: {
         pks?: import("../config/commonCrud.js").Pk[];
-    } & import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean>;
+    } & KeepObjectsOption & import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean>;
     /**
      * Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
      */

package/types/use/listRelated.d.ts

@@ -2,7 +2,7 @@
  * @typedef {object} ListRelatedRule - The rule for defining relationships for objects in a list.
  * @property {string} [fkKey] - Specifies the foreign key on each row used to link objects across lists. Defaults to
  *  the rule's own key when omitted.
- * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+ * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v25. The option never named a primary key.
  *  A rule setting both uses `fkKey`.
  * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The objects that can be related based on the foreign key.
@@ -185,7 +185,7 @@ export type ListRelatedRule = {
      */
     fkKey?: string;
     /**
-     * Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+     * Deprecated alias for `fkKey`, removed in v25. The option never named a primary key.
      * A rule setting both uses `fkKey`.
      */
     pkKey?: string;

package/types/use/objectInstance.d.ts

@@ -121,13 +121,21 @@ export function useObjectInstance({ props, handlers }: ObjectInstanceOptions): O
 /**
  * @typedef {{[key:string]: any}} AdditionalArgs - Arbitrary extra arguments forwarded through to an object instance's CRUD operations.
  */
+/**
+ * @typedef {object} KeepObjectOption - Per-call control over whether the instance applies its own result to `state.object`.
+ * @property {boolean} [keepObject=false] - When true, the instance leaves `state.object` and `state.deleted` untouched
+ *  after a successful handler result. The caller reconciles through `clear` or direct state writes. The instance
+ *  consumes the option before calling the crud handler.
+ *
+ *  Concurrent `retrieve` calls share the first in-flight promise, including that run's `keepObject` setting.
+ */
 /**
  * @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.
- * @property {(args?: AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} delete - Called to delete the current object on the server.
- * @property {(args: ObjectInstancePatchArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} patch - Called to patch the current object on the server.
+ * @property {(args: ObjectInstanceCreateArgs & KeepObjectOption & 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> & KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} retrieve - Called to retrieve the current object by pk from the server.
+ * @property {(args: ObjectInstanceUpdateArgs & KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} update - Called to update the current object on the server.
+ * @property {(args?: KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} delete - Called to delete the current object on the server.
+ * @property {(args: ObjectInstancePatchArgs & KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} patch - Called to patch the current object on the server.
  * @property {(args: {action: string} & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|void|null>} executeAction - Called to execute certain action on the current object. Resolves the handler's own resolved value, or `null` when the action failed.
  * @property {() => void} clear - Called to clear the object state.
  */
@@ -313,6 +321,19 @@ export type ObjectInstancePatchArgs = {
 export type AdditionalArgs = {
     [key: string]: any;
 };
+/**
+ * Per-call control over whether the instance applies its own result to `state.object`.
+ */
+export type KeepObjectOption = {
+    /**
+     * When true, the instance leaves `state.object` and `state.deleted` untouched
+     * after a successful handler result. The caller reconciles through `clear` or direct state writes. The instance
+     * consumes the option before calling the crud handler.
+     *
+     * Concurrent `retrieve` calls share the first in-flight promise, including that run's `keepObject` setting.
+     */
+    keepObject?: boolean;
+};
 /**
  * The functions available on the object instance.
  */
@@ -320,23 +341,23 @@ export type ObjectInstanceMyFunctions = {
     /**
      * Called to turn the current object into a new object on the server.
      */
-    create: (args: ObjectInstanceCreateArgs & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
+    create: (args: ObjectInstanceCreateArgs & KeepObjectOption & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
      * 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>;
+    retrieve: (args?: Partial<import("./cancellableIntent.js").CommonRunTracking> & KeepObjectOption & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
      * Called to update the current object on the server.
      */
-    update: (args: ObjectInstanceUpdateArgs & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
+    update: (args: ObjectInstanceUpdateArgs & KeepObjectOption & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
      * Called to delete the current object on the server.
      */
-    delete: (args?: AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
+    delete: (args?: KeepObjectOption & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
      * Called to patch the current object on the server.
      */
-    patch: (args: ObjectInstancePatchArgs & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
+    patch: (args: ObjectInstancePatchArgs & KeepObjectOption & AdditionalArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
      * Called to execute certain action on the current object. Resolves the handler's own resolved value, or `null` when the action failed.
      */

package/types/use/objectRelated.d.ts

@@ -131,7 +131,7 @@ export class ObjectRelatedError extends Error {
  * @typedef {object} ObjectRelatedRule - The rule for defining relationships for the managed object to other collections of objects.
  * @property {string} [fkKey] - The foreign key on the managed object that corresponds to the key in the related
  *  object. Defaults to the rule's own key when omitted.
- * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+ * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v25. The option never named a primary key.
  *  A rule setting both uses `fkKey`.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The related objects, indexed by the key in the related object.
  * @property {string[]} [order] - The order of the related objects, if the related objects are an array.
@@ -225,7 +225,7 @@ export type ObjectRelatedRule = {
      */
     fkKey?: string;
     /**
-     * Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+     * Deprecated alias for `fkKey`, removed in v25. The option never named a primary key.
      * A rule setting both uses `fkKey`.
      */
     pkKey?: string;

package/use/listInstance.js

@@ -136,6 +136,13 @@ export class ListInstanceError extends Error {
  * @typedef {(total: ColumnTotals) => void} SetColumnTotalsFn - Signature for the handler that updates the list's column totals.
  */
 
+/**
+ * @typedef {object} KeepObjectsOption - Per-call control over whether the list applies its own result to `state.objects`.
+ * @property {boolean} [keepObjects=false] - When true, `bulkDelete` leaves `state.objects` untouched after a successful
+ *  handler result. The caller reconciles through `deleteListObject`, `pushObjects`, or `clearList`. The instance
+ *  consumes the option before calling the crud handler.
+ */
+
 /**
  * @typedef {object} ListInstanceMyFunctions - Defines the methods provided by the list instance for managing objects in the list.
  * @property {PushObjectsFn} pushObjects - Customizable callback for handling new objects per page.
@@ -146,7 +153,7 @@ export class ListInstanceError extends Error {
  *  or error state.
  * @property {() => import('../config/commonCrud.js').Pk} getFakePk - Generates a unique fake pk for use within the list.
  * @property {(args?: import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
- * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success. The promise carries a `cancel` method when the handler's promise did.
+ * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & KeepObjectsOption & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success. Omitting `pks` names every row the list holds. On success, the list removes named loaded rows unless `keepObjects` is true. Missing loaded rows are ignored. The promise carries a `cancel` method when the handler's promise did.
  * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
  * @property {(info: PaginateInfo) => void} setPaginateInfo - The method to update pagination information.
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
@@ -472,6 +479,9 @@ export function useListInstance({ props, handlers = {} }) {
             loadingError.clearError();
             loadingError.setLoading();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let listPromise = null;
             try {
                 const listCrudArgs = {
@@ -482,6 +492,7 @@ export function useListInstance({ props, handlers = {} }) {
                     pushObjects: self.pushObjects,
                     clearObjects: self.clearList,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                     setPaginateInfo: self.setPaginateInfo,
                     setColumnTotals: self.setColumnTotals,
                 };
@@ -495,7 +506,9 @@ export function useListInstance({ props, handlers = {} }) {
             promises.list = wrapMaybeCancellable(
                 listPromise
                     .then(() => {
-                        return true;
+                        // The handler owns the rows on this path, so there is nothing here to withhold. A cancelled
+                        // run still reports false, matching the rejection a cancelling handler usually produces.
+                        return !isCancelled.value;
                     })
                     .catch((/** @type {Error} */ error) => {
                         // A deliberate cancellation rejects with the cancel reason; that is not an error.
@@ -518,7 +531,7 @@ export function useListInstance({ props, handlers = {} }) {
             );
             return promises.list;
         },
-        bulkDelete: ({ pks, ...additionalArgs } = {}) => {
+        bulkDelete: ({ pks, keepObjects = false, ...additionalArgs } = {}) => {
             if (state.loading) {
                 // we throw because we want devs to see this error in the console
                 // state.error should be for user facing errors, or unknown errors
@@ -530,6 +543,9 @@ export function useListInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let bulkDeletePromise = null;
             try {
                 bulkDeletePromise = state.crud.bulkDelete({
@@ -539,6 +555,7 @@ export function useListInstance({ props, handlers = {} }) {
                     pkKey: state.pkKey,
                     params: state.params,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(bulkDeletePromise, ListInstanceError, "bulkDelete");
             } catch (error) {
@@ -549,9 +566,26 @@ export function useListInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 bulkDeletePromise
                     .then(() => {
-                        batchObjectChanges(() => {
-                            assignReactiveObject(_objectsProxy, {});
-                        });
+                        if (isCancelled.value) {
+                            return false;
+                        }
+                        if (!keepObjects) {
+                            batchObjectChanges(() => {
+                                pks.forEach((pk) => {
+                                    try {
+                                        self.deleteListObject(pk);
+                                    } catch (err) {
+                                        // A bulk delete may name rows outside the loaded page, so a pk the list does
+                                        // not hold is expected. The subscription path warns here; this one stays quiet,
+                                        // or every cross-page delete would log.
+                                        if (err.name === "ListInstanceError" && err.code === "missing-object") {
+                                            return;
+                                        }
+                                        throw err;
+                                    }
+                                });
+                            });
+                        }
                         loadingError.clearError();
                         return true;
                     })
@@ -586,6 +620,9 @@ export function useListInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let executeActionPromise = null;
             try {
                 executeActionPromise = state.crud.executeAction({
@@ -596,6 +633,7 @@ export function useListInstance({ props, handlers = {} }) {
                     pkKey: state.pkKey,
                     params: state.params,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(executeActionPromise, ListInstanceError, "executeAction");
             } catch (error) {
@@ -606,6 +644,9 @@ export function useListInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 executeActionPromise
                     .then((/** @type {object|string} */ responseData) => {
+                        if (isCancelled.value) {
+                            return null;
+                        }
                         loadingError.clearError();
                         return responseData;
                     })

package/use/listRelated.js

@@ -46,7 +46,7 @@ export class ListRelatedError extends Error {
  * @typedef {object} ListRelatedRule - The rule for defining relationships for objects in a list.
  * @property {string} [fkKey] - Specifies the foreign key on each row used to link objects across lists. Defaults to
  *  the rule's own key when omitted.
- * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+ * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v25. The option never named a primary key.
  *  A rule setting both uses `fkKey`.
  * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The objects that can be related based on the foreign key.

package/use/objectInstance.js

@@ -76,13 +76,22 @@ import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
  * @typedef {{[key:string]: any}} AdditionalArgs - Arbitrary extra arguments forwarded through to an object instance's CRUD operations.
  */
 
+/**
+ * @typedef {object} KeepObjectOption - Per-call control over whether the instance applies its own result to `state.object`.
+ * @property {boolean} [keepObject=false] - When true, the instance leaves `state.object` and `state.deleted` untouched
+ *  after a successful handler result. The caller reconciles through `clear` or direct state writes. The instance
+ *  consumes the option before calling the crud handler.
+ *
+ *  Concurrent `retrieve` calls share the first in-flight promise, including that run's `keepObject` setting.
+ */
+
 /**
  * @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.
- * @property {(args?: AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} delete - Called to delete the current object on the server.
- * @property {(args: ObjectInstancePatchArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} patch - Called to patch the current object on the server.
+ * @property {(args: ObjectInstanceCreateArgs & KeepObjectOption & 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> & KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} retrieve - Called to retrieve the current object by pk from the server.
+ * @property {(args: ObjectInstanceUpdateArgs & KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} update - Called to update the current object on the server.
+ * @property {(args?: KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} delete - Called to delete the current object on the server.
+ * @property {(args: ObjectInstancePatchArgs & KeepObjectOption & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} patch - Called to patch the current object on the server.
  * @property {(args: {action: string} & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|void|null>} executeAction - Called to execute certain action on the current object. Resolves the handler's own resolved value, or `null` when the action failed.
  * @property {() => void} clear - Called to clear the object state.
  */
@@ -258,7 +267,7 @@ export function useObjectInstance({ props, handlers = {} }) {
     /** @type {ObjectInstance} */
     const instance = {
         state,
-        create: ({ object, ...additionalArgs }) => {
+        create: ({ object, keepObject = false, ...additionalArgs }) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (state.loading) {
                 // we throw because we want devs to see this error in the console
@@ -268,6 +277,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let createPromise = null;
             try {
                 createPromise = state.crud.create({
@@ -277,6 +289,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     params: state.params,
                     pkKey: state.pkKey,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(createPromise, ObjectError, "create");
             } catch (error) {
@@ -288,8 +301,13 @@ export function useObjectInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 createPromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
-                        assignReactiveObject(state.object, object);
-                        state.deleted = false;
+                        if (isCancelled.value) {
+                            return false;
+                        }
+                        if (!keepObject) {
+                            assignReactiveObject(state.object, object);
+                            state.deleted = false;
+                        }
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -311,7 +329,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
-        retrieve: (args = {}) => {
+        retrieve: ({ keepObject = false, ...args } = {}) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (promises.retrieve) {
                 // if a retrieve is already in progress, return the existing promise
@@ -326,6 +344,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let retrievePromise = null;
             try {
                 retrievePromise = state.crud.retrieve({
@@ -335,6 +356,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     params: state.params,
                     pkKey: state.pkKey,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(retrievePromise, ObjectError, "retrieve");
             } catch (error) {
@@ -346,8 +368,13 @@ export function useObjectInstance({ props, handlers = {} }) {
             promises.retrieve = wrapMaybeCancellable(
                 retrievePromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
-                        assignReactiveObject(state.object, object);
-                        state.deleted = false;
+                        if (isCancelled.value) {
+                            return false;
+                        }
+                        if (!keepObject) {
+                            assignReactiveObject(state.object, object);
+                            state.deleted = false;
+                        }
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -372,7 +399,7 @@ export function useObjectInstance({ props, handlers = {} }) {
 
             return promises.retrieve;
         },
-        update: ({ object, ...additionalArgs }) => {
+        update: ({ object, keepObject = false, ...additionalArgs }) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (state.loading) {
                 // we throw because we want devs to see this error in the console
@@ -382,6 +409,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let updatePromise = null;
             try {
                 updatePromise = state.crud.update({
@@ -391,6 +421,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     params: state.params,
                     pkKey: state.pkKey,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(updatePromise, ObjectError, "update");
             } catch (error) {
@@ -401,8 +432,13 @@ export function useObjectInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 updatePromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
-                        assignReactiveObject(state.object, object);
-                        state.deleted = false;
+                        if (isCancelled.value) {
+                            return false;
+                        }
+                        if (!keepObject) {
+                            assignReactiveObject(state.object, object);
+                            state.deleted = false;
+                        }
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -424,7 +460,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
-        delete: (args = {}) => {
+        delete: ({ keepObject = false, ...args } = {}) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (state.loading) {
                 // we throw because we want devs to see this error in the console
@@ -434,6 +470,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let deletePromise = null;
             try {
                 deletePromise = state.crud.delete({
@@ -442,6 +481,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     pk: state.pk,
                     pkKey: state.pkKey,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(deletePromise, ObjectError, "delete");
             } catch (error) {
@@ -452,8 +492,13 @@ export function useObjectInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 deletePromise
                     .then(() => {
-                        state.deleted = true;
-                        assignReactiveObject(state.object, {});
+                        if (isCancelled.value) {
+                            return false;
+                        }
+                        if (!keepObject) {
+                            state.deleted = true;
+                            assignReactiveObject(state.object, {});
+                        }
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -475,7 +520,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
-        patch: ({ partialObject, ...additionalArgs }) => {
+        patch: ({ partialObject, keepObject = false, ...additionalArgs }) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (state.loading) {
                 // we throw because we want devs to see this error in the console
@@ -485,6 +530,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let patchPromise = null;
             try {
                 patchPromise = state.crud.patch({
@@ -495,6 +543,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     pkKey: state.pkKey,
                     params: state.params,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(patchPromise, ObjectError, "patch");
             } catch (error) {
@@ -505,8 +554,13 @@ export function useObjectInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 patchPromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
-                        assignReactiveObject(state.object, object);
-                        state.deleted = false;
+                        if (isCancelled.value) {
+                            return false;
+                        }
+                        if (!keepObject) {
+                            assignReactiveObject(state.object, object);
+                            state.deleted = false;
+                        }
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -535,6 +589,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const isCancelled = ref(false);
+            const setCancelled = () => {
+                isCancelled.value = true;
+            };
             let executeActionPromise = null;
             try {
                 executeActionPromise = state.crud.executeAction({
@@ -544,6 +601,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     pk: state.pk,
                     pkKey: state.pkKey,
                     isCancelled: readonly(isCancelled),
+                    setCancelled,
                 });
                 assertHandlerPromise(executeActionPromise, ObjectError, "executeAction");
             } catch (error) {
@@ -555,6 +613,9 @@ export function useObjectInstance({ props, handlers = {} }) {
             return wrapMaybeCancellable(
                 executeActionPromise
                     .then((/** @type {object|string|void} */ responseData) => {
+                        if (isCancelled.value) {
+                            return null;
+                        }
                         return responseData;
                     })
                     .catch((/** @type {Error} */ error) => {

package/use/objectRelated.js

@@ -47,7 +47,7 @@ export class ObjectRelatedError extends Error {
  * @typedef {object} ObjectRelatedRule - The rule for defining relationships for the managed object to other collections of objects.
  * @property {string} [fkKey] - The foreign key on the managed object that corresponds to the key in the related
  *  object. Defaults to the rule's own key when omitted.
- * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+ * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v25. The option never named a primary key.
  *  A rule setting both uses `fkKey`.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The related objects, indexed by the key in the related object.
  * @property {string[]} [order] - The order of the related objects, if the related objects are an array.

package/utils/relatedCalculatedHelpers.js

@@ -78,7 +78,7 @@ export function warnDeprecatedRulePkKey(composableName, ruleKey, rule, warned) {
     warned.add(ruleKey);
     const bothNames = rule.fkKey !== undefined ? ` This rule sets both, and "fkKey" is the one used.` : "";
     console.warn(
-        `[${composableName}] Rule "${ruleKey}" uses "pkKey", which is deprecated and will be removed in v24. Rename it to "fkKey", which is what the option has always meant.${bothNames}`
+        `[${composableName}] Rule "${ruleKey}" uses "pkKey", which is deprecated and will be removed in v25. Rename it to "fkKey", which is what the option has always meant.${bothNames}`
     );
 }