@arrai-innovations/reactive-helpers 18.0.0 → 18.0.2

package/types/utils/watches.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Helper function to get the resulting promise from an AwaitTimeout instance.
+ *
+ * @param {number} timeout - The timeout in milliseconds.
+ * @returns {Promise} A promise that resolves after the specified timeout.
+ */
+export function doAwaitTimeout(timeout: number): Promise<any>;
+/**
+ * Helper function to get the resulting promise from an AwaitNot instance.
+ *
+ * @param {object} options - Configuration options for AwaitNot.
+ * @param {object} options.obj - The object containing the property to watch.
+ * @param {string} options.prop - The property name to watch within the object.
+ * @param {import("vue").Ref} [options.ref] - A Vue ref to directly watch if provided.
+ * @param {boolean} [options.couldAlreadyBeFalse=false] - Indicates if the property could already be in the false state at initialization.
+ * @param {number} [options.timeout=1000] - The timeout in milliseconds before the promise is rejected.
+ * @returns {Promise} A promise that resolves when the property toggles from true to false.
+ */
+export function doAwaitNot({ obj, prop, ref, couldAlreadyBeFalse, timeout }: {
+    obj: object;
+    prop: string;
+    ref?: import("vue").Ref;
+    couldAlreadyBeFalse?: boolean;
+    timeout?: number;
+}): Promise<any>;
+/**
+ * @module utils/watches.js
+ * @description
+ *
+ * A collection of utility classes and functions for managing Vue.js watchers.
+ *
+ */
+/**
+ * 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.
+ */
+export class ImmediateStopWatch {
+    /**
+     * Starts the watch.
+     *
+     * @param {import("vue").WatchSource | import("vue").WatchSource[]} watchSources - The source(s) to watch.
+     * @param {import("vue").WatchCallback} watchFunc - The callback to execute when the source changes.
+     * @param {any[]} [watchFuncArgs=[]] - Optional arguments to pass to the watch function.
+     * @param {import("vue").WatchOptions} [watchOptions={}] - Optional watch options.
+     * @returns {void}
+     */
+    start(watchSources: import("vue").WatchSource | import("vue").WatchSource[], watchFunc: import("vue").WatchCallback, watchFuncArgs?: any[], watchOptions?: import("vue").WatchOptions): void;
+    stopWatch: import("vue").WatchHandle;
+    /**
+     * Stops the watch.
+     *
+     * @returns {void}
+     */
+    stop(): void;
+}
+/**
+ * The error thrown when an AwaitTimeout operation times out.
+ *
+ * @property {string} code - The error code.
+ */
+export class AwaitTimeoutError extends Error {
+    constructor(message: any, code: any);
+    code: any;
+}
+/**
+ * The error thrown when an AwaitNot operation times out.
+ *
+ * @property {string} code - The error code.
+ * @property {string} name - The error name.
+ */
+export class AwaitNotError extends Error {
+    constructor(message: any, code: any);
+    code: any;
+}
+/**
+ * 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.
+ */
+export class AwaitTimeout {
+    /**
+     * Creates an instance of AwaitTimeout with a specified timeout duration.
+     *
+     * @param {object} options - The options for the AwaitTimeout.
+     * @param {number} [options.timeout=1000] - The timeout in milliseconds.
+     */
+    constructor({ timeout }: {
+        timeout?: number;
+    });
+    promise: Promise<any>;
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+    timeout: number;
+    timeoutId: NodeJS.Timeout;
+    cancelledError: AwaitTimeoutError;
+    /**
+     * Starts the timeout process. If the timeout duration is reached without being stopped, the promise resolves.
+     *
+     * @returns {void}
+     */
+    start(): void;
+    /**
+     * Stops the timeout if it is active, rejecting the promise with a "Cancelled" error. Clears all pending actions.
+     *
+     * @returns {void}
+     */
+    stop(): void;
+}
+/**
+ * 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.
+ */
+export class AwaitNot {
+    /**
+     * Initializes the AwaitNot with specified options for reactive property watching and timeout settings.
+     *
+     * @param {object} options - Configuration options for AwaitNot.
+     * @param {object} [options.obj] - The object containing the property to watch.
+     * @param {string} [options.prop] - The property name to watch within the object.
+     * @param {import("vue").Ref} [options.ref] - A Vue ref to directly watch if provided.
+     * @param {boolean} [options.couldAlreadyBeFalse=false] - Indicates if the property could already be in the false state at initialization.
+     * @param {number} [options.timeout=1000] - The timeout in milliseconds before the promise is rejected.
+     */
+    constructor({ obj, prop, ref, couldAlreadyBeFalse, timeout }: {
+        obj?: object;
+        prop?: string;
+        ref?: import("vue").Ref;
+        couldAlreadyBeFalse?: boolean;
+        timeout?: number;
+    });
+    timeout: AwaitTimeout;
+    promise: Promise<any>;
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+    couldAlreadyBeFalse: boolean;
+    ref: Readonly<import("vue").Ref<any, any>>;
+    trueISW: ImmediateStopWatch;
+    falseISW: ImmediateStopWatch;
+    timeoutError: AwaitNotError;
+    /**
+     * 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}
+     */
+    start(): void;
+    /**
+     * Stops all watchers and the timeout, cleaning up resources.
+     *
+     * @returns {void}
+     */
+    stop(): void;
+}
+//# sourceMappingURL=watches.d.ts.map

