@arrai-innovations/reactive-helpers 3.2.1 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "3.2.1",
+    "version": "4.0.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "directories": {
@@ -54,6 +54,7 @@
         "lodash": "^4.17.21",
         "pinst": "^3.0.0",
         "vue": "^3.2.33",
+        "vue-deepunref": "^1.0.1",
         "vue-router": "^4.0.15"
     }
 }

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

@@ -0,0 +1,76 @@
+import { nextTick } from "vue";
+import { deepUnref } from "vue-deepunref";
+
+describe("use/listCalculated", () => {
+    let useListInstance, useListCalculated;
+    beforeEach(async () => {
+        const listInstanceModule = await import("../../../use/listInstance");
+        useListInstance = listInstanceModule.useListInstance;
+        const listCalculatedModule = await import("../../../use/listCalculated");
+        useListCalculated = listCalculatedModule.useListCalculated;
+    });
+    it("should return a list of calculated items", async () => {
+        const mainListInstance = useListInstance({});
+        const calculatedListInstance = useListInstance({});
+        mainListInstance.addListObject({
+            id: "1",
+            name: "main",
+            calculated_items: ["2", "3"],
+            calculated_id: "4",
+        });
+        calculatedListInstance.addListObject({
+            id: "2",
+            name: "calculated1",
+        });
+        calculatedListInstance.addListObject({
+            id: "3",
+            name: "calculated2",
+        });
+        calculatedListInstance.addListObject({
+            id: "4",
+            name: "calculated3",
+        });
+        const listCalculated = useListCalculated({
+            parentState: mainListInstance.state,
+            calculatedObjectsRules: {
+                calculatedItems: (obj) => obj.calculated_items.map((x) => calculatedListInstance.state.objects[x]),
+                calculatedItem: (obj) => calculatedListInstance.state.objects[obj.calculated_id],
+            },
+            calculatedObjectsPropertyName: "myCalculatedObjects",
+        });
+        await nextTick();
+        // listCalculated.state.objects is doing proxy shenanigans
+        // in uses handler.has
+        expect("myCalculatedObjects" in listCalculated.state).toBe(true);
+        expect(!!listCalculated.state.myCalculatedObjects?.[1]).toBe(true);
+        expect("calculatedItems" in listCalculated.state.myCalculatedObjects[1]).toBe(true);
+        expect("calculatedItem" in listCalculated.state.myCalculatedObjects[1]).toBe(true);
+        // expect uses enumeration, which uses handler.ownKeys and handler.getOwnPropertyDescriptor
+        expect(deepUnref(listCalculated.state.objects)).toEqual({
+            1: {
+                id: "1",
+                name: "main",
+                calculated_id: "4",
+                calculated_items: ["2", "3"],
+            },
+        });
+        expect(deepUnref(listCalculated.state.myCalculatedObjects)).toEqual({
+            1: {
+                calculatedItems: [
+                    {
+                        id: "2",
+                        name: "calculated1",
+                    },
+                    {
+                        id: "3",
+                        name: "calculated2",
+                    },
+                ],
+                calculatedItem: {
+                    id: "4",
+                    name: "calculated3",
+                },
+            },
+        });
+    });
+});

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

@@ -1,7 +1,7 @@
 import { nextTick, reactive, ref } from "vue";
-import { doAwaitNot } from "../../../utils/watches";
+import { deepUnref } from "vue-deepunref";
 import { useListFilters, useListSort } from "../../../use";
-import { unrefAndToRawDeep } from "../../../utils";
+import { doAwaitNot } from "../../../utils/watches";
 
 describe("use/listFilter", () => {
     let useListInstance, useListFilter, setDefaultSearchOptions;
@@ -318,10 +318,10 @@ describe("use/listFilter", () => {
 
             expect(listFilters.A.state.excludedValues).toEqual({ id: 1, name: "three" });
             expect(listFilters.B.state.allowedValues).toEqual({ id: 2, name: "four" });
-            expect(unrefAndToRawDeep(listFilters.A.parentState)).toEqual(unrefAndToRawDeep(listFilterA.parentState));
-            expect(unrefAndToRawDeep(listFilters.B.parentState)).toEqual(unrefAndToRawDeep(listFilterB.parentState));
-            expect(unrefAndToRawDeep(listFilters.A.state)).toEqual(unrefAndToRawDeep(listFilterA.state));
-            expect(unrefAndToRawDeep(listFilters.B.state)).toEqual(unrefAndToRawDeep(listFilterB.state));
+            expect(deepUnref(listFilters.A.parentState)).toEqual(deepUnref(listFilterA.parentState));
+            expect(deepUnref(listFilters.B.parentState)).toEqual(deepUnref(listFilterB.parentState));
+            expect(deepUnref(listFilters.A.state)).toEqual(deepUnref(listFilterA.state));
+            expect(deepUnref(listFilters.B.state)).toEqual(deepUnref(listFilterB.state));
         });
     });
 });

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

