@arrai-innovations/reactive-helpers 14.1.0 → 15.0.0

package/config/listCrud.js

@@ -14,6 +14,7 @@ const defaultCrud = {
     list: undefined,
     bulkDelete: undefined,
     subscribe: undefined,
+    executeAction: undefined,
 };
 
 /**
@@ -76,10 +77,15 @@ const defaultCrud = {
  * @typedef {(SubscribeFnArgs)=>void} SubscribeFn
  */
 
+/**
+ * @typedef {(ExecuteActionFnArgs)=>void} ExecuteActionFn
+ */
+
 /**
  * @typedef {object} ListCrudFunctions
  * @property {ListFn} [list] - The list function to get a list of items.
  * @property {BulkDeleteFn} [bulkDelete] - The delete function to bulk delete a list of items.
+ * @property {ExecuteActionFn} [executeAction] - The  function to execute a certain action on a list of items.
  * @property {SubscribeFn} [subscribe] - The subscribe function to get a subscription to a list of items.
  */
 
@@ -95,10 +101,11 @@ const defaultCrud = {
  * @throws {Error} - If unknown keys are passed.
  * @returns {void}
  */
-export const setListCrud = ({ list, bulkDelete, subscribe, args = {}, ...rest }) => {
+export const setListCrud = ({ list, bulkDelete, subscribe, executeAction, args = {}, ...rest }) => {
     defaultCrud.list = list;
     defaultCrud.subscribe = subscribe;
     defaultCrud.bulkDelete = bulkDelete;
+    defaultCrud.executeAction = executeAction;
     Object.assign(defaultCrud.args, cloneDeep(args));
     if (Object.keys(rest).length) {
         throw new Error(`Unknown key(s) passed to setListCrud: ${Object.keys(rest).join(", ")}`);

package/docs/config/listCrud.md

@@ -54,6 +54,12 @@ The default arguments for the crud functions.
 
 The delete function to bulk delete a list of items.
 
+##### executeAction
+
+> **executeAction**: [`ExecuteActionFn`](listCrud.md#executeactionfn)
+
+The  function to execute a certain action on a list of items.
+
 ##### list
 
 > **list**: [`ListFn`](listCrud.md#listfn)
@@ -187,6 +193,22 @@ The method to call when new data is received.
 
 ***
 
+### ExecuteActionFn()
+
+> **ExecuteActionFn**\<\>: (`ExecuteActionFnArgs`) => `void`
+
+#### Type Parameters
+
+#### Parameters
+
+• **ExecuteActionFnArgs**: `any`
+
+#### Returns
+
+`void`
+
+***
+
 ### ListFn()
 
 > **ListFn**\<\>: (`ListFnArgs`) => `void`
@@ -275,6 +297,10 @@ The default arguments for the crud functions.
 
 The delete function to bulk delete a list of items.
 
+• **reactiveCrud.executeAction**: [`ExecuteActionFn`](listCrud.md#executeactionfn)
+
+The  function to execute a certain action on a list of items.
+
 • **reactiveCrud.list**: [`ListFn`](listCrud.md#listfn)
 
 The list function to get a list of items.

package/docs/use/list.md

@@ -6,6 +6,56 @@
 
 # use/list
 
+## Classes
+
+### ListError
+
+Custom error class for use list errors.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### new ListError()
+
+> **new ListError**(`message`, `code`): [`ListError`](list.md#listerror)
+
+Creates a new ListError.
+
+###### Parameters
+
+• **message**: `string`
+
+The error message.
+
+• **code**: `string`
+
+The error code.
+
+###### Returns
+
+[`ListError`](list.md#listerror)
+
+###### Overrides
+
+`Error.constructor`
+
+#### Properties
+
+##### code
+
+> **code**: `string`
+
+##### name
+
+> **name**: `string`
+
+###### Inherited from
+
+`Error.name`
+
 ## Interfaces
 
 ### ListManagerProperties
@@ -280,6 +330,10 @@ The options for the list./.
 ```vue
 ```
 
+#### Throws
+
+- If required options are not provided.
+
 ***
 
 ### useLists()

package/docs/use/listInstance.md

@@ -77,6 +77,16 @@ Adds an object to the list.
 
 `void`
 
+##### bulkDelete()
+
+> **bulkDelete**: () => `Promise`\<`void`\>
+
+Initiates a bulk delete operation on all objects in the list.
+
+###### Returns
+
+`Promise`\<`void`\>
+
 ##### clearList()
 
 > **clearList**: () => `void`
@@ -115,6 +125,16 @@ Deletes an object from the list by pk.
 
 `void`
 
+##### executeAction()
+
+> **executeAction**: () => `Promise`\<`void`\>
+
+Initiates an action on all objects in the list.
+
+###### Returns
+
+`Promise`\<`void`\>
+
 ##### getFakePk()
 
 > **getFakePk**: () => `string`
@@ -182,6 +202,13 @@ Default implementation are used as set by `setListCrud`.
 Provide the implementation for the bulkDelete
  function.
 
+###### executeAction
+
+> **executeAction**: [`ExecuteActionFn`](../config/listCrud.md#executeactionfn)
+
+Provide the implementation for the executeAction
+ function.
+
 ###### list
 
 > **list**: [`ListFn`](../config/listCrud.md#listfn)
@@ -493,7 +520,7 @@ watch(toRef(props, "someListFilter"), (newValue, oldValue) => {
 
 #### Throws
 
-If the props are missing.
+If the props or keepOldPages are missing.
 
 ***
 

package/docs/use/listSubscription.md

@@ -362,7 +362,9 @@ const listSubscription = useListSubscription({ props: listSubscriptionProps });
 
 #### Throws
 
-- If both listInstance and props are passed, or if neither are passed.
+- If both listInstance and props are passed, or if neither are
+passed. Also thrown if clearListOnListIntentTriggered is not passed or if neither listInstance
+nor keepOldPages are passed.
 
 ***
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "14.1.0",
+    "version": "15.0.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",

package/tests/unit/config/listCrud.spec.js

@@ -30,7 +30,9 @@ describe("config/listCrud.js", () => {
              */
             const retrievedCrud = reactive({});
             expect(() => getListCrud(retrievedCrud)).not.toThrow();
-            expect(new Set(Object.keys(retrievedCrud))).toEqual(new Set(["list", "bulkDelete", "subscribe", "args"]));
+            expect(new Set(Object.keys(retrievedCrud))).toEqual(
+                new Set(["list", "bulkDelete", "executeAction", "subscribe", "args"])
+            );
             expect(retrievedCrud.args).not.toBe(crud.args);
             expect(retrievedCrud.args).toEqual(crud.args);
             expect(retrievedCrud.list).toBe(crud.list);

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

@@ -15,8 +15,8 @@ describe("use/listCalculated", () => {
         AwaitNot = watchesModule.AwaitNot;
     });
     it("should return a list of calculated items", async () => {
-        const mainListInstance = useListInstance({ props: { pkKey: "id" } });
-        const calculatedListInstance = useListInstance({ props: { pkKey: "id" } });
+        const mainListInstance = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
+        const calculatedListInstance = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
         mainListInstance.addListObject({
             id: "1",
             name: "main",
@@ -77,8 +77,8 @@ describe("use/listCalculated", () => {
         });
     });
     it("should allow calculated objects to return results based on related objects", async () => {
-        const mainListInstance = useListInstance({ props: { pkKey: "id" } });
-        const relatedListInstance = useListInstance({ props: { pkKey: "id" } });
+        const mainListInstance = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
+        const relatedListInstance = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
         mainListInstance.addListObject({
             id: "1",
             name: "main",

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

@@ -19,7 +19,7 @@ describe("use/listFilter", () => {
     });
 
     it("should match an allowed filter function", async () => {
-        const list = useListInstance({ props: { pkKey: "id" } });
+        const list = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
         const filter = useListFilter({
             parentState: list.state,
             allowedFilter: (object) => object.id === 1 || object.id === 3,
@@ -65,7 +65,7 @@ describe("use/listFilter", () => {
         });
     });
     it("should match an excluded filter function", async () => {
-        const list = useListInstance({ props: { pkKey: "id" } });
+        const list = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
         const filter = useListFilter({
             parentState: list.state,
             excludedFilter: (object) => object.id == 2 || object.id == 4,
@@ -111,7 +111,7 @@ describe("use/listFilter", () => {
         });
     });
     it("no args: returns objects unfiltered", async () => {
-        const listInstance = useListInstance({ props: { pkKey: "id" } });
+        const listInstance = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
         const listItems = [
             { id: 4, name: "four", has_things: true },
             { id: 2, name: "two", has_things: true },
@@ -135,7 +135,7 @@ describe("use/listFilter", () => {
             vi.resetAllMocks();
             const orderByRules = [{ key: "name", desc: true, localeCompare: false }];
             const sortThrottleWait = 0;
-            const listInstance = useListInstance({ props: { pkKey: "id" } });
+            const listInstance = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
             const listItems = [
                 { id: 4, name: "four", has_things: true },
                 { id: 2, name: "two", has_things: true },
@@ -177,6 +177,7 @@ describe("use/listFilter", () => {
                         fields,
                     },
                 },
+                keepOldPages: false,
             });
             const listInstanceB = useListInstance({
                 props: {
@@ -186,6 +187,7 @@ describe("use/listFilter", () => {
                         fields,
                     },
                 },
+                keepOldPages: false,
             });
             const excludedFilter = (object) => object.id === 1 || object.name === "three";
             const allowedFilter = (object) => object.id === 2 || object.name === "four";
@@ -223,7 +225,7 @@ describe("use/listFilter", () => {
     });
     describe("useListFilters updates index when", () => {
         it("parentInstance.objects is updated", async () => {
-            const list = useListInstance({ props: { pkKey: "id" } });
+            const list = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
             const filter = useListFilter({
                 parentState: list.state,
                 allowedFilter: (object) => !!object.allowed?.every((e) => e),
@@ -264,8 +266,8 @@ describe("use/listFilter", () => {
             });
         });
         it("parentInstance.relatedObjects is updated", async () => {
-            const list = useListInstance({ props: { pkKey: "id" } });
-            const relatedList = useListInstance({ props: { pkKey: "id" } });
+            const list = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
+            const relatedList = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
             const related = useListRelated({
                 parentState: list.state,
                 relatedObjectsRules: {
@@ -320,7 +322,7 @@ describe("use/listFilter", () => {
             });
         });
         it("parentInstance.calculatedObjects is updated", async () => {
-            const list = useListInstance({ props: { pkKey: "id" } });
+            const list = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
             const calculated = useListCalculated({
                 parentState: list.state,
                 calculatedObjectsRules: reactive({
@@ -364,7 +366,7 @@ describe("use/listFilter", () => {
         });
     });
     it("you can use nested useListFilters", async () => {
-        const list = useListInstance({ props: { pkKey: "id" } });
+        const list = useListInstance({ props: { pkKey: "id" }, keepOldPages: false });
 
         function filter1AllowedFilter(object) {
             return object.has_things && object.has_stuff;