@arrai-innovations/reactive-helpers 11.1.0 → 11.3.0

package/docs.md

@@ -686,12 +686,13 @@ The configuration options used to create a list subscription.
 **Kind**: global typedef  
 **Properties**
 
-| Name         | Type             | Description                                                                              |
-| ------------ | ---------------- | ---------------------------------------------------------------------------------------- |
-| props        | `object`         | passed on to a created list instance if one is not provided                              |
-| functions    | `object`         | passed on to a created list instance if one is not provided                              |
-| listInstance | [`ListInstance`] | a list instance to use instead of creating one                                           |
-| keepOldPages | `boolean`        | if true, pages will not be cleared when defaultPageCallback is called. default is false. |
+| Name                           | Type             | Description                                                                              |
+| ------------------------------ | ---------------- | ---------------------------------------------------------------------------------------- |
+| props                          | `object`         | passed on to a created list instance if one is not provided                              |
+| functions                      | `object`         | passed on to a created list instance if one is not provided                              |
+| listInstance                   | [`ListInstance`] | a list instance to use instead of creating one                                           |
+| keepOldPages                   | `boolean`        | if true, pages will not be cleared when defaultPageCallback is called. default is false. |
+| clearListOnListIntentTriggered | `boolean`        | if true, the list will be cleared when the list intent is triggered. default is false.   |
 
 ## ListSubscriptionState
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "11.1.0",
+    "version": "11.3.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",

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

@@ -3,7 +3,7 @@ import { expectErrorToBeNull } from "../expectHelpers.js";
 import flushPromises from "flush-promises";
 import keyBy from "lodash-es/keyBy.js";
 import { inspect } from "util";
-import { isReactive, nextTick, reactive } from "vue";
+import { isReactive, nextTick, reactive, isRef, isReadonly } from "vue";
 
 afterAll(() => {
     vi.restoreAllMocks();
@@ -16,6 +16,7 @@ describe("use/listInstance.spec.js", function () {
         const listCrud = await import("../../../config/listCrud.js");
         const imported = await import("../../../use/listInstance");
         globalList = vi.fn();
+        globalList.cancel = vi.fn();
         listCrud.setListCrud({
             list: globalList,
             args: { stream: "test_stream" },
@@ -128,6 +129,7 @@ describe("use/listInstance.spec.js", function () {
                 listArgs: { user: 1 },
                 retrieveArgs: { fields: fields },
                 pageCallback: passedPageCallback,
+                isCancelled: expect.any(Object), // ref
             });
             expect(globalList).toHaveBeenCalledTimes(1);
         });
@@ -153,6 +155,7 @@ describe("use/listInstance.spec.js", function () {
                 listArgs: { user: 1 },
                 retrieveArgs: { fields: fields },
                 pageCallback: expect.any(Function),
+                isCancelled: expect.any(Object), // ref
             });
             expect(globalList).toHaveBeenCalledTimes(1);
             expectErrorToBeNull(listInstance.state.error);
@@ -207,6 +210,7 @@ describe("use/listInstance.spec.js", function () {
                 listArgs: { user: 1 },
                 retrieveArgs: { fields: fields },
                 pageCallback: passedPageCallback,
+                isCancelled: expect.any(Object), // ref
             });
             expect(globalList).toHaveBeenCalledTimes(1);
         });
@@ -272,6 +276,7 @@ describe("use/listInstance.spec.js", function () {
                 listArgs: { user: 1 },
                 retrieveArgs: { fields: fields },
                 pageCallback: passedPageCallback,
+                isCancelled: expect.any(Object), // ref
             });
             expect(globalList).toHaveBeenCalledTimes(1);
         });
@@ -318,6 +323,7 @@ describe("use/listInstance.spec.js", function () {
                 listArgs: { user: 1 },
                 retrieveArgs: { fields: fields },
                 pageCallback: passedPageCallback,
+                isCancelled: expect.any(Object), // ref
             });
             expect(globalList).toHaveBeenCalledTimes(1);
 
@@ -560,4 +566,39 @@ describe("use/listInstance.spec.js", function () {
         expect(listInstance.state.order).toEqual(crudListResolvedPage3.map((e) => e.id.toString()));
         expect(listInstance.state.objectsInOrder).toEqual(crudListResolvedPage3);
     });
