@arrai-innovations/reactive-helpers 18.0.0 → 18.0.2

package/docs/utils/watches.md

@@ -1,489 +0,0 @@
-[**@arrai-innovations/reactive-helpers**](../README.md)
-
-***
-
-[@arrai-innovations/reactive-helpers](../README.md) / utils/watches
-
-# utils/watches
-
-## Classes
-
-### AwaitNot
-
-Manages an asynchronous watch on a property, waiting for it to toggle between true and false states.
-This class uses immediate watchers to react to changes and supports a timeout to limit waiting duration.
-
-#### Constructors
-
-##### new AwaitNot()
-
-> **new AwaitNot**(`options`): [`AwaitNot`](watches.md#awaitnot)
-
-Initializes the AwaitNot with specified options for reactive property watching and timeout settings.
-
-###### Parameters
-
-###### options
-
-Configuration options for AwaitNot.
-
-###### couldAlreadyBeFalse
-
-`boolean` = `false`
-
-Indicates if the property could already be in the false state at initialization.
-
-###### obj
-
-`any`
-
-The object containing the property to watch.
-
-###### prop
-
-`string`
-
-The property name to watch within the object.
-
-###### ref
-
-`Ref`
-
-A Vue ref to directly watch if provided.
-
-###### timeout
-
-`number` = `1000`
-
-The timeout in milliseconds before the promise is rejected.
-
-###### Returns
-
-[`AwaitNot`](watches.md#awaitnot)
-
-#### Properties
-
-##### couldAlreadyBeFalse
-
-> **couldAlreadyBeFalse**: `boolean`
-
-##### falseISW
-
-> **falseISW**: [`ImmediateStopWatch`](watches.md#immediatestopwatch)
-
-##### promise
-
-> **promise**: `Promise`\<`any`\>
-
-##### ref
-
-> **ref**: `Readonly`\<`Ref`\>
-
-##### reject()
-
-> **reject**: (`reason`?) => `void`
-
-###### Parameters
-
-###### reason?
-
-`any`
-
-###### Returns
-
-`void`
-
-##### resolve()
-
-> **resolve**: (`value`) => `void`
-
-###### Parameters
-
-###### value
-
-`any`
-
-###### Returns
-
-`void`
-
-##### timeout
-
-> **timeout**: [`AwaitTimeout`](watches.md#awaittimeout)
-
-##### timeoutError
-
-> **timeoutError**: [`AwaitNotError`](watches.md#awaitnoterror)
-
-##### trueISW
-
-> **trueISW**: [`ImmediateStopWatch`](watches.md#immediatestopwatch)
-
-#### Methods
-
-##### start()
-
-> **start**(): `void`
-
-Starts the process of watching the property for changes between true and false.
-It sets up the necessary watchers and a timeout if specified.
-
-###### Returns
-
-`void`
-
-##### stop()
-
-> **stop**(): `void`
-
-Stops all watchers and the timeout, cleaning up resources.
-
-###### Returns
-
-`void`
-
-***
-
-### AwaitNotError
-
-The error thrown when an AwaitNot operation times out.
-
-#### Extends
-
-- `Error`
-
-#### Constructors
-
-##### new AwaitNotError()
-
-> **new AwaitNotError**(`message`, `code`): [`AwaitNotError`](watches.md#awaitnoterror)
-
-###### Parameters
-
-###### message
-
-`any`
-
-###### code
-
-`any`
-
-###### Returns
-
-[`AwaitNotError`](watches.md#awaitnoterror)
-
-###### Overrides
-
-`Error.constructor`
-
-#### Properties
-
-##### code
-
-> **code**: `any`
-
-The error code.
-
-##### name
-
-> **name**: `string`
-
-The error name.
-
-###### Inherited from
-
-`Error.name`
-
-***
-
-### AwaitTimeout
-
-A utility class for managing a promise that resolves or rejects based on a set timeout or an explicit stop action.
-This class is useful for implementing timeouts in asynchronous operations, where you might need to reject a promise
-if an operation takes too long or cancel the timeout based on certain conditions.
-
-#### Constructors
-
-##### new AwaitTimeout()
-
-> **new AwaitTimeout**(`options`): [`AwaitTimeout`](watches.md#awaittimeout)
-
-Creates an instance of AwaitTimeout with a specified timeout duration.
-
-###### Parameters
-
-###### options
-
-The options for the AwaitTimeout.
-
-###### timeout
-
-`number` = `1000`
-
-The timeout in milliseconds.
-
-###### Returns
-
-[`AwaitTimeout`](watches.md#awaittimeout)
-
-#### Properties
-
-##### cancelledError
-
-> **cancelledError**: [`AwaitTimeoutError`](watches.md#awaittimeouterror)
-
-##### promise
-
-> **promise**: `Promise`\<`any`\>
-
-##### reject()
-
-> **reject**: (`reason`?) => `void`
-
-###### Parameters
-
-###### reason?
-
-`any`
-
-###### Returns
-
-`void`
-
-##### resolve()
-
-> **resolve**: (`value`) => `void`
-
-###### Parameters
-
-###### value
-
-`any`
-
-###### Returns
-
-`void`
-
-##### timeout
-
-> **timeout**: `number`
-
-##### timeoutId
-
-> **timeoutId**: `Timeout`
-
-#### Methods
-
-##### start()
-
-> **start**(): `void`
-
-Starts the timeout process. If the timeout duration is reached without being stopped, the promise resolves.
-
-###### Returns
-
-`void`
-
-##### stop()
-
-> **stop**(): `void`
-
-Stops the timeout if it is active, rejecting the promise with a "Cancelled" error. Clears all pending actions.
-
-###### Returns
-
-`void`
-
-***
-
-### AwaitTimeoutError
-
-The error thrown when an AwaitTimeout operation times out.
-
-#### Extends
-
-- `Error`
-
-#### Constructors
-
-##### new AwaitTimeoutError()
-
-> **new AwaitTimeoutError**(`message`, `code`): [`AwaitTimeoutError`](watches.md#awaittimeouterror)
-
-###### Parameters
-
-###### message
-
-`any`
-
-###### code
-
-`any`
-
-###### Returns
-
-[`AwaitTimeoutError`](watches.md#awaittimeouterror)
-
-###### Overrides
-
-`Error.constructor`
-
-#### Properties
-
-##### code
-
-> **code**: `any`
-
-The error code.
-
-##### name
-
-> **name**: `string`
-
-###### Inherited from
-
-`Error.name`
-
-***
-
-### ImmediateStopWatch
-
-Provides a mechanism for immediately starting and potentially stopping a Vue.js watcher
-during its first invocation. This is useful when the need arises to terminate the watch
-based on conditions encountered during the initial execution of the watch function.
-
-#### Constructors
-
-##### new ImmediateStopWatch()
-
-> **new ImmediateStopWatch**(): [`ImmediateStopWatch`](watches.md#immediatestopwatch)
-
-###### Returns
-
-[`ImmediateStopWatch`](watches.md#immediatestopwatch)
-
-#### Properties
-
-##### stopWatch
-
-> **stopWatch**: `WatchHandle`
-
-#### Methods
-
-##### start()
-
-> **start**(`watchSources`, `watchFunc`, `watchFuncArgs`?, `watchOptions`?): `void`
-
-Starts the watch.
-
-###### Parameters
-
-###### watchSources
-
-The source(s) to watch.
-
-`WatchSource`\<`any`\> | `WatchSource`\<`any`\>[]
-
-###### watchFunc
-
-`WatchCallback`\<`any`, `any`\>
-
-The callback to execute when the source changes.
-
-###### watchFuncArgs?
-
-`any`[] = `[]`
-
-Optional arguments to pass to the watch function.
-
-###### watchOptions?
-
-`WatchOptions` = `{}`
-
-Optional watch options.
-
-###### Returns
-
-`void`
-
-##### stop()
-
-> **stop**(): `void`
-
-Stops the watch.
-
-###### Returns
-
-`void`
-
-## Functions
-
-### doAwaitNot()
-
-> **doAwaitNot**(`options`): `Promise`\<`any`\>
-
-Helper function to get the resulting promise from an AwaitNot instance.
-
-#### Parameters
-
-##### options
-
-Configuration options for AwaitNot.
-
-###### couldAlreadyBeFalse
-
-`boolean` = `true`
-
-Indicates if the property could already be in the false state at initialization.
-
-###### obj
-
-`any`
-
-The object containing the property to watch.
-
-###### prop
-
-`string`
-
-The property name to watch within the object.
-
-###### ref
-
-`Ref`
-
-A Vue ref to directly watch if provided.
-
-###### timeout
-
-`number` = `1000`
-
-The timeout in milliseconds before the promise is rejected.
-
-#### Returns
-
-`Promise`\<`any`\>
-
-A promise that resolves when the property toggles from true to false.
-
-***
-
-### doAwaitTimeout()
-
-> **doAwaitTimeout**(`timeout`): `Promise`\<`any`\>
-
-Helper function to get the resulting promise from an AwaitTimeout instance.
-
-#### Parameters
-
-##### timeout
-
-`number`
-
-The timeout in milliseconds.
-
-#### Returns
-
-`Promise`\<`any`\>
-
-A promise that resolves after the specified timeout.

package/eslint.config.js

@@ -1,125 +0,0 @@
-import js from "@eslint/js";
-import globals from "globals";
-import pluginVue from "eslint-plugin-vue";
-import eslintConfigPrettier from "eslint-config-prettier";
-import jsdoc from "eslint-plugin-jsdoc";
-import { FlatCompat } from "@eslint/eslintrc";
-import vitest from "eslint-plugin-vitest";
-
-const compat = new FlatCompat({ baseDirectory: import.meta.dirname });
-export default [
-    { ignores: [".prettierrc.js", "typedoc-local-plugins", "docs"] },
-    {
-        languageOptions: {
-            globals: {
-                ...globals.browser,
-                ...globals.node,
-                ...globals.es2023,
-            },
-        },
-    },
-    // non-tests
-    {
-        name: "non-tests",
-        files: ["config/**/*.js", "use/**/*.js", "utils/**/*.js", "index.js"],
-        plugins: {
-            ...pluginVue.configs["flat/recommended"].reduce((acc, config) => {
-                return { ...acc, plugins: { ...acc.plugins, ...config.plugins } };
-            }).plugins,
-            ...compat.extends("@vue/eslint-config-prettier/skip-formatting").reduce((acc, config) => {
-                return { ...acc, plugins: { ...acc.plugins, ...config.plugins } };
-            }, {}).plugins,
-            ...jsdoc.configs["flat/recommended-typescript-flavor-error"].plugins,
-        },
-        settings: {
-            jsdoc: {
-                mode: "typescript",
-            },
-        },
-        rules: {
-            ...js.configs.recommended.rules,
-            ...pluginVue.configs["flat/recommended"].reduce((acc, config) => {
-                return { ...acc, rules: { ...acc.rules, ...config.rules } };
-            }, {}).rules,
-            ...eslintConfigPrettier.rules,
-            ...compat.extends("@vue/eslint-config-prettier/skip-formatting").reduce((acc, config) => {
-                return {
-                    ...acc,
-                    rules: {
-                        ...acc.rules,
-                        ...config.rules,
-                    },
-                };
-            }, {}).rules,
-            ...jsdoc.configs["flat/recommended-typescript-flavor-error"].rules,
-            "no-console": "off",
-            "no-debugger": process.env.NODE_ENV === "production" ? "error" : "off",
-            "space-before-function-paren": [
-                "error",
-                {
-                    anonymous: "always",
-                    named: "never",
-                    asyncArrow: "always",
-                },
-            ],
-            "jsdoc/require-jsdoc": [
-                "error",
-                {
-                    publicOnly: true,
-                    enableFixer: false,
-                },
-            ],
-            "jsdoc/check-param-names": "error",
-            "jsdoc/check-property-names": "error",
-            "jsdoc/check-tag-names": [
-                "error",
-                {
-                    definedTags: [
-                        // using typescript flavour for jsdoc, but not using typescript
-                        //  we still need to define these tags
-                        "typedef",
-                        "type",
-                    ],
-                },
-            ],
-            "jsdoc/empty-tags": "error",
-            "jsdoc/multiline-blocks": "error",
-            "jsdoc/no-defaults": "off",
-            "jsdoc/require-asterisk-prefix": "error",
-            "jsdoc/require-description-complete-sentence": "error",
-            "jsdoc/require-hyphen-before-param-description": "error",
-            "jsdoc/require-param": "error",
-            "jsdoc/require-property": [
-                "error",
-                {
-                    enableFixer: false,
-                },
-            ],
-            "jsdoc/tag-lines": [
-                "error",
-                "always",
-                {
-                    count: 0,
-                    startLines: 1,
-                    endLines: 1,
-                },
-            ],
-        },
-    },
-    // tests
-    {
-        name: "tests",
-        files: ["tests/**/*.js"],
-        plugins: { vitest },
-        languageOptions: {
-            globals: {
-                ...vitest.environments.env.globals,
-            },
-        },
-        rules: {
-            ...vitest.configs.recommended.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/lint-staged.config.js

@@ -1,10 +0,0 @@
-export default {
-    "**/*.{js,cjs,mjs,ts,jsx,tsx}": [
-        "npx --no-install eslint --cache --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/makeTypeDoc.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-set -e  # Enable exit on error
-BLUE_COLOR='\033[1;38;2;0;119;247m'
-ORANGE_COLOR='\033[1;38;2;255;127;0m'
-RESET_COLOR='\033[0m'
-TEMP_DIR=$(mktemp -d -t docs-XXXXXXXXXX)
-cleanup() {
-  rm -rf "${TEMP_DIR}"
-}
-trap cleanup EXIT
-npx --no-install typedoc --out "${TEMP_DIR}" --plugin typedoc-plugin-markdown --disableSources
-set +e
-diff -u -r "${TEMP_DIR}" ./docs > /dev/null
-diff_exit_code=$?
-set -e
-
-if [ "${diff_exit_code}" -ne 0 ]; then
-  echo -e "[${0}] ${ORANGE_COLOR}Docs are out of date, updating...${RESET_COLOR}"
-  rm -rf ./docs
-  mv "${TEMP_DIR}" ./docs
-  git add ./docs
-else
-  echo -e "[${0}] ${BLUE_COLOR}Docs are up to date${RESET_COLOR}"
-fi
-exit 0

package/make_type_doc.js

@@ -1,59 +0,0 @@
-#!/usr/bin/env node
-
-import { execSync } from "child_process";
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const scriptName = path.basename(__filename);
-
-const BLUE_COLOR = "\u001b[1;38;2;0;119;247m";
-const ORANGE_COLOR = "\u001b[1;38;2;255;127;0m";
-const RESET_COLOR = "\u001b[0m";
-
-const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "docs-"));
-const docsDir = path.resolve("./docs");
-
-function cleanup() {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-}
-
-process.on("exit", cleanup);
-process.on("SIGINT", () => {
-    cleanup();
-    process.exit(1);
-});
-
-execSync(`npx --no-install typedoc --out "${tempDir}" --plugin typedoc-plugin-markdown --disableSources`, {
-    stdio: "inherit",
-});
-
-let docsAreDifferent = false;
-
-try {
-    execSync(`git diff --no-index --quiet "${tempDir}" "${docsDir}"`, {
-        stdio: "inherit",
-    });
-} catch (error) {
-    if (error.status === 1) {
-        // Differences found
-        docsAreDifferent = true;
-    } else {
-        // Unexpected error
-        throw error;
-    }
-}
-
-if (docsAreDifferent) {
-    console.log(`[${scriptName}] ${ORANGE_COLOR}Docs are out of date, updating...${RESET_COLOR}`);
-    fs.rmSync("./docs", { recursive: true, force: true });
-    fs.renameSync(tempDir, "./docs");
-    execSync(`git add ./docs`, { stdio: "inherit" });
-} else {
-    console.log(`[${scriptName}] ${BLUE_COLOR}Docs are up to date${RESET_COLOR}`);
-}
-
-cleanup();
-process.exit(0);