@arrai-innovations/reactive-helpers 18.0.1 → 18.1.0

package/config/listCrud.js

@@ -86,7 +86,7 @@ const defaultCrud = {
  */
 
 /**
- * @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 {(ExecuteActionFnArgs)=>Promise<import('./objectCrud.js').CrudResponse|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

@@ -1,7 +1,8 @@
 import { addOrUpdateReactiveObject } from "../utils/assignReactiveObject.js";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import isFunction from "lodash-es/isFunction.js";
-import { isReactive, toRef } from "vue";
+import { isReactive, readonly, toRef } from "vue";
+import { CancellablePromise } from "../utils/cancellablePromise.js";
 
 /**
  * Configuration for the default object crud functions.
@@ -9,89 +10,160 @@ import { isReactive, toRef } from "vue";
  * @module config/objectCrud.js
  */
 
-const defaultCrud = {
-    args: {},
-    retrieve: undefined,
-    create: undefined,
-    update: undefined,
-    patch: undefined,
-    delete: undefined,
-    subscribe: undefined,
+/**
+ * @template T
+ * @param {string} name - The name of the method.
+ * @returns {(...args:any[]) => import('../utils/cancellablePromise.js')
+ *                               .MaybeCancellablePromise<T>} - A function that returns a rejected promise with an error message.
+ */
+const missingMethod = (name) => () => {
+    return CancellablePromise.reject(new Error(`Crud method "${name}" is not implemented.`));
+};
+
+/**
+ * @template T
+ * @param {string} name - The name of the method.
+ * @returns {(...args:any[]) => import('../utils/cancellablePromise.js')
+ *                               .CancellablePromise<T>} - A function that returns a rejected promise with an error message.
+ */
+const requiredCancelMissingMethod = (name) => () => {
+    return CancellablePromise(
+        new Promise(() => {
+            return Promise.reject(new Error(`Crud method "${name}" is not implemented.`));
+        }),
+        () => {
+            // do nothing
+        }
+    );
 };
 
+/**
+ * @typedef {{[key:string]: any}} ObjectCrudArgsArgs
+ */
+
 /**
  * Defines the CRUD-related functions and additional utilities provided by the object instance.
  *
  * @typedef {object} ObjectCrudArgsProperties
- * @property {object} [args={}] - The arguments to be passed to the crud functions.
+ * @property {ObjectCrudArgsArgs} args - The arguments to be passed to the crud functions.
+ */
+
+/**
+ * @typedef {object} ObjectCrudArgsOption
+ * @property {ObjectCrudArgsArgs} [crudArgs={}] - The arguments to be passed to the crud functions.
  */
 
 /**
  * @typedef {object} CreateDetailArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
- * @property {object} object - The data to be acted upon.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} crudArgs - The arguments to be passed to the crud functions.
+ * @property {{[key:string]: any}} object - The data to be acted upon.
+ * @property {{[key:string]: any}} retrieveArgs - The arguments to be passed to the retrieve function.
  * @property {string} pkKey - The key name of the primary key.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
  */
 
 /**
  * @typedef {object} RetrieveDetailArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @property {{[key:string]: any}} crudArgs - The arguments to be passed to the crud functions.
  * @property {string} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
  */
 
 /**
  * @typedef {object} UpdateDetailArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
- * @property {import('../use/objectInstance.js').CrudObject} object - The data to be acted upon.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} crudArgs - The arguments to be passed to the crud functions.
+ * @property {import('../use/objectInstance.js').ExistingCrudObject} object - The data to be acted upon.
+ * @property {{[key:string]: any}} retrieveArgs - The arguments to be passed to the retrieve function.
  * @property {string} pkKey - The key name of the primary key.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
  */
 
 /**
  * @typedef {object} DeleteDetailArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @property {{[key:string]: any}} crudArgs - The arguments to be passed to the crud functions.
  * @property {string} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
  */
 
 /**
  * @typedef {object} PartialDetailArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @property {{[key:string]: any}} crudArgs - The arguments to be passed to the crud functions.
  * @property {string} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} partialObject - The data to be acted upon.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} partialObject - The data to be acted upon.
+ * @property {{[key:string]: any}} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ */
+
+/**
+ * @callback CrudSubscribeCallback
+ * @param {import('../use/objectInstance.js').ExistingCrudObject} data - The data to be passed to the callback.
+ * @param {string} action - The action that was performed.
  */
 
 /**
  * @typedef {object} SubscribeArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @property {{[key:string]: any}} crudArgs - The arguments to be passed to the crud functions.
  * @property {string} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
- * @property {(
- *     data:import('../use/objectInstance.js').CrudObject, action:string
- * ) => void} callback - The callback to be called when the object is updated.
+ * @property {{[key:string]: any}} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {CrudSubscribeCallback} callback - The callback to be called when the object is updated.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ */
+
+/**
+ * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string>} CrudResponse
  */
 
 /**
- * @typedef {Promise<object|string> & { cancel: () => Promise<void>|void }} ResponseData
+ * @callback CrudCreateFn
+ * @param {CreateDetailArgs} args - The arguments to be passed to the create function.
+ * @returns {CrudResponse} - The response data from the create function.
+ */
+
+/**
+ * @callback CrudRetrieveFn
+ * @param {RetrieveDetailArgs} args - The arguments to be passed to the retrieve function.
+ * @returns {CrudResponse} - The response data from the retrieve function.
+ */
+
+/**
+ * @callback CrudUpdateFn
+ * @param {UpdateDetailArgs} args - The arguments to be passed to the update function.
+ * @returns {CrudResponse} - The response data from the update function.
+ */
+
+/**
+ * @callback CrudPatchFn
+ * @param {PartialDetailArgs} args - The arguments to be passed to the patch function.
+ * @returns {CrudResponse} - The response data from the patch function.
+ */
+
+/**
+ * @callback CrudDeleteFn
+ * @param {DeleteDetailArgs} args - The arguments to be passed to the delete function.
+ * @returns {CrudResponse} - The response data from the delete function.
+ */
+
+/**
+ * @callback CrudSubscribeFn
+ * @param {SubscribeArgs} args - The arguments to be passed to the subscribe function.
+ * @returns {import('../utils/cancellablePromise.js').CancellablePromise<void>} - The cancellable promise.
  */
 
 /**
  * Defines the CRUD-related functions and additional utilities provided by the object instance.
  *
  * @typedef {object} ObjectCrudFunctions
- * @property {(CreateDetailArgs)=>ResponseData} [create] - A function to be used instead of the default crud create function.
- * @property {(RetrieveDetailArgs)=>ResponseData} [retrieve] - A function to be used instead of the default crud retrieve function.
- * @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 & { cancel: () => Promise<void>|void }} [subscribe] - A function to be used instead of the default crud subscribe function.
+ * @property {CrudCreateFn} [create] - A function to be used instead of the default crud create function.
+ * @property {CrudRetrieveFn} [retrieve] - A function to be used instead of the default crud retrieve function.
+ * @property {CrudUpdateFn} [update] - A function to be used instead of the default crud update function.
+ * @property {CrudDeleteFn} [delete] - A function to be used instead of the default crud delete function.
+ * @property {CrudPatchFn} [patch] - A function to be used instead of the default crud patch function.
+ * @property {CrudSubscribeFn} [subscribe] - A function to be used instead of the default crud subscribe function.
  */
 
 /**
@@ -101,6 +173,18 @@ const defaultCrud = {
  *
  */
 
+const _defaultCrud = {
+    args: {},
+    retrieve: /** @type {CrudRetrieveFn} */ missingMethod("retrieve"),
+    create: /** @type {CrudCreateFn} */ missingMethod("create"),
+    update: /** @type {CrudUpdateFn} */ missingMethod("update"),
+    patch: /** @type {CrudPatchFn} */ missingMethod("patch"),
+    delete: /** @type {CrudDeleteFn} */ missingMethod("delete"),
+    subscribe: /** @type {CrudSubscribeFn} */ requiredCancelMissingMethod("subscribe"),
+};
+
+export const defaultCrud = readonly(_defaultCrud);
+
 /**
  * Set the object crud functions.
  *
@@ -108,14 +192,14 @@ const defaultCrud = {
  * @throws {Error} - if unknown keys are passed.
  */
 export const setObjectCrud = ({ retrieve, create, update, patch, delete: deleteFn, subscribe, args = {}, ...rest }) => {
-    defaultCrud.retrieve = retrieve;
-    defaultCrud.create = create;
-    defaultCrud.update = update;
-    defaultCrud.patch = patch;
-    defaultCrud.delete = deleteFn;
-    defaultCrud.subscribe = subscribe;
+    _defaultCrud.retrieve = retrieve ?? missingMethod("retrieve");
+    _defaultCrud.create = create ?? missingMethod("create");
+    _defaultCrud.update = update ?? missingMethod("update");
+    _defaultCrud.patch = patch ?? missingMethod("patch");
+    _defaultCrud.delete = deleteFn ?? missingMethod("delete");
+    _defaultCrud.subscribe = subscribe ?? requiredCancelMissingMethod("subscribe");
     // defensive cloning
-    Object.assign(defaultCrud.args, cloneDeep(args));
+    Object.assign(_defaultCrud.args, cloneDeep(args));
     if (Object.keys(rest).length) {
         throw new Error(`Unknown key(s) passed to setObjectCrud: ${Object.keys(rest).join(", ")}`);
     }
@@ -124,17 +208,15 @@ export const setObjectCrud = ({ retrieve, create, update, patch, delete: deleteF
 /**
  * Get the previously set object crud functions.
  *
- * @param {import("vue").UnwrapNestedRefs<object>} reactiveCrud - The reactive object you want to add the resulting crud to.
+ * @param {import("vue").UnwrapNestedRefs<ObjectCrudArgsProperties>} reactiveCrud - The reactive object you want to add the resulting crud to.
  * @param {object} options - The options for the reactive crud object.
- * @param {import("vue").UnwrapNestedRefs<{
- *     crudArgs: ObjectCrudArgsProperties|undefined,
- * }>} [options.props] - The props with any passed crudArgs.
+ * @param {import("vue").UnwrapNestedRefs<ObjectCrudArgsOption>} [options.props] - The props with any passed crudArgs.
  * @param {ObjectCrudFunctions} [options.functions] - Any functions to override the default crud functions.
  * @throws {Error} - If an invalid function is passed, or if the function is not a function.
  */
 export const getObjectCrud = (reactiveCrud, { props, functions } = {}) => {
     // don't mutate the default crud
-    Object.assign(reactiveCrud, cloneDeep(defaultCrud));
+    Object.assign(reactiveCrud, cloneDeep(_defaultCrud));
     if (props?.crudArgs) {
         addOrUpdateReactiveObject(reactiveCrud.args, props.crudArgs);
     }

package/index.js

@@ -23,8 +23,11 @@ export * from "./use/proxyLoadingError.js";
 export * from "./use/search.js";
 export * from "./use/watchesRunning.js";
 export * from "./utils/assignReactiveObject.js";
+export * from "./utils/cancellableFetch.js";
+export * from "./utils/cancellablePromise.js";
 export * from "./utils/classes.js";
 export * from "./utils/compact.js";
+export * from "./utils/deepUnref.js";
 export * from "./utils/deleteKey.js";
 export * from "./utils/flattenPaths.js";
 export * from "./utils/getFakePk.js";

package/package.json

@@ -1,9 +1,24 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "18.0.1",
+    "version": "18.1.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",
+    "types": "types/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./index.js",
+            "types": "./types/index.d.ts"
+        }
+    },
+    "files": [
+        "index.js",
+        "README.md",
+        "use/",
+        "utils/",
+        "config/",
+        "types/"
+    ],
     "directories": {
         "use": "use",
         "utils": "utils",

package/types/config/listCrud.d.ts

@@ -0,0 +1,153 @@
+export function setListCrud({ list, bulkDelete, subscribe, executeAction, args, ...rest }: ListCrudFunctions & Partial<ListCrudArgs>): void;
+export function getListCrud(reactiveCrud: import("vue").UnwrapNestedRefs<ListCrudFunctions & ListCrudArgs>, { props, functions }?: {
+    props?: import("vue").UnwrapNestedRefs<{
+        crudArgs: object | undefined;
+    }>;
+    functions?: ListCrudFunctions & ListCrudArgs;
+}): void;
+export type PaginateInfo = {
+    /**
+     * - The total records.
+     */
+    totalRecords: number;
+    /**
+     * - The total pages.
+     */
+    totalPages: number;
+    /**
+     * - The per page.
+     */
+    perPage: number;
+};
+export type PageCallback = (newObjects: import("../use/listInstance.js").ListObject, paginationInfo: PaginateInfo | undefined) => void;
+export type ListFnArgs = {
+    /**
+     * - The arguments to be passed to the crud functions.
+     */
+    crudArgs: object;
+    /**
+     * - The key name of the primary key.
+     */
+    pkKey: string;
+    /**
+     * - The arguments to be passed to the retrieve function.
+     */
+    retrieveArgs: object;
+    /**
+     * - The arguments to be passed for list crud functions.
+     */
+    listArgs: object;
+    /**
+     * - The method to call with new page(s) of data received.
+     */
+    pageCallback: PageCallback;
+    /**
+     * - A ref to a boolean indicating whether the request has
+     * been cancelled.
+     */
+    isCancelled: Readonly<import("vue").Ref<boolean>>;
+};
+export type DeleteFnArgs = {
+    /**
+     * - The arguments to be passed to the crud functions.
+     */
+    crudArgs: object;
+    /**
+     * - The ids of the objects to be deleted.
+     */
+    pks: string[];
+    /**
+     * - The key name of the primary key.
+     */
+    pkKey: string;
+};
+export type SubscriptionEventCallback = (newOrUpdatedOrDeleteObject: import("../use/listInstance.js").ListObject | string, action: "create" | "update" | "delete") => void;
+export type SubscribeFnArgs = {
+    /**
+     * - The arguments to be passed to the crud functions.
+     */
+    crudArgs: object;
+    /**
+     * - The key name of the primary key.
+     */
+    pkKey: string;
+    /**
+     * - The arguments to be passed to the retrieve function.
+     */
+    retrieveArgs: object;
+    /**
+     * - The arguments to be passed for list crud functions.
+     */
+    listArgs: object;
+    /**
+     * - The method to call when new data is received.
+     */
+    subscriptionEventCallback: SubscriptionEventCallback;
+};
+export type ExecuteActionFnArgs = {
+    /**
+     * - The arguments to be passed to the crud functions.
+     */
+    crudArgs: object;
+    /**
+     * - The ids of the objects to be acted upon.
+     */
+    pks: string[];
+    /**
+     * - The key name of the primary key.
+     */
+    pkKey: string;
+    /**
+     * - The action to execute.
+     */
+    action: string;
+};
+/**
+ * - The list function to get a list of items, returning a boolean indicating success.
+ */
+export type ListFn = (ListFnArgs: any) => Promise<boolean> & {
+    cancel: () => Promise<void> | void;
+};
+/**
+ * - The delete function to bulk delete a list of items.
+ */
+export type BulkDeleteFn = (DeleteFnArgs: any) => Promise<boolean> & {
+    cancel: () => Promise<void> | void;
+};
+/**
+ * - The subscribe function to set up a subscription to a list of items.
+ */
+export type SubscribeFn = (SubscribeFnArgs: any) => Promise<boolean> & {
+    cancel: () => Promise<void> | void;
+};
+/**
+ * - The function to execute a certain action on a list of items, returning the response data or false.
+ */
+export type ExecuteActionFn = (ExecuteActionFnArgs: any) => Promise<import("./objectCrud.js").CrudResponse | false> & {
+    cancel: () => Promise<void> | void;
+};
+export type ListCrudFunctions = {
+    /**
+     * - The list function to get a list of items.
+     */
+    list?: ListFn;
+    /**
+     * - The delete function to bulk delete a list of items.
+     */
+    bulkDelete?: BulkDeleteFn;
+    /**
+     * - The  function to execute a certain action on a list of items.
+     */
+    executeAction?: ExecuteActionFn;
+    /**
+     * - The subscribe function to get a subscription to a list of items.
+     */
+    subscribe?: SubscribeFn;
+};
+export type ListCrudArgs = {
+    /**
+     * - The default arguments for the crud functions.
+     */
+    args?: object;
+};
+//# sourceMappingURL=listCrud.d.ts.map

package/types/config/listCrud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listCrud.d.ts","sourceRoot":"","sources":["../../config/listCrud.js"],"names":[],"mappings":"AA+GO,2FAJI,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,GAEvC,IAAI,CAWhB;AAYM,0CAPI,OAAO,KAAK,EAAE,gBAAgB,CAAC,iBAAiB,GAAG,YAAY,CAAC,yBAExE;IAEa,KAAK,GAFV,OAAO,KAAK,EAAE,gBAAgB,CAAC;QACnC,QAAQ,EAAE,MAAM,GAAC,SAAS,CAAC;KAC9B,CAAC;IACiD,SAAS,GAApD,iBAAiB,GAAG,YAAY;CAC1C,QAmBA;;;;;kBAjIa,MAAM;;;;gBACN,MAAM;;;;aACN,MAAM;;2BAIP,CACN,UAAU,EAAC,OAAO,wBAAwB,EAAE,UAAU,EACtD,cAAc,EAAE,YAAY,GAAC,SAAS,KACvC,IAAI;;;;;cAKI,MAAM;;;;WACN,MAAM;;;;kBACN,MAAM;;;;cACN,MAAM;;;;kBACN,YAAY;;;;;iBACZ,QAAQ,CAAC,OAAO,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;;;;;;cAMpC,MAAM;;;;SACN,MAAM,EAAE;;;;WACR,MAAM;;wCAIP,CACN,0BAA0B,EAAC,OAAO,wBAAwB,EAAE,UAAU,GAAC,MAAM,EAC7E,MAAM,EAAE,QAAQ,GAAC,QAAQ,GAAC,QAAQ,KACnC,IAAI;;;;;cAKI,MAAM;;;;WACN,MAAM;;;;kBACN,MAAM;;;;cACN,MAAM;;;;+BACN,yBAAyB;;;;;;cAKzB,MAAM;;;;SACN,MAAM,EAAE;;;;WACR,MAAM;;;;YACN,MAAM;;;;;qBAIP,CAAC,UAAU,KAAA,KAAG,OAAO,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,CAAA;CAAE;;;;2BAIrE,CAAC,YAAY,KAAA,KAAG,OAAO,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,CAAA;CAAE;;;;0BAIvE,CAAC,eAAe,KAAA,KAAG,OAAO,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,CAAA;CAAE;;;;8BAI1E,CAAC,mBAAmB,KAAA,KAAG,OAAO,CAAC,OAAO,iBAAiB,EAAE,YAAY,GAAC,KAAK,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,CAAA;CAAE;;;;;WAKlH,MAAM;;;;iBACN,YAAY;;;;oBACZ,eAAe;;;;gBACf,WAAW;;;;;;WAKX,MAAM"}