@arrai-innovations/reactive-helpers 11.4.2 → 13.0.0

package/jsdoc-to-markdown.sh

@@ -1,16 +0,0 @@
-#!/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/tests/unit/.eslintrc.cjs

@@ -1,11 +0,0 @@
-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",
-        "vitest/valid-expect": "off", // we want to use expect(value, message).toBe(expected), which is not supported by this rule
-    },
-};

package/tests/unit/config/index.spec.js

@@ -1,18 +0,0 @@
-import * as config from "../../../config/index.js";
-import fs from "fs/promises";
-
-describe("config/index.js", function () {
-    it("should export everything exported by individual files", async function () {
-        const files = await fs.readdir("./config");
-        const modules = files.filter((file) => file.endsWith(".js") && file !== "index.js");
-        const exportedKeys = [];
-        for (const module of modules) {
-            const moduleExports = await import(`../../../config/${module}`);
-            exportedKeys.push(...Object.keys(moduleExports).filter((key) => key !== "default"));
-        }
-        const useKeys = Object.keys(config);
-        useKeys.sort();
-        exportedKeys.sort();
-        expect(useKeys).toEqual(exportedKeys);
-    });
-});

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

@@ -1,18 +0,0 @@
-import * as use from "../../../use/index.js";
-import fs from "fs/promises";
-
-describe("use/index.js", function () {
-    it("should export everything exported by individual files", async function () {
-        const files = await fs.readdir("./use");
-        const modules = files.filter((file) => file.endsWith(".js") && file !== "index.js");
-        const exportedKeys = [];
-        for (const module of modules) {
-            const moduleExports = await import(`../../../use/${module}`);
-            exportedKeys.push(...Object.keys(moduleExports).filter((key) => key !== "default"));
-        }
-        const useKeys = Object.keys(use);
-        useKeys.sort();
-        exportedKeys.sort();
-        expect(useKeys).toEqual(exportedKeys);
-    });
-});

package/tests/unit/utils/index.spec.js

@@ -1,18 +0,0 @@
-import * as utils from "../../../utils/index.js";
-import fs from "fs/promises";
-
-describe("utils/index.js", function () {
-    it("should export everything exported by individual files", async function () {
-        const files = await fs.readdir("./utils");
-        const modules = files.filter((file) => file.endsWith(".js") && file !== "index.js");
-        const exportedKeys = [];
-        for (const module of modules) {
-            const moduleExports = await import(`../../../utils/${module}`);
-            exportedKeys.push(...Object.keys(moduleExports).filter((key) => key !== "default"));
-        }
-        const utilsKeys = Object.keys(utils);
-        utilsKeys.sort();
-        exportedKeys.sort();
-        expect(utilsKeys).toEqual(exportedKeys);
-    });
-});

package/use/index.js

@@ -1,19 +0,0 @@
-export * from "./cancellableIntent.js";
-export * from "./combineClasses.js";
-export * from "./list.js";
-export * from "./listCalculated.js";
-export * from "./listKeys.js";
-export * from "./listFilter.js";
-export * from "./listInstance.js";
-export * from "./listRelated.js";
-export * from "./listSearch.js";
-export * from "./listSort.js";
-export * from "./listSubscription.js";
-export * from "./object.js";
-export * from "./objectCalculated.js";
-export * from "./objectInstance.js";
-export * from "./objectRelated.js";
-export * from "./objectSubscription.js";
-export * from "./paginatedListInstance.js";
-export * from "./search.js";
-export * from "./watchesRunning.js";

package/utils/debugMessage.js