package/types/utils/watches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watches.d.ts","sourceRoot":"","sources":["../../utils/watches.js"],"names":[],"mappings":"AAiJA;;;;;GAKG;AACH,wCAHW,MAAM,gBAOhB;AAyKD;;;;;;;;;;GAUG;AACH,6EAPG;IAAwB,GAAG,EAAnB,MAAM;IACU,IAAI,EAApB,MAAM;IACsB,GAAG,GAA/B,OAAO,KAAK,EAAE,GAAG;IACC,mBAAmB,GAArC,OAAO;IACU,OAAO,GAAxB,MAAM;CACd,gBAMF;AAjVD;;;;;;GAMG;AAEH;;;;GAIG;AACH;IAGI;;;;;;;;OAQG;IACH,oBANW,OAAO,KAAK,EAAE,WAAW,GAAG,OAAO,KAAK,EAAE,WAAW,EAAE,aACvD,OAAO,KAAK,EAAE,aAAa,kBAC3B,GAAG,EAAE,iBACL,OAAO,KAAK,EAAE,YAAY,GACxB,IAAI,CAShB;IAHG,qCAA6D;IAKjE;;;;OAIG;IACH,QAFa,IAAI,CAOhB;CACJ;AAED;;;;GAIG;AACH;IACI,qCAIC;IADG,UAAgB;CAEvB;AAED;;;;;GAKG;AACH;IACI,qCAIC;IADG,UAAgB;CAEvB;AAeD;;;;GAIG;AACH;IACI;;;;;OAKG;IACH,yBAFG;QAAyB,OAAO,GAAxB,MAAM;KAChB,EAUA;IARG,sBAGE;IAFE,8BAAsB;IACtB,+BAAoB;IAExB,gBAAsB;IACtB,0BAAqB;IAErB,kCAA6E;IAGjF;;;;OAIG;IACH,SAFa,IAAI,CAQhB;IAED;;;;OAIG;IACH,QAFa,IAAI,CAchB;CACJ;AAgGD;;;GAGG;AACH;IACI;;;;;;;;;OASG;IACH,8DANG;QAAyB,GAAG,GAApB,MAAM;QACW,IAAI,GAArB,MAAM;QACsB,GAAG,GAA/B,OAAO,KAAK,EAAE,GAAG;QACC,mBAAmB,GAArC,OAAO;QACU,OAAO,GAAxB,MAAM;KAChB,EAqBA;IAlBO,sBAA4C;IAEhD,sBAGE;IAFE,8BAAsB;IACtB,+BAAoB;IAExB,6BAA8C;IAE1C,2CAAc;IAIlB,4BAAuC;IACvC,6BAAwC;IAGpC,4BAA2D;IAInE;;;;;OAKG;IACH,SAFa,IAAI,CA4BhB;IAED;;;;OAIG;IACH,QAFa,IAAI,CAQhB;CACJ"}

