@arrai-innovations/reactive-helpers 8.0.3 → 8.0.4

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

@@ -4,8 +4,8 @@ module.exports = {
     env: {
         node: true,
     },
-
-    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier"],
+    plugins: ["jsdoc"],
+    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier", "plugin:jsdoc/recommended-error"],
 
     parserOptions: {
         parser: "babel-eslint",
@@ -22,5 +22,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,15 @@
+#!/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 ./docs.new.md ./docs.md
+  exit $diffCode
+fi
+set -e
+rm ./docs.new.md

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,8 +1,9 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "8.0.3",
+    "version": "8.0.4",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
+    "type": "module",
     "directories": {
         "use": "use",
         "utils": "utils",
@@ -12,7 +13,8 @@
         "test": "jest",
         "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",
@@ -28,6 +30,7 @@
         "@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",
         "@vue/compiler-sfc": "^3.3.4",
@@ -39,9 +42,11 @@
         "doctoc": "^2.1.0",
         "eslint": "^7.32.0",
         "eslint-plugin-jest": "^26.1.5",
+        "eslint-plugin-jsdoc": "^46.2.6",
         "eslint-plugin-vue": "^8.7.1",
         "flush-promises": "^1.0.2",
-        "lint-staged": "^11.1.2",
+        "jsdoc-to-markdown": "^8.0.0",
+        "lint-staged": "^13.2.2",
         "prettier": "2.6.2"
     },
     "dependencies": {

package/utils/assignReactiveObject.js

@@ -4,6 +4,11 @@ import isArray from "lodash-es/isArray";
 import isObject from "lodash-es/isObject";
 import { isReactive, isRef, toRef, unref } from "vue";
 
+/**
+ * Reactive object assignment utilities
+ * @module utils/assignReactiveObject
+ */
+
 export class AssignReactiveObjectError extends Error {
     constructor(message) {
         super(message);
@@ -12,13 +17,18 @@ export class AssignReactiveObjectError extends Error {
 }
 
 /**
- * @typedef {Ref|object|array} ValidTargetOrSource targets and sources must be refs, objects, or arrays
+ * @typedef {*} Ref A Vue ref
+ * @private
+ */
+
+/**
+ * @typedef {Ref|object|Array} ValidTargetOrSource targets and sources must be refs, objects, or arrays
  * and refs must ultimately resolve to objects or arrays
  */
 
 /**
  * Validates that a value is an array or an object, and throws an error if it is not.
- *
+ * @private
  * @param {string} key The key being validated.
  * @param {*} value The value being validated.
  * @throws {AssignReactiveObjectError} If the value is not an array or an object.
@@ -31,6 +41,7 @@ function isArrayOrObject(key, value) {
 
 /**
  * @typedef validateTargetAndSourceResult
+ * @private
  * @property {ValidTargetOrSource} target The validated target value.
  * @property {ValidTargetOrSource} source The validated source value.
  */
@@ -38,7 +49,7 @@ function isArrayOrObject(key, value) {
 /**
  * Validates that the target and source values are arrays or objects, and returns them.
  * If either value is a ref, it is dereferenced before validation.
- *
+ * @private
  * @param {ValidTargetOrSource} target The target value to validate.
  * @param {ValidTargetOrSource} source The source value to validate.
  * @returns {validateTargetAndSourceResult} An object containing the validated target and source values.
@@ -63,11 +74,11 @@ function validateTargetAndSource(target, source) {
 /**
  * Replaces keys in a target object or array with reactive refs to the corresponding keys in a
  * source object or array.
- *
+ * @private
  * @param {ValidTargetOrSource} target The object receiving values.
  * @param {ValidTargetOrSource} source The object providing values.
- * @param {array} keys The keys to replace.
- * @param {array} {exclude} Keys to exclude from replacement.
+ * @param {Array} keys The keys to replace.
+ * @param {Array} [exclude] Keys to exclude from replacement.
  * @returns {boolean} True if any keys were replaced, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
@@ -91,11 +102,11 @@ function reactiveReplaceKeys(target, source, keys, exclude = []) {
 
 /**
  * Adds to a target the missing keys from a source. `addedKeys` can be precalculated to avoid recalculation.
- *
+ * @function addReactiveObject
  * @param {ValidTargetOrSource} target The object receiving values.
  * @param {ValidTargetOrSource} source The object providing values.
- * @param {array} {exclude} Keys to exclude from the addition.
- * @param {array} {addedKeys} Precaulcated array of keys to add, if available. Otherwise, the
+ * @param {Array} [exclude] Keys to exclude from the addition.
+ * @param {Array} [addedKeys] Precaulcated array of keys to add, if available. Otherwise, the
  * keys will be calculated.
  * @returns {boolean} True if any keys were added, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
@@ -113,11 +124,11 @@ export function addReactiveObject(target, source, exclude = [], addedKeys = null
 
 /**
  * Updates a target with mutually shared keys from a source. `sameKeys` can be precalculated to avoid recalculation.
- *
+ * @function updateReactiveObject
  * @param {ValidTargetOrSource} target The object receiving values.
  * @param {ValidTargetOrSource} source The object providing values.
- * @param {array} {exclude} Keys to exclude from the update.
- * @param {array} {sameKeys} Precaulcated array of keys to update, if available. Otherwise, the
+ * @param {Array} [exclude] Keys to exclude from the update.
+ * @param {Array} [sameKeys] Precaulcated array of keys to update, if available. Otherwise, the
  * keys will be calculated.
  * @returns {boolean} True if any keys were updated, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
@@ -135,19 +146,20 @@ export function updateReactiveObject(target, source, exclude = [], sameKeys = nu
 
 /**
  * Adds to a target the missing keys from a source, and updates a target with mutually shared keys from a source.
- *
+ * @function addOrUpdateReactiveObject
  * @param {ValidTargetOrSource} target The object receiving values.
  * @param {ValidTargetOrSource} source The object providing values.
- * @param {array} {exclude} Keys to exclude from the addition or update.
- * @param {array} {addedKeys} Precaulcated array of keys to add, if available. Otherwise, the
+ * @param {Array} [exclude] Keys to exclude from the addition or update.
+ * @param {Array} [addedKeys] Precaulcated array of keys to add, if available. Otherwise, the
  * keys will be calculated.
- * @param {array} {sameKeys} Precaulcated array of keys to update, if available. Otherwise, the
+ * @param {Array} [sameKeys] Precaulcated array of keys to update, if available. Otherwise, the
  * keys will be calculated.
+ * @returns {boolean} True if any keys were added or updated, false otherwise.
  */
 export function addOrUpdateReactiveObject(target, source, exclude = [], addedKeys = null, sameKeys = null) {
     if (!addedKeys && !sameKeys) {
         if (target === source) {
-            return;
+            return false;
         }
         ({ target, source } = validateTargetAndSource(target, source));
         ({ addedKeys, sameKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []));
@@ -160,11 +172,11 @@ export function addOrUpdateReactiveObject(target, source, exclude = [], addedKey
 
 /**
  * Removes keys from a target that are not present in a source.
- *
+ * @function trimReactiveObject
  * @param {ValidTargetOrSource} target The object receiving trimming.
  * @param {ValidTargetOrSource|null} source The object that provides the allowed set of keys for calculating `removedKeys`.
- * @param {array} {exclude} Keys to exclude from removal.
- * @param {array} {removedKeys} An array to store removed keys.
+ * @param {Array} [exclude] Keys to exclude from removal.
+ * @param {Array} [removedKeys] An array to store removed keys.
  * @returns {boolean} True if any keys were removed, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
@@ -200,15 +212,16 @@ export function trimReactiveObject(target, source, exclude = [], removedKeys = n
 /**
  * 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.
- *
+ * @function assignReactiveObject
  * @param {ValidTargetOrSource} target The target object or array.
  * @param {ValidTargetOrSource} source The reactive object to assign.
- * @param {array} {exclude} Keys to exclude from the assignment.
+ * @param {Array} [exclude] Keys to exclude from the assignment.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
  */
 export function assignReactiveObject(target, source, exclude = []) {
     if (target === source) {
-        return;
+        return false;
     }
     ({ target, source } = validateTargetAndSource(target, source));
     const { addedKeys, sameKeys, removedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
@@ -223,16 +236,17 @@ export function assignReactiveObject(target, source, exclude = []) {
  * keys present in the source are added to the target, and keys present in both are updated in the target.
  *
  * As an internal function, this function does not validate its arguments and has no optional arguments.
- *
+ * @private
  * @param {ValidTargetOrSource} target The object receiving updates.
  * @param {ValidTargetOrSource} source The object providing updates.
- * @param {array} exclude Keys to exclude from the update.
- * @param {array} addedKeys Precaulcated array of keys to add, if available. Otherwise, the
+ * @param {Array} exclude Keys to exclude from the update.
+ * @param {Array} addedKeys Precaulcated array of keys to add, if available. Otherwise, the
  * keys will be calculated.
- * @param {array} sameKeys Precaulcated array of keys to update, if available. Otherwise, the
+ * @param {Array} sameKeys Precaulcated array of keys to update, if available. Otherwise, the
  * keys will be calculated.
  * @param {string} path The current path, used to rescope exclude for the next level.
- * @param {function} fn The recursive function to call, likely the calling function itself.
+ * @param {Function} fn The recursive function to call, likely the calling function itself.
+ * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
  */
 function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn) {
     let didAnything = false;
@@ -265,11 +279,11 @@ function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn)
  * keys present in the source are added to the target, and keys present in both are updated in the target.
  *
  * An internal function to avoid validating arguments repeatedly.
- *
+ * @private
  * @param {ValidTargetOrSource} target The object receiving updates.
  * @param {ValidTargetOrSource} source The object providing updates.
- * @param {array} {exclude} Keys to exclude from the assignment.
- * @param {string} {path} The current path, used to rescope exclude for the next level.
+ * @param {Array} [exclude] Keys to exclude from the assignment.
+ * @param {string} [path] The current path, used to rescope exclude for the next level.
  * @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.
  */
@@ -284,17 +298,17 @@ function assignReactiveObjectRecursive(target, source, exclude = [], path = "")
 /**
  * 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.
- *
+ * @function assignReactiveObjectDeep
  * @param {ValidTargetOrSource} target The object receiving updates.
  * @param {ValidTargetOrSource} source The object providing updates.
- * @param {array} {exclude} Keys to exclude from the assignment.
+ * @param {Array} [exclude] Keys to exclude from the assignment.
  * @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.
  */
 export function assignReactiveObjectDeep(target, source, exclude = []) {
     // exclude keys will need to be lodash get strings
     if (target === source) {
-        return;
+        return false;
     }
     ({ target, source } = validateTargetAndSource(target, source));
     return assignReactiveObjectRecursive(target, source, exclude);
@@ -305,11 +319,12 @@ export function assignReactiveObjectDeep(target, source, exclude = []) {
  * keys present in both are updated in the target. Missing keys are not removed.
  *
  * As an internal function, this function does not validate its argument.
- *
+ * @private
  * @param {ValidTargetOrSource} target The object receiving updates.
  * @param {ValidTargetOrSource} source The object providing updates.
- * @param {array} [exclude] Keys to exclude from the update.
+ * @param {Array} [exclude] Keys to exclude from the update.
  * @param {string} [path] The current path, used to rescope exclude for the next level.
+ * @returns {boolean} True if any keys were added or updated, false otherwise.
  */
 function addOrUpdateReactiveObjectRecursive(target, source, exclude = [], path = "") {
     let addedKeys,
@@ -320,18 +335,18 @@ function addOrUpdateReactiveObjectRecursive(target, source, exclude = [], path =
 /**
  * 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.
- *
+ * @function addOrUpdateReactiveObjectDeep
  * @param {ValidTargetOrSource} target The object receiving updates.
  * @param {ValidTargetOrSource} source The object providing updates.
- * @param {array} [exclude] Keys to exclude from the update.
+ * @param {Array} [exclude] Keys to exclude from the update.
  * @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.
  */
 export function addOrUpdateReactiveObjectDeep(target, source, exclude = []) {
     // exclude keys will need to be lodash get strings
     if (target === source) {
-        return;
+        return false;
     }
     ({ target, source } = validateTargetAndSource(target, source));
-    addOrUpdateReactiveObjectRecursive(target, source, exclude);
+    return addOrUpdateReactiveObjectRecursive(target, source, exclude);
 }

package/utils/debugMessage.js

@@ -4,10 +4,14 @@ import { isSet, partial, union } from "lodash-es";
 import debounce from "lodash-es/debounce";
 import { unref } from "vue";
 
+/**
+ * Configurable logging of debug messages at runtime.
+ * @module utils/debugMessage
+ */
+
 /**
  * Whether debug messages are enabled or not. For deploying to production with debugging but not
  * spamming everyone with debug messages.
- *
  * @type {boolean}
  */
 window.RH_DEBUG = false;
@@ -20,7 +24,6 @@ window.RH_DEBUG = false;
  * The special category "*" will match all messages.
  * Strings passed as keys will be treated as a single category.
  * Sets can also be passed as keys, which is what the arrays get converted to.
- *
  * @type {Map<string[]|string|Set, boolean>}
  * @example
  * window.RH_DEBUG = true; // turn it on
@@ -34,7 +37,6 @@ window.RH_DEBUG_CATEGORIES = new Map();
 /**
  * Group identical messages together and show a count of how many times they were logged.
  * Messages are only shown on the trailing edge, so logging is delayed and somewhat out of order.
- *
  * @type {boolean}
  */
 window.RH_DEBOUNCE_DEBUG = false;
@@ -42,7 +44,6 @@ window.RH_DEBOUNCE_DEBUG = false;
 /**
  * Whether to process arguments to be more friendly for console.log, with regard to circular references
  * and not recursing into vue components.
- *
  * @type {boolean}
  */
 window.RH_TRANSFORM_MESSAGES = true;
@@ -53,9 +54,10 @@ const messageBounceFns = {};
 const counts = {};
 
 /**
+ * @private
  * @param {Set} categoriesSet categories for the message log
  * @param {string} categoriesKey key for debouncing
- * @param {*[]} messages
+ * @param {Array.<*>} messages messages to log
  */
 const doLog = (categoriesSet, categoriesKey, messages) => {
     if (messages.length > 0) {
@@ -74,7 +76,8 @@ const doLog = (categoriesSet, categoriesKey, messages) => {
 /**
  * Process a value for logging, dealing with circular references and
  * not recursing into vue components.
- *
+ * @private
+ * @function inspectWalkFn
  * @param {Map} seenObjects for circlular reference detection
  * @param {string} key keys is an unused argument from walk
  * @param {*} value value to process
@@ -98,8 +101,9 @@ export const inspectWalkFn = (seenObjects, key, value, path) => {
 };
 
 /**
- * @param {(string|function)[]} messages messages to resolve
- * @returns {*[]} resolved messages
+ * @private
+ * @param {Array.<string | Function>} messages messages to resolve
+ * @returns {Array.<*>} resolved messages
  */
 const resolveMessages = (messages) => {
     const resolvedMessages = [];
@@ -115,9 +119,11 @@ const resolveMessages = (messages) => {
 };
 
 /**
+ * @private
  * @param {Set} categoriesSet categories for the message log
  * @param {string} categoriesKey key for debouncing
- * @param {*[]} messages messages to log
+ * @param {Array.<*>} messages messages to log
+ * @returns {void}
  */
 const doDebouncedLog = (categoriesSet, categoriesKey, messages) => {
     if (!window.RH_DEBOUNCE_DEBUG) {
@@ -134,18 +140,22 @@ const doDebouncedLog = (categoriesSet, categoriesKey, messages) => {
 };
 
 /**
+ * @private
  * @param {string} categoriesKey categories for the message log
- * @param {(string|function)[]} messages messages to log
+ * @param {Array.<string | Function>} messages messages to log
  * @returns {string} key
- **/
+ */
 const getKey = (categoriesKey, messages) => `${categoriesKey}|${messages.join("-")}`;
 
 /**
- * @typedef {Object} DebugMessageFunction
- * @property {function(...((string|function)[]|string|function)): void} log log a message
+ * Logs debug messages based on the specified categories and logging rules.
+ * @typedef {object} DebugMessageFunction
+ * @property {function(...(Array.<string | Function> | string | Function)): void} messages log a message
  */
 
 /**
+ * Returns a function that logs debug messages based on enabled categories.
+ * @function useDebugMessage
  * @param {string[]} categories categories for the message log
  * @returns {DebugMessageFunction} debug message function
  */

package/utils/flattenPaths.js

@@ -1,12 +1,17 @@
 import isArray from "lodash-es/isArray";
 import isObject from "lodash-es/isObject";
 
+/**
+ * Get all paths from an array or object.
+ * @module utils/flattenPaths
+ */
+
 /**
  * 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.
- *
- * @param {Array|Object} arrayOrObject array or object to flatten
+ * @function flattenPaths
+ * @param {Array | object} arrayOrObject array or object to flatten
  * @param {string} currentPath current path, for recursion or as a starting point
  * @returns {string[]} paths
  */

package/utils/keyDiff.js

@@ -2,27 +2,35 @@ import { flattenPaths } from "./flattenPaths.js";
 import { difference, intersection } from "./set.js";
 
 /**
+ * Calculate the difference between objects in terms of what keys
+ * are the same, what keys are removed, and what keys are added.
+ * @module utils/keyDiff
+ */
+
+/**
+ * Options for keyDiff and keyDiffDeep
  * @typedef {object} KeyDiffOptions
- * @property {boolean} [sameKeys=true]
- * @property {boolean} [removedKeys=true]
- * @property {boolean} [addedKeys=true]
+ * @property {boolean} [sameKeys=true] - if true, return keys that are the same
+ * @property {boolean} [removedKeys=true] - if true, return keys that are removed
+ * @property {boolean} [addedKeys=true] - if true, return keys that are added
  */
 
 /**
+ * Result object of keyDiff and keyDiffDeep
  * @typedef {object} KeyDiffResult
- * @property {string[]} [sameKeys]
- * @property {string[]} [removedKeys]
- * @property {string[]} [addedKeys]
+ * @property {string[]} [sameKeys] - if sameKeys option is true, return keys that are the same
+ * @property {string[]} [removedKeys] - if removedKeys option is true, return keys that are removed
+ * @property {string[]} [addedKeys] - if addedKeys option is true, return keys that are added
  */
 
 /**
  * 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.
- *
- * @param {string[]} newKeys
- * @param {string[]} oldKeys
- * @param {KeyDiffOptions} [options]
- * @returns {KeyDiffResult}
+ * are the same, what keys are removed, and what keys are added.
+ * @function keyDiff
+ * @param {string[]} newKeys - keys to consider as new
+ * @param {string[]} oldKeys - keys to consider as old
+ * @param {KeyDiffOptions} [options] - which differences are returned
+ * @returns {KeyDiffResult} - the differences
  */
 export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true, addedKeys = true } = {}) {
     const newKeysSet = new Set(newKeys);
@@ -43,11 +51,11 @@ export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true,
 /**
  * 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.
- *
- * @param {object} newObj
- * @param {object} oldObj
- * @param {KeyDiffOptions} [options]
- * @returns {KeyDiffResult}
+ * @function keyDiffDeep
+ * @param {object} newObj - the new version of the object
+ * @param {object} oldObj - the old version of the object
+ * @param {KeyDiffOptions} [options] - which differences are returned
+ * @returns {KeyDiffResult} - the differences
  */
 export function keyDiffDeep(newObj, oldObj, options = {}) {
     const newPaths = flattenPaths(newObj);

package/utils/lifecycleDebug.js

@@ -18,6 +18,11 @@ import {
     unref,
 } from "vue";
 
+/**
+ * Debug lifecycle hooks
+ * @module utils/lifecycleDebug
+ */
+
 window.RH_DEBUG_SKIP_EMPTY_CHANGE_EFFECTS = true;
 
 export const customHandlers = {
@@ -81,7 +86,11 @@ const defaultHandler = (debugMessage) => {
 };
 
 /**
- * @param {string[]} categories
+ * Using useDebugMessage, log lifecycle events for the current component, with the specified categories.
+ * @function useLifecycleDebug
+ * @param {string[]} categories - the categories to give messages this generates
+ * @param {string[]} [includes] - the lifecycle functions to include
+ * @param {string[]} [excludes] - the lifecycle functions to exclude
  */
 export function useLifecycleDebug(categories, includes = [], excludes = []) {
     const lifeCycleFns = {

package/utils/transformWalk.js

@@ -1,9 +1,13 @@
 import { isSet } from "lodash-es";
 
+/**
+ * Object walking utility.
+ * @module utils/transformWalk
+ */
+
 /**
  * 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.
- *
  * @example
  *
  * const obj = {
@@ -27,9 +31,9 @@ import { isSet } from "lodash-es";
  * //     d: [3, 4, { e: 10 }]
  * //   }
  * // }
- *
+ * @function transformWalk
  * @param {*} obj The object to start walking from.
- * @param {function} transformFn The function to transform each value.
+ * @param {Function} transformFn The function to transform each value.
  * @param {string} path The path to the current value.
  * @returns {*} The transformed initial value.
  */

package/.lintstagedrc

@@ -1,14 +0,0 @@
-{
-    "**/*.{js,cjs,mjs,ts,jsx,tsx}": [
-        "npx --no-install eslint --fix"
-    ],
-    "**/*.{markdown,md}": [
-        "npx --no-install doctoc --github -u ."
-    ],
-    "**/*.{js,cjs,mjs,ts,jsx,tsx,less,scss,css,vue,markdown,json,md,yml,yaml,html}": [
-        "npx --no-install prettier --write"
-    ],
-    ".circleci/config.yml": [
-        "circleci config validate"
-    ]
-}