@arrai-innovations/reactive-helpers 15.0.0 → 16.0.0

package/config/listCrud.js

@@ -66,19 +66,27 @@ const defaultCrud = {
  */
 
 /**
- * @typedef {(ListFnArgs)=>void} ListFn
+ * @typedef {object} ExecuteActionFnArgs
+ * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @property {string[]} pks - The ids of the objects to be acted upon.
+ * @property {string} pkKey - The key name of the primary key.
+ * @property {string} action - The action to execute.
+ */
+
+/**
+ * @typedef {(ListFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} ListFn - The list function to get a list of items, returning a boolean indicating success.
  */
 
 /**
- * @typedef {(DeleteFnArgs)=>void} BulkDeleteFn
+ * @typedef {(DeleteFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} BulkDeleteFn - The delete function to bulk delete a list of items.
  */
 
 /**
- * @typedef {(SubscribeFnArgs)=>void} SubscribeFn
+ * @typedef {(SubscribeFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} SubscribeFn - The subscribe function to set up a subscription to a list of items.
  */
 
 /**
- * @typedef {(ExecuteActionFnArgs)=>void} ExecuteActionFn
+ * @typedef {(ExecuteActionFnArgs)=>Promise<import('./objectCrud.js').ResponseData|false> & { cancel: () => Promise<void>|void }} ExecuteActionFn - The function to execute a certain action on a list of items, returning the response data or false.
  */
 
 /**

package/config/objectCrud.js

@@ -79,7 +79,7 @@ const defaultCrud = {
  */
 
 /**
- * @typedef {Promise<object|string>} ResponseData
+ * @typedef {Promise<object|string> & { cancel: () => Promise<void>|void }} ResponseData
  */
 
 /**
@@ -91,7 +91,7 @@ const defaultCrud = {
  * @property {(UpdateDetailArgs)=>ResponseData} [update] - A function to be used instead of the default crud update function.
  * @property {(DeleteDetailArgs)=>ResponseData} [delete] - A function to be used instead of the default crud delete function.
  * @property {(PartialDetailArgs)=>ResponseData} [patch] - A function to be used instead of the default crud patch function.
- * @property {(SubscribeArgs)=>void} [subscribe] - A function to be used instead of the default crud subscribe function.
+ * @property {(SubscribeArgs)=>void & { cancel: () => Promise<void>|void }} [subscribe] - A function to be used instead of the default crud subscribe function.
  */
 
 /**

package/docs/README.md

@@ -35,6 +35,7 @@
 - [utils/deleteKey](utils/deleteKey.md)
 - [utils/flattenPaths](utils/flattenPaths.md)
 - [utils/getFakePk](utils/getFakePk.md)
+- [utils/keepAliveTry](utils/keepAliveTry.md)
 - [utils/keyDiff](utils/keyDiff.md)
 - [utils/loadingCombine](utils/loadingCombine.md)
 - [utils/proxyRunning](utils/proxyRunning.md)

package/docs/config/listCrud.md

@@ -32,6 +32,36 @@ The ids of the objects to be deleted.
 
 ***
 
+### ExecuteActionFnArgs
+
+#### Properties
+
+##### action
+
+> **action**: `string`
+
+The action to execute.
+
+##### crudArgs
+
+> **crudArgs**: `any`
+
+The arguments to be passed to the crud functions.
+
+##### pkKey
+
+> **pkKey**: `string`
+
+The key name of the primary key.
+
+##### pks
+
+> **pks**: `string`[]
+
+The ids of the objects to be acted upon.
+
+***
+
 ### ListCrudArgs
 
 #### Properties
@@ -179,7 +209,9 @@ The method to call when new data is received.
 
 ### BulkDeleteFn()
 
-> **BulkDeleteFn**\<\>: (`DeleteFnArgs`) => `void`
+> **BulkDeleteFn**\<\>: (`DeleteFnArgs`) => `Promise`\<`boolean`\> & `object`
+
+The delete function to bulk delete a list of items.
 
 #### Type Parameters
 
@@ -189,13 +221,15 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<`boolean`\> & `object`
 
 ***
 
 ### ExecuteActionFn()
 
-> **ExecuteActionFn**\<\>: (`ExecuteActionFnArgs`) => `void`
+> **ExecuteActionFn**\<\>: (`ExecuteActionFnArgs`) => `Promise`\<[`config/objectCrud`](objectCrud.md) \| `false`\> & `object`
+
+The function to execute a certain action on a list of items, returning the response data or false.
 
 #### Type Parameters
 
@@ -205,13 +239,15 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<[`config/objectCrud`](objectCrud.md) \| `false`\> & `object`
 
 ***
 
 ### ListFn()
 
-> **ListFn**\<\>: (`ListFnArgs`) => `void`
+> **ListFn**\<\>: (`ListFnArgs`) => `Promise`\<`boolean`\> & `object`
+
+The list function to get a list of items, returning a boolean indicating success.
 
 #### Type Parameters
 
@@ -221,7 +257,7 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<`boolean`\> & `object`
 
 ***
 
@@ -245,7 +281,9 @@ The method to call when new data is received.
 
 ### SubscribeFn()
 
-> **SubscribeFn**\<\>: (`SubscribeFnArgs`) => `void`
+> **SubscribeFn**\<\>: (`SubscribeFnArgs`) => `Promise`\<`boolean`\> & `object`
+
+The subscribe function to set up a subscription to a list of items.
 
 #### Type Parameters
 
@@ -255,7 +293,7 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<`boolean`\> & `object`
 
 ***
 

package/docs/config/objectCrud.md

@@ -142,7 +142,7 @@ A function to be used instead of the default crud retrieve function.
 
 ##### subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -152,7 +152,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ##### update()
 
@@ -322,7 +322,17 @@ The arguments to be passed to the retrieve function.
 
 ### ResponseData
 
-> **ResponseData**\<\>: `Promise`\<`object` \| `string`\>
+> **ResponseData**\<\>: `Promise`\<`object` \| `string`\> & `object`
+
+#### Type declaration
+
+##### cancel()
+
+> **cancel**: () => `Promise`\<`void`\> \| `void`
+
+###### Returns
+
+`Promise`\<`void`\> \| `void`
 
 #### Type Parameters
 

package/docs/use/listInstance.md

@@ -79,13 +79,13 @@ Adds an object to the list.
 
 ##### bulkDelete()
 
-> **bulkDelete**: () => `Promise`\<`void`\>
+> **bulkDelete**: () => `Promise`\<`boolean`\>
 
-Initiates a bulk delete operation on all objects in the list.
+Initiates a bulk delete operation on all objects in the list, returning a promise to a boolean indicating success.
 
 ###### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`boolean`\>
 
 ##### clearList()
 
@@ -127,13 +127,13 @@ Deletes an object from the list by pk.
 
 ##### executeAction()
 
-> **executeAction**: () => `Promise`\<`void`\>
+> **executeAction**: () => `Promise`\<`any`\>
 
-Initiates an action on all objects in the list.
+Initiates an action on all objects in the list, returning the response, or false if the action failed.
 
 ###### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`any`\>
 
 ##### getFakePk()
 
@@ -147,13 +147,13 @@ Generates a unique fake pk for use within the list.
 
 ##### list()
 
-> **list**: () => `Promise`\<`void`\>
+> **list**: () => `Promise`\<`boolean`\>
 
-Initiates a fetch to retrieve objects according to the CRUD configuration.
+Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
 
 ###### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`boolean`\>
 
 ##### pageCallback()
 

package/docs/use/loadingError.md

@@ -52,16 +52,12 @@ Set the loading state.
 
 #### Properties
 
-##### clearError()
+##### clearError
 
-> **clearError**: () => `void`
+> **clearError**: [`ClearErrorFn`](loadingError.md#clearerrorfn)
 
 Clear the error state.
 
-###### Returns
-
-`void`
-
 ##### error
 
 > **error**: `Readonly`\<`Ref`\<`Error`\>\>
@@ -82,6 +78,20 @@ Whether the component is loading.
 
 ## Type Aliases
 
+### ClearErrorFn()
+
+> **ClearErrorFn**\<\>: () => `void`
+
+Clear the error state.
+
+#### Type Parameters
+
+#### Returns
+
+`void`
+
+***
+
 ### LoadingError
 
 > **LoadingError**\<\>: [`LoadingErrorStatus`](loadingError.md#loadingerrorstatus) & [`LoadingErrorMutations`](loadingError.md#loadingerrormutations)

package/docs/use/object.md

@@ -100,7 +100,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crudArgs.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -110,7 +110,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crudArgs.update()
 
@@ -284,7 +284,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -294,7 +294,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 

package/docs/use/objectCalculated.md

@@ -94,7 +94,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -104,7 +104,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 
@@ -348,7 +348,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -358,7 +358,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 

package/docs/use/objectInstance.md

@@ -63,48 +63,90 @@ The error code.
 
 #### Properties
 
-##### clear
+##### clear()
 
-> **clear**: `Function`
+> **clear**: () => `void`
 
 Called to clear the object state.
 
+###### Returns
+
+`void`
+
 ##### clearError
 
-> **clearError**: `Function`
+> **clearError**: [`ClearErrorFn`](loadingError.md#clearerrorfn)
 
 Called to clear the error state.
 
-##### create
+##### create()
 
-> **create**: `Function`
+> **create**: (`args`) => `Promise`\<`boolean`\>
 
 Called to turn the current object into a new object on the server.
 
-##### delete
+###### Parameters
+
+• **args**
+
+• **args.object**: `any`
+
+###### Returns
 
-> **delete**: `Function`
+`Promise`\<`boolean`\>
+
+##### delete()
+
+> **delete**: () => `Promise`\<`boolean`\>
 
 Called to delete the current object on the server.
 
-##### patch
+###### Returns
+
+`Promise`\<`boolean`\>
 
-> **patch**: `Function`
+##### patch()
+
+> **patch**: (`args`) => `Promise`\<`boolean`\>
 
 Called to patch the current object on the server.
 
-##### retrieve
+###### Parameters
+
+• **args**
 
-> **retrieve**: `Function`
+• **args.partialObject**: [`CrudObject`](objectInstance.md#crudobject)
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
+##### retrieve()
+
+> **retrieve**: () => `Promise`\<`boolean`\>
 
 Called to retrieve the current object by pk from the server.
 
-##### update
+###### Returns
+
+`Promise`\<`boolean`\>
 
-> **update**: `Function`
+##### update()
+
+> **update**: (`args`) => `Promise`\<`boolean`\>
 
 Called to update the current object on the server.
 
+###### Parameters
+
+• **args**
+
+• **args.object**: [`CrudObject`](objectInstance.md#crudobject)
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
 ***
 
 ### ObjectInstanceOptions
@@ -193,7 +235,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crudArgs.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -203,7 +245,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crudArgs.update()
 
@@ -319,7 +361,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -329,7 +371,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 

package/docs/use/objectRelated.md

@@ -94,7 +94,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -104,7 +104,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 
@@ -280,7 +280,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -290,7 +290,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 

package/docs/use/objectSubscription.md

@@ -225,7 +225,7 @@ A function to be used instead of the default crud retrieve function.
 
 ###### crud.subscribe()
 
-> **subscribe**: (`SubscribeArgs`) => `void`
+> **subscribe**: (`SubscribeArgs`) => `void` & `object`
 
 A function to be used instead of the default crud subscribe function.
 
@@ -235,7 +235,7 @@ A function to be used instead of the default crud subscribe function.
 
 ###### Returns
 
-`void`
+`void` & `object`
 
 ###### crud.update()
 

package/docs/utils/classes.md

@@ -59,7 +59,7 @@ Normalize various ways of specifying CSS classes into an object for use in Vue.j
 
 #### Parameters
 
-• ...**classes**: (`string` \| `string`[] \| `string`[][] \| `object` \| `Ref`\<`string` \| `string`[] \| `string`[][]\>)[]
+• ...**classes**: (`string` \| `string`[] \| `object` \| `string`[][] \| `Ref`\<`string` \| `string`[] \| `string`[][]\>)[]
 
 A mixed array containing multiple ways of specifying CSS classes.
 

package/docs/utils/keepAliveTry.md

@@ -0,0 +1,51 @@
+[**@arrai-innovations/reactive-helpers**](../README.md) • **Docs**
+
+***
+
+[@arrai-innovations/reactive-helpers](../README.md) / utils/keepAliveTry
+
+# utils/keepAliveTry
+
+## Functions
+
+### tryOnActivated()
+
+> **tryOnActivated**(`fn`, `target`?): `void`
+
+If there is an active component, set up an onActivated hook.
+
+#### Parameters
+
+• **fn**: `Function`
+
+The function to call.
+
+• **target?**: `any`
+
+The target to call the function on.
+
+#### Returns
+
+`void`
+
+***
+
+### tryOnDeactivated()
+
+> **tryOnDeactivated**(`fn`, `target`?): `void`
+
+If there is an active component, set up an onDeactivated hook.
+
+#### Parameters
+
+• **fn**: `Function`
+
+The function to call.
+
+• **target?**: `any`
+
+The target to call the function on.
+
+#### Returns
+
+`void`

package/index.js

@@ -28,6 +28,7 @@ export * from "./utils/compact.js";
 export * from "./utils/deleteKey.js";
 export * from "./utils/flattenPaths.js";
 export * from "./utils/getFakePk.js";
+export * from "./utils/keepAliveTry.js";
 export * from "./utils/keyDiff.js";
 export * from "./utils/loadingCombine.js";
 export * from "./utils/relatedCalculatedHelpers.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "15.0.0",
+    "version": "16.0.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",
@@ -65,6 +65,7 @@
         "vue-deepunref": "^1.0.1"
     },
     "peerDependencies": {
+        "@vueuse/core": "^11.2.0",
         "lodash-es": "^4.17.21",
         "vue": "^3.4.30"
     }

package/tests/unit/use/listInstance.spec.js

@@ -12,19 +12,43 @@ afterAll(() => {
 
 const fields = ["id", "__str__", "name"];
 describe("use/listInstance.spec.js", function () {
-    let useListInstance, ListInstanceError, useListInstances, globalList, globalbulkDelete, globalexecuteAction;
+    let useListInstance,
+        ListInstanceError,
+        useListInstances,
+        globalList,
+        globalBulkDelete,
+        globalExecuteAction,
+        globalListCancel,
+        globalBulkDeleteCancel,
+        globalExecuteActionCancel;
     beforeEach(async () => {
         const listCrud = await import("../../../config/listCrud.js");
         const imported = await import("../../../use/listInstance.js");
+        globalListCancel = vi.fn();
+        globalBulkDeleteCancel = vi.fn();
+        globalExecuteActionCancel = vi.fn();
         globalList = vi.fn();
-        globalbulkDelete = vi.fn(() => Promise.resolve(true));
-        globalexecuteAction = vi.fn(() => Promise.resolve(true));
-        // @ts-ignore
-        globalList.cancel = vi.fn();
+        globalBulkDelete = vi.fn(
+            (() => {
+                const fn = () => Promise.resolve(true);
+                fn.cancel = globalBulkDeleteCancel;
+                return fn;
+            })()
+        );
+        globalExecuteAction = vi.fn(
+            (() => {
+                const fn = () => Promise.resolve(true);
+                fn.cancel = globalExecuteActionCancel;
+                return fn;
+            })()
+        );
         listCrud.setListCrud({
+            // @ts-ignore - mock is an acceptable substitute
             list: globalList,
-            bulkDelete: globalbulkDelete,
-            executeAction: globalexecuteAction,
+            // @ts-ignore - mock is an acceptable substitute
+            bulkDelete: globalBulkDelete,
+            // @ts-ignore - mock is an acceptable substitute
+            executeAction: globalExecuteAction,
             args: { stream: "test_stream" },
         });
         useListInstance = imported.useListInstance;
@@ -675,19 +699,19 @@ describe("use/listInstance.spec.js", function () {
             expectErrorToBeNull(listInstance.state.error);
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBe(true);
-            expect(globalexecuteAction).toHaveBeenCalledWith({
+            expect(globalExecuteAction).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },
                 pkKey: "id",
                 pks: Object.keys(crudListResolvedObjects2).map(Number),
             });
 
-            expect(globalexecuteAction).toHaveBeenCalledTimes(1);
+            expect(globalExecuteAction).toHaveBeenCalledTimes(1);
 
             // @ts-ignore - executeAction is set in a promise, since we await this will be set
             crudListResolve();
             await flushPromises();
             await expect(executeActionResolve).resolves.toBe(true);
-            expect({ ...listInstance.state.objects }).toEqual({});
+            expect({ ...listInstance.state.objects }).toEqual(crudListResolvedObjects2);
         });
         it("succeeds with non-standard primary key", async function () {
             const listArgs = reactive({
@@ -723,19 +747,19 @@ describe("use/listInstance.spec.js", function () {
             expectErrorToBeNull(listInstance.state.error);
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBe(true);
-            expect(globalexecuteAction).toHaveBeenCalledWith({
+            expect(globalExecuteAction).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },
                 pkKey: "unique",
                 pks: Object.keys(crudListResolvedObjectsNonStandardPK).map(Number),
             });
 
-            expect(globalexecuteAction).toHaveBeenCalledTimes(1);
+            expect(globalExecuteAction).toHaveBeenCalledTimes(1);
 
-            // @ts-ignore - globalexecuteAction is set in a promise, since we await this will be set
+            // @ts-ignore - globalExecuteAction is set in a promise, since we await this will be set
             crudListResolve();
             await flushPromises();
             await expect(executeActionResolve).resolves.toBe(true);
-            expect({ ...listInstance.state.objects }).toEqual({});
+            expect({ ...listInstance.state.objects }).toEqual(crudListResolvedObjectsNonStandardPK);
         });
         it("already loading", async function () {
             const listArgs = reactive({
@@ -752,7 +776,7 @@ describe("use/listInstance.spec.js", function () {
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBeUndefined();
             expect({ ...listInstance.state.objects }).toEqual({});
-            globalexecuteAction.mockImplementation(() => new Promise(() => {}));
+            globalExecuteAction.mockImplementation(() => new Promise(() => {}));
             listInstance.executeAction();
             expectErrorToBeNull(listInstance.state.error);
             expect(listInstance.state.errored).toBe(false);
@@ -778,7 +802,7 @@ describe("use/listInstance.spec.js", function () {
                 crudListReject = reject;
             });
             let passedPageCallback;
-            globalexecuteAction.mockImplementation(({ pageCallback }) => {
+            globalExecuteAction.mockImplementation(({ pageCallback }) => {
                 passedPageCallback = pageCallback;
                 return crudListPromise;
             });
@@ -808,12 +832,12 @@ describe("use/listInstance.spec.js", function () {
             expect(listInstance.state.errored).toBe(true);
             expect(listInstance.state.loading).toBe(false);
             expect({ ...listInstance.state.objects }).toEqual({});
-            expect(globalexecuteAction).toHaveBeenCalledWith({
+            expect(globalExecuteAction).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },
                 pkKey: "id",
                 pks: [],
             });
-            expect(globalexecuteAction).toHaveBeenCalledTimes(1);
+            expect(globalExecuteAction).toHaveBeenCalledTimes(1);
         });
     });
     describe("bulkDelete", function () {
@@ -851,13 +875,13 @@ describe("use/listInstance.spec.js", function () {
             expectErrorToBeNull(listInstance.state.error);
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBe(true);
-            expect(globalbulkDelete).toHaveBeenCalledWith({
+            expect(globalBulkDelete).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },
                 pkKey: "id",
                 pks: Object.keys(crudListResolvedObjects2).map(Number),
             });
 
-            expect(globalbulkDelete).toHaveBeenCalledTimes(1);
+            expect(globalBulkDelete).toHaveBeenCalledTimes(1);
 
             // @ts-ignore - bulkDeleteResolve is set in a promise, since we await this will be set
             crudListResolve();
@@ -899,13 +923,13 @@ describe("use/listInstance.spec.js", function () {
             expectErrorToBeNull(listInstance.state.error);
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBe(true);
-            expect(globalbulkDelete).toHaveBeenCalledWith({
+            expect(globalBulkDelete).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },
                 pkKey: "unique",
                 pks: Object.keys(crudListResolvedObjectsNonStandardPK).map(Number),
             });
 
-            expect(globalbulkDelete).toHaveBeenCalledTimes(1);
+            expect(globalBulkDelete).toHaveBeenCalledTimes(1);
 
             // @ts-ignore - bulkDeleteResolve is set in a promise, since we await this will be set
             crudListResolve();
@@ -928,7 +952,7 @@ describe("use/listInstance.spec.js", function () {
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBeUndefined();
             expect({ ...listInstance.state.objects }).toEqual({});
-            globalbulkDelete.mockImplementation(() => new Promise(() => {}));
+            globalBulkDelete.mockImplementation(() => new Promise(() => {}));
             expectErrorToBeNull(listInstance.state.error);
             expect(listInstance.state.errored).toBe(false);
             expect(listInstance.state.loading).toBeUndefined();
@@ -957,7 +981,7 @@ describe("use/listInstance.spec.js", function () {
                 crudListReject = reject;
             });
             let passedPageCallback;
-            globalbulkDelete.mockImplementation(({ pageCallback }) => {
+            globalBulkDelete.mockImplementation(({ pageCallback }) => {
                 passedPageCallback = pageCallback;
                 return crudListPromise;
             });
@@ -987,12 +1011,12 @@ describe("use/listInstance.spec.js", function () {
             expect(listInstance.state.errored).toBe(true);
             expect(listInstance.state.loading).toBe(false);
             expect({ ...listInstance.state.objects }).toEqual({});
-            expect(globalbulkDelete).toHaveBeenCalledWith({
+            expect(globalBulkDelete).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },
                 pkKey: "id",
                 pks: [],
             });
-            expect(globalbulkDelete).toHaveBeenCalledTimes(1);
+            expect(globalBulkDelete).toHaveBeenCalledTimes(1);
         });
     });
     describe("getFakePk", function () {

package/tsconfig.json

@@ -12,8 +12,8 @@
         "moduleResolution": "nodenext",
         "esModuleInterop": true,
         "target": "es2023",
-        "types": ["vitest/globals"]
+        "types": ["vitest/globals"],
+        "skipLibCheck": true
     },
-    // match with ./makeTypeDoc.sh
     "include": ["config/**/*.js", "use/**/*.js", "utils/**/*.js", "tests/**/*.js", "index.js"]
 }