@@ -1,209 +0,0 @@
-import { isSuperset } from "./set.js";
-import { transformWalk } from "./transformWalk.js";
-import debounce from "lodash-es/debounce.js";
-import isSet from "lodash-es/isSet.js";
-import partial from "lodash-es/partial.js";
-import union from "lodash-es/union.js";
-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;
-
-/**
- * Map of categories to whether they are enabled or not. The order of the entries are important.
- * All categories in the key must be present for the entry to match.
- * The first matching entry with a value opf true will show the message.
- * The first matching entry with a value of false will hide the message.
- * 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
- * window.RH_DEBUG_CATEGORIES.set(["ofc-form-component", "lifecycle"], true); // show messages matching both categories
- * window.RH_DEBUG_CATEGORIES.set(["lifecycle"], false); // turn off lifecycle messages not matching the above
- * window.RH_DEBUG_CATEGORIES.set(["dropDown"], true); // show dropDown messages except where disabled by the above
- * window.RH_DEBUG_CATEGORIES.set(["*"], false); // turn off all messages not matching the above
- */
-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;
-
-/**
- * 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;
-
-const DEBOUNCE_WAIT = 50;
-const log = console.log;
-const messageBounceFns = {};
-const counts = {};
-
-/**
- * @private
- * @param {Set} categoriesSet categories for the message log
- * @param {string} categoriesKey key for debouncing
- * @param {Array.<*>} messages messages to log
- */
-const doLog = (categoriesSet, categoriesKey, messages) => {
-    if (messages.length > 0) {
-        const key = getKey(categoriesKey, messages);
-        const count = counts[key];
-        const logArgs = [Array.from(categoriesSet).join(","), ...messages];
-        if (count > 1) {
-            logArgs.push(`(${count})`);
-        }
-        log(...logArgs);
-        delete counts[key];
-        delete messageBounceFns[key];
-    }
-};
-
-/**
- * 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
- * @param {string} path path to the value, used for display in circular references
- * @returns {*} processed value
- */
-export const inspectWalkFn = (seenObjects, key, value, path) => {
-    // return primatives as-is
-    if (typeof value !== "object" || value === null) {
-        return value;
-    }
-    if (seenObjects.has(value)) {
-        return `「Dupe:${seenObjects.get(value)}」`;
-    }
-    seenObjects.set(value, path);
-    if (value?.type?.__name) {
-        // vue component instance
-        return `⧼ Component:${value.type.__name} ⧽`;
-    }
-    return value;
-};
-
-/**
- * @private
- * @param {Array.<string | Function>} messages messages to resolve
- * @returns {Array.<*>} resolved messages
- */
-const resolveMessages = (messages) => {
-    const resolvedMessages = [];
-    for (const message of messages) {
-        let toPush = unref(typeof message === "function" ? message() : message);
-        if (window.RH_TRANSFORM_MESSAGES) {
-            const seenObjects = new Map();
-            toPush = transformWalk(toPush, partial(inspectWalkFn, seenObjects));
-        }
-        resolvedMessages.push(toPush);
-    }
-    return resolvedMessages;
-};
-
-/**
- * @private
- * @param {Set} categoriesSet categories for the message log
- * @param {string} categoriesKey key for debouncing
- * @param {Array.<*>} messages messages to log
- * @returns {void}
- */
-const doDebouncedLog = (categoriesSet, categoriesKey, messages) => {
-    if (!window.RH_DEBOUNCE_DEBUG) {
-        return doLog(categoriesSet, categoriesKey, messages);
-    }
-    const key = getKey(categoriesKey, messages);
-    let debouncedLog = messageBounceFns[key];
-    if (!debouncedLog) {
-        debouncedLog = debounce(doLog, DEBOUNCE_WAIT, { leading: false, trailing: true });
-        messageBounceFns[key] = debouncedLog;
-    }
-    debouncedLog(categoriesSet, categoriesKey, messages);
-    counts[key] = (counts[key] || 0) + 1;
-};
-
-/**
- * @private
- * @param {string} categoriesKey categories for the message log
- * @param {Array.<string | Function>} messages messages to log
- * @returns {string} key
- */
-const getKey = (categoriesKey, messages) => `${categoriesKey}|${messages.join("-")}`;
-
-/**
- * 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
- */
-export function useDebugMessage(categories) {
-    const categoriesSet = isSet(categories) ? categories : new Set(categories);
-    const sortedCategories = Array.from(categoriesSet).sort();
-    const categoriesKey = categoriesSet.size > 0 ? `[${sortedCategories.join(", ")}]` : "";
-
-    const debugMessage = (...messages) => {
-        if (!window.RH_DEBUG) {
-            return;
-        }
-        for (const [rule, enabledOrDisabled] of window.RH_DEBUG_CATEGORIES.entries()) {
-            let ruleSet;
-            if (Array.isArray(rule)) {
-                ruleSet = new Set(rule);
-            } else if (typeof rule === "string") {
-                ruleSet = new Set(rule.split(","));
-            } else if (rule.toString() === "[object Set]") {
-                ruleSet = rule;
-            } else if (rule === "*") {
-                ruleSet = new Set(["*"]);
-            } else {
-                throw new Error(`Unexpected rule type: ${typeof rule}, ${rule}`);
-            }
-            // if categoriesSet is a superset of ruleSet, then apply the rule
-            // first applicable rule wins
-            if (isSuperset(categoriesSet, ruleSet) || ruleSet.has("*")) {
-                if (enabledOrDisabled === true) {
-                    doDebouncedLog(categoriesSet, categoriesKey, resolveMessages(messages));
-                    return;
-                } else if (enabledOrDisabled === false) {
-                    return;
-                }
-                // ignore other values
-            }
-        }
-        doDebouncedLog(categoriesSet, categoriesKey, resolveMessages(messages));
-    };
-    /**
-     * @param {string[]} moreCategories categories to add
-     * @returns {DebugMessageFunction} new debug message function
-     */
-    debugMessage.more = (moreCategories) => {
-        // return a new debugMessage so the added categories are only applied to the new debugMessage
-        return useDebugMessage(union(categoriesSet, isSet(moreCategories) ? moreCategories : new Set(moreCategories)));
-    };
-    return debugMessage;
-}

