@arrai-innovations/reactive-helpers 18.1.0 → 20.0.0

package/README.md

@@ -70,11 +70,11 @@ The container for your list of objects, providing loading or error status.
 import { setListCrud } from "@arrai-innovations/reactive-helpers";
 
 setListCrud({
-    list: async function listCrudAdaptor({ crudArgs, retrieveArgs, listArgs, pageCallback }) {
+    list: async function listCrudAdaptor({ target, params, pageCallback }) {
         // todo: your implemenation here.
-        const listOfObjects = await talkToServer(crudArgs, retrieveArgs, listArgs);
+        const listOfObjects = await talkToServer(target, params);
         pageCallback(listOfObjects);
-        const nextListOfObjects = await talkToServerAgain(crudArgs, retrieveArgs, listArgs);
+        const nextListOfObjects = await talkToServerAgain(target, params);
         pageCallback(nextListOfObjects);
     },
 });
@@ -86,15 +86,12 @@ import { useListInstance } from "@arrai-innovations/reactive-helpers";
 import { reactive } from "vue";
 
 const listProps = reactive({
-    // crudArgs are implementation specific to your crud functions.
-    crudArgs: {
+    // target are implementation specific to your crud handlers.
+    target: {
         stream: "contacts",
     },
     pkKey: "id",
-    retrieveArgs: {
-        fields: ["id", "has_name", "lexical_name", "organization", "phone"],
-    },
-    listArgs,
+    params,
 });
 const contacts = useListInstance({
     props: listProps,
@@ -110,12 +107,12 @@ console.log(contacts.error);
 console.log(contacts.objects);
 // { contacts keyed by 'id' }
 // change list or retrieve args directly
-contacts.state.retrieveArgs.fields.push("message_count");
+contacts.state.params.fields.push("message_count");
 await contacts.list();
 console.log(contacts.objects);
 // { contacts keyed by 'id' with message_count  }
 // change list or retrieve args indirectly
-listProps.listArgs.has_organization = false;
+listProps.params.has_organization = false;
 await contacts.list();
 console.log(contacts.objects);
 // { contacts keyed by 'id' with organizationless contacts  }
@@ -130,7 +127,7 @@ Adds functionality to a list instance to receive updates from the server.
 import { setListCrud } from "@arrai-innovations/reactive-helpers";
 setListCrud({
     ..., // in addition to the list crud adaptor above
-    subscribe: function subscribeCrudAdaptor({ crudArgs, retrieveArgs, listArgs, eventCallback }) {
+    subscribe: function subscribeCrudAdaptor({ target, params, eventCallback }) {
         // todo: your implemenation here.
         const subscription = talkToServer(function (data, action) {
             eventCallback(data, action);
@@ -150,19 +147,17 @@ import { useListInstance, useListSubscription } from "@arrai-innovations/reactiv
 import { reactive } from "vue";
 
 const listProps = reactive({
-    // crudArgs are implementation specific to your crud functions.
-    crudArgs: {
+    // target are implementation specific to your crud handlers.
+    target: {
         stream: "contacts",
         includeCreateEvents: true,
         subscribeAction: "subscribe_contacts",
         unsubscribeAction: "unsubscribe_contacts",
     },
     pkKey: "id",
-    retrieveArgs: {
-        fields: ["id", "has_name", "lexical_name", "organization", "phone"],
-    },
-    listArgs: {
+    params: {
         has_organization: true,
+        fields: ["id", "has_name", "lexical_name", "organization", "phone"],
     },
 });
 const contacts = useListInstance({
@@ -179,9 +174,9 @@ contactsSubscription.subscribe();
 // stop getting updates.
 contactsSubscription.unsubscribe();
 // re-retreive the list of existing contacts including another field.
-contacts.retrieveArgs.fields.push("message_count");
+contacts.params.fields.push("message_count");
 // re-retreive the list of all existing contacts.
-delete contacts.listArgs.has_organization;
+delete contacts.params.has_organization;
 ```
 
 ```js
@@ -190,17 +185,15 @@ import { useListSubscription } from "@arrai-innovations/reactive-helpers";
 import { reactive } from "vue";
 
 const listProps = reactive({
-    // crudArgs are implementation specific to your crud functions.
-    crudArgs: {
+    // target are implementation specific to your crud handlers.
+    target: {
         stream: "contacts",
         includeCreateEvents: true,
         subscribeAction: "subscribe_contacts",
         unsubscribeAction: "unsubscribe_contacts",
     },
-    retrieveArgs: {
+    params: {
         fields: ["id", "has_name", "lexical_name", "organization", "phone"],
-    },
-    listArgs: {
         has_organization: true,
     },
 });
@@ -221,7 +214,7 @@ import { reactive, toRef } from "vue";
 
 const organizationsProps = reactive({
     pkKey: "id",
-    retrieveArgs: {
+    params: {
         fields: ["id", "name"],
     },
 });
@@ -230,7 +223,7 @@ const organizations = useListInstance({
 });
 const contactsProps = reactive({
     pkKey: "id",
-    retrieveArgs: {
+    params: {
         fields: ["id", "lexical_name", "organization"],
     },
 });
@@ -306,7 +299,7 @@ import { nextTick, reactive } from "vue";
 
 const contactsProps = reactive({
     pkKey: "id",
-    retrieveArgs: {
+    params: {
         fields: ["id", "has_name", "has_billing", "lexical_name", "organization"],
     },
 });
@@ -361,7 +354,7 @@ import { reactive, ref } from "vue";
 
 const contactsProps = reactive({
     pkKey: "id",
-    retrieveArgs: {
+    params: {
         fields: ["id", "has_name", "has_billing", "lexical_name", "organization"],
     },
 });
@@ -406,7 +399,7 @@ import { reactive } from "vue";
 
 const contactsProps = reactive({
     pkKey: "id",
-    retrieveArgs: {
+    params: {
         fields: ["id", "has_name", "has_billing", "lexical_name", "organization"],
     },
 });
@@ -451,7 +444,7 @@ import { reactive } from "vue";
 
 const contactsProps = reactive({
     pkKey: "id",
-    retrieveArgs: {
+    params: {
         fields: ["id", "has_name", "lexical_name", "organization"],
     },
 });
@@ -488,19 +481,17 @@ import { useList } from "@arrai-innovations/reactive-helpers";
 import { reactive, toRef } from "vue";
 
 const managedListProps = reactive({
-    // crudArgs are implementation specific to your crud functions.
-    crudArgs: {
+    // target are implementation specific to your crud handlers.
+    target: {
         stream: "contacts",
         includeCreateEvents: true,
         subscribeAction: "subscribe_contacts",
         unsubscribeAction: "unsubscribe_contacts",
     },
     pkKey: "id",
-    retrieveArgs: {
-        fields: ["id", "has_name", "lexical_name", "organization", "phone"],
-    },
-    listArgs: {
+    params: {
         has_organization: true,
+        fields: ["id", "has_name", "lexical_name", "organization", "phone"],
     },
     relatedObjectsRules: {
         organization: {
@@ -524,7 +515,7 @@ const managedListProps = reactive({
 });
 const managedList = useList({
     props: managedListProps,
-    functions: {
+    handlers: {
         list: customListFunction,
         subscribe: customSubscribeFunction,
     },
@@ -553,31 +544,31 @@ console.log(managedList.managed);
 import { setObjectCrud } from "@arrai-innovations/reactive-helpers";
 
 setObjectCrud({
-    create: async function createCrudAdaptor({ crudArgs, retrieveArgs, object }) {
+    create: async function createCrudAdaptor({ target, params, object }) {
         // todo: your implemenation here.
         const newObject = await talkToServer(object);
         return newObject;
     },
-    retrieve: async function retrieveCrudAdaptor({ crudArgs, retrieveArgs, id }) {
+    retrieve: async function retrieveCrudAdaptor({ target, params, id }) {
         // todo: your implemenation here.
         const retrievedObject = await talkToServer(id);
         return retrievedObject;
     },
-    update: async function updateCrudAdaptor({ crudArgs, retrieveArgs, object }) {
+    update: async function updateCrudAdaptor({ target, params, object }) {
         // todo: your implemenation here.
         const updatedObject = await talkToServer(object);
         return updatedObject;
     },
-    delete: async function deleteCrudAdaptor({ crudArgs, id }) {
+    delete: async function deleteCrudAdaptor({ target, id }) {
         // todo: your implemenation here.
         await talkToServer(id);
     },
-    patch: async function patchCrudAdaptor({ crudArgs, retrieveArgs, id, partialObject }) {
+    patch: async function patchCrudAdaptor({ target, params, id, partialObject }) {
         // todo: your implemenation here.
         const patchedObject = await talkToServer(object);
         return patchedObject; // still return the full object.
     },
-    subscribe: function subscribeCrudAdaptor({ crudArgs, retrieveArgs, listArgs, eventCallback }) {
+    subscribe: function subscribeCrudAdaptor({ target, params, params, eventCallback }) {
         // todo: your implemenation here.
         const subscription = talkToServer(function (data, action) {
             eventCallback(data, action);
@@ -602,10 +593,10 @@ import {
 
 const contactObject = useObjectInstance({
     props: {
-        crudArgs: {
+        target: {
             stream: "contacts",
         },
-        retrieveArgs: {
+        params: {
             fields: ["id", "has_name", "lexical_name", "organization", "phone"],
         },
         id: contactId,
@@ -618,10 +609,10 @@ const contactSubscription = useObjectSubscription({
 // or
 const contactSubscription = useObjectSubscription({
     props: {
-        crudArgs: {
+        target: {
             stream: "contacts",
         },
-        retrieveArgs: {
+        params: {
             fields: ["id", "has_name", "lexical_name", "organization", "phone"],
         },
         id: contactId,
@@ -630,10 +621,10 @@ const contactSubscription = useObjectSubscription({
 console.log(contactSubscription.state.object);
 const organizations = useList({
     props: {
-        crudArgs: {
+        target: {
             stream: "organizations",
         },
-        retrieveArgs: {
+        params: {
             fields: ["id", "name"],
         },
     },
@@ -667,10 +658,10 @@ import { useObject } from "@arrai-innovations/reactive-helpers";
 import { reactive } from "vue";
 
 const managedObjectProps = reactive({
-    crudArgs: {
+    target: {
         stream: "contacts",
     },
-    retrieveArgs: {
+    params: {
         fields: ["id", "has_name", "lexical_name", "organization", "phone"],
     },
     pk: contactId,
@@ -690,7 +681,7 @@ const managedObjectProps = reactive({
 });
 const managedObject = useObject({
     props: managedObjectProps,
-    functions: {
+    handlers: {
         retrieve: customRetrieveFunction,
         subscribe: customSubscribeFunction,
     },
@@ -948,11 +939,17 @@ await awaitNot3.promise;
     ```bash
     $ npm ci
     ```
-3. Run tests via jest:
+3. Run tests via vitest:
     ```bash
     $ npm test
     ```
 4. Run tests with coverage output:
+
     ```bash
     $ npm run coverage
     ```
+
+5. Generate types and typedocs:
+    ```bash
+    $ npm run docs
+    ```

package/config/commonCrud.js

@@ -0,0 +1,75 @@
+import { CancellablePromise } from "../utils/cancellablePromise.js";
+import cloneDeep from "lodash-es/cloneDeep.js";
+import { addOrUpdateReactiveObject } from "../utils/assignReactiveObject.js";
+import isFunction from "lodash-es/isFunction.js";
+import { refIfReactive } from "../utils/refIfReactive.js";
+
+/**
+ * @param {string} name - The name of the method.
+ * @returns {(...args: any[]) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<any>} - A function that returns a rejected promise with an error message.
+ */
+export const missingMethod = (name) => () =>
+    CancellablePromise.reject(new Error(`Crud method "${name}" is not implemented.`));
+
+// HACK: eslint, tsc, webstorm all can't agree on how to do this right
+// noinspection JSValidateTypes,JSUnusedLocalSymbols
+/**
+ * @param {string} name - The name of the method.
+ * @returns {(
+ *     (..._args: any[]) => import('../utils/cancellablePromise.js').CancellablePromise<void>
+ * )} - A function that returns a rejected promise with an error message.
+ */
+export const requiredCancelMissingMethod =
+    (name) =>
+    /* eslint-disable no-unused-vars */
+    // @ts-ignore - refuses to accept returned CancellablePromise<void> = imported CancellablePromise<void>
+    (..._args) =>
+        CancellablePromise(Promise.reject(new Error(`Crud method "${name}" is not implemented.`)), () => {});
+/* eslint-enable no-unused-vars */
+
+/**
+ * Creates a default CRUD object with the given keys.
+ *
+ * @param {string[]} keys - The CRUD function keys.
+ * @param {Set<string>} cancellableKeys - Which ones need required cancellation.
+ * @returns {object} - The default CRUD object.
+ */
+export const createDefaultCrud = (keys, cancellableKeys = new Set()) => {
+    const result = { args: {} };
+    for (const key of keys) {
+        result[key] = cancellableKeys.has(key) ? requiredCancelMissingMethod(key) : missingMethod(key);
+    }
+    return result;
+};
+
+/**
+ * Assigns the default CRUD handlers to the target object.
+ *
+ * @param {object} target - The reactive object to assign to.
+ * @param {object} defaultCrud - The default CRUD definition (usually created by `createDefaultCrud`).
+ * @param {object} [options] - The options object.
+ * @param {object} [options.props] - The props object.
+ * @param {object} [options.handlers] - The functions to assign.
+ * @param {Set<string>} [options.validKeys] - The valid keys for the handlers.
+ */
+export function assignCrud(
+    target,
+    defaultCrud,
+    { props, handlers, validKeys = new Set(Object.keys(defaultCrud).filter((k) => k !== "args")) } = {}
+) {
+    Object.assign(target, cloneDeep(defaultCrud));
+    if (props?.target) {
+        addOrUpdateReactiveObject(target.args, props.target);
+    }
+    if (handlers) {
+        for (const [key, fn] of Object.entries(handlers)) {
+            if (!validKeys.has(key)) {
+                throw new Error(`Invalid function key "${key}" passed to assignCrud`);
+            }
+            if (!isFunction(fn)) {
+                throw new Error(`Function "${key}" is not actually a function`);
+            }
+            target[key] = refIfReactive(handlers, key, fn);
+        }
+    }
+}

package/config/listCrud.js

@@ -1,22 +1,13 @@
-import { addOrUpdateReactiveObject } from "../utils/assignReactiveObject.js";
+import { assignCrud, createDefaultCrud } from "./commonCrud.js";
 import cloneDeep from "lodash-es/cloneDeep.js";
-import isFunction from "lodash-es/isFunction.js";
-import { isReactive, toRef } from "vue";
+import { readonly } from "vue";
 
 /**
- * Configuration for the default list crud functions.
+ * Configuration for the default list crud handlers.
  *
  * @module config/listCrud.js
  */
 
-const defaultCrud = {
-    args: {},
-    list: undefined,
-    bulkDelete: undefined,
-    subscribe: undefined,
-    executeAction: undefined,
-};
-
 /**
  * @typedef {object} PaginateInfo
  * @property {number} totalRecords - The total records.
@@ -32,21 +23,22 @@ const defaultCrud = {
  */
 
 /**
- * @typedef {object} ListFnArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @typedef {object} ListArgs
+ * @property {object} target - The arguments to be passed to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
- * @property {object} listArgs - The arguments to be passed for list crud functions.
+ * @property {object} params - The arguments to be passed for list crud handlers.
  * @property {PageCallback} pageCallback - The method to call with new page(s) of data received.
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to a boolean indicating whether the request has
  *  been cancelled.
  */
 
 /**
- * @typedef {object} DeleteFnArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @typedef {object} BulkDeleteArgs
+ * @property {object} target - The arguments to be passed to the crud handlers.
  * @property {string[]} pks - The ids of the objects to be deleted.
  * @property {string} pkKey - The key name of the primary key.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to a boolean indicating whether the request has
+ *  been cancelled.
  */
 
 /**
@@ -57,95 +49,102 @@ const defaultCrud = {
  */
 
 /**
- * @typedef {object} SubscribeFnArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @typedef {object} ListSubscribeArgs
+ * @property {object} target - The arguments to be passed to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
- * @property {object} listArgs - The arguments to be passed for list crud functions.
+ * @property {object} params - The arguments to be passed for list crud handlers.
  * @property {SubscriptionEventCallback} subscriptionEventCallback - The method to call when new data is received.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to a boolean indicating whether the request has
+ *  been cancelled.
  */
 
 /**
- * @typedef {object} ExecuteActionFnArgs
- * @property {object} crudArgs - The arguments to be passed to the crud functions.
+ * @typedef {object} ExecuteActionArgs
+ * @property {object} target - The arguments to be passed to the crud handlers.
  * @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.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to a boolean indicating whether the request has
+ *  been cancelled.
  */
 
 /**
- * @typedef {(ListFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} ListFn - The list function to get a list of items, returning a boolean indicating success.
+ * @callback CrudListFn
+ * @param {ListArgs} args - The arguments to be passed to the crud handlers.
+ * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} - A promise that resolves to a boolean indicating success.
  */
 
 /**
- * @typedef {(DeleteFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} BulkDeleteFn - The delete function to bulk delete a list of items.
+ * @callback CrudBulkDeleteFn
+ * @param {BulkDeleteArgs} args - The arguments to be passed to the crud handlers.
+ * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} - A promise that resolves to a boolean indicating success.
  */
 
 /**
- * @typedef {(SubscribeFnArgs)=>Promise<boolean> & { cancel: () => Promise<void>|void }} SubscribeFn - The subscribe function to set up a subscription to a list of items.
+ * @callback CrudListSubscribeFn
+ * @param {ListSubscribeArgs} args - The arguments to be passed to the crud handlers.
+ * @returns {import('../utils/cancellablePromise.js').CancellablePromise<void>} - A promise that resolves to a boolean indicating success.
  */
 
 /**
- * @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.
+ * @callback CrudExecuteActionFn
+ * @param {ExecuteActionArgs} args - The arguments to be passed to the crud handlers.
+ * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|null>} - A promise that resolves the result of the action, returned to the executor.
  */
 
 /**
- * @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.
+ * @typedef {object} ListCrudHandlers
+ * @property {CrudListFn} [list] - The list function to get a list of items.
+ * @property {CrudBulkDeleteFn} [bulkDelete] - The delete function to bulk delete a list of items.
+ * @property {CrudExecuteActionFn} [executeAction] - The  function to execute a certain action on a list of items.
+ * @property {CrudListSubscribeFn} [subscribe] - The subscribe function to get a subscription to a list of items.
  */
 
 /**
- * @typedef {object} ListCrudArgs
- * @property {object} [args={}] - The default arguments for the crud functions.
+ * @typedef {object} ListTarget
+ * @property {object} args - The default arguments for the crud handlers.
  */
 
 /**
- * Set the list and subscribe functions for the default crud.
+ * @typedef {object} ListTargetOption
+ * @property {object} [target={}] - The default arguments for the crud handlers.
+ */
+
+const _defaultCrud = createDefaultCrud(["list", "bulkDelete", "executeAction", "subscribe"], new Set(["subscribe"]));
+
+/**
+ * The default list crud handlers.
+ *
+ * @type {Readonly<ListCrudHandlers>}
+ */
+export const defaultListCrud = readonly(_defaultCrud);
+
+/**
+ * Set the list and subscribe handlers for the default crud.
  *
- * @param {ListCrudFunctions & Partial<ListCrudArgs>} options - The options for the default crud.
+ * @param {ListCrudHandlers & Partial<ListTarget>} options - The options for the default crud.
  * @throws {Error} - If unknown keys are passed.
  * @returns {void}
  */
-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(", ")}`);
+export const setListCrud = ({ args = {}, ...rest }) => {
+    Object.assign(_defaultCrud.args, cloneDeep(args));
+    for (const [key, value] of Object.entries(rest)) {
+        if (!(key in _defaultCrud)) {
+            throw new Error(`Unknown key "${key}" passed to setListCrud`);
+        }
+        _defaultCrud[key] = value ?? _defaultCrud[key];
     }
 };
 
 /**
- * Get the previously set list and subscribe functions for the default crud.
+ * Get the previously set list and subscribe handlers for the default crud.
  *
- * @param {import("vue").UnwrapNestedRefs<ListCrudFunctions & ListCrudArgs>} reactiveCrud - The reactive crud object, which will be mutated.
+ * @param {import("vue").UnwrapNestedRefs<ListCrudHandlers & ListTarget>} target - The reactive crud object, which will be mutated.
  * @param {object} options - The options for the default crud.
- * @param {import("vue").UnwrapNestedRefs<{
- *     crudArgs: object|undefined,
- * }>} [options.props] - The props to set for the crud.
- * @param {ListCrudFunctions & ListCrudArgs} [options.functions] - The functions to set for the crud.
- */
-export const getListCrud = (reactiveCrud, { props, functions } = {}) => {
-    // don't mutate the default crud
-    Object.assign(reactiveCrud, cloneDeep(defaultCrud));
-    if (props?.crudArgs) {
-        addOrUpdateReactiveObject(reactiveCrud.args, props.crudArgs);
-    }
-    if (functions) {
-        for (const [key, value] of Object.entries(functions)) {
-            if (isFunction(value) && key in reactiveCrud) {
-                reactiveCrud[key] = isReactive(functions)
-                    ? // @ts-ignore - this is a valid key...
-                      toRef(functions, key)
-                    : value;
-            } else {
-                throw Error(`Invalid function "${key}" for getListCrud: invalid key or not a function.`);
-            }
-        }
-    }
+ * @param {import("vue").UnwrapNestedRefs<ListTargetOption>} [options.props] - The props to set for the crud.
+ * @param {ListCrudHandlers} [options.handlers] - The functions to set for the crud.
+ * @throws {Error} - If an invalid function is passed, or if the function is not a function.
+ */
+export const getListCrud = (target, options) => {
+    assignCrud(target, _defaultCrud, options);
 };