@arrai-innovations/reactive-helpers 8.0.4 → 8.1.1

package/.eslintrc.cjs

@@ -5,11 +5,7 @@ module.exports = {
         node: true,
     },
     plugins: ["jsdoc"],
-    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier", "plugin:jsdoc/recommended-error"],
-
-    parserOptions: {
-        parser: "babel-eslint",
-    },
+    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier", "plugin:jsdoc/recommended"],
 
     rules: {
         "no-console": "off", // console.error is useful.

package/docs.md

@@ -9,6 +9,35 @@
 | [utils/lifecycleDebug]       | Debug lifecycle hooks                                                                                                        |
 | [utils/transformWalk]        | Object walking utility.                                                                                                      |
 
+## Constants
+
+| Name               | Description |
+| ------------------ | ----------- |
+| [objectifyClasses] |
+| [combineClasses]   |
+| [stringifyClass]   |
+| [stringifyClasses] |
+
+## Functions
+
+| Name                         | Description |
+| ---------------------------- | ----------- |
+| [useCombineClasses(classes)] |
+
+## Typedefs
+
+| Name                 | Description                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| [CSSValue]           | A string representing a CSS class or a space-separated list of CSS classes.                            |
+| [CSSObject]          | A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class. |
+| [CSSClasses]         | A mixed array containing multiple ways of specifying CSS classes.                                      |
+| [CSSStringOrObject]  | The amalgamated classes as returned by `objectifyClasses` & `combineClasses`.                          |
+| [CSSValue]           | A string representing a CSS class or a space-separated list of CSS classes.                            |
+| [CSSObject]          | A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class. |
+| [CSSClasses]         | A mixed array containing multiple ways of specifying CSS classes.                                      |
+| [CSSClassesWithRefs] | A mixed array containing multiple ways of specifying CSS classes.                                      |
+| [CSSStringOrObject]  | A CSS object or a space-separated list of CSS classes.                                                 |
+
 ## utils/assignReactiveObject
 
 Reactive object assignment utilities
@@ -320,6 +349,105 @@ const transformed = transformWalk(obj, (key, value, path) => {
 // }
 ```
 
+## objectifyClasses
+
+**Kind**: global constant  
+**Returns**: [`CSSStringOrObject`][1] - A CSS object or a space-separated list of CSS classes.
+
+| Param      | Type           | Description                                                       |
+| ---------- | -------------- | ----------------------------------------------------------------- |
+| ...classes | [`CSSClasses`] | A mixed array containing multiple ways of specifying CSS classes. |
+
+## combineClasses
+
+**Kind**: global constant  
+**Returns**: [`CSSStringOrObject`] - A CSS object or a space-separated list of CSS classes.
+
+| Param      | Type                   | Description                                                                                                   |
+| ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
+| ...classes | [`CSSClassesWithRefs`] | Handles as arguments the multiple ways of specifying CSS class related values, including refs to such values. |
+
+## stringifyClass
+
+**Kind**: global constant  
+**Returns**: `CSSString` - A space-separated list of CSS classes.
+
+| Param | Type           | Description                                                       |
+| ----- | -------------- | ----------------------------------------------------------------- |
+| cls   | [`CSSClasses`] | A mixed array containing multiple ways of specifying CSS classes. |
+
+## stringifyClasses
+
+**Kind**: global constant  
+**Returns**: `CSSString` - A space-separated list of CSS classes.
+
+| Param      | Type           | Description                                                                    |
+| ---------- | -------------- | ------------------------------------------------------------------------------ |
+| ...classes | [`CSSClasses`] | Handles as arguments the multiple ways of specifying CSS class related values. |
+
+## useCombineClasses(classes)
+
+**Kind**: global function  
+**Returns**: `Ref.<CSSStringOrObject>` - A Vue ref pointing to the amalgamated CSS string or object.
+
+| Param   | Type           | Description                                                                                  |
+| ------- | -------------- | -------------------------------------------------------------------------------------------- |
+| classes | [`CSSClasses`] | A mixed array containing multiple ways of specifying CSS classes. Non-ref values are cloned. |
+
+## CSSValue
+
+A string representing a CSS class or a space-separated list of CSS classes.
+
+**Kind**: global typedef
+
+## CSSObject
+
+A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
+
+**Kind**: global typedef
+
+## CSSClasses
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+**Kind**: global typedef
+
+## CSSStringOrObject
+
+The amalgamated classes as returned by `objectifyClasses` & `combineClasses`.
+
+**Kind**: global typedef
+
+## CSSValue
+
+A string representing a CSS class or a space-separated list of CSS classes.
+
+**Kind**: global typedef
+
+## CSSObject
+
+A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
+
+**Kind**: global typedef
+
+## CSSClasses
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+**Kind**: global typedef
+
+## CSSClassesWithRefs
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+**Kind**: global typedef
+
+## CSSStringOrObject
+
+A CSS object or a space-separated list of CSS classes.
+
+**Kind**: global typedef
+
 <!-- LINKS -->
 
 [utils/assignreactiveobject]: #utilsassignreactiveobject
@@ -328,6 +456,15 @@ const transformed = transformWalk(obj, (key, value, path) => {
 [utils/keydiff]: #utilskeydiff
 [utils/lifecycledebug]: #utilslifecycledebug
 [utils/transformwalk]: #utilstransformwalk
+[objectifyclasses]: #objectifyclasses
+[combineclasses]: #combineclasses
+[stringifyclass]: #stringifyclass
+[stringifyclasses]: #stringifyclasses
+[cssvalue]: #cssvalue
+[cssobject]: #cssobject
+[cssclasses]: #cssclasses
+[cssstringorobject]: #cssstringorobject
+[cssclasseswithrefs]: #cssclasseswithrefs
 [~validtargetorsource]: #utilsassignreactiveobjectvalidtargetorsource
 [`utils/assignreactiveobject`]: #utilsassignreactiveobject
 [~debugmessagefunction]: #utilsdebugmessagedebugmessagefunction
@@ -338,6 +475,11 @@ const transformed = transformWalk(obj, (key, value, path) => {
 [`utils/keydiff`]: #utilskeydiff
 [`utils/lifecycledebug`]: #utilslifecycledebug
 [`utils/transformwalk`]: #utilstransformwalk
+[1]: #cssstringorobject
+[`cssclasses`]: #cssclasses
+[`cssstringorobject`]: #cssstringorobject
+[`cssclasseswithrefs`]: #cssclasseswithrefs
+[usecombineclasses(classes)]: #usecombineclassesclasses
 [~addreactiveobject(target, source, \[exclude\], \[addedkeys\])]: #utilsassignreactiveobjectaddreactiveobjecttarget-source-exclude-addedkeys
 [~updatereactiveobject(target, source, \[exclude\], \[samekeys\])]: #utilsassignreactiveobjectupdatereactiveobjecttarget-source-exclude-samekeys
 [~addorupdatereactiveobject(target, source, \[exclude\], \[addedkeys\], \[samekeys\])]: #utilsassignreactiveobjectaddorupdatereactiveobjecttarget-source-exclude-addedkeys-samekeys

package/jsdoc-to-markdown.sh

@@ -8,8 +8,9 @@ diffCode=$?
 # we want to return a non-zero exit code if the files are different, to stop the commit
 if [ $diffCode != 0 ]; then
   echo "docs.md is out of date, see git diff for details"
-  mv ./docs.new.md ./docs.md
+  mv -f ./docs.new.md ./docs.md
   exit $diffCode
 fi
-set -e
-rm ./docs.new.md
+rm -f ./docs.new.md
+git rm ./docs.new.md > /dev/null 2>&1
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "8.0.4",
+    "version": "8.1.1",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",
@@ -10,7 +10,7 @@
         "tests": "tests"
     },
     "scripts": {
-        "test": "jest",
+        "test": "vitest",
         "coverage": "npm run coverage:clean; npm test -- --coverage=true",
         "coverage:clean": "rm -rf coverage",
         "prepare": "husky install",
@@ -28,32 +28,29 @@
     "homepage": "https://github.com/arrai-innovations/reactive-helpers#readme",
     "devDependencies": {
         "@arrai-innovations/commitlint-config": "^1.1.0",
-        "@babel/preset-env": "^7.17.10",
         "@commitlint/cli": "^16.2.4",
         "@godaddy/dmd": "^1.0.4",
         "@trivago/prettier-plugin-sort-imports": "^4.1.1",
-        "@types/jest": "^27.5.0",
+        "@vitest/coverage-v8": "^0.32.2",
         "@vue/compiler-sfc": "^3.3.4",
         "@vue/eslint-config-prettier": "^7.0.0",
         "@vue/test-utils": "^2.3.2",
-        "@vue/vue3-jest": "^27.0.0",
-        "babel-eslint": "^10.1.0",
-        "babel-jest": "^27.5.1",
         "doctoc": "^2.1.0",
-        "eslint": "^7.32.0",
-        "eslint-plugin-jest": "^26.1.5",
+        "eslint": ">=8.0.0",
         "eslint-plugin-jsdoc": "^46.2.6",
+        "eslint-plugin-vitest": "0.2.6",
+        "eslint-plugin-vitest-globals": "^1.3.1",
         "eslint-plugin-vue": "^8.7.1",
         "flush-promises": "^1.0.2",
         "jsdoc-to-markdown": "^8.0.0",
         "lint-staged": "^13.2.2",
-        "prettier": "2.6.2"
+        "prettier": "2.6.2",
+        "vitest": "^0.32.2"
     },
     "dependencies": {
         "browser-util-inspect": "^0.2.0",
         "flexsearch": "^0.7.21",
         "husky": "^7.0.4",
-        "jest": "^27.5.1",
         "pinst": "^3.0.0",
         "vue-deepunref": "^1.0.1"
     },

package/tests/unit/.eslintrc.cjs

@@ -1,10 +1,10 @@
 module.exports = {
-    plugins: ["jest"],
-    extends: ["plugin:jest/recommended"],
+    plugins: ["vitest"],
+    extends: ["eslint:recommended", "plugin:vitest/recommended", "plugin:vitest-globals/recommended"],
     env: {
-        "jest/globals": true,
+        "vitest-globals/env": true,
     },
     rules: {
-        "jest/no-conditional-expect": "off",
+        "vitest/no-conditional-expect": "off",
     },
 };

package/tests/unit/crudPromise.js

@@ -11,7 +11,7 @@ export class CancellableResolvable {
     constructor() {
         const newResolvable = new Resolvable();
         const cancelResolvable = new Resolvable();
-        newResolvable.promise.cancel = jest
+        newResolvable.promise.cancel = vi
             .fn()
             .mockImplementationOnce(async () => cancelResolvable.promise)
             .mockRejectedValue(new Error("cancel already called"));

package/tests/unit/mockOnUnmounted.js

@@ -1,8 +1,8 @@
 export function getMockOnUnmounted() {
     const mockOnUnmounted = {};
-    jest.mock("vue", () => ({
+    vi.mock("vue", () => ({
         _esModule: true,
-        ...jest.requireActual("vue"),
+        ...vi.requireActual("vue"),
         onUnmounted: () => mockOnUnmounted,
     }));
     return mockOnUnmounted;

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

@@ -0,0 +1,150 @@
+import { useCancellableIntent } from "../../../use/index.js";
+import { CancellableResolvable } from "../crudPromise.js";
+import flushPromises from "flush-promises";
+import { nextTick, reactive, ref } from "vue";
+
+describe("use/cancellableIntent", () => {
+    let mockAwaitableWithCancel, cancellableResolvable;
+    beforeEach(async () => {
+        cancellableResolvable = new CancellableResolvable();
+        mockAwaitableWithCancel = vi.fn().mockReturnValue(cancellableResolvable.promise);
+    });
+    afterEach(() => {
+        cancellableResolvable = null;
+        vi.resetAllMocks();
+    });
+    it("should throw an error if awaitableWithCancel is not provided", () => {
+        expect(() => {
+            useCancellableIntent({});
+        }).toThrow("awaitableWithCancel is required");
+    });
+
+    it("should throw an error if awaitableWithCancel is not a function", () => {
+        expect(() => {
+            useCancellableIntent({
+                awaitableWithCancel: "not a function",
+            });
+        }).toThrow("awaitableWithCancel must be a function");
+    });
+    describe("Resolution", () => {
+        it("should initiate the intent and resolve the promise when the awaitableWithCancel resolves", async () => {
+            const subscribeIntent = useCancellableIntent({
+                awaitableWithCancel: mockAwaitableWithCancel,
+                watchArguments: {
+                    testArg: 1,
+                },
+            });
+            await nextTick();
+            await flushPromises();
+            expect(mockAwaitableWithCancel).toHaveBeenCalledTimes(1);
+            expect(subscribeIntent.state.active).toBe(true);
+            expect(subscribeIntent.state.resolving).toBe(true);
+
+            cancellableResolvable.resolve(true);
+
+            await nextTick();
+            await flushPromises();
+
+            expect(subscribeIntent.state.active).toBe(false);
+            expect(subscribeIntent.state.resolving).toBe(false);
+        });
+    });
+
+    describe("Cancellation", () => {
+        it("should cancel the previous promise when watched arguments changed", async () => {
+            let testArgRef = ref(1);
+            const subscribeIntent = useCancellableIntent({
+                awaitableWithCancel: mockAwaitableWithCancel,
+                watchArguments: reactive({
+                    testArg: testArgRef,
+                }),
+                clearActiveOnResolved: true,
+            });
+            await nextTick();
+            await flushPromises();
+            expect(mockAwaitableWithCancel).toHaveBeenCalledTimes(1);
+            expect(subscribeIntent.state.active).toBe(true);
+            expect(subscribeIntent.state.resolving).toBe(true);
+            testArgRef.value = 2;
+
+            await nextTick();
+            await flushPromises();
+            expect(cancellableResolvable.promise.cancel).toHaveBeenCalledTimes(1);
+            expect(subscribeIntent.state.active).toBe(true);
+            expect(subscribeIntent.state.resolving).toBe(true);
+
+            cancellableResolvable.resolve(true);
+            await nextTick();
+            await flushPromises();
+            expect(subscribeIntent.state.active).toBe(false);
+            expect(subscribeIntent.state.resolving).toBe(false);
+        });
+    });
+
+    describe("Delay", () => {
+        it("should handle the delayed watch properly", async () => {
+            let testGuardRef = ref(true);
+            const subscribeIntent = useCancellableIntent({
+                awaitableWithCancel: mockAwaitableWithCancel,
+                watchArguments: {
+                    testArg: 1,
+                },
+                guardArguments: reactive({
+                    testGuard: testGuardRef,
+                }),
+            });
+
+            expect(mockAwaitableWithCancel).not.toHaveBeenCalled();
+            expect(subscribeIntent.state.activeCount).toBeUndefined();
+            expect(subscribeIntent.state.resolvingCount).toBeUndefined();
+
+            testGuardRef.value = false;
+            await nextTick();
+            await flushPromises();
+            expect(mockAwaitableWithCancel).toHaveBeenCalled();
+            expect(subscribeIntent.state.active).toBe(true);
+            expect(subscribeIntent.state.resolving).toBe(true);
+
+            cancellableResolvable.resolve(true);
+            await nextTick();
+            await flushPromises();
+            expect(subscribeIntent.state.active).toBe(false);
+            expect(subscribeIntent.state.resolving).toBe(false);
+        });
+    });
+    describe("Rejection", () => {
+        //error is not being caught
+        it.skip("errored", async () => {
+            const consoleErrorMock = vi.spyOn(console, "error").mockImplementation(() => {});
+            const subscribeIntent = useCancellableIntent({
+                awaitableWithCancel: mockAwaitableWithCancel,
+                watchArguments: {
+                    testArg: 1,
+                },
+            });
+            await nextTick();
+            await flushPromises();
+
+            const mockError = new Error("rejected");
+            cancellableResolvable.reject(mockError);
+
+            await nextTick();
+            await flushPromises();
+
+            expect(cancellableResolvable.promise.cancel).toHaveBeenCalledTimes(1);
+            expect(subscribeIntent.state.active).toBe(true);
+            expect(subscribeIntent.state.resolving).toBe(true);
+
+            await cancellableResolvable.cancel.resolve(true);
+            await nextTick();
+            await flushPromises();
+
+            await expect(cancellableResolvable.promise).rejects.toThrow(mockError);
+            expect(consoleErrorMock).toHaveBeenCalledWith(mockError);
+            expect(subscribeIntent.state.active).toBe(false);
+            expect(subscribeIntent.state.resolving).toBe(false);
+            expect(subscribeIntent.state.errored).toBe(true);
+            expect(subscribeIntent.state.error).toBe(mockError);
+        });
+    });
+});

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

@@ -10,8 +10,8 @@ describe("use/listCalculated", () => {
         useListCalculated = listCalculatedModule.useListCalculated;
     });
     it("should return a list of calculated items", async () => {
-        const mainListInstance = useListInstance({});
-        const calculatedListInstance = useListInstance({});
+        const mainListInstance = useListInstance({ props: {} });
+        const calculatedListInstance = useListInstance({ props: {} });
         mainListInstance.addListObject({
             id: "1",
             name: "main",
@@ -36,15 +36,13 @@ describe("use/listCalculated", () => {
                 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(!!listCalculated.state.calculatedObjects?.[1]).toBe(true);
+        expect("calculatedItems" in listCalculated.state.calculatedObjects[1]).toBe(true);
+        expect("calculatedItem" in listCalculated.state.calculatedObjects[1]).toBe(true);
         // expect uses enumeration, which uses handler.ownKeys and handler.getOwnPropertyDescriptor
         expect(deepUnref(listCalculated.state.objects)).toEqual({
             1: {
@@ -54,7 +52,7 @@ describe("use/listCalculated", () => {
                 calculated_items: ["2", "3"],
             },
         });
-        expect(deepUnref(listCalculated.state.myCalculatedObjects)).toEqual({
+        expect(deepUnref(listCalculated.state.calculatedObjects)).toEqual({
             1: {
                 calculatedItems: [
                     {

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

@@ -18,7 +18,7 @@ describe("use/listFilter", () => {
     });
 
     it("should match an allowed values list", async () => {
-        const list = useListInstance({});
+        const list = useListInstance({ props: {} });
         const filter = useListFilter({
             parentState: list.state,
             allowedValues: reactive({
@@ -52,7 +52,7 @@ describe("use/listFilter", () => {
         });
     });
     it("should match an allowed filter function", async () => {
-        const list = useListInstance({});
+        const list = useListInstance({ props: {} });
         const filter = useListFilter({
             parentState: list.state,
             allowedFilter: (object) => object.id == 1 || object.id == 3,
@@ -84,7 +84,7 @@ describe("use/listFilter", () => {
     });
     it("should match by search term", async () => {
         const textSearchValue = ref("one");
-        const list = useListInstance({});
+        const list = useListInstance({ props: {} });
         const filter = useListFilter({
             parentState: list.state,
             useTextSearch: true,
@@ -151,7 +151,7 @@ describe("use/listFilter", () => {
         });
     });
     it("should match an excluded filter function", async () => {
-        const list = useListInstance({});
+        const list = useListInstance({ props: {} });
         const filter = useListFilter({
             parentState: list.state,
             excludedFilter: (object) => object.id == 2 || object.id == 4,
@@ -182,7 +182,7 @@ describe("use/listFilter", () => {
         });
     });
     it("should exclude an excludedValues parameter", async () => {
-        const list = useListInstance({});
+        const list = useListInstance({ props: {} });
         const filter = useListFilter({
             parentState: list.state,
             excludedValues: reactive({
@@ -216,7 +216,7 @@ describe("use/listFilter", () => {
         });
     });
     it("no args: returns objects unfiltered", async () => {
-        const listInstance = useListInstance({});
+        const listInstance = useListInstance({ props: {} });
         const listItems = [
             { id: 4, name: "four", has_things: true },
             { id: 2, name: "two", has_things: true },
@@ -235,10 +235,10 @@ describe("use/listFilter", () => {
     });
     describe("useListFilter operates on parentState modified by useListSort", () => {
         it("computes state.order and state.objects in order", async () => {
-            jest.resetAllMocks();
+            vi.resetAllMocks();
             const orderByRules = [{ key: "name", desc: true, localeCompare: false }];
             const sortThrottleWait = 0;
-            const listInstance = useListInstance({});
+            const listInstance = useListInstance({ props: {} });
             const listItems = [
                 { id: 4, name: "four", has_things: true },
                 { id: 2, name: "two", has_things: true },
@@ -266,20 +266,24 @@ describe("use/listFilter", () => {
     });
     describe("useListFilters accepts args and parentInstances", () => {
         it("returns filtered objects", async () => {
-            jest.resetAllMocks();
+            vi.resetAllMocks();
             const fields = ["id", "__str__", "name"];
             const listInstanceA = useListInstance({
-                crudArgs: { stream: "test_streamA" },
-                listArgs: { user: 1 },
-                retrieveArgs: {
-                    fields,
+                props: {
+                    crudArgs: { stream: "test_streamA" },
+                    listArgs: { user: 1 },
+                    retrieveArgs: {
+                        fields,
+                    },
                 },
             });
             const listInstanceB = useListInstance({
-                crudArgs: { stream: "test_streamB" },
-                listArgs: { user: 2 },
-                retrieveArgs: {
-                    fields,
+                props: {
+                    crudArgs: { stream: "test_streamB" },
+                    listArgs: { user: 2 },
+                    retrieveArgs: {
+                        fields,
+                    },
                 },
             });
             const listFilterA = useListFilter({