package/utils/debugWatch.js

@@ -1,29 +0,0 @@
-import { keyDiff } from "./keyDiff.js";
-import isEqual from "lodash-es/isEqual.js";
-import { watch } from "vue";
-import { deepUnref } from "vue-deepunref";
-
-export const debugWatch = (target, name) => {
-    return watch(
-        () => deepUnref(target),
-        (newState, oldState) => {
-            console.log(`Watch triggered ${name}`);
-            const diff = keyDiff(Object.keys(newState || {}), Object.keys(oldState || {}));
-            for (const addedKey of Array.from(diff.addedKeys)) {
-                console.log(`${name} added key ${addedKey}`, deepUnref(newState[addedKey]));
-            }
-            for (const removedKey of Array.from(diff.removedKeys)) {
-                console.log(`${name} removed key ${removedKey}`, deepUnref(oldState[removedKey]));
-            }
-            for (const sameKey of Array.from(diff.sameKeys)) {
-                if (!isEqual(deepUnref(newState[sameKey]), deepUnref(oldState[sameKey]))) {
-                    console.log(`${name} same key ${sameKey}`, newState[sameKey], oldState[sameKey]);
-                }
-            }
-        },
-        {
-            deep: true,
-            immediate: true,
-        }
-    );
-};

package/utils/index.js

@@ -1,16 +0,0 @@
-export * from "./assignReactiveObject.js";
-export * from "./classes.js";
-export * from "./compact.js";
-export * from "./debugMessage.js";
-export * from "./debugWatch.js";
-export * from "./deleteKey.js";
-export * from "./flattenPaths.js";
-export * from "./getFakeId.js";
-export * from "./keyDiff.js";
-export * from "./lifecycleDebug.js";
-export * from "./loadingCombine.js";
-export * from "./proxyRunning.js";
-export * from "./relatedCalculatedHelpers.js";
-export * from "./set.js";
-export * from "./transformWalk.js";
-export * from "./watches.js";

package/utils/lifecycleDebug.js