@@ -1,5 +1,5 @@
 import { nextTick } from "vue";
-import { unrefAndToRawDeep } from "../../../utils/unrefAndToRawDeep";
+import { deepUnref } from "vue-deepunref";
 
 describe("use/listRelated", () => {
     let useListInstance, useListRelated;
@@ -47,31 +47,34 @@ describe("use/listRelated", () => {
         await nextTick();
         // listRelated.state.objects is doing proxy shenanigans
         // in uses handler.has
-        expect("myRelatedObjects" in listRelated.state.objects[1]).toBe(true);
-        expect("relatedItems" in listRelated.state.objects[1].myRelatedObjects).toBe(true);
-        expect("relatedItem" in listRelated.state.objects[1].myRelatedObjects).toBe(true);
+        expect("myRelatedObjects" in listRelated.state).toBe(true);
+        expect(!!listRelated.state.myRelatedObjects?.[1]).toBe(true);
+        expect("relatedItems" in listRelated.state.myRelatedObjects[1]).toBe(true);
+        expect("relatedItem" in listRelated.state.myRelatedObjects[1]).toBe(true);
         // expect uses enumeration, which uses handler.ownKeys and handler.getOwnPropertyDescriptor
-        expect(unrefAndToRawDeep(listRelated.state.objects)).toEqual({
+        expect(deepUnref(listRelated.state.objects)).toEqual({
             1: {
                 id: "1",
                 name: "main",
                 related_id: "4",
                 related_items: ["2", "3"],
-                myRelatedObjects: {
-                    relatedItems: [
-                        {
-                            id: "2",
-                            name: "related1",
-                        },
-                        {
-                            id: "3",
-                            name: "related2",
-                        },
-                    ],
-                    relatedItem: {
-                        id: "4",
-                        name: "related3",
+            },
+        });
+        expect(deepUnref(listRelated.state.myRelatedObjects)).toEqual({
+            1: {
+                relatedItems: [
+                    {
+                        id: "2",
+                        name: "related1",
                     },
+                    {
+                        id: "3",
+                        name: "related2",
+                    },
+                ],
+                relatedItem: {
+                    id: "4",
+                    name: "related3",
                 },
             },
         });

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

@@ -1,5 +1,6 @@
 import { nextTick } from "vue";
-import { doAwaitTimeout, unrefAndToRawDeep } from "../../../utils";
+import { deepUnref } from "vue-deepunref";
+import { doAwaitTimeout } from "../../../utils";
 
 describe("use/useListSort", () => {
     let listInstance,
@@ -178,10 +179,10 @@ describe("use/useListSort", () => {
             },
             listInstances
         );
-        expect(unrefAndToRawDeep(listSorts.A.parentState)).toEqual(unrefAndToRawDeep(listInstanceA.state));
-        expect(unrefAndToRawDeep(listSorts.B.parentState)).toEqual(unrefAndToRawDeep(listInstanceB.state));
-        expect(unrefAndToRawDeep(listSorts.A.state)).toEqual(unrefAndToRawDeep(listSortA.state));
-        expect(unrefAndToRawDeep(listSorts.B.state)).toEqual(unrefAndToRawDeep(listSortB.state));
+        expect(deepUnref(listSorts.A.parentState)).toEqual(deepUnref(listInstanceA.state));
+        expect(deepUnref(listSorts.B.parentState)).toEqual(deepUnref(listInstanceB.state));
+        expect(deepUnref(listSorts.A.state)).toEqual(deepUnref(listSortA.state));
+        expect(deepUnref(listSorts.B.state)).toEqual(deepUnref(listSortB.state));
     });
     describe("useListSort/sortThrottleWait", () => {
         it("respects throttle time prior to triggering", async () => {

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

@@ -1,7 +1,7 @@
-import { nextTick, reactive } from "vue";
-import { inspect } from "util";
-import { doAwaitTimeout } from "../../../utils";
 import flushPromises from "flush-promises";
+import { inspect } from "util";
+import { nextTick, reactive } from "vue";
+import { doAwaitNot, doAwaitTimeout } from "../../../utils";
 import { CancellableResolvable } from "../crudPromise";
 import { poll } from "../poll";
 
@@ -512,8 +512,12 @@ describe("use/listSubscription.spec.js", function () {
             listArgs.user = 2;
             retrieveArgs.fields = ["name"];
             await nextTick();
-            await flushPromises();
-            await doAwaitTimeout(1500);
+            await crudSubscribeResolvable[1].resolve();
+            await crudListResolvable[1].resolve();
+            await doAwaitNot({
+                obj: listSubscription.listIntent.state,
+                prop: "resolving",
+            });
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
             expect(crudSubscribe).toHaveBeenCalledWith({

package/use/cancellableIntent.js

@@ -1,9 +1,10 @@
-import { effectScope, isReactive, isRef, onScopeDispose, reactive, unref, watch } from "vue";
-import { cloneDeep, isEqual } from "lodash";
+import { identity, isEqual } from "lodash";
+import { effectScope, nextTick, onScopeDispose, reactive, readonly, watch } from "vue";
+import { deepUnref } from "vue-deepunref";
 
 /*
  * Calls your awaitable function with the arguments you pass in, when the watch arguments change and are all truthy.
- * Watch arguments can be an array or an object.
+ * Watch arguments should be a reactive object.
  * If the promise is not resolved before the watch arguments change again, the previous promise is cancelled.
  */
 export function useCancellableIntent({ awaitableWithCancel, watchArguments = {}, clearActiveOnResolved = true }) {
@@ -15,11 +16,12 @@ export function useCancellableIntent({ awaitableWithCancel, watchArguments = {},
     }
     const state = reactive({
         active: undefined,
+        resolving: undefined,
         errored: false,
         error: null,
         clearActiveOnResolved,
     });
-    let previousWatchArguments = null,
+    let previousWatchValues = null,
         cancelFunction = null;
 
     const es = effectScope();
@@ -32,6 +34,7 @@ export function useCancellableIntent({ awaitableWithCancel, watchArguments = {},
     async function cancel() {
         if (cancelFunction) {
             state.active = false;
+            state.resolving = false;
             const cancelPromise = cancelFunction().catch(console.error);
             cancelFunction = null;
             return cancelPromise;
@@ -39,54 +42,58 @@ export function useCancellableIntent({ awaitableWithCancel, watchArguments = {},
         return false;
     }
 
-    es.run(() => {
-        watch(
-            isReactive(watchArguments) || isRef(watchArguments) ? watchArguments : Object.values(watchArguments),
-            () => {
-                let newArguments = cloneDeep(watchArguments.map((arg) => unref(arg)));
-                if (isEqual(unref(watchArguments), previousWatchArguments)) {
-                    return;
-                }
-                previousWatchArguments = newArguments;
-                cancel().catch(console.error);
-                if (Object.values(previousWatchArguments).every((v) => unref(v))) {
-                    state.errored = false;
-                    state.error = null;
-                    let awaitablePromise = awaitableWithCancel();
-                    state.active = true;
-                    if (awaitablePromise.cancel) {
-                        cancelFunction = async () => {
-                            state.active = false;
-                            cancelFunction = null;
-                            return awaitablePromise.cancel();
-                        };
-                    }
-                    awaitablePromise
-                        .then(() => {
-                            if (state.clearActiveOnResolved) {
-                                cancelFunction = null;
-                                state.active = false;
-                            }
-                        })
-                        .catch(async (err) => {
-                            await cancel();
-                            console.error(err);
-                            state.errored = true;
-                            state.error = err;
-                            throw err;
-                        });
-                }
-            },
-            {
-                deep: true,
-                immediate: true,
+    const watchFn = () => {
+        let newWatchValues = deepUnref(Object.values(watchArguments));
+        if (isEqual(newWatchValues, previousWatchValues)) {
+            return;
+        }
+        previousWatchValues = newWatchValues;
+        cancel().catch(console.error);
+        if (Object.values(previousWatchValues).every(identity)) {
+            state.errored = false;
+            state.error = null;
+            let awaitablePromise = awaitableWithCancel();
+            state.active = true;
+            state.resolving = true;
+            if (awaitablePromise.cancel) {
+                cancelFunction = async () => {
+                    state.active = false;
+                    state.resolving = false;
+                    cancelFunction = null;
+                    return awaitablePromise.cancel();
+                };
             }
-        );
+            awaitablePromise
+                .then(() => {
+                    state.resolving = false;
+                    if (state.clearActiveOnResolved) {
+                        cancelFunction = null;
+                        state.active = false;
+                    }
+                })
+                .catch(async (err) => {
+                    await cancel();
+                    console.error(err);
+                    state.errored = true;
+                    state.error = err;
+                    throw err;
+                });
+        }
+    };
+
+    es.run(() => {
+        watch(() => Object.values(watchArguments), watchFn, {
+            // this can't be immediate because subscribe wants to look at our state, which won't exist yet.
+            deep: true,
+        });
+
+        nextTick().then(watchFn);
 
         onScopeDispose(cancel);
     });
     return {
         state,
+        watchArguments: readonly(watchArguments),
         stop,
         cancel,
     };

package/use/index.js

@@ -1,4 +1,5 @@
 export * from "./cancellableIntent.js";
+export * from "./list.js";
 export * from "./listCalculated.js";
 export * from "./listFilter.js";
 export * from "./listInstance.js";

package/use/list.js

@@ -0,0 +1,112 @@
+import { effectScope, reactive, shallowReactive, shallowReadonly, toRef, watch } from "vue";
+import { useListCalculated } from "./listCalculated";
+import { useListInstance } from "./listInstance";
+import { useListRelated } from "./listRelated";
+import { useListSubscription } from "./listSubscription";
+
+// the big brother of useObject, managing a chain of useList* instances.
+export const useList = ({ props, functions }) => {
+    const managed = shallowReactive({
+        listInstance: null,
+        listSubscription: null,
+        listRelated: null,
+        listCalculated: null,
+    });
+    const es = effectScope();
+
+    managed.listInstance = useListInstance({
+        crudArgs: toRef(props, "crudArgs"),
+        functions,
+        retrieveArgs: toRef(props, "retrieveArgs"),
+        listArgs: toRef(props, "listArgs"),
+    });
+
+    const intentPropsWatch = () => {
+        es.run(() => {
+            let nextState = managed.listInstance?.state;
+            // true or false, having a key is intent to use
+            const hasIntendToList = "intendToList" in props;
+            if (hasIntendToList && !managed.listSubscription) {
+                managed.listSubscription = useListSubscription({
+                    listInstance: managed.listInstance,
+                });
+                managed.listSubscription.state.intendToList = toRef(props, "intendToList");
+            } else if (!hasIntendToList && managed.listSubscription) {
+                managed.listSubscription.effectScope.stop();
+                managed.listSubscription = null;
+            }
+            const hasRelatedObjectRules = "relatedObjectsRules" in props;
+            if (hasRelatedObjectRules && !managed.listRelated) {
+                nextState = managed.listSubscription?.state || nextState;
+                managed.listRelated = useListRelated({
+                    parentState: nextState,
+                    relatedObjectsRules: toRef(props, "relatedObjectsRules"),
+                });
+            } else if (!hasRelatedObjectRules && managed.listRelated) {
+                managed.listRelated.effectScope.stop();
+                managed.listRelated = null;
+            }
+            const hasCalculatedObjectRules = "calculatedObjectsRules" in props;
+            if (hasCalculatedObjectRules && !managed.listCalculated) {
+                nextState = managed.listRelated?.state || nextState;
+                managed.listCalculated = useListCalculated({
+                    parentState: nextState,
+                    calculatedObjectsRules: toRef(props, "calculatedObjectsRules"),
+                });
+            } else if (!hasCalculatedObjectRules && managed.listCalculated) {
+                managed.listCalculated.effectScope.stop();
+                managed.listCalculated = null;
+            }
+        });
+    };
+
+    const exposedState = reactive({});
+
+    es.run(() => {
+        watch(
+            [
+                //
+                toRef(props, "intendToList"),
+                toRef(props, "relatedObjectsRules"),
+                toRef(props, "calculatedObjectsRules"),
+            ],
+            intentPropsWatch,
+            { immediate: true }
+        );
+        const propertiesToRelay = [
+            "loading",
+            "error",
+            "errored",
+            "objects",
+            "order",
+            "objectsInOrder",
+            "running",
+            "relatedObjects",
+            "calculatedObjects",
+        ];
+        watch(
+            () =>
+                managed.listCalculated?.state ||
+                managed.listRelated?.state ||
+                managed.listSubscription?.state ||
+                managed.listInstance?.state,
+            (newState, oldState) => {
+                if (newState !== oldState && newState) {
+                    propertiesToRelay.forEach((x) => {
+                        exposedState[x] = toRef(newState, x);
+                    });
+                }
+            },
+            {
+                immediate: true,
+            }
+        );
+    });
+
+    return {
+        // we manage the keys on both of these, so hands off the root.
+        managed: shallowReadonly(managed),
+        state: shallowReadonly(exposedState),
+        effectScope: es,
+    };
+};

package/use/listCalculated.js

@@ -19,11 +19,11 @@ export function useListCalculated({
     parentState,
     calculatedObjectsRules,
     calculatedObjectsPropertyName = "calculatedObjects", // NOT REACTIVE
+    passThroughPropertyNames = ["relatedObjects"], // NOT REACTIVE
 }) {
     const state = reactive({
         calculatedObjectsRules,
         calculatedObjectsObjects: {},
-        objects: {},
         parentStateObjectsWatchRunning: false,
         calculatedObjectsWatchRunning: false,
     });
@@ -39,7 +39,6 @@ export function useListCalculated({
         );
         for (const removedKey of removedKeys) {
             delete state.calculatedObjectsObjects[removedKey];
-            delete state.objects[removedKey];
             if (calculatedObjectsEffectScopes[removedKey]) {
                 calculatedObjectsEffectScopes[removedKey].stop();
                 delete calculatedObjectsEffectScopes[removedKey];
@@ -47,63 +46,46 @@ export function useListCalculated({
         }
         for (const addedKey of addedKeys) {
             state.calculatedObjectsObjects[addedKey] = {};
-            state.objects[addedKey] = new Proxy(parentState.objects[addedKey], {
-                get(target, prop, receiver) {
-                    if (prop === copn) {
-                        return state.calculatedObjectsObjects[addedKey];
-                    }
-                    return Reflect.get(target, prop, receiver);
-                },
-                ownKeys(target) {
-                    return Reflect.ownKeys(target).concat(copn);
-                },
-            });
         }
         state.parentStateObjectsWatchRunning = false;
     }
 
     function calculatedObjectsWatch() {
-        if (state.calculatedObjectsRules === false) {
-            return;
-        }
-        const calculatedObjectsRulesIsEmpty = isEmpty(state.calculatedObjectsRules);
+        const calculatedObjectsRulesIsEmpty = !state.calculatedObjectsRules || isEmpty(state.calculatedObjectsRules);
         for (const objectKey of Object.keys(state.calculatedObjectsObjects)) {
-            const calculatedObjectsEffectScope = effectScope();
-            calculatedObjectsEffectScope.run(() => {
-                const calculatedObjectsObject = state.calculatedObjectsObjects[objectKey];
-                const originalObject = parentState.objects[objectKey];
-                if (!calculatedObjectsObject[copn]) {
-                    calculatedObjectsObject[copn] = {};
-                }
-                let removedRuleKeys, addedRuleKeys;
-                if (!calculatedObjectsRulesIsEmpty) {
-                    ({ removedKeys: removedRuleKeys, addedKeys: addedRuleKeys } = keyDiff(
-                        Object.keys(state.calculatedObjectsRules),
-                        Object.keys(calculatedObjectsObject[copn])
-                    ));
-                } else {
-                    if (isEmpty(calculatedObjectsObject[copn])) {
-                        return;
-                    }
-                    removedRuleKeys = Object.keys(calculatedObjectsObject[copn]);
-                    addedRuleKeys = [];
-                }
-                for (const removedRuleKey of removedRuleKeys) {
-                    delete calculatedObjectsObject[copn][removedRuleKey];
+            if (!calculatedObjectsEffectScopes[objectKey]) {
+                calculatedObjectsEffectScopes[objectKey] = effectScope();
+            }
+            const originalObject = parentState.objects[objectKey];
+            if (!state.calculatedObjectsObjects[objectKey]) {
+                state.calculatedObjectsObjects[objectKey] = {};
+            }
+            const calculatedObjectsObject = state.calculatedObjectsObjects[objectKey];
+            let removedRuleKeys, addedRuleKeys;
+            if (!calculatedObjectsRulesIsEmpty) {
+                ({ removedKeys: removedRuleKeys, addedKeys: addedRuleKeys } = keyDiff(
+                    Object.keys(state.calculatedObjectsRules),
+                    Object.keys(calculatedObjectsObject)
+                ));
+            } else {
+                if (isEmpty(calculatedObjectsObject)) {
+                    return;
                 }
+                removedRuleKeys = Object.keys(calculatedObjectsObject);
+                addedRuleKeys = [];
+            }
+            for (const removedRuleKey of removedRuleKeys) {
+                delete calculatedObjectsObject[removedRuleKey];
+            }
+            calculatedObjectsEffectScopes[objectKey].run(() => {
                 for (const addedRuleKey of addedRuleKeys) {
-                    calculatedObjectsObject[copn][addedRuleKey] = computed(() => {
+                    calculatedObjectsObject[addedRuleKey] = computed(() => {
                         return state.calculatedObjectsRules?.[addedRuleKey]?.(originalObject);
                     });
                 }
             });
-            if (calculatedObjectsEffectScopes[objectKey]) {
-                calculatedObjectsEffectScopes[objectKey].stop();
-            }
-            calculatedObjectsEffectScopes[objectKey] = calculatedObjectsEffectScope;
         }
         state.calculatedObjectsWatchRunning = false;
-        parentStateObjectsWatch();
     }
 
     let watchesRunning = null;
@@ -118,7 +100,12 @@ export function useListCalculated({
         state.retrieveArgs = toRef(parentState, "retrieveArgs");
         state.listArgs = toRef(parentState, "listArgs");
         state.order = toRef(parentState, "order");
-        state.objectsInOrder = computed(() => state.order.map((id) => state.objects[id]));
+        state.objects = toRef(parentState, "objects");
+        state.objectsInOrder = toRef(parentState, "objectsInOrder");
+        state[copn] = toRef(state, "calculatedObjectsObjects");
+        for (let key in passThroughPropertyNames) {
+            state[key] = toRef(parentState, key);
+        }
 
         watch(() => Object.keys(parentState.objects), parentStateObjectsWatch, { immediate: true });
         watch(
@@ -134,7 +121,11 @@ export function useListCalculated({
         );
 
         watchesRunning = useWatchesRunning({
-            triggerRefs: [computed(() => (!isEmpty(state.calculatedObjectsRules) ? parentState.loading : false))],
+            triggerRefs: [
+                computed(() =>
+                    state.calculatedObjectsRules && !isEmpty(state.calculatedObjectsRules) ? parentState.loading : false
+                ),
+            ],
             watchSentinelRefs: [
                 toRef(state, "parentStateObjectsWatchRunning"),
                 toRef(state, "calculatedObjectsWatchRunning"),

package/use/listInstance.js

@@ -1,5 +1,6 @@
 import inspect from "browser-util-inspect";
 import { cloneDeep } from "lodash";
+import { isFunction } from "lodash";
 import { computed, effectScope, reactive } from "vue";
 import { addOrUpdateReactiveObject, assignReactiveObject } from "../utils/assignReactiveObject";
 import { getFakeId } from "../utils/getFakeId";
@@ -30,7 +31,7 @@ export function useListInstances(listInstanceArgs) {
     return instances;
 }
 
-export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {} }) {
+export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {}, functions = {} }) {
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
     const _objectsMap = new Map();
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
@@ -82,6 +83,13 @@ export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {} })
     if (crudArgs) {
         addOrUpdateReactiveObject(state.crud.args, crudArgs);
     }
+    for (const [key, value] of Object.entries(functions)) {
+        if (isFunction(value) && key in state.crud) {
+            state.crud[key] = value;
+        } else {
+            throw ListError(`Invalid function "${key}" for useListInstance: invalid key or not a function.`);
+        }
+    }
 
     const defaultPageCallback = (newObjects) => {
         newObjects.forEach((newObject) => {