package/typedoc.json

@@ -1,7 +1,6 @@
 {
     "entryPoints": ["config/**/*.js", "use/**/*.js", "utils/**/*.js"],
     "out": "docs",
-    "exclude": [],
     "excludeExternals": true,
     "excludePrivate": true,
     "excludeProtected": true,

package/use/cancellableIntent.js

@@ -3,6 +3,7 @@ import isEmpty from "lodash-es/isEmpty.js";
 import isEqual from "lodash-es/isEqual.js";
 import { computed, effectScope, nextTick, onScopeDispose, reactive, readonly, watch } from "vue";
 import { deepUnref } from "vue-deepunref";
+import { tryOnActivated, tryOnDeactivated } from "../utils/keepAliveTry.js";
 
 /**
  * @module use/cancellableIntent.js - A composable function for handling cancellable intents.
@@ -209,6 +210,17 @@ export function useCancellableIntent({
         }
     };
 
+    const cleanup = () => {
+        // cancel the intent when the component is deactivated
+        cancel();
+        if (state.clearActiveOnResolved) {
+            // otherwise it clears when resolved
+            cancelFunction = null;
+        }
+        // reset the previous watch values for the next activation
+        previousWatchValues = null;
+    };
+
     es.run(() => {
         state.active = computed(() => {
             if (state.activeCount === undefined) {
@@ -233,9 +245,16 @@ export function useCancellableIntent({
             deep: true,
         });
 
-        nextTick().then(intentWatch);
+        tryOnActivated(() => {
+            state.activeCount = 0;
+            state.resolvingCount = 0;
+            // trigger the intent watch manually to get current watch values
+            intentWatch();
+        });
+        tryOnDeactivated(cleanup);
+        onScopeDispose(cleanup);
 
-        onScopeDispose(cancel);
+        nextTick().then(intentWatch);
     });
     return {
         state,

package/use/listInstance.js

@@ -117,9 +117,9 @@ export class ListInstanceError extends Error {
  * @property {(objectId: string) => void} deleteListObject - Deletes an object from the list by pk.
  * @property {() => void} clearList - Clears all objects and errors from the list.
  * @property {() => string} getFakePk - Generates a unique fake pk for use within the list.
- * @property {() => Promise<void>} list - Initiates a fetch to retrieve objects according to the CRUD configuration.
- * @property {() => Promise<void>} bulkDelete - Initiates a bulk delete operation on all objects in the list.
- * @property {() => Promise<void>} executeAction - Initiates an action on all objects in the list.
+ * @property {() => Promise<boolean>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
+ * @property {() => Promise<boolean>} bulkDelete - Initiates a bulk delete operation on all objects in the list, returning a promise to a boolean indicating success.
+ * @property {() => Promise<object|string|false>} executeAction - Initiates an action on all objects in the list, returning the response, or false if the action failed.
  */
 
 /**
@@ -344,10 +344,9 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
                 pks: Object.keys(state.objects).map(Number),
                 pkKey: state.pkKey,
             })
-            .then(() => {
-                assignReactiveObject(state.objects, {});
+            .then((responseData) => {
                 loadingError.clearError();
-                return Promise.resolve(true);
+                return Promise.resolve(responseData);
             })
             .catch((error) => {
                 loadingError.setError(error);
@@ -493,6 +492,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
         state.order = computed(() => Object.keys(state.objects));
     });
 
+    // This isn't a direct return because we want the live returnedObject.pageCallback in list()
     const returnedObject = {
         state,
         list,

package/use/loadingError.js

@@ -4,6 +4,10 @@ import { readonly, ref } from "vue";
  * @module use/loadingError.js - A composable function for managing loading and error states.
  */
 
+/**
+ * @typedef {() => void} ClearErrorFn - Clear the error state.
+ */
+
 /**
  * The common API for loading and error states.
  *
@@ -11,7 +15,7 @@ import { readonly, ref } from "vue";
  * @property {Readonly<import("vue").Ref<boolean|undefined>>} loading - Whether the component is loading.
  * @property {Readonly<import("vue").Ref<Error|null>>} error - The error that occurred.
  * @property {Readonly<import("vue").Ref<boolean>>} errored - Whether an error has occurred.
- * @property {() => void} clearError - Clear the error state.
+ * @property {ClearErrorFn} clearError - Clear the error state.
  */
 
 /**

package/use/objectCalculated.js

@@ -200,47 +200,51 @@ export function useObjectCalculated({ parentState, calculatedObjectRules }) {
             state[key] = toRef(parentState, key);
         }
 
-        watch([() => state.calculatedObjectRules && Object.keys(state.calculatedObjectRules)], () => {
-            /** @type {Set<string>|undefined} */
-            let addedKeys = undefined,
+        watch(
+            [() => state.calculatedObjectRules && Object.keys(state.calculatedObjectRules)],
+            () => {
                 /** @type {Set<string>|undefined} */
-                removedKeys = undefined,
-                /** @type {Set<string>|undefined} */
-                sameKeys = undefined;
-            if (!state.calculatedObjectRules) {
-                removedKeys = new Set(Object.keys(calculatedObjectOriginalFunctions));
-                addedKeys = new Set();
-                sameKeys = new Set();
-            } else {
-                ({ addedKeys, removedKeys, sameKeys } = keyDiff(
-                    Object.keys(state.calculatedObjectRules),
-                    Object.keys(calculatedObjectOriginalFunctions)
-                ));
-            }
-            for (const sameKey of sameKeys) {
-                if (calculatedObjectOriginalFunctions[sameKey] !== state.calculatedObjectRules[sameKey]) {
-                    removedKeys.add(sameKey);
-                    addedKeys.add(sameKey);
+                let addedKeys = undefined,
+                    /** @type {Set<string>|undefined} */
+                    removedKeys = undefined,
+                    /** @type {Set<string>|undefined} */
+                    sameKeys = undefined;
+                if (!state.calculatedObjectRules) {
+                    removedKeys = new Set(Object.keys(calculatedObjectOriginalFunctions));
+                    addedKeys = new Set();
+                    sameKeys = new Set();
+                } else {
+                    ({ addedKeys, removedKeys, sameKeys } = keyDiff(
+                        Object.keys(state.calculatedObjectRules),
+                        Object.keys(calculatedObjectOriginalFunctions)
+                    ));
                 }
-            }
-            for (const removedKey of removedKeys) {
-                delete calculatedObjectOriginalFunctions[removedKey];
-                delete state.calculatedObject[removedKey];
-                if (calculatedObjectEffectScopes[removedKey]) {
-                    calculatedObjectEffectScopes[removedKey].stop();
-                    delete calculatedObjectEffectScopes[removedKey];
+                for (const sameKey of sameKeys) {
+                    if (calculatedObjectOriginalFunctions[sameKey] !== state.calculatedObjectRules[sameKey]) {
+                        removedKeys.add(sameKey);
+                        addedKeys.add(sameKey);
+                    }
                 }
-            }
-            for (const addedKey of addedKeys) {
-                calculatedObjectOriginalFunctions[addedKey] = state.calculatedObjectRules[addedKey];
-                calculatedObjectEffectScopes[addedKey] = effectScope();
-                calculatedObjectEffectScopes[addedKey].run(() => {
-                    state.calculatedObject[addedKey] = computed(() =>
-                        calculatedObjectOriginalFunctions[addedKey](state.object, state.relatedObject)
-                    );
-                });
-            }
-        });
+                for (const removedKey of removedKeys) {
+                    delete calculatedObjectOriginalFunctions[removedKey];
+                    delete state.calculatedObject[removedKey];
+                    if (calculatedObjectEffectScopes[removedKey]) {
+                        calculatedObjectEffectScopes[removedKey].stop();
+                        delete calculatedObjectEffectScopes[removedKey];
+                    }
+                }
+                for (const addedKey of addedKeys) {
+                    calculatedObjectOriginalFunctions[addedKey] = state.calculatedObjectRules[addedKey];
+                    calculatedObjectEffectScopes[addedKey] = effectScope();
+                    calculatedObjectEffectScopes[addedKey].run(() => {
+                        state.calculatedObject[addedKey] = computed(() =>
+                            calculatedObjectOriginalFunctions[addedKey](state.object, state.relatedObject)
+                        );
+                    });
+                }
+            },
+            { immediate: true }
+        );
 
         watchesRunning = useWatchesRunning({
             triggerRefs: [computed(() => (!isEmpty(state.calculatedObjectRules) ? parentState.loading : false))],

package/use/objectInstance.js

@@ -59,13 +59,13 @@ import { reactive, toRef } from "vue";
  * The functions available on the object instance.
  *
  * @typedef {object} ObjectInstanceFunctions
- * @property {Function} create - Called to turn the current object into a new object on the server.
- * @property {Function} retrieve - Called to retrieve the current object by pk from the server.
- * @property {Function} update - Called to update the current object on the server.
- * @property {Function} delete - Called to delete the current object on the server.
- * @property {Function} patch - Called to patch the current object on the server.
- * @property {Function} clearError - Called to clear the error state.
- * @property {Function} clear - Called to clear the object state.
+ * @property {(args: { object: object }) => Promise<boolean>} create - Called to turn the current object into a new object on the server.
+ * @property {() => Promise<boolean>} retrieve - Called to retrieve the current object by pk from the server.
+ * @property {(args: { object: CrudObject }) => Promise<boolean>} update - Called to update the current object on the server.
+ * @property {() => Promise<boolean>} delete - Called to delete the current object on the server.
+ * @property {(args: { partialObject: CrudObject }) => Promise<boolean>} patch - Called to patch the current object on the server.
+ * @property {import('./loadingError.js').ClearErrorFn} clearError - Called to clear the error state.
+ * @property {() => void} clear - Called to clear the object state.
  */
 
 /**
@@ -362,7 +362,7 @@ export function useObjectInstance({ props, functions = {} }) {
         assignReactiveObject(state.object, {});
     }
 
-    return reactive({
+    return {
         state,
         create,
         retrieve,
@@ -371,5 +371,5 @@ export function useObjectInstance({ props, functions = {} }) {
         patch,
         clearError: loadingError.clearError,
         clear,
-    });
+    };
 }

package/utils/keepAliveTry.js

@@ -0,0 +1,28 @@
+import { onActivated, onDeactivated } from "vue";
+import { getLifeCycleTarget } from "@vueuse/core";
+
+/**
+ * If there is an active component, set up an onActivated hook.
+ *
+ * @param {Function} fn - The function to call.
+ * @param {any} [target] - The target to call the function on.
+ */
+export function tryOnActivated(fn, target) {
+    const instance = getLifeCycleTarget(target);
+    if (instance) {
+        onActivated(fn, target);
+    }
+}
+
+/**
+ * If there is an active component, set up an onDeactivated hook.
+ *
+ * @param {Function} fn - The function to call.
+ * @param {any} [target] - The target to call the function on.
+ */
+export function tryOnDeactivated(fn, target) {
+    const instance = getLifeCycleTarget(target);
+    if (instance) {
+        onDeactivated(fn, target);
+    }
+}