package/use/loadingError.js

@@ -24,7 +24,7 @@ import { readonly, ref } from "vue";
  * @typedef {object} LoadingErrorMutations
  * @property {() => void} setLoading - Set the loading state.
  * @property {() => void} clearLoading - Clear the loading state.
- * @property {(error) => void} setError - Set the error state.
+ * @property {(error: Error) => void} setError - Set the error state.
  */
 
 /**

package/.circleci/config.yml

@@ -1,88 +0,0 @@
-version: 2.1
-orbs:
-    eslint: arrai/eslint@8.1.0
-    prettier: arrai/prettier@5.10.0
-    npm: arrai/npm@3.1.0
-    github: arrai/github@5.0.0
-workflows:
-    test:
-        jobs:
-            - npm/coverage:
-                  name: tests
-                  context: arrai-global
-                  filters:
-                      branches:
-                          only:
-                              - main
-            - npm/coverage:
-                  name: tests-no-badge
-                  context: arrai-global
-                  create_badges: false
-                  filters:
-                      tags:
-                          only: /.*/
-                      branches:
-                          ignore:
-                              - main
-            - npm/publish:
-                  name: publish
-                  context: arrai-private-package-publishing
-                  requires:
-                      - tests-no-badge
-                  filters:
-                      tags:
-                          only: /.*/
-                      branches:
-                          ignore: /.*/
-            - github/create_release:
-                  name: release_on_github
-                  context: arrai-global
-                  requires:
-                      - tests-no-badge
-                  filters:
-                      tags:
-                          only: /.*/
-                      branches:
-                          ignore: /.*/
-    lint:
-        jobs:
-            - eslint/eslint_fixed_ip:
-                  name: eslint
-                  context: arrai-global
-                  files: "."
-                  wd: "."
-                  config:
-                      - run:
-                            name: NPM
-                            command: npm ci
-                  filters:
-                      branches:
-                          only:
-                              - main
-            - eslint/eslint:
-                  name: eslint-no-badge
-                  files: "."
-                  wd: "."
-                  config:
-                      - run:
-                            name: NPM
-                            command: npm ci
-                  create_badges: false
-                  filters:
-                      branches:
-                          ignore:
-                              - main
-            - prettier/code_style_fixed_ip:
-                  name: prettier
-                  context: arrai-global
-                  filters:
-                      branches:
-                          only:
-                              - main
-            - prettier/code_style:
-                  name: prettier-no-badge
-                  create_badges: false
-                  filters:
-                      branches:
-                          ignore:
-                              - main

package/.commitlintrc.json

@@ -1,25 +0,0 @@
-{
-    "extends": ["@commitlint/config-conventional"],
-    "rules": {
-        "type-enum": [
-            2,
-            "always",
-            [
-                "build",
-                "ci",
-                "chore",
-                "content",
-                "docs",
-                "feat",
-                "fix",
-                "perf",
-                "refactor",
-                "remove",
-                "revert",
-                "style",
-                "test",
-                "wip"
-            ]
-        ]
-    }
-}

package/.editorconfig

@@ -1,5 +0,0 @@
-[*.{js,jsx,ts,tsx,vue,markdown,md,yml}]
-indent_style = space
-indent_size = 4
-trim_trailing_whitespace = true
-insert_final_newline = true

package/.husky/commit-msg

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-
-npx --no-install commitlint --edit "$1"

package/.husky/pre-commit

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-
-npx --no-install lint-staged

package/.idea/codeStyles/codeStyleConfig.xml

@@ -1,5 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <state>
-    <option name="PREFERRED_PROJECT_CODE_STYLE" value="Default (3)" />
-  </state>
-</component>

package/.idea/encodings.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="Encoding">
-    <file url="PROJECT" charset="UTF-8" />
-  </component>
-</project>

package/.idea/inspectionProfiles/Project_Default.xml

@@ -1,7 +0,0 @@
-<component name="InspectionProjectProfileManager">
-  <profile version="1.0">
-    <option name="myName" value="Project Default" />
-    <inspection_tool class="ES6PreferShortImport" enabled="true" level="WEAK WARNING" enabled_by_default="true" editorAttributes="INFO_ATTRIBUTES" />
-    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
-  </profile>
-</component>