+    describe("list promise cancellation", function () {
+        it("cancels and sets isCancelled", async function () {
+            let myListFnCancelResolve, passedIsCancelled;
+            const myListFn = vi.fn().mockImplementation(({ isCancelled }) => {
+                passedIsCancelled = isCancelled;
+                const promise = new Promise(() => {});
+                promise.cancel = async () => {
+                    await new Promise((resolve) => {
+                        myListFnCancelResolve = resolve;
+                    });
+                };
+                return promise;
+            });
+            const listInstance = useListInstance({
+                props: {},
+                functions: {
+                    list: myListFn,
+                },
+            });
+
+            const cancelablePromise = listInstance.list();
+
+            expect(passedIsCancelled).toBeTruthy();
+            expect(isRef(passedIsCancelled)).toBe(true);
+            expect(isReadonly(passedIsCancelled)).toBe(true);
+            expect(passedIsCancelled.value).toBe(false);
+            expect(cancelablePromise.cancel).toBeTruthy();
+
+            const cancelPromise = cancelablePromise.cancel();
+            myListFnCancelResolve();
+            await cancelPromise;
+
+            expect(passedIsCancelled.value).toBe(true);
+        });
+    });
 });

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

@@ -142,7 +142,6 @@ describe("use/listSubscription.spec.js", function () {
                 obj: listSubscription.subscribeIntent.state,
                 prop: "active",
             });
-            expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
             expect(returnValue).toBe(true);
 