@@ -1,126 +0,0 @@
-import { inspectWalkFn, useDebugMessage } from "./debugMessage.js";
-import { keyDiffDeep } from "./keyDiff.js";
-import { transformWalk } from "./transformWalk.js";
-import isEqual from "lodash-es/isEqual.js";
-import partial from "lodash-es/partial.js";
-import {
-    onActivated,
-    onBeforeMount,
-    onBeforeUnmount,
-    onBeforeUpdate,
-    onDeactivated,
-    onErrorCaptured,
-    onMounted,
-    onRenderTracked,
-    onRenderTriggered,
-    onServerPrefetch,
-    onUnmounted,
-    onUpdated,
-    unref,
-} from "vue";
-
-/**
- * Debug lifecycle hooks
- * @module utils/lifecycleDebug
- */
-
-window.RH_DEBUG_SKIP_EMPTY_CHANGE_EFFECTS = true;
-
-export const customHandlers = {
-    onRenderTriggered: (debugMessage, e) => {
-        const newSeenObjects = new Map();
-        const newValue = transformWalk(e.newValue, partial(inspectWalkFn, newSeenObjects));
-        const oldSeenObjects = new Map();
-        const oldValue = transformWalk(e.oldValue, partial(inspectWalkFn, oldSeenObjects));
-        let keyDiffResults;
-        if (typeof newValue !== "object" || typeof oldValue !== "object") {
-            keyDiffResults = keyDiffDeep(newValue, oldValue);
-            keyDiffResults.changedKeys = new Set();
-            for (const key of keyDiffResults.sameKeys) {
-                // since it is a deep diff, object equality is fine to not trigger a change
-                if (newValue[key] !== oldValue[key]) {
-                    keyDiffResults.changedKeys.add(key);
-                }
-            }
-            delete keyDiffResults.sameKeys;
-            for (const key in keyDiffResults) {
-                if (keyDiffResults[key].size === 0) {
-                    delete keyDiffResults[key];
-                }
-            }
-            if (Object.keys(keyDiffResults).length === 0 && window.RH_DEBUG_SKIP_EMPTY_CHANGE_EFFECTS) {
-                return;
-            }
-        } else {
-            if (isEqual(newValue, oldValue)) {
-                return;
-            }
-        }
-        const debugArgs = [
-            {
-                effect: e.effect,
-                fn: e.effect.fn,
-                target: unref(e.target),
-                type: e.type,
-                key: e.key,
-                newValue,
-                oldValue,
-                oldTarget: unref(e.oldTarget),
-            },
-        ];
-        if (keyDiffResults) {
-            debugArgs.push(keyDiffResults);
-        }
-        debugMessage(...debugArgs);
-    },
-    onRenderTracked: (debugMessage, e) => {
-        debugMessage({
-            fn: e.effect.fn,
-            target: unref(e.target),
-            type: e.type,
-            key: e.key,
-        });
-    },
-};
-const defaultHandler = (debugMessage) => {
-    debugMessage();
-};
-
-/**
- * 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 = {
-        onActivated,
-        onBeforeMount,
-        onBeforeUnmount,
-        onBeforeUpdate,
-        onDeactivated,
-        onErrorCaptured,
-        onMounted,
-        onRenderTracked,
-        onRenderTriggered,
-        onServerPrefetch,
-        onUnmounted,
-        onUpdated,
-    };
-    const hasIncludes = includes && includes.length > 0;
-    const hasExcludes = excludes && excludes.length > 0;
-    for (const key in lifeCycleFns) {
-        if (hasIncludes && !includes.includes(key)) {
-            continue;
-        }
-        if (hasExcludes && excludes.includes(key)) {
-            continue;
-        }
-        const myCategories = new Set(categories);
-        myCategories.add("lifecycle");
-        myCategories.add(key);
-        const debugMessage = useDebugMessage(myCategories);
-        lifeCycleFns[key](partial(customHandlers[key] || defaultHandler, debugMessage));
-    }
-}