package/.idea/modules.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectModuleManager">
-    <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/reactive-helpers.iml" filepath="$PROJECT_DIR$/.idea/reactive-helpers.iml" />
-    </modules>
-  </component>
-</project>

package/.idea/prettier.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="PrettierConfiguration">
-    <option name="myRunOnSave" value="true" />
-    <option name="myRunOnReformat" value="true" />
-    <option name="myFilesPattern" value="{**/*,*}.{js,ts,jsx,tsx,less,scss,css,vue,markdown,md,json,yml,yaml,html}" />
-  </component>
-</project>

package/.idea/reactive-helpers.iml

@@ -1,15 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="WEB_MODULE" version="4">
-  <component name="NewModuleRootManager">
-    <content url="file://$MODULE_DIR$">
-      <sourceFolder url="file://$MODULE_DIR$/tests" isTestSource="true" />
-      <excludeFolder url="file://$MODULE_DIR$/temp" />
-      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
-      <excludeFolder url="file://$MODULE_DIR$/tmp" />
-      <excludeFolder url="file://$MODULE_DIR$/.idea" />
-      <excludeFolder url="file://$MODULE_DIR$/coverage" />
-    </content>
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
-</module>

package/.prettierignore

@@ -1,5 +0,0 @@
-node_modules
-package.json
-package-lock.json
-coverage
-docs

package/.prettierrc.cjs

@@ -1,5 +0,0 @@
-module.exports = {
-    trailingComma: "es5", // stay safe cause we are browser code.
-    printWidth: 120,
-    tabWidth: 4,
-};

package/.vscode/extensions.json

@@ -1,3 +0,0 @@
-{
-    "recommendations": ["dbaeumer.vscode-eslint", "znck.vue", "galloween.jsdoc-highlight-code"]
-}

package/docs/README.md

@@ -1,45 +0,0 @@
-**@arrai-innovations/reactive-helpers**
-
-***
-
-# @arrai-innovations/reactive-helpers
-
-## Modules
-
-- [config/listCrud](config/listCrud.md)
-- [config/objectCrud](config/objectCrud.md)
-- [use/cancellableIntent](use/cancellableIntent.md)
-- [use/combineClasses](use/combineClasses.md)
-- [use/list](use/list.md)
-- [use/listCalculated](use/listCalculated.md)
-- [use/listFilter](use/listFilter.md)
-- [use/listInstance](use/listInstance.md)
-- [use/listKeys](use/listKeys.md)
-- [use/listRelated](use/listRelated.md)
-- [use/listSearch](use/listSearch.md)
-- [use/listSort](use/listSort.md)
-- [use/listSubscription](use/listSubscription.md)
-- [use/loadingError](use/loadingError.md)
-- [use/object](use/object.md)
-- [use/objectCalculated](use/objectCalculated.md)
-- [use/objectInstance](use/objectInstance.md)
-- [use/objectRelated](use/objectRelated.md)
-- [use/objectSubscription](use/objectSubscription.md)
-- [use/paginatedListInstance](use/paginatedListInstance.md)
-- [use/proxyLoadingError](use/proxyLoadingError.md)
-- [use/search](use/search.md)
-- [use/watchesRunning](use/watchesRunning.md)
-- [utils/assignReactiveObject](utils/assignReactiveObject.md)
-- [utils/classes](utils/classes.md)
-- [utils/compact](utils/compact.md)
-- [utils/deleteKey](utils/deleteKey.md)
-- [utils/flattenPaths](utils/flattenPaths.md)
-- [utils/getFakePk](utils/getFakePk.md)
-- [utils/keepAliveTry](utils/keepAliveTry.md)
-- [utils/keyDiff](utils/keyDiff.md)
-- [utils/loadingCombine](utils/loadingCombine.md)
-- [utils/proxyRunning](utils/proxyRunning.md)
-- [utils/relatedCalculatedHelpers](utils/relatedCalculatedHelpers.md)
-- [utils/set](utils/set.md)
-- [utils/transformWalk](utils/transformWalk.md)
-- [utils/watches](utils/watches.md)