@arrai-innovations/reactive-helpers 1.2.3 → 2.0.0

package/use/listInstance.js

@@ -1,5 +1,5 @@
-import { cloneDeep, isEmpty } from "lodash";
-import { computed, effectScope, reactive, unref } from "vue";
+import { cloneDeep } from "lodash";
+import { computed, effectScope, reactive } from "vue";
 import { assignReactiveObject } from "../utils/assignReactiveObject";
 import { getFakeId } from "../utils/getFakeId";
 import inspect from "browser-util-inspect";
@@ -30,23 +30,24 @@ export function useListInstances(listInstanceArgs) {
     return instances;
 }
 
-export function useListInstance({ crudArgs, defaultListArgs = {}, defaultRetrieveArgs = {} }) {
+export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {} }) {
     const state = reactive({
-        listInstanceCrud: {
+        crud: {
             args: {},
             list: undefined,
         },
-        defaultRetrieveArgs,
-        defaultListArgs,
+        retrieveArgs,
+        listArgs,
         objects: {},
         loading: undefined,
         errored: false,
         error: null,
         order: [],
     });
-    Object.assign(state.listInstanceCrud, cloneDeep(defaultCrud));
+    // prevent linking of all instances to the same default .args object
+    Object.assign(state.crud, cloneDeep(defaultCrud));
     if (crudArgs) {
-        assignReactiveObject(state.listInstanceCrud.args, crudArgs);
+        assignReactiveObject(state.crud.args, crudArgs);
     }
 
     const defaultPageCallback = (newObjects) => {
@@ -59,37 +60,47 @@ export function useListInstance({ crudArgs, defaultListArgs = {}, defaultRetriev
         });
     };
 
-    async function list({ listArgs, retrieveArgs } = {}) {
+    function list() {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.loading) {
-            throw new ListError("already loading.");
-        }
-        if (isEmpty(retrieveArgs) && !isEmpty(unref(state.defaultRetrieveArgs))) {
-            retrieveArgs = unref(state.defaultRetrieveArgs);
-        }
-        if (isEmpty(listArgs) && !isEmpty(unref(state.defaultListArgs))) {
-            listArgs = unref(state.defaultListArgs);
+            return Promise.reject(new ListError("already loading."));
         }
+        let returnPromiseResolve;
+        const returnPromise = new Promise((resolve) => {
+            returnPromiseResolve = resolve;
+        });
         state.loading = true;
         state.errored = false;
         state.error = null;
-        return state.listInstanceCrud
-            .list({
-                crudArgs: state.listInstanceCrud.args,
-                retrieveArgs,
-                listArgs,
-                pageCallback: returnedObject.pageCallback,
-            })
+        const listPromise = state.crud.list({
+            crudArgs: state.crud.args,
+            retrieveArgs: state.retrieveArgs,
+            listArgs: state.listArgs,
+            pageCallback: returnedObject.pageCallback,
+        });
+        if (listPromise.cancel) {
+            returnPromise.cancel = async () => {
+                let promise = listPromise.cancel();
+                state.loading = false;
+                returnPromiseResolve(false);
+                if (promise) {
+                    await promise;
+                }
+            };
+        }
+        // the indirection of promises here is to allow us to do additional work on listPromise's cancel
+        listPromise
             .then(() => {
-                return Promise.resolve(true);
+                state.loading = false;
+                returnPromiseResolve(true);
             })
             .catch((error) => {
+                state.loading = false;
                 state.errored = true;
                 state.error = error;
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                state.loading = false;
+                returnPromiseResolve(false);
             });
+        return returnPromise;
     }
 
     function addListObject(object) {

package/use/listSubscription.js

@@ -1,8 +1,9 @@
-import { effectScope, onScopeDispose, reactive, toRef } from "vue";
+import { computed, effectScope, reactive, toRef } from "vue";
 import { useListInstance } from "./listInstance";
 import { cloneDeep, isEmpty, isObject } from "lodash";
 import { assignReactiveObject } from "../utils/assignReactiveObject";
 import inspect from "browser-util-inspect";
+import { useCancellableIntent } from "../utils/cancellableIntent";
 
 export class ListSubscriptionError extends Error {
     constructor(message) {
@@ -12,11 +13,13 @@ export class ListSubscriptionError extends Error {
 }
 
 const defaultCrud = {
+    args: {},
     subscribe: undefined,
 };
 
-export function setListSubscriptionCrud({ subscribe }) {
+export function setListSubscriptionCrud({ subscribe, args = {} }) {
     defaultCrud.subscribe = subscribe;
+    Object.assign(defaultCrud.args, args);
 }
 
 export function useListSubscriptions(args, listInstances = {}) {
@@ -27,35 +30,41 @@ export function useListSubscriptions(args, listInstances = {}) {
     return subscriptions;
 }
 
-export function useListSubscription({ listInstance, crudArgs, defaultListArgs, defaultRetrieveArgs }) {
+export function useListSubscription({ listInstance, crudArgs, listArgs, retrieveArgs }) {
     if (!listInstance) {
-        listInstance = useListInstance({ crudArgs, defaultListArgs, defaultRetrieveArgs });
+        listInstance = useListInstance({ crudArgs, listArgs, retrieveArgs });
     }
-    let cancelSubscription = null;
+    let subscribeIntent, listIntent;
     const state = reactive({
-        listSubscriptionCrud: {},
+        crud: {
+            args: {},
+            subscribe: undefined,
+        },
+        subscriptionLoading: undefined,
+        subscriptionErrored: false,
+        subscriptionError: null,
+        intendToList: false,
         intendToSubscribe: false,
     });
-    assignReactiveObject(state.listSubscriptionCrud, cloneDeep(defaultCrud));
+    // prevent linking of all instances to the same default .args object
+    Object.assign(state.crud, cloneDeep(defaultCrud));
+    if (crudArgs) {
+        assignReactiveObject(state.crud.args, crudArgs);
+    }
 
-    async function subscribe({ listArgs, retrieveArgs } = {}) {
-        if (!listArgs) {
-            listArgs = cloneDeep(listInstance.state.defaultListArgs);
-        }
-        if (!retrieveArgs) {
-            retrieveArgs = cloneDeep(listInstance.state.defaultRetrieveArgs);
+    function publicSubscribe({ list = true } = {}) {
+        let didSubscribe = false;
+        if (!state.intendToSubscribe) {
+            state.intendToSubscribe = true;
+            didSubscribe = true;
         }
-        if (!cancelSubscription) {
-            cancelSubscription = await state.listSubscriptionCrud.subscribe({
-                crudArgs: listInstance.state.listInstanceCrud.args,
-                listArgs,
-                retrieveArgs,
-                subscriptionEventCallback,
-            });
-            state.subscribed = true;
-            return true;
+        if (list) {
+            if (!state.intendToList) {
+                state.intendToList = true;
+                didSubscribe = true;
+            }
         }
-        return false;
+        return didSubscribe;
     }
 
     function subscriptionEventCallback(data, action) {
@@ -72,14 +81,17 @@ export function useListSubscription({ listInstance, crudArgs, defaultListArgs, d
         }
     }
 
-    async function unsubscribe() {
-        if (cancelSubscription) {
-            const returnValue = await cancelSubscription();
-            state.subscribed = false;
-            cancelSubscription = null;
-            return returnValue;
+    function publicUnsubscribe() {
+        let didUnsubscribe = false;
+        if (state.intendToSubscribe) {
+            state.intendToSubscribe = false;
+            didUnsubscribe = true;
         }
-        return false;
+        if (state.intendToList) {
+            state.intendToList = false;
+            didUnsubscribe = true;
+        }
+        return didUnsubscribe;
     }
 
     function addFromSubscription(data) {
@@ -128,19 +140,53 @@ export function useListSubscription({ listInstance, crudArgs, defaultListArgs, d
     const es = effectScope();
 
     es.run(() => {
+        state.loading = computed(() => listInstance.state.loading || state.subscriptionLoading);
+        state.errored = computed(() => listInstance.state.errored || state.subscriptionErrored);
+        state.error = computed(() => listInstance.state.error || state.subscriptionError);
+
+        state.retrieveArgs = computed(() => listInstance.state.retrieveArgs);
+        state.listArgs = computed(() => listInstance.state.listArgs);
         state.objects = toRef(listInstance.state, "objects");
         state.order = toRef(listInstance.state, "order");
         state.objectsInOrder = toRef(listInstance.state, "objectsInOrder");
-        onScopeDispose(async () => {
-            await unsubscribe();
+
+        subscribeIntent = useCancellableIntent({
+            awaitableWithCancel: () => {
+                // this function cannot be async, or the resulting promise will lose its .cancel() method
+                const subscribePromise = state.crud.subscribe({
+                    crudArgs: cloneDeep(state.crud.args),
+                    listArgs: cloneDeep(listInstance.state.listArgs),
+                    retrieveArgs: cloneDeep(listInstance.state.retrieveArgs),
+                    subscriptionEventCallback,
+                });
+                // catching makes a new promise, we need to make sure the cancel method lives on.
+                const catchPromise = subscribePromise.catch((err) => {
+                    console.error(err);
+                    state.subscriptionErrored = true;
+                    state.subscriptionError = err;
+                });
+                catchPromise.cancel = subscribePromise.cancel;
+                return catchPromise;
+            },
+            watchArguments: [toRef(state, "intendToSubscribe"), toRef(state, "listArgs"), toRef(state, "retrieveArgs")],
+            clearActiveOnResolved: false,
+        });
+
+        state.subscribed = toRef(subscribeIntent.state, "active");
+
+        listIntent = useCancellableIntent({
+            awaitableWithCancel: listInstance.list,
+            watchArguments: [toRef(state, "intendToList"), toRef(state, "listArgs"), toRef(state, "retrieveArgs")],
         });
     });
 
     return {
         state,
         listInstance,
-        subscribe,
-        unsubscribe,
+        listIntent,
+        subscribeIntent,
+        subscribe: publicSubscribe,
+        unsubscribe: publicUnsubscribe,
         effectScope: es,
     };
 }

package/use/objectInstance.js

@@ -1,5 +1,5 @@
-import { cloneDeep, isEmpty } from "lodash";
-import { effectScope, reactive, unref } from "vue";
+import { cloneDeep } from "lodash";
+import { effectScope, reactive } from "vue";
 import { assignReactiveObject } from "../utils/assignReactiveObject";
 
 export class ObjectError extends Error {
@@ -24,7 +24,7 @@ export function setObjectInstanceCrud({ retrieve, create, update, patch, delete:
     defaultCrud.update = update;
     defaultCrud.patch = patch;
     defaultCrud.delete = deleteFn;
-    assignReactiveObject(defaultCrud.args, args);
+    Object.assign(defaultCrud.args, args);
 }
 
 export function useObjectInstances(instanceArgs) {
@@ -35,9 +35,9 @@ export function useObjectInstances(instanceArgs) {
     return instances;
 }
 
-export function useObjectInstance({ crudArgs, retrieveArgs }) {
+export function useObjectInstance({ crudArgs, id, retrieveArgs }) {
     const state = reactive({
-        objectInstanceCrud: {
+        crud: {
             args: {},
             retrieve: undefined,
             create: undefined,
@@ -46,32 +46,32 @@ export function useObjectInstance({ crudArgs, retrieveArgs }) {
             delete: undefined,
         },
         object: {},
-        defaultRetrieveArgs: retrieveArgs,
+        id,
+        retrieveArgs,
         loading: undefined,
         errored: false,
         error: null,
         deleted: false,
     });
-    assignReactiveObject(state.objectInstanceCrud, cloneDeep(defaultCrud));
+    // prevent linking of all instances to the same default .args object
+    Object.assign(state.crud, cloneDeep(defaultCrud));
     if (crudArgs) {
-        assignReactiveObject(state.objectInstanceCrud.args, crudArgs);
+        assignReactiveObject(state.crud.args, crudArgs);
     }
 
-    async function retrieve({ id, ...retrieveArgs }) {
+    function retrieve() {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.loading) {
-            throw new ObjectError("already loading.");
-        }
-        if (isEmpty(retrieveArgs) && !isEmpty(unref(state.defaultRetrieveArgs))) {
-            retrieveArgs = unref(state.defaultRetrieveArgs);
+            return Promise.reject(new ObjectError("already loading."));
         }
         state.loading = true;
         state.errored = false;
         state.error = null;
-        return state.objectInstanceCrud
+        return state.crud
             .retrieve({
-                crudArgs: state.objectInstanceCrud.args,
-                id,
-                retrieveArgs,
+                crudArgs: state.crud.args,
+                id: state.id,
+                retrieveArgs: state.retrieveArgs,
             })
             .then((object) => {
                 assignReactiveObject(state.object, object);
@@ -87,21 +87,18 @@ export function useObjectInstance({ crudArgs, retrieveArgs }) {
             });
     }
 
-    async function create({ object, ...retrieveArgs }) {
+    async function create({ object }) {
         if (state.loading) {
             throw new ObjectError("already loading.");
         }
-        if (isEmpty(retrieveArgs) && !isEmpty(unref(state.defaultRetrieveArgs))) {
-            retrieveArgs = unref(state.defaultRetrieveArgs);
-        }
         state.loading = true;
         state.errored = false;
         state.error = null;
-        return state.objectInstanceCrud
+        return state.crud
             .create({
-                crudArgs: state.objectInstanceCrud.args,
+                crudArgs: state.crud.args,
                 object,
-                retrieveArgs,
+                retrieveArgs: state.retrieveArgs,
             })
             .then((object) => {
                 assignReactiveObject(state.object, object);
@@ -117,21 +114,18 @@ export function useObjectInstance({ crudArgs, retrieveArgs }) {
             });
     }
 
-    async function update({ object, ...retrieveArgs }) {
+    async function update({ object }) {
         if (state.loading) {
             throw new ObjectError("already loading.");
         }
-        if (isEmpty(retrieveArgs) && !isEmpty(unref(state.defaultRetrieveArgs))) {
-            retrieveArgs = unref(state.defaultRetrieveArgs);
-        }
         state.loading = true;
         state.errored = false;
         state.error = null;
-        return state.objectInstanceCrud
+        return state.crud
             .update({
-                crudArgs: state.objectInstanceCrud.args,
+                crudArgs: state.crud.args,
                 object,
-                retrieveArgs,
+                retrieveArgs: state.retrieveArgs,
             })
             .then((object) => {
                 assignReactiveObject(state.object, object);
@@ -147,22 +141,19 @@ export function useObjectInstance({ crudArgs, retrieveArgs }) {
             });
     }
 
-    async function patch({ id, partialObject, ...retrieveArgs }) {
+    async function patch({ partialObject }) {
         if (state.loading) {
             throw new ObjectError("already loading.");
         }
-        if (isEmpty(retrieveArgs) && !isEmpty(unref(state.defaultRetrieveArgs))) {
-            retrieveArgs = unref(state.defaultRetrieveArgs);
-        }
         state.loading = true;
         state.errored = false;
         state.error = null;
-        return state.objectInstanceCrud
+        return state.crud
             .patch({
-                crudArgs: state.objectInstanceCrud.args,
-                id,
+                crudArgs: state.crud.args,
+                id: state.id,
                 partialObject,
-                retrieveArgs,
+                retrieveArgs: state.retrieveArgs,
             })
             .then((object) => {
                 assignReactiveObject(state.object, object);
@@ -178,17 +169,17 @@ export function useObjectInstance({ crudArgs, retrieveArgs }) {
             });
     }
 
-    async function deleteFn(id) {
+    async function deleteFn() {
         if (state.loading) {
             throw new ObjectError("already loading.");
         }
         state.loading = true;
         state.errored = false;
         state.error = null;
-        return state.objectInstanceCrud
+        return state.crud
             .delete({
-                crudArgs: state.objectInstanceCrud.args,
-                id,
+                crudArgs: state.crud.args,
+                id: state.id,
             })
             .then(() => {
                 state.deleted = true;

package/use/objectSubscription.js

@@ -1,7 +1,8 @@
-import { identity } from "lodash";
-import { computed, effectScope, onScopeDispose, reactive, watch } from "vue";
+import { cloneDeep } from "lodash";
+import { computed, effectScope, reactive, toRef } from "vue";
 import { assignReactiveObject } from "../utils/assignReactiveObject";
 import { useObjectInstance } from "./objectInstance";
+import { useCancellableIntent } from "../utils/cancellableIntent";
 
 export class ObjectSubscriptionError extends Error {
     constructor(message) {
@@ -10,12 +11,14 @@ export class ObjectSubscriptionError extends Error {
     }
 }
 
-const defaultCrud = reactive({
+const defaultCrud = {
+    args: {},
     subscribe: undefined,
-});
+};
 
-export function setObjectSubscriptionCrud({ subscribe }) {
+export function setObjectSubscriptionCrud({ subscribe, args = {} }) {
     defaultCrud.subscribe = subscribe;
+    Object.assign(defaultCrud.args, args);
 }
 
 export function useObjectSubscriptions(subscriptionArgs) {
@@ -27,61 +30,70 @@ export function useObjectSubscriptions(subscriptionArgs) {
 }
 
 export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveArgs = {} }) {
+    if (retrieveArgs && objectInstance) {
+        throw new ObjectSubscriptionError(
+            "Cannot use retrieveArgs and objectInstance together, set retrieveArgs on objectInstance instead"
+        );
+    }
     if (!objectInstance) {
-        objectInstance = useObjectInstance({ crudArgs, retrieveArgs });
+        objectInstance = useObjectInstance({ crudArgs, id, retrieveArgs });
     }
     const state = reactive({
-        objectSubscriptionCrud: {
+        crud: {
+            args: {},
             subscribe: undefined,
         },
         id,
-        retrieveArgs,
         subscriptionLoading: undefined,
         subscriptionErrored: false,
         subscriptionError: null,
-        subscribed: false,
+        subscribed: undefined,
         intendToSubscribe: false,
         intendToRetrieve: false,
     });
-    assignReactiveObject(state.objectSubscriptionCrud, defaultCrud);
-    let cancelSubscription;
+    // prevent linking of all instances to the same default .args object
+    Object.assign(state.crud, cloneDeep(defaultCrud));
+    if (crudArgs) {
+        assignReactiveObject(state.crud.args, crudArgs);
+    }
+
+    let subscribeIntent, retrieveIntent;
 
     function updateFromSubscription(data) {
-        assignReactiveObject(objectInstance.state.object, data);
+        assignReactiveObject(state.object, data);
     }
 
     function deleteFromSubscription() {
-        objectInstance.state.deleted = true;
-        assignReactiveObject(objectInstance.state.object, {});
+        state.deleted = true;
+        assignReactiveObject(state.object, {});
     }
 
-    async function publicSubscribe({ retrieve = true } = {}) {
+    function publicSubscribe({ retrieve = true } = {}) {
+        let didSubscribe = false;
         if (!state.intendToSubscribe) {
             state.intendToSubscribe = true;
+            didSubscribe = true;
         }
         if (retrieve) {
             if (!state.intendToRetrieve) {
                 state.intendToRetrieve = true;
+                didSubscribe = true;
             }
         }
-        return subscribe();
+        return didSubscribe;
     }
 
-    async function subscribe() {
-        if (cancelSubscription || state.subscribed) {
-            throw new ObjectSubscriptionError("already subscribed.");
-        }
-        if (![state.id, state.retrieveArgs].every(identity)) {
-            // delayed until stuff is true;
-            return false;
+    function subscribe() {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
+        if (subscribeIntent.state.active || state.subscribed) {
+            return Promise.reject(new ObjectSubscriptionError("already subscribed or subscribing."));
         }
         state.subscriptionLoading = true;
         state.subscriptionErrored = false;
         state.subscriptionError = null;
         let subscribePromise;
-        cancelSubscription = () => subscribePromise.cancel();
-        subscribePromise = state.objectSubscriptionCrud.subscribe({
-            crudArgs: objectInstance.state.objectInstanceCrud.args,
+        subscribePromise = state.crud.subscribe({
+            crudArgs: state.crud.args,
             id,
             retrieveArgs: state.retrieveArgs,
             callback: (data, action) => {
@@ -92,7 +104,14 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
                 }
             },
         });
-        return subscribePromise
+        let cancelSubscription = async () => {
+            let cancelPromise = subscribePromise.cancel();
+            cancelSubscription = null;
+            state.subscribed = false;
+            return cancelPromise;
+        };
+        // then/catch/finally makes a new promise, we need to make sure the cancel method lives on.
+        const catchPromise = subscribePromise
             .then(() => {
                 state.subscribed = true;
                 return Promise.resolve(true);
@@ -110,26 +129,21 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
             .finally(() => {
                 state.subscriptionLoading = false;
             });
+        catchPromise.cancel = cancelSubscription;
+        return catchPromise;
     }
 
-    async function publicUnsubscribe() {
+    function publicUnsubscribe() {
+        let didUnsubscribe = false;
         if (state.intendToSubscribe) {
             state.intendToSubscribe = false;
+            didUnsubscribe = true;
         }
         if (state.intendToRetrieve) {
             state.intendToRetrieve = false;
+            didUnsubscribe = true;
         }
-        return unsubscribe();
-    }
-
-    async function unsubscribe() {
-        if (cancelSubscription) {
-            state.subscribed = false;
-            let returnPromise = cancelSubscription();
-            cancelSubscription = null;
-            return returnPromise;
-        }
-        return false;
+        return didUnsubscribe;
     }
 
     const es = effectScope();
@@ -139,46 +153,27 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
         state.errored = computed(() => objectInstance.state.errored || state.subscriptionErrored);
         state.error = computed(() => objectInstance.state.error || state.subscriptionError);
 
-        watch(
-            [() => state.intendToSubscribe, () => state.id, () => state.retrieveArgs],
-            async (newArgs, oldArgs) => {
-                const everyNew = newArgs.every((e) => e);
-                const everyOld = oldArgs.every((e) => e);
-                if (everyOld) {
-                    await unsubscribe();
-                }
-                if (everyNew) {
-                    if (!cancelSubscription && !state.subscribed) {
-                        await subscribe().catch(console.error);
-                    }
-                }
-            },
-            {
-                deep: true,
-            }
-        );
+        state.retrieveArgs = computed(() => objectInstance.state.retrieveArgs);
+        state.object = toRef(objectInstance.state, "object");
+        state.deleted = toRef(objectInstance.state, "deleted");
 
-        watch(
-            [() => state.intendToRetrieve, () => state.id, () => state.retrieveArgs],
-            async (newArgs) => {
-                const everyNew = newArgs.every((e) => e);
-                if (everyNew) {
-                    if (!objectInstance.state.loading) {
-                        await objectInstance.retrieve({ id: state.id, ...state.retrieveArgs }).catch(console.error);
-                    }
-                }
-            },
-            { deep: true }
-        );
+        subscribeIntent = useCancellableIntent({
+            awaitableWithCancel: subscribe,
+            watchArguments: [toRef(state, "intendToSubscribe"), toRef(state, "id"), toRef(state, "retrieveArgs")],
+            clearActiveOnResolved: false,
+        });
 
-        onScopeDispose(async () => {
-            await unsubscribe();
+        retrieveIntent = useCancellableIntent({
+            awaitableWithCancel: objectInstance.retrieve,
+            watchArguments: [toRef(state, "intendToRetrieve"), toRef(state, "id"), toRef(state, "retrieveArgs")],
         });
     });
 
     return {
         state,
         objectInstance,
+        subscribeIntent,
+        retrieveIntent,
         subscribe: publicSubscribe,
         unsubscribe: publicUnsubscribe,
         updateFromSubscription,