@arrai-innovations/reactive-helpers 8.0.3 → 8.1.0

package/{.eslintrc.js → .eslintrc.cjs}

@@ -4,12 +4,8 @@ module.exports = {
     env: {
         node: true,
     },
-
-    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier"],
-
-    parserOptions: {
-        parser: "babel-eslint",
-    },
+    plugins: ["jsdoc"],
+    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier", "plugin:jsdoc/recommended-error"],
 
     rules: {
         "no-console": "off", // console.error is useful.
@@ -22,5 +18,6 @@ module.exports = {
                 asyncArrow: "always",
             },
         ],
+        "jsdoc/require-jsdoc": "off", // let's ease into this
     },
 };

package/.jsdoc2md.json

@@ -0,0 +1,4 @@
+{
+    "files": ["use/**/*.js", "utils/**/*.js"],
+    "plugin": "@godaddy/dmd"
+}

package/README.md

@@ -5,7 +5,7 @@
 ![ESLint](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/eslint.svg)
 ![Prettier](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/prettier.svg)
 
-VueJS 3 utility composition functions to help manipulate objects and lists.
+Vue.js 3 utility composition functions to help manipulate objects and lists.
 
 <!-- prettier-ignore-start -->
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -14,6 +14,7 @@ VueJS 3 utility composition functions to help manipulate objects and lists.
 - [Install](#install)
 - [Usage](#usage)
   - [Import](#import)
+  - [JSDocs](#jsdocs)
   - [List](#list)
     - [Instance](#instance)
     - [Subscription](#subscription)
@@ -46,8 +47,18 @@ $ npm install @arrai-innovations/reactive-helpers
 ```js
 // base import contains all exports
 import { useListInstance, useObjectInstance } from "@arrai-innovations/reactive-helpers";
+// you can also import individual modules
+import { useListInstance } from "@arrai-innovations/reactive-helpers/use/listInstance";
+// or the module categories
+import { useObjectInstance } from "@arrai-innovations/reactive-helpers/use";
 ```
 
+See the [JSDocs](./docs.md) for list of available modules and imports.
+
+### JSDocs
+
+[View the JSDocs](./docs.md)
+
 ### List
 
 #### Instance

package/docs.md

@@ -0,0 +1,350 @@
+## Modules
+
+| Module                       | Description                                                                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| [utils/assignReactiveObject] | Reactive object assignment utilities                                                                                         |
+| [utils/debugMessage]         | Configurable logging of debug messages at runtime.                                                                           |
+| [utils/flattenPaths]         | Get all paths from an array or object.                                                                                       |
+| [utils/keyDiff]              | Calculate the difference between objects in terms of what keys are the same, what keys are removed, and what keys are added. |
+| [utils/lifecycleDebug]       | Debug lifecycle hooks                                                                                                        |
+| [utils/transformWalk]        | Object walking utility.                                                                                                      |
+
+## utils/assignReactiveObject
+
+Reactive object assignment utilities
+
+-   [utils/assignReactiveObject]
+    -   [~addReactiveObject(target, source, \[exclude\], \[addedKeys\])]
+    -   [~updateReactiveObject(target, source, \[exclude\], \[sameKeys\])]
+    -   [~addOrUpdateReactiveObject(target, source, \[exclude\], \[addedKeys\], \[sameKeys\])]
+    -   [~trimReactiveObject(target, source, \[exclude\], \[removedKeys\])]
+    -   [~assignReactiveObject(target, source, \[exclude\])]
+    -   [~assignReactiveObjectDeep(target, source, \[exclude\])]
+    -   [~addOrUpdateReactiveObjectDeep(target, source, \[exclude\])]
+    -   [~ValidTargetOrSource]
+
+### utils/assignReactiveObject~addReactiveObject(target, source, \[exclude\], \[addedKeys\])
+
+Adds to a target the missing keys from a source. `addedKeys` can be precalculated to avoid recalculation.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were added, false otherwise.  
+**Throws**:
+
+-   `AssignReactiveObjectError` If either target or source are not ultimately objects or arrays.
+
+| Param         | Type                  | Description                                                                              |
+| ------------- | --------------------- | ---------------------------------------------------------------------------------------- |
+| target        | `ValidTargetOrSource` | The object receiving values.                                                             |
+| source        | `ValidTargetOrSource` | The object providing values.                                                             |
+| \[exclude\]   | `Array`               | Keys to exclude from the addition.                                                       |
+| \[addedKeys\] | `Array`               | Precaulcated array of keys to add, if available. Otherwise, the keys will be calculated. |
+
+### utils/assignReactiveObject~updateReactiveObject(target, source, \[exclude\], \[sameKeys\])
+
+Updates a target with mutually shared keys from a source. `sameKeys` can be precalculated to avoid recalculation.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were updated, false otherwise.  
+**Throws**:
+
+-   `AssignReactiveObjectError` If either target or source are not ultimately objects or arrays.
+
+| Param        | Type                  | Description                                                                                 |
+| ------------ | --------------------- | ------------------------------------------------------------------------------------------- |
+| target       | `ValidTargetOrSource` | The object receiving values.                                                                |
+| source       | `ValidTargetOrSource` | The object providing values.                                                                |
+| \[exclude\]  | `Array`               | Keys to exclude from the update.                                                            |
+| \[sameKeys\] | `Array`               | Precaulcated array of keys to update, if available. Otherwise, the keys will be calculated. |
+
+### utils/assignReactiveObject~addOrUpdateReactiveObject(target, source, \[exclude\], \[addedKeys\], \[sameKeys\])
+
+Adds to a target the missing keys from a source, and updates a target with mutually shared keys from a source.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were added or updated, false otherwise.
+
+| Param         | Type                  | Description                                                                                 |
+| ------------- | --------------------- | ------------------------------------------------------------------------------------------- |
+| target        | `ValidTargetOrSource` | The object receiving values.                                                                |
+| source        | `ValidTargetOrSource` | The object providing values.                                                                |
+| \[exclude\]   | `Array`               | Keys to exclude from the addition or update.                                                |
+| \[addedKeys\] | `Array`               | Precaulcated array of keys to add, if available. Otherwise, the keys will be calculated.    |
+| \[sameKeys\]  | `Array`               | Precaulcated array of keys to update, if available. Otherwise, the keys will be calculated. |
+
+### utils/assignReactiveObject~trimReactiveObject(target, source, \[exclude\], \[removedKeys\])
+
+Removes keys from a target that are not present in a source.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were removed, false otherwise.  
+**Throws**:
+
+-   `AssignReactiveObjectError` If either target or source are not ultimately objects or arrays.
+
+| Param           | Type                            | Description                                                                     |
+| --------------- | ------------------------------- | ------------------------------------------------------------------------------- |
+| target          | `ValidTargetOrSource`           | The object receiving trimming.                                                  |
+| source          | `ValidTargetOrSource` \| `null` | The object that provides the allowed set of keys for calculating `removedKeys`. |
+| \[exclude\]     | `Array`                         | Keys to exclude from removal.                                                   |
+| \[removedKeys\] | `Array`                         | An array to store removed keys.                                                 |
+
+### utils/assignReactiveObject~assignReactiveObject(target, source, \[exclude\])
+
+Change a target to match a source, where keys missing from the source are removed from the target,
+keys present in the source are added to the target, and keys present in both are updated in the target.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were added, updated, or removed, false otherwise.  
+**Throws**:
+
+-   `AssignReactiveObjectError` If either target or source are not ultimately objects or arrays.
+
+| Param       | Type                  | Description                          |
+| ----------- | --------------------- | ------------------------------------ |
+| target      | `ValidTargetOrSource` | The target object or array.          |
+| source      | `ValidTargetOrSource` | The reactive object to assign.       |
+| \[exclude\] | `Array`               | Keys to exclude from the assignment. |
+
+### utils/assignReactiveObject~assignReactiveObjectDeep(target, source, \[exclude\])
+
+Recursively change a target to match a source, where keys missing from the source are removed from the target,
+keys present in the source are added to the target, and keys present in both are updated in the target.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were added, updated, or removed, false otherwise.  
+**Throws**:
+
+-   `AssignReactiveObjectError` If either target or source are not ultimately objects or arrays.
+
+| Param       | Type                  | Description                          |
+| ----------- | --------------------- | ------------------------------------ |
+| target      | `ValidTargetOrSource` | The object receiving updates.        |
+| source      | `ValidTargetOrSource` | The object providing updates.        |
+| \[exclude\] | `Array`               | Keys to exclude from the assignment. |
+
+### utils/assignReactiveObject~addOrUpdateReactiveObjectDeep(target, source, \[exclude\])
+
+Recursively change a target to match a source, where keys present in the source are added to the target, and
+keys present in both are updated in the target. Missing keys are not removed.
+
+**Kind**: inner method of [`utils/assignReactiveObject`]  
+**Returns**: `boolean` - True if any keys were added or updated, false otherwise.  
+**Throws**:
+
+-   `AssignReactiveObjectError` If either target or source are not ultimately objects or arrays.
+
+| Param       | Type                  | Description                      |
+| ----------- | --------------------- | -------------------------------- |
+| target      | `ValidTargetOrSource` | The object receiving updates.    |
+| source      | `ValidTargetOrSource` | The object providing updates.    |
+| \[exclude\] | `Array`               | Keys to exclude from the update. |
+
+### utils/assignReactiveObject~ValidTargetOrSource
+
+targets and sources must be refs, objects, or arrays
+and refs must ultimately resolve to objects or arrays
+
+**Kind**: inner typedef of [`utils/assignReactiveObject`]
+
+## utils/debugMessage
+
+Configurable logging of debug messages at runtime.
+
+-   [utils/debugMessage]
+    -   [~useDebugMessage(categories)]
+    -   [~DebugMessageFunction]
+
+### utils/debugMessage~useDebugMessage(categories)
+
+Returns a function that logs debug messages based on enabled categories.
+
+**Kind**: inner method of [`utils/debugMessage`]  
+**Returns**: `DebugMessageFunction` - debug message function
+
+| Param      | Type             | Description                    |
+| ---------- | ---------------- | ------------------------------ |
+| categories | `Array.<string>` | categories for the message log |
+
+### utils/debugMessage~DebugMessageFunction
+
+Logs debug messages based on the specified categories and logging rules.
+
+**Kind**: inner typedef of [`utils/debugMessage`]  
+**Properties**
+
+| Name     | Type       | Description   |
+| -------- | ---------- | ------------- |
+| messages | `function` | log a message |
+
+## utils/flattenPaths
+
+Get all paths from an array or object.
+
+### utils/flattenPaths~flattenPaths(arrayOrObject, currentPath)
+
+Turn an array or object into an array of path strings. Recurses for any found arrays or objects.
+
+Array indexes are wrapped in square brackets and object keys are prefixed with a period.
+
+**Kind**: inner method of [`utils/flattenPaths`]  
+**Returns**: `Array.<string>` - paths
+
+| Param         | Type                | Description                                        |
+| ------------- | ------------------- | -------------------------------------------------- |
+| arrayOrObject | `Array` \| `object` | array or object to flatten                         |
+| currentPath   | `string`            | current path, for recursion or as a starting point |
+
+## utils/keyDiff
+
+Calculate the difference between objects in terms of what keys
+are the same, what keys are removed, and what keys are added.
+
+-   [utils/keyDiff]
+    -   [~keyDiff(newKeys, oldKeys, \[options\])]
+    -   [~keyDiffDeep(newObj, oldObj, \[options\])]
+    -   [~KeyDiffOptions]
+    -   [~KeyDiffResult]
+
+### utils/keyDiff~keyDiff(newKeys, oldKeys, \[options\])
+
+Calculate the difference between two arrays of keys, in terms of what keys
+are the same, what keys are removed, and what keys are added.
+
+**Kind**: inner method of [`utils/keyDiff`]  
+**Returns**: `KeyDiffResult` - - the differences
+
+| Param       | Type             | Description                    |
+| ----------- | ---------------- | ------------------------------ |
+| newKeys     | `Array.<string>` | keys to consider as new        |
+| oldKeys     | `Array.<string>` | keys to consider as old        |
+| \[options\] | `KeyDiffOptions` | which differences are returned |
+
+### utils/keyDiff~keyDiffDeep(newObj, oldObj, \[options\])
+
+Calculate the difference between two objects, in terms of what keys are the same,
+what keys are removed, and what keys are added. Keys are sourced deeply in the objects.
+
+**Kind**: inner method of [`utils/keyDiff`]  
+**Returns**: `KeyDiffResult` - - the differences
+
+| Param       | Type             | Description                    |
+| ----------- | ---------------- | ------------------------------ |
+| newObj      | `object`         | the new version of the object  |
+| oldObj      | `object`         | the old version of the object  |
+| \[options\] | `KeyDiffOptions` | which differences are returned |
+
+### utils/keyDiff~KeyDiffOptions
+
+Options for keyDiff and keyDiffDeep
+
+**Kind**: inner typedef of [`utils/keyDiff`]  
+**Properties**
+
+| Name            | Type      | Default | Description                            |
+| --------------- | --------- | ------- | -------------------------------------- |
+| \[sameKeys\]    | `boolean` | `true`  | if true, return keys that are the same |
+| \[removedKeys\] | `boolean` | `true`  | if true, return keys that are removed  |
+| \[addedKeys\]   | `boolean` | `true`  | if true, return keys that are added    |
+
+### utils/keyDiff~KeyDiffResult
+
+Result object of keyDiff and keyDiffDeep
+
+**Kind**: inner typedef of [`utils/keyDiff`]  
+**Properties**
+
+| Name            | Type             | Description                                                 |
+| --------------- | ---------------- | ----------------------------------------------------------- |
+| \[sameKeys\]    | `Array.<string>` | if sameKeys option is true, return keys that are the same   |
+| \[removedKeys\] | `Array.<string>` | if removedKeys option is true, return keys that are removed |
+| \[addedKeys\]   | `Array.<string>` | if addedKeys option is true, return keys that are added     |
+
+## utils/lifecycleDebug
+
+Debug lifecycle hooks
+
+### utils/lifecycleDebug~useLifecycleDebug(categories, \[includes\], \[excludes\])
+
+Using useDebugMessage, log lifecycle events for the current component, with the specified categories.
+
+**Kind**: inner method of [`utils/lifecycleDebug`]
+
+| Param        | Type             | Description                                    |
+| ------------ | ---------------- | ---------------------------------------------- |
+| categories   | `Array.<string>` | the categories to give messages this generates |
+| \[includes\] | `Array.<string>` | the lifecycle functions to include             |
+| \[excludes\] | `Array.<string>` | the lifecycle functions to exclude             |
+
+## utils/transformWalk
+
+Object walking utility.
+
+### utils/transformWalk~transformWalk(obj, transformFn, path)
+
+Recursively walks through an object's values and applies a transformation function to each value.
+The value recursed into is the transformed value, not the original value.
+
+**Kind**: inner method of [`utils/transformWalk`]  
+**Returns**: `*` - The transformed initial value.
+
+| Param       | Type       | Description                           |
+| ----------- | ---------- | ------------------------------------- |
+| obj         | `*`        | The object to start walking from.     |
+| transformFn | `function` | The function to transform each value. |
+| path        | `string`   | The path to the current value.        |
+
+**Example**
+
+```js
+const obj = {
+    a: 1,
+    b: {
+        c: 2,
+        d: [3, 4, { e: 5 }],
+    },
+};
+
+const transformed = transformWalk(obj, (key, value, path) => {
+    if (key === "e") {
+        return value * 2;
+    }
+    return value;
+});
+// transformed = {
+//   a: 1,
+//   b: {
+//     c: 2,
+//     d: [3, 4, { e: 10 }]
+//   }
+// }
+```
+
+<!-- LINKS -->
+
+[utils/assignreactiveobject]: #utilsassignreactiveobject
+[utils/debugmessage]: #utilsdebugmessage
+[utils/flattenpaths]: #utilsflattenpaths
+[utils/keydiff]: #utilskeydiff
+[utils/lifecycledebug]: #utilslifecycledebug
+[utils/transformwalk]: #utilstransformwalk
+[~validtargetorsource]: #utilsassignreactiveobjectvalidtargetorsource
+[`utils/assignreactiveobject`]: #utilsassignreactiveobject
+[~debugmessagefunction]: #utilsdebugmessagedebugmessagefunction
+[`utils/debugmessage`]: #utilsdebugmessage
+[`utils/flattenpaths`]: #utilsflattenpaths
+[~keydiffoptions]: #utilskeydiffkeydiffoptions
+[~keydiffresult]: #utilskeydiffkeydiffresult
+[`utils/keydiff`]: #utilskeydiff
+[`utils/lifecycledebug`]: #utilslifecycledebug
+[`utils/transformwalk`]: #utilstransformwalk
+[~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
+[~trimreactiveobject(target, source, \[exclude\], \[removedkeys\])]: #utilsassignreactiveobjecttrimreactiveobjecttarget-source-exclude-removedkeys
+[~assignreactiveobject(target, source, \[exclude\])]: #utilsassignreactiveobjectassignreactiveobjecttarget-source-exclude
+[~assignreactiveobjectdeep(target, source, \[exclude\])]: #utilsassignreactiveobjectassignreactiveobjectdeeptarget-source-exclude
+[~addorupdatereactiveobjectdeep(target, source, \[exclude\])]: #utilsassignreactiveobjectaddorupdatereactiveobjectdeeptarget-source-exclude
+[~usedebugmessage(categories)]: #utilsdebugmessageusedebugmessagecategories
+[~keydiff(newkeys, oldkeys, \[options\])]: #utilskeydiffkeydiffnewkeys-oldkeys-options
+[~keydiffdeep(newobj, oldobj, \[options\])]: #utilskeydiffkeydiffdeepnewobj-oldobj-options

package/jsdoc-to-markdown.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -e
+npx --no-install jsdoc-to-markdown > ./docs.new.md
+npx --no-install prettier --write docs.new.md > /dev/null
+set +e
+diff ./docs.new.md ./docs.md > /dev/null
+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 -f ./docs.new.md ./docs.md
+  exit $diffCode
+fi
+rm -f ./docs.new.md
+git rm ./docs.new.md > /dev/null 2>&1
+exit 0

package/lint-staged.config.js

@@ -0,0 +1,10 @@
+export default {
+    "**/*.{js,cjs,mjs,ts,jsx,tsx}": [
+        "npx --no-install eslint --fix",
+        "npx --no-install prettier --write",
+        () => "npm run docs",
+    ],
+    "**/*.{markdown,md}": ["npx --no-install doctoc --github -u ."],
+    "**/*.{less,scss,css,vue,markdown,json,md,yml,yaml,html}": ["npx --no-install prettier --write"],
+    ".circleci/config.yml": ["circleci config validate"],
+};

package/package.json

@@ -1,18 +1,20 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "8.0.3",
+    "version": "8.1.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
+    "type": "module",
     "directories": {
         "use": "use",
         "utils": "utils",
         "tests": "tests"
     },
     "scripts": {
-        "test": "jest",
+        "test": "vitest",
         "coverage": "npm run coverage:clean; npm test -- --coverage=true",
         "coverage:clean": "rm -rf coverage",
-        "prepare": "husky install"
+        "prepare": "husky install",
+        "docs": "./jsdoc-to-markdown.sh"
     },
     "repository": {
         "type": "git",
@@ -26,29 +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",
-        "lint-staged": "^11.1.2",
-        "prettier": "2.6.2"
+        "jsdoc-to-markdown": "^8.0.0",
+        "lint-staged": "^13.2.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

@@ -0,0 +1,10 @@
+module.exports = {
+    plugins: ["vitest"],
+    extends: ["eslint:recommended", "plugin:vitest/recommended", "plugin:vitest-globals/recommended"],
+    env: {
+        "vitest-globals/env": true,
+    },
+    rules: {
+        "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;