@@ -288,7 +287,6 @@ describe("use/listSubscription.spec.js", function () {
             crudSubscribeResolvable[0].cancel.resolve(true);
             const returnValue = await unsubscribe;
             await poll(() => !listSubscription.state.subscribed);
-            expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
             expect(returnValue).toBe(true);
             expect(listSubscription.state.subscribed).toBe(false);
@@ -322,7 +320,6 @@ describe("use/listSubscription.spec.js", function () {
             crudSubscribeResolvable[0].cancel.resolve(true);
             const returnValue = await unsubscribePromise;
             await poll(() => !listSubscription.state.subscribed);
-            expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
             expect(returnValue).toBe(true);
             expect(listSubscription.state.subscribed).toBe(false);
@@ -382,7 +379,6 @@ describe("use/listSubscription.spec.js", function () {
             crudSubscribeResolvable[0].cancel.resolve(true);
             const returnValue = await unsubscribePromise;
             await poll(() => !listSubscription.state.subscribed);
-            expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
             expect(returnValue).toBe(true);
             expect(listSubscription.state.subscribed).toBe(false);
@@ -455,7 +451,6 @@ describe("use/listSubscription.spec.js", function () {
             crudSubscribeResolvable[0].cancel.resolve(true);
             const returnValue = await unsubscribePromise;
             await poll(() => !listSubscription.state.subscribed);
-            expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
             expect(returnValue).toBe(true);
             expect(listSubscription.state.subscribed).toBe(false);
@@ -508,7 +503,6 @@ describe("use/listSubscription.spec.js", function () {
             await crudSubscribeResolvable[1].resolve();
             await crudListResolvable[1].resolve();
             await poll(() => listSubscription.state.subscribed);
-            expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[0].promise.cancel).toHaveBeenCalledTimes(1);
 
             expect(crudSubscribe).toHaveBeenCalledTimes(2);
@@ -518,7 +512,6 @@ describe("use/listSubscription.spec.js", function () {
             const returnValue = await unsubscribePromise;
             expect(returnValue).toBe(true);
             await poll(() => !listSubscription.state.subscribed);
-            expect(crudSubscribeResolvable[1].promise.cancel).toHaveBeenCalledWith();
             expect(crudSubscribeResolvable[1].promise.cancel).toHaveBeenCalledTimes(1);
             expect(listSubscription.state.subscribed).toBe(false);
         });
@@ -622,4 +615,52 @@ describe("use/listSubscription.spec.js", function () {
         expect(inspect(listSubscription.A)).toEqual(inspect(listSubscriptionA));
         expect(inspect(listSubscription.B)).toEqual(inspect(listSubscriptionB));
     });
+    describe("clearListOnListIntentTriggered true", function () {
+        it("on true", async function () {
+            crudSubscribeResolvable[0].promise.cancel.mockImplementation(() => Promise.resolve(true));
+            const listArgs = reactive({
+                user: 1,
+            });
+            const retrieveArgs = reactive({
+                fields: fields,
+            });
+            const listInstance = useListInstance({
+                props: { listArgs, retrieveArgs },
+            });
+            listInstance.clearList = vi.fn().mockImplementationOnce(() => undefined);
+            const listSubscription = useListSubscription({
+                listInstance,
+                clearListOnListIntentTriggered: true,
+            });
+            listSubscription.subscribe();
+            await nextTick();
+            await flushPromises();
+            listArgs.user = 2;
+            expect(listInstance.clearList).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe("clearListOnListIntentTriggered false", function () {
+        it("on true", async function () {
+            crudSubscribeResolvable[0].promise.cancel.mockImplementation(() => Promise.resolve(true));
+            const listArgs = reactive({
+                user: 1,
+            });
+            const retrieveArgs = reactive({
+                fields: fields,
+            });
+            const listInstance = useListInstance({
+                props: { listArgs, retrieveArgs },
+            });
+            listInstance.clearList = vi.fn().mockImplementationOnce(() => undefined);
+            const listSubscription = useListSubscription({
+                listInstance,
+                clearListOnListIntentTriggered: false,
+            });
+            listSubscription.subscribe();
+            await nextTick();
+            await flushPromises();
+            listArgs.user = 2;
+            expect(listInstance.clearList).toHaveBeenCalledTimes(0);
+        });
+    });
 });

package/use/cancellableIntent.js

@@ -54,7 +54,7 @@ export function useCancellableIntent({
         return false;
     }
 
-    const doIntentWatch = async () => {
+    const doIntentWatch = () => {
         state.errored = false;
         state.error = null;
         if (state.activeCount === undefined) {
@@ -127,13 +127,13 @@ export function useCancellableIntent({
         }
     };
 
-    const guardWatch = async () => {
+    const guardWatch = () => {
         if (delayedWatch) {
             // if all guards are false, run the watch
             if (Object.values(guardArguments).every((x) => !x)) {
                 const myDelayedWatch = delayedWatch;
                 delayedWatch = null;
-                await myDelayedWatch();
+                myDelayedWatch();
             }
         }
     };

package/use/list.js

@@ -31,6 +31,7 @@ export const useList = ({
     functions = {},
     paged = false,
     keepOldPages = false,
+    clearListOnListIntentTriggered = false,
     searchThrottle = 500,
     sortThrottleWait,
     searchShowAllWhenEmpty,
@@ -63,6 +64,7 @@ export const useList = ({
 
         managed.listSubscription = useListSubscription({
             listInstance: managed.listInstance,
+            clearListOnListIntentTriggered,
         });
         managed.listSubscription.state.intendToList = toRef(props, "intendToList");
         managed.listSubscription.state.intendToSubscribe = toRef(props, "intendToSubscribe");

package/use/listInstance.js

@@ -2,7 +2,7 @@ import { getListCrud } from "../config/listCrud.js";
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { getFakeId } from "../utils/getFakeId.js";
 import inspect from "browser-util-inspect";
-import { effectScope, reactive, toRef, watch, computed, unref } from "vue";
+import { effectScope, reactive, toRef, watch, computed, unref, ref, readonly } from "vue";
 
 export class ListError extends Error {
     constructor(message, code) {
@@ -182,16 +182,19 @@ export function useListInstance({ props, functions = {}, keepOldPages = false })
         state.loading = true;
         state.errored = false;
         state.error = null;
+        const isCancelled = ref(false);
         const listPromise = state.crud.list({
             crudArgs: state.crud.args,
             retrieveArgs: state.retrieveArgs,
             listArgs: state.listArgs,
             pageCallback: returnedObject.pageCallback,
+            isCancelled: readonly(isCancelled),
         });
         let resolveState = false;
         if (listPromise.cancel) {
             promises.list.cancel = async () => {
                 let promise = listPromise.cancel();
+                isCancelled.value = true;
                 if (promise) {
                     await promise;
                 }

package/use/listSubscription.js

@@ -22,6 +22,7 @@ export class ListSubscriptionError extends Error {
  * @property {object} functions - passed on to a created list instance if one is not provided
  * @property {ListInstance} listInstance - a list instance to use instead of creating one
  * @property {boolean} keepOldPages - if true, pages will not be cleared when defaultPageCallback is called. default is false.
+ * @property {boolean} clearListOnListIntentTriggered - if true, the list will be cleared when the list intent is triggered. default is false.
  */
 
 /* eslint-disable jsdoc/check-types */
@@ -70,7 +71,13 @@ export function useListSubscriptions(args, listInstances = {}) {
  * @param {ListSubscriptionOptions} options - the configuration options for the list subscription
  * @returns {ListSubscription} - the list subscription
  */
-export function useListSubscription({ listInstance, props, functions, keepOldPages = false }) {
+export function useListSubscription({
+    listInstance,
+    props,
+    functions,
+    keepOldPages = false,
+    clearListOnListIntentTriggered = false,
+}) {
     if (!listInstance && !props) {
         throw new ListSubscriptionError("useListSubscription should be passed listInstance or props and functions.");
     }
@@ -233,7 +240,12 @@ export function useListSubscription({ listInstance, props, functions, keepOldPag
         state.subscribed = toRef(subscribeIntent.state, "active");
 
         listIntent = useCancellableIntent({
-            awaitableWithCancel: listInstance.list,
+            awaitableWithCancel: () => {
+                if (clearListOnListIntentTriggered) {
+                    listInstance.clearList();
+                }
+                return listInstance.list();
+            },
             watchArguments: reactive({
                 intendToList: toRef(state, "intendToList"),
                 listArgs: toRef(parentState, "listArgs"),