@arrai-innovations/reactive-helpers 14.1.0 → 16.0.0

package/config/listCrud.js

@@ -14,6 +14,7 @@ const defaultCrud = {
     list: undefined,
     bulkDelete: undefined,
     subscribe: undefined,
+    executeAction: undefined,
 };
 
 /**
@@ -65,21 +66,34 @@ 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)=>Promise<boolean> & { cancel: () => Promise<void>|void }} BulkDeleteFn - The delete function to bulk delete a list of items.
  */
 
 /**
- * @typedef {(DeleteFnArgs)=>void} BulkDeleteFn
+ * @typedef {(SubscribeFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} SubscribeFn - The subscribe function to set up a subscription to a list of items.
  */
 
 /**
- * @typedef {(SubscribeFnArgs)=>void} SubscribeFn
+ * @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.
  */
 
 /**
  * @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 +109,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/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
@@ -54,6 +84,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)
@@ -173,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
 
@@ -183,13 +221,33 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<`boolean`\> & `object`
+
+***
+
+### ExecuteActionFn()
+
+> **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
+
+#### Parameters
+
+• **ExecuteActionFnArgs**: `any`
+
+#### Returns
+
+`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
 
@@ -199,7 +257,7 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<`boolean`\> & `object`
 
 ***
 
@@ -223,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
 
@@ -233,7 +293,7 @@ The method to call when new data is received.
 
 #### Returns
 
-`void`
+`Promise`\<`boolean`\> & `object`
 
 ***
 
@@ -275,6 +335,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/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/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`\<`boolean`\>
+
+Initiates a bulk delete operation on all objects in the list, returning a promise to a boolean indicating success.
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
 ##### clearList()
 
 > **clearList**: () => `void`
@@ -115,6 +125,16 @@ Deletes an object from the list by pk.
 
 `void`
 
+##### executeAction()
+
+> **executeAction**: () => `Promise`\<`any`\>
+
+Initiates an action on all objects in the list, returning the response, or false if the action failed.
+
+###### Returns
+
+`Promise`\<`any`\>
+
 ##### getFakePk()
 
 > **getFakePk**: () => `string`
@@ -127,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()
 
@@ -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/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()