@arrai-innovations/reactive-helpers 11.4.2 → 13.0.0

package/utils/classes.js

@@ -7,51 +7,27 @@ import isString from "lodash-es/isString.js";
 import { isRef, unref } from "vue";
 
 /**
- * @typedef {*} Ref A Vue ref
- * @private
- */
-
-/**
- * @typedef {string} CSSString A string representing a CSS class or a space-separated list of CSS classes.
- * @typedef {CSSString|CSSString[]} CSSClassNames An array of CSS string(s) or a single CSS string.
- * @typedef {boolean|Ref<boolean>} CSSValue A truthy value or a reference to a truthy value, indicating whether to apply a CSS class, or unapply it if already applied.
- */
-/* eslint-disable jsdoc/check-types */
-// types valid for jsdoc-to-markdown, which uses the strict jsdoc.app. Object shorthand syntax doesn't work.
-/**
- * @typedef {Object.<CSSString, CSSValue>} CSSObject A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
- */
-/* eslint-enable jsdoc/check-types */
-/**
- * @typedef {Array<CSSClassNames, CSSString[], CSSString, CSSObject>} CSSClasses A mixed array containing multiple ways of specifying CSS classes.
- */
-/**
- * A mixed array containing multiple ways of specifying CSS classes.
- * @typedef {Array<
- *   CSSClassNames,
- *   CSSString[],
- *   CSSString,
- *   CSSObject,
- *   Ref<CSSClassNames>,
- *   Ref<CSSString[]>,
- *   Ref<CSSString>,
- *   Ref<CSSClassNames>
- * >} CSSClassesWithRefs
- */
-/**
- * @typedef {CSSString|CSSObject} CSSStringOrObject A CSS object or a space-separated list of CSS classes.
- */
-
-/**
- * @param {...CSSClasses} classes A mixed array containing multiple ways of specifying CSS classes.
- * @returns {CSSStringOrObject} A CSS object or a space-separated list of CSS classes.
+ * Normalize various ways of specifying CSS classes into an object for use in Vue.js.
+ *
+ * @param {...(
+ *     string |
+ *     string[] |
+ *     string[][] |
+ *     {[key: string]: boolean | import("vue").Ref<boolean> } |
+ *     import("vue").Ref<string | string[] | string[][]>
+ * )} classes - A mixed array containing multiple ways of specifying CSS classes.
+ * @returns {(
+ *   {[key: string]: boolean | import("vue").Ref<boolean> }|
+ *   {[key: string]: boolean | import("vue").Ref<boolean> }[]
+ * )} An object or array of objects containing CSS classes. Arrays are used if refs are present, to preserve order
+ *  of operations in reactive contexts.
  */
 export const objectifyClasses = (...classes) => {
     const flatClasses = classes.flat(Infinity).filter(identity);
     const objects = flatClasses.map((c) => {
         if (isString(c)) {
-            c = c.split(/\s+/);
-            c = c.reduce((acc, c) => {
+            const cSplit = c.split(/\s+/);
+            c = cSplit.reduce((acc, c) => {
                 acc[c] = true;
                 return acc;
             }, {});
@@ -91,8 +67,14 @@ export const objectifyClasses = (...classes) => {
     return Object.assign({}, ...objects);
 };
 
+/**
+ * @private
+ * @param {(import("vue").Ref<any>|any)[]} val - The value to unref.
+ * @returns {any[]} - The value with refs unref'd.
+ */
 const deepUnrefArrays = (val) => {
     // object values as refs is fine, but array elements as refs should be unref'd
+    /** @type {any} */
     let checkedVal = isRef(val) ? unref(val) : val;
 
     if (!isObject(checkedVal)) {
@@ -112,12 +94,35 @@ const deepUnrefArrays = (val) => {
 };
 
 /**
- * @param {...CSSClassesWithRefs} classes Handles as arguments the multiple ways of specifying CSS class related
- *  values, including refs to such values.
- * @returns {CSSStringOrObject} A CSS object or a space-separated list of CSS classes.
+ * @typedef {(
+ *     string |
+ *     { [classnames: string]: boolean | import("vue").Ref<boolean> } |
+ *     { [classnames: string]: boolean | import("vue").Ref<boolean> }[]
+ * )} CombinedClasses - The normalized form of the CSS classes, either as a string of space-separated class names or an
+ */
+
+/**
+ * @typedef {(
+ *     (string | string[] | string[][]) |
+ *     { [classnames: string]: boolean | import("vue").Ref<boolean> } |
+ *     import("vue").Ref<string | string[] | string[][]> |
+ *     import("vue").Ref<{ [classnames: string]: (boolean | import("vue").Ref<boolean>) }> |
+ *     import("vue").UnwrapNestedRefs<{ [classnames: string]: (boolean | import("vue").Ref<boolean>) }>
+ * )} CombinedClassesArgument
+ */
+
+/**
+ * Combines and normalizes different formats of CSS class specifications into a single format suitable for Vue.js
+ *  components. If objects are in the mix, objects are returned. Otherwise, a string is returned.
+ *
+ * We unref your refs, so probably want a computed around this.
+ *
+ * @param {...(CombinedClassesArgument|CombinedClassesArgument[])} classes - A variable list of class specifications in
+ *  different formats.
+ * @returns {CombinedClasses} - The normalized form of the CSS classes, either as a string of space-separated class
+ *  names or an object map of class names to boolean values indicating their presence.
  */
 export const combineClasses = (...classes) => {
-    // we unref your refs, so probably want a computed around this
     // ultimately, strings and objects are classes, arrays are organization and containers
     const rawClasses = deepUnrefArrays(classes);
     const flattenedClasses = rawClasses.flat(Infinity);
@@ -134,8 +139,10 @@ export const combineClasses = (...classes) => {
 };
 
 /**
- * @param {CSSClasses} cls A mixed array containing multiple ways of specifying CSS classes.
- * @returns {CSSString} A space-separated list of CSS classes.
+ * Normalizes various ways of specifying CSS classes into a space-separated list of CSS classes.
+ *
+ * @param {string | string[] | {[classnames: string]: boolean}} cls - Handles the multiple ways of specifying CSS class related values.
+ * @returns {string} A space-separated list of CSS classes.
  */
 export const stringifyClass = (cls) => {
     if (isArray(cls)) {
@@ -150,8 +157,10 @@ export const stringifyClass = (cls) => {
 };
 
 /**
- * @param {...CSSClasses} classes Handles as arguments the multiple ways of specifying CSS class related values.
- * @returns {CSSString} A space-separated list of CSS classes.
+ * Normalizes various ways of specifying CSS classes into a space-separated list of CSS classes.
+ *
+ * @param {...(string | string[] | {[classnames: string]: boolean})} classes - Handles the multiple ways of specifying CSS class related values.
+ * @returns {string} - A space-separated list of CSS classes.
  */
 export const stringifyClasses = (...classes) =>
     classes

package/utils/compact.js

@@ -1,5 +1,13 @@
 import isEmpty from "lodash-es/isEmpty.js";
 
+/**
+ * Remove empty objects from a mixed object array tree. Mutates
+ * the object.
+ *
+ * @private
+ * @param {object} obj - The object to remove empty objects from.
+ * @returns {void}
+ */
 const removeEmptyObjectsRecursive = (obj) => {
     if (typeof obj !== "object" || obj === null) {
         return;
@@ -18,18 +26,26 @@ const removeEmptyObjectsRecursive = (obj) => {
         for (const item of obj) {
             removeEmptyObjectsRecursive(item);
         }
-        return;
     }
 };
 
 /**
  * Remove empty objects from a mixed object array tree. Mutates the object.
- * @param {object | Array} obj - The object or array to remove empty objects from.
+ *
+ * @param {object|Array} obj - The object or array to remove empty objects from.
+ * @returns {void}
  */
 export const removeEmptyObjects = (obj) => {
     removeEmptyObjectsRecursive(obj);
 };
 
+/**
+ * Remove empty objects from a mixed object array tree. Mutates the object.
+ *
+ * @private
+ * @param {object} obj - The object to remove empty objects from.
+ * @returns {void}
+ */
 const compactSparseArraysRecursive = (obj) => {
     if (typeof obj !== "object" || obj === null) {
         return;
@@ -52,12 +68,20 @@ const compactSparseArraysRecursive = (obj) => {
 
 /**
  * Remove undefined values from arrays in a mixed object array tree. Mutates the object.
+ *
  * @param {object | Array} obj - The object or array to compact sparse arrays in.
  */
 export const compactSparseArrays = (obj) => {
     compactSparseArraysRecursive(obj);
 };
 
+/**
+ * Remove empty objects and undefined values from arrays in a mixed object array tree. Mutates the object.
+ *
+ * @private
+ * @param {object} obj - The object to remove empty objects from and compact sparse arrays in.
+ * @returns {void}
+ */
 const removeEmptyObjectsAndCompactSparseArraysRecursive = (obj) => {
     if (typeof obj !== "object" || obj === null) {
         return;
@@ -85,7 +109,9 @@ const removeEmptyObjectsAndCompactSparseArraysRecursive = (obj) => {
 
 /**
  * Remove empty objects and undefined values from arrays in a mixed object array tree. Mutates the object.
+ *
  * @param {object | Array} obj - The object or array to remove empty objects from and compact sparse arrays in.
+ * @returns {void}
  */
 export const removeEmptyObjectsAndCompactSparseArrays = (obj) => {
     removeEmptyObjectsAndCompactSparseArraysRecursive(obj);

package/utils/deleteKey.js

@@ -14,6 +14,13 @@ function toKey(value) {
     return result == "0" && 1 / value == -(1 / 0) ? "-0" : result;
 }
 
+/**
+ * Split a string into an array of keys.
+ *
+ * @param {string} string - The string to split.
+ * @param {object} object - The object to split keys for.
+ * @returns {string[]} Returns the new array of split keys.
+ */
 export function lodashLikePathSplit(string, object) {
     if (isArray(string)) {
         return string;
@@ -25,14 +32,20 @@ export function lodashLikePathSplit(string, object) {
     if (string.charCodeAt(0) === 46 /* . */) {
         result.push("");
     }
+    // @ts-ignore - based on lodash-es/_stringToPath
     string.replace(rePropName, function (match, number, quote, subString) {
         result.push(quote ? subString.replace(reEscapeChar, "$1") : number || match);
     });
     return result;
 }
 
+/**
+ * Delete a key from an object. Lodash-like delete function, as companion for get/set.
+ *
+ * @param {object} obj - The object to modify.
+ * @param {string} path - The key to delete.
+ */
 export function del(obj, path) {
-    // lodash-like delete function, as companion for get/set
     if (!obj) {
         return;
     }

package/utils/flattenPaths.js

@@ -3,22 +3,32 @@ import isObject from "lodash-es/isObject.js";
 
 /**
  * Get all paths from an array or object.
- * @module utils/flattenPaths
+ *
+ * @module utils/flattenPaths.js
  */
 
 /**
  * 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.
- * @function flattenPaths
- * @param {Array | object} arrayOrObject array or object to flatten
- * @param {object} options options
- * @param {string} options.currentPath current path, for recursion or as a starting point
- * @param {number} options.depth current depth, for recursion
- * @param {number} options.limit limit the depth of recursion
- * @returns {string[]} paths
+ *
+ * @param {Array | object} arrayOrObject - Array or object to flatten.
+ * @param {object} [options] - Options.
+ * @param {string} [options.currentPath=""] - Current path, for recursion or as a starting point.
+ * @param {number} [options.depth=0] - Current depth, for recursion.
+ * @param {number} [options.limit=0] - Limit the depth of recursion.
+ * @returns {string[]} Paths.
  */
-export function flattenPaths(arrayOrObject, { currentPath = "", depth = 0, limit = 0 } = {}) {
+export function flattenPaths(arrayOrObject, { currentPath, depth, limit } = {}) {
+    if (typeof currentPath === "undefined") {
+        currentPath = "";
+    }
+    if (typeof depth === "undefined") {
+        depth = 0;
+    }
+    if (typeof limit === "undefined") {
+        limit = 0;
+    }
     // arrayOrObject keys or indexes values can be objects or arrays.
     // find all paths you could use lodash to "get()" to.
     // indexes use `[${index}]`, keys use `.${key}`

package/utils/getFakeId.js

@@ -2,6 +2,16 @@ import isArray from "lodash-es/isArray.js";
 import isMap from "lodash-es/isMap.js";
 import isSet from "lodash-es/isSet.js";
 
+/**
+ * Get a fake id that is not in the array, set, map, or object.
+ *
+ * @param {Array|Set|Map|object} arraySetMapOrObject - The array, set, map, or object to check for the fake id.
+ *  An array is assumed to be an array of objects.
+ *  A set is assumed to be a set of ids.
+ *  A map or object is assumed to be an object with keys that are ids.
+ * @param {string} key - The key to check for in the array or object.
+ * @returns {string} - The fake id.
+ */
 export function getFakeId(arraySetMapOrObject, key = "id") {
     // sets are assumed to be of ids
     // arrays are assumed to be objects with an property matching the passed key
@@ -18,5 +28,5 @@ export function getFakeId(arraySetMapOrObject, key = "id") {
     do {
         fakeId = Math.floor(Math.random() * Number.MIN_SAFE_INTEGER);
     } while (test());
-    return fakeId;
+    return fakeId.toString();
 }

package/utils/keyDiff.js

@@ -4,43 +4,34 @@ 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
+ *
+ * @module utils/keyDiff.js
  */
 
 /**
- * Options for keyDiff and keyDiffDeep
- * @typedef {object} KeyDiffOptions
- * @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
+ * Result object of keyDiff and keyDiffDeep.
+ *
  * @typedef {object} KeyDiffResult
- * @property {Set} [sameKeys] - if sameKeys option is true, return keys that are the same
- * @property {Set} [removedKeys] - if removedKeys option is true, return keys that are removed
- * @property {Set} [addedKeys] - if addedKeys option is true, return keys that are added
+ * @property {Set} [sameKeys] - If sameKeys option is true, return keys that are the same.
+ * @property {Set} [removedKeys] - If removedKeys option is true, return keys that are removed.
+ * @property {Set} [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.
- * @function keyDiff
- * @param {string[]|Set} newKeys - keys to consider as new
- * @param {string[]|Set} oldKeys - keys to consider as old
- * @param {KeyDiffOptions} [options] - which differences are returned
- * @returns {KeyDiffResult} - the differences
+ *
+ * @param {string[]|Set} newKeys - Keys to consider as new.
+ * @param {string[]|Set} oldKeys - Keys to consider as old.
+ * @param {object} [options] - Which differences are returned.
+ * @param {boolean} [options.sameKeys=true] - If true, return keys that are the same.
+ * @param {boolean} [options.removedKeys=true] - If true, return keys that are removed.
+ * @param {boolean} [options.addedKeys=true] - If true, return keys that are added.
+ * @returns {KeyDiffResult} - The differences.
  */
 export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true, addedKeys = true } = {}) {
-    let newKeysSet = newKeys;
-    let oldKeysSet = oldKeys;
-    if (!(newKeys instanceof Set)) {
-        newKeysSet = new Set(newKeys);
-    }
-    if (!(oldKeys instanceof Set)) {
-        oldKeysSet = new Set(oldKeys);
-    }
+    let newKeysSet = newKeys instanceof Set ? newKeys : new Set(newKeys);
+    let oldKeysSet = oldKeys instanceof Set ? oldKeys : new Set(oldKeys);
     const returnValue = {};
     if (sameKeys) {
         returnValue.sameKeys = intersection(newKeysSet, oldKeysSet);
@@ -57,15 +48,15 @@ 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.
- * @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
- * @param {boolean} [options.sameKeys] - if true, return keys that are the same
- * @param {boolean} [options.removedKeys] - if true, return keys that are removed
- * @param {boolean} [options.addedKeys] - if true, return keys that are added
- * @param {number} [options.limit] - limit the depth of recursion
- * @returns {KeyDiffResult} - the differences
+ *
+ * @param {object} newObj - The new version of the object.
+ * @param {object} oldObj - The old version of the object.
+ * @param {object} [options] - Which differences are returned.
+ * @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.
+ * @property {number} [limit] - Limit the depth of recursion.
+ * @returns {KeyDiffResult} - The differences.
  */
 export function keyDiffDeep(newObj, oldObj, options = {}) {
     const additionalFlattenArgs = [];

package/utils/loadingCombine.js

@@ -1,8 +1,11 @@
+/**
+ * Combine multiple loading states into a single loading state. If any are loading, the combined state is loading.
+ * If all are undefined, the combined state is undefined. Otherwise, the combined state is not loading.
+ *
+ * @param  {...(boolean | undefined)} loadingStates -  The loading states to combine.
+ * @returns {boolean | undefined} The combined loading state.
+ */
 export function loadingCombine(...loadingStates) {
-    // loadingStates is an array of booleans or undefined
-    // if any true, return true
-    // if all undefined, return undefined
-    // otherwise return false (all false)
     if (loadingStates.some((loadingState) => loadingState === true)) {
         return true;
     }

package/utils/proxyRunning.js

@@ -1,12 +1,20 @@
 import { nextTick, toRef, watch } from "vue";
 
-export function proxyRunning(parentState, parentStateProp, state, prop) {
-    // we want you to have been running false for two ticks before we stop you, but we want you to start running true immediately
-    //  the point of this is to reduce running flicker where the stack has running states awaiting other running states
+/**
+ * Proxy a parent's running state to a child's running state.
+ *
+ * @param {import("vue").UnwrapNestedRefs<object>} parentState - The parent state.
+ * @param {string} parentStateProp - The parent state property.
+ * @param {import("vue").Ref<boolean>} ref - The ref to proxy to.
+ */
+export function proxyRunning(parentState, parentStateProp, ref) {
+    // we want you to have been running false for two ticks before we stop you, but we want you to start running
+    //  true immediately the point of this is to reduce running flicker where the stack has running states awaiting
+    //  other running states
     let falseTickCount = 0;
     const checkStillFalse = () => {
         if (falseTickCount > 1) {
-            state[prop] = false;
+            ref.value = false;
             falseTickCount = 0;
         } else if (parentState[parentStateProp] === false) {
             falseTickCount++;
@@ -16,11 +24,11 @@ export function proxyRunning(parentState, parentStateProp, state, prop) {
         }
     };
     watch(toRef(parentState, parentStateProp), (running) => {
-        if (running && state[prop] !== running) {
-            state[prop] = running;
-        } else if (!running && state[prop] !== running) {
+        if (running && ref.value !== running) {
+            ref.value = running;
+        } else if (!running && ref.value !== running) {
             nextTick(checkStillFalse);
         }
     });
-    state[prop] = parentState[parentStateProp];
+    ref.value = parentState[parentStateProp];
 }

package/utils/relatedCalculatedHelpers.js

@@ -1,6 +1,15 @@
 export const relatedItemRegex = /^relatedItem\./;
 export const calculatedItemRegex = /^calculatedItem\./;
 
+/**
+ * Get the object and key of a calculated item.
+ *
+ * @param {object} obj - The object to get the calculated item from.
+ * @param {object} relatedObj - The object to get the related item from.
+ * @param {object} calculatedObj - The object to get the calculated item from.
+ * @param {string} key - The key to get the calculated item from.
+ * @returns {[object, string]} The object and key of the calculated item.
+ */
 export const getObjectRelatedCalculatedByKey = (obj, relatedObj, calculatedObj, key) => {
     let getObj = obj,
         getKey = key.replace(relatedItemRegex, () => {
@@ -16,6 +25,14 @@ export const getObjectRelatedCalculatedByKey = (obj, relatedObj, calculatedObj,
     return [getObj, getKey];
 };
 
+/**
+ * Get the object and key of a related item.
+ *
+ * @param {object} obj - The object to get the related item from.
+ * @param {object} relatedObj - The object to get the related item from.
+ * @param {string} key - The key to get the related item from.
+ * @returns {[object, string]} The object and key of the related item.
+ */
 export const getObjectRelatedByKey = (obj, relatedObj, key) => {
     let getObj = obj,
         getKey = key.replace(relatedItemRegex, () => {

package/utils/set.js

@@ -1,5 +1,16 @@
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set#implementing_basic_set_operations
 
+/**
+ * Checks if one set is a superset of another set, meaning all elements of the subset are contained within the set.
+ *
+ * @param {Set} set - The candidate superset.
+ * @param {Set} subset - The candidate subset.
+ * @returns {boolean} Returns true if the set contains all elements of the subset, otherwise false.
+ * @example
+ * const a = new Set([1, 2, 3]);
+ * const b = new Set([2, 3]);
+ * console.log(isSuperset(a, b)); // true
+ */
 export const isSuperset = (set, subset) => {
     for (const elem of subset) {
         if (!set.has(elem)) {
@@ -9,6 +20,17 @@ export const isSuperset = (set, subset) => {
     return true;
 };
 
+/**
+ * Returns the union of two sets, containing all unique elements from both sets.
+ *
+ * @param {Set} setA - The first set.
+ * @param {Set} setB - The second set.
+ * @returns {Set} A new Set containing all elements from both input sets.
+ * @example
+ * const a = new Set([1, 2, 3]);
+ * const b = new Set([3, 4, 5]);
+ * console.log(union(a, b)); // Set(1, 2, 3, 4, 5)
+ */
 export const union = (setA, setB) => {
     const _union = new Set(setA);
     for (let elem of setB) {
@@ -17,6 +39,17 @@ export const union = (setA, setB) => {
     return _union;
 };
 
+/**
+ * Returns the intersection of two sets, containing only elements that are present in both sets.
+ *
+ * @param {Set} setA - The first set.
+ * @param {Set} setB - The second set.
+ * @returns {Set} A new Set containing common elements from both input sets.
+ * @example
+ * const a = new Set([1, 2, 3]);
+ * const b = new Set([2, 3, 4]);
+ * console.log(intersection(a, b)); // Set(2, 3)
+ */
 export const intersection = (setA, setB) => {
     const _intersection = new Set();
     for (const elem of setB) {
@@ -27,6 +60,17 @@ export const intersection = (setA, setB) => {
     return _intersection;
 };
 
+/**
+ * Returns the symmetric difference of two sets, containing elements present in only one of the sets.
+ *
+ * @param {Set} setA - The first set.
+ * @param {Set} setB - The second set.
+ * @returns {Set} A new Set containing elements that are only in one of the input sets.
+ * @example
+ * const a = new Set([1, 2, 3]);
+ * const b = new Set([3, 4, 5]);
+ * console.log(symmetricDifference(a, b)); // Set(1, 2, 4, 5)
+ */
 export const symmetricDifference = (setA, setB) => {
     const _difference = new Set(setA);
     for (const elem of setB) {
@@ -39,6 +83,17 @@ export const symmetricDifference = (setA, setB) => {
     return _difference;
 };
 
+/**
+ * Returns the difference of two sets, containing elements present only in the first set but not in the second.
+ *
+ * @param {Set} setA - The first set.
+ * @param {Set} setB - The second set.
+ * @returns {Set} A new Set containing elements from the first set that are not in the second set.
+ * @example
+ * const a = new Set([1, 2, 3]);
+ * const b = new Set([3, 4]);
+ * console.log(difference(a, b)); // Set(1, 2)
+ */
 export const difference = (setA, setB) => {
     const _difference = new Set(setA);
     for (const elem of setB) {
@@ -47,6 +102,17 @@ export const difference = (setA, setB) => {
     return _difference;
 };
 
+/**
+ * Tests if two sets are equal, meaning they contain exactly the same elements.
+ *
+ * @param {Set} setA - The first set.
+ * @param {Set} setB - The second set.
+ * @returns {boolean} Returns true if both sets are equal in size and content, otherwise false.
+ * @example
+ * const a = new Set([1, 2, 3]);
+ * const b = new Set([1, 2, 3]);
+ * console.log(equals(a, b)); // true
+ */
 export const equals = (setA, setB) => {
     return setA.size === setB.size && isSuperset(setA, setB);
 };

package/utils/transformWalk.js

@@ -2,12 +2,18 @@ import isSet from "lodash-es/isSet.js";
 
 /**
  * Object walking utility.
- * @module utils/transformWalk
+ *
+ * @module utils/transformWalk.js
  */
 
 /**
  * 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.
+ *
+ * @param {object} obj - The object to start walking from.
+ * @param {Function} transformFn - The function to transform each value.
+ * @param {string} path - The path to the current value.
+ * @returns {object} The transformed object.
  * @example
  *
  * const obj = {
@@ -31,11 +37,6 @@ import isSet from "lodash-es/isSet.js";
  * //     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 {string} path The path to the current value.
- * @returns {*} The transformed initial value.
  */
 export const transformWalk = (obj, transformFn, path = "") => {
     if (typeof obj !== "object" || obj === null || isSet(obj)) {