@keeex/utils 7.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023 KeeeX SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @keeex/utils
+
+
+
+Utility functions in pure JS used in many places.
+
+You should check the API documentation for detailed informations about each functions.
+This is a general feature list overview.
+
+## Async utility
+
+- `AsyncTrigger`, for easy debouncing
+- `DeferredPromise` to manipulate the usual `resolve()` and `reject()` functions outside of a
+  promise block
+- `KeyCache` to create a basic key-value cache with asynchronous fetch
+- `TimeCache` to create a cache that keeps a value for a given amount of time and can automatically
+  refresh it
+- `Queues` to create parallel queues of tasks
+
+## Marshalling
+
+Serialization of random data into byte buffers.
+
+## Types
+
+Various type-checking helpers to create TypeScript type predicates.
+Supports "shortcut" versions for performance after a full check was done.
+
+## Array
+
+Generic operations on arrays, as well as array coercion.
+
+## Uint8Array and ArrayBuffer
+
+Conversion between different formats and search in buffer functions.
+
+## base58, base64
+
+Utility to manipulate strings encoded in these formats.
+
+## benchmark
+
+Code to run a JavaScript function a lot to get performance benchmarks.
+Includes some form of "automatic" probing to get good average values.
+
+## bytebuffer
+
+Helper wrapping JavaScript DataView into convenient functions.
+
+## dict
+
+Functions to copy records with primitive types (deep copy).
+
+## error
+
+Coerce anything (`unknown`) into an `Error` object for easier error handling.
+
+## global
+
+Functions to use a JavaScript environment "global" dataset.
+Handles multiple environment somewhat gracefully.
+
+## idx
+
+IDX check and manipulation functions
+
+## json
+
+JSON parsing with type safety.
+Also, a "canonical" JSON encoder that ensure property order is consistent.
+
+## log
+
+Generic logging functionality.
+Supports various log level, timestamping, error chaining, stacktrace stripping.
+
+## number
+
+Manipulate number.
+Currently only round to a given decimal place.
+
+## path
+
+Generic filename sanitization.
+
+## promise
+
+Helpers around promises.
+
+- controlled async delay
+- retry a promise until it succeed (with max tries)
+- run an array of promise, stop at the first that succeed
+
+## starttime
+
+Get the elapsed time since the JavaScript environment started.
+
+## string
+
+String and UTF-8 manipulations.
+
+## units
+
+Convers between various units.
+Generic functions are available as well as byte and time conversions.

package/lib/array.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+export type EqualityFunction<T1, T2> = (op1: T1, op2: T2) => boolean;
+/**
+ * Compare two array-like structure for equal content
+ *
+ * @public
+ */
+export declare const arrayEqual: <T1 = unknown, T2 = unknown>(op1: ArrayLike<T1>, op2: ArrayLike<T2>, eqFunc?: EqualityFunction<T1, T2>) => boolean;
+/**
+ * Return either the array provided, or an array containing the single element provided.
+ *
+ * @public
+ */
+export declare const asArray: <T>(data: Array<T> | (T extends Array<unknown> ? never : T)) => Array<T>;

package/lib/array.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+const useEqOp = (op1, op2) => op1 === op2;
+/**
+ * Compare two array-like structure for equal content
+ *
+ * @public
+ */
+export const arrayEqual = (op1, op2, eqFunc = useEqOp) => {
+    if (op1.length !== op2.length)
+        return false;
+    for (let index = 0; index < op1.length; ++index) {
+        if (!eqFunc(op1[index], op2[index]))
+            return false;
+    }
+    return true;
+};
+/**
+ * Return either the array provided, or an array containing the single element provided.
+ *
+ * @public
+ */
+export const asArray = (data) => Array.isArray(data) ? data : [data];

package/lib/arraybuffer.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+export declare const getArrayBuffer: (typedArray: ArrayBuffer | Uint8Array) => ArrayBuffer;
+/**
+ * Convert an ArrayBuffer to a raw string.
+ *
+ * @public
+ */
+export declare const ab2str: (ab: ArrayBuffer) => string;
+/**
+ * Convert a raw string to an ArrayBuffer.
+ *
+ * @public
+ */
+export declare const str2ab: (str: string) => ArrayBuffer;
+/**
+ * Convert an ArrayBuffer to an hex string.
+ *
+ * @public
+ */
+export declare const ab2hex: (ab: ArrayBuffer, usePrefix?: boolean) => string;
+/**
+ * Convert an hex string to an ArrayBuffer.
+ *
+ * @public
+ */
+export declare const hex2ab: (hex: string) => ArrayBuffer;
+/**
+ * Concatenate multiple array buffers into one output.
+ *
+ * The output will have each buffer length put in it so the buffers can be split
+ * afterward using explodeBuffersList(). Simple concatenation is available with merge().
+ *
+ * @public
+ */
+export declare const concatenateBuffersList: (buffers: Array<ArrayBuffer>, addEndMarker?: boolean) => ArrayBuffer;
+/**
+ * Separate buffers merged with concatenateBuffersList().
+ *
+ * @public
+ */
+export declare const explodeBuffersList: (mergedBuffers: ArrayBuffer) => Array<ArrayBuffer>;
+/** @public */
+export declare const concatenatedBuffersListSize: (mergedBuffers: ArrayBuffer) => number;
+/**
+ * Merge ArrayBuffers into one.
+ *
+ * @public
+ */
+export declare const merge: (buffers: Array<ArrayBuffer>) => ArrayBuffer;
+/**
+ * Convert an array buffer to a b64 string.
+ *
+ * @public
+ */
+export declare const ab2b64: (data: ArrayBuffer) => string;
+/**
+ * Convert a b64 string to an array buffer.
+ *
+ * @param strict - If enabled, prevent input from having extra data after the B64 string.
+ *
+ * @public
+ */
+export declare const b642ab: (data: string, strict?: boolean) => ArrayBuffer;
+/**
+ * Convert an UTF-8 string into an arraybuffer.
+ *
+ * @public
+ */
+export declare const utf82ab: (str: string) => ArrayBuffer;
+/**
+ * Convert back an arraybuffer into an UTF-8 string.
+ *
+ * @public
+ */
+export declare const ab2utf8: (ab: ArrayBuffer) => string;
+/**
+ * Compare that the content of two ArrayBuffer is equal.
+ *
+ * @public
+ */
+export declare const abEqual: (ab1: ArrayBuffer, ab2: ArrayBuffer) => boolean;
+/**
+ * Find the position of a string in a buffer
+ *
+ * @param needle - String to find. Only work with 1 byte-wide characters.
+ *
+ * @param ab - Buffer to look into
+ *
+ * @param startPosition - Starting index to look from
+ *
+ * @returns
+ * The position of the string in the buffer. If not found returns -1
+ *
+ * @public
+ */
+export declare const findString: (needle: string, ab: ArrayBuffer, startPosition?: number) => number;
+/**
+ * Find the position of a string in a buffer from the end
+ *
+ * @param needle - String to find. Only work with 1 byte characters.
+ *
+ * @param ab - Buffer to look into
+ *
+ * @param startPosition - Starting index to look from
+ *
+ * @param endPosition - Last index to look from. The needle must fit completely before this.
+ * -1 mean end of the file.
+ *
+ * @returns
+ * The position of the string in the buffer. If not found returns -1
+ *
+ * @public
+ */
+export declare const findLastString: (needle: string, ab: ArrayBuffer, startPosition?: number, endPosition?: number) => number;
+/**
+ * Check if a byte sequence looks like a valid UTF-8 sequence that *does* have wide characters.
+ *
+ * https://en.wikipedia.org/wiki/UTF-8
+ *
+ * @returns
+ * `true` if the byte sequence does contain UTF-8 sequences.
+ * Regular ASCII string will return `false` as they won't contain such sequence.
+ */
+export declare const isUTF8Sequence: (ab: ArrayBuffer) => boolean;

package/lib/arraybuffer.js

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+import { ab2b64 as bitsAb2b64, b642ab as bitsB642ab, getArrayBuffer as bitsGetArrayBuffer, } from "./bits/arraybuffer.js";
+import { getUint8Array, buf82str, str2buf8, buf82hex, hex2buf8, concatenateBuf8List, explodeBuf8List, merge as mergeBuf8, utf82buf8, buf82utf8, buf8Equal, findString as findStringBuf8, findLastString as findLastStringBuf8, concatenatedBuf8ListSize, isUTF8Sequence as isUTF8SequenceBuf8, } from "./uint8array.js";
+import { bufferAb2B64, bufferB642Ab, haveBufferBase64 } from "./utils/buffer.js";
+export const getArrayBuffer = bitsGetArrayBuffer;
+/**
+ * Convert an ArrayBuffer to a raw string.
+ *
+ * @public
+ */
+export const ab2str = (ab) => buf82str(getUint8Array(ab));
+/**
+ * Convert a raw string to an ArrayBuffer.
+ *
+ * @public
+ */
+export const str2ab = (str) => getArrayBuffer(str2buf8(str));
+/**
+ * Convert an ArrayBuffer to an hex string.
+ *
+ * @public
+ */
+export const ab2hex = (ab, usePrefix) => buf82hex(getUint8Array(ab), usePrefix);
+/**
+ * Convert an hex string to an ArrayBuffer.
+ *
+ * @public
+ */
+export const hex2ab = (hex) => getArrayBuffer(hex2buf8(hex));
+/**
+ * Concatenate multiple array buffers into one output.
+ *
+ * The output will have each buffer length put in it so the buffers can be split
+ * afterward using explodeBuffersList(). Simple concatenation is available with merge().
+ *
+ * @public
+ */
+export const concatenateBuffersList = (buffers, addEndMarker = false) => getArrayBuffer(concatenateBuf8List(buffers.map((buffer) => getUint8Array(buffer)), addEndMarker));
+/**
+ * Separate buffers merged with concatenateBuffersList().
+ *
+ * @public
+ */
+export const explodeBuffersList = (mergedBuffers) => explodeBuf8List(getUint8Array(mergedBuffers)).map((buf8) => getArrayBuffer(buf8));
+/** @public */
+export const concatenatedBuffersListSize = (mergedBuffers) => concatenatedBuf8ListSize(getUint8Array(mergedBuffers));
+/**
+ * Merge ArrayBuffers into one.
+ *
+ * @public
+ */
+export const merge = (buffers) => getArrayBuffer(mergeBuf8(buffers.map((buffer) => getUint8Array(buffer))));
+/**
+ * Convert an array buffer to a b64 string.
+ *
+ * @public
+ */
+export const ab2b64 = haveBufferBase64() ? bufferAb2B64 : bitsAb2b64;
+/**
+ * Convert a b64 string to an array buffer.
+ *
+ * @param strict - If enabled, prevent input from having extra data after the B64 string.
+ *
+ * @public
+ */
+export const b642ab = haveBufferBase64() ? bufferB642Ab : bitsB642ab;
+/**
+ * Convert an UTF-8 string into an arraybuffer.
+ *
+ * @public
+ */
+export const utf82ab = (str) => getArrayBuffer(utf82buf8(str));
+/**
+ * Convert back an arraybuffer into an UTF-8 string.
+ *
+ * @public
+ */
+export const ab2utf8 = (ab) => buf82utf8(getUint8Array(ab));
+/**
+ * Compare that the content of two ArrayBuffer is equal.
+ *
+ * @public
+ */
+export const abEqual = (ab1, ab2) => buf8Equal(getUint8Array(ab1), getUint8Array(ab2));
+/**
+ * Find the position of a string in a buffer
+ *
+ * @param needle - String to find. Only work with 1 byte-wide characters.
+ *
+ * @param ab - Buffer to look into
+ *
+ * @param startPosition - Starting index to look from
+ *
+ * @returns
+ * The position of the string in the buffer. If not found returns -1
+ *
+ * @public
+ */
+export const findString = (needle, ab, startPosition = 0) => findStringBuf8(needle, getUint8Array(ab), startPosition);
+/**
+ * Find the position of a string in a buffer from the end
+ *
+ * @param needle - String to find. Only work with 1 byte characters.
+ *
+ * @param ab - Buffer to look into
+ *
+ * @param startPosition - Starting index to look from
+ *
+ * @param endPosition - Last index to look from. The needle must fit completely before this.
+ * -1 mean end of the file.
+ *
+ * @returns
+ * The position of the string in the buffer. If not found returns -1
+ *
+ * @public
+ */
+export const findLastString = (needle, ab, startPosition = 0, endPosition = -1) => findLastStringBuf8(needle, getUint8Array(ab), startPosition, endPosition);
+/**
+ * Check if a byte sequence looks like a valid UTF-8 sequence that *does* have wide characters.
+ *
+ * https://en.wikipedia.org/wiki/UTF-8
+ *
+ * @returns
+ * `true` if the byte sequence does contain UTF-8 sequences.
+ * Regular ASCII string will return `false` as they won't contain such sequence.
+ */
+export const isUTF8Sequence = (ab) => isUTF8SequenceBuf8(getUint8Array(ab));

package/lib/async/asynctrigger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+export type TriggerFunction = () => void | Promise<void>;
+/**
+ * Trigger a function after a certain delay expired when you call trigger().
+ *
+ * @public
+ */
+export default class AsyncTrigger {
+    #private;
+    /**
+     * @param delayMs - Delay before calling the function after the most recent call to trigger()
+     *
+     * @param triggerFunction - Function to call when the delay expires
+     * If it returns a promise, we wait for the promise to resolve before allowing
+     * the trigger to proc again.
+     */
+    constructor(delayMs: number, triggerFunction: TriggerFunction);
+    /**
+     * Trigger the function after a delay.
+     *
+     * This function can be called repeteadly; the delay will restart with each
+     * call.
+     * If the trigger function is running when trigger() is called, it is
+     * automatically rescheduled.
+     *
+     * @public
+     */
+    trigger: () => void;
+    /**
+     * Cancel a pending trigger.
+     * Can safely be called even if no pending trigger exists.
+     *
+     * @public
+     */
+    cancel: () => void;
+}

package/lib/async/asynctrigger.js

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+/**
+ * Trigger a function after a certain delay expired when you call trigger().
+ *
+ * @public
+ */
+export default class AsyncTrigger {
+    #timeoutInstance;
+    #running;
+    #reschedule;
+    #delayMs;
+    #triggerFunction;
+    /**
+     * @param delayMs - Delay before calling the function after the most recent call to trigger()
+     *
+     * @param triggerFunction - Function to call when the delay expires
+     * If it returns a promise, we wait for the promise to resolve before allowing
+     * the trigger to proc again.
+     */
+    constructor(delayMs, triggerFunction) {
+        this.#timeoutInstance = undefined;
+        this.#running = false;
+        this.#reschedule = false;
+        this.#delayMs = delayMs;
+        this.#triggerFunction = triggerFunction;
+    }
+    /**
+     * Trigger the function after a delay.
+     *
+     * This function can be called repeteadly; the delay will restart with each
+     * call.
+     * If the trigger function is running when trigger() is called, it is
+     * automatically rescheduled.
+     *
+     * @public
+     */
+    trigger = () => {
+        if (this.#running) {
+            this.#reschedule = true;
+            return;
+        }
+        if (this.#timeoutInstance)
+            clearTimeout(this.#timeoutInstance);
+        this.#realSchedule();
+    };
+    /**
+     * Cancel a pending trigger.
+     * Can safely be called even if no pending trigger exists.
+     *
+     * @public
+     */
+    cancel = () => {
+        if (this.#running && this.#reschedule)
+            this.#reschedule = false;
+        if (this.#timeoutInstance) {
+            clearTimeout(this.#timeoutInstance);
+            this.#timeoutInstance = undefined;
+        }
+    };
+    #realSchedule = () => {
+        this.#timeoutInstance = setTimeout(this.#doTrigger, this.#delayMs);
+    };
+    /** Only called by setTimeout() */
+    #doTrigger = () => {
+        this.#timeoutInstance = undefined;
+        this.#running = true;
+        const res = this.#triggerFunction();
+        if (res instanceof Promise) {
+            // We're waiting a promise
+            res
+                // eslint-disable-next-line promise/prefer-await-to-then
+                .then(() => {
+                this.#running = false;
+                // eslint-disable-next-line promise/always-return
+                if (this.#reschedule) {
+                    this.#reschedule = false;
+                    this.#realSchedule();
+                }
+            })
+                // eslint-disable-next-line promise/prefer-await-to-then
+                .catch((error) => {
+                // eslint-disable-next-line no-console
+                console.error("An error occurred during an async trigger:", error);
+            });
+            return;
+        }
+        // Not a promise
+        this.#running = false;
+        if (this.#reschedule) {
+            this.#reschedule = false;
+            this.#realSchedule();
+        }
+    };
+}

package/lib/async/deferredpromise.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ */
+/**
+ * Allows returning a promise and resolving it in another scope
+ *
+ * @public
+ */
+export declare class DeferredPromise<ResultType> {
+    #private;
+    /** The actual promise that can be awaited */
+    promise: Promise<ResultType>;
+    constructor();
+    /** Indicate if the promise already resolved or rejected. */
+    get resolved(): boolean;
+    /** Can be called from anywhere; will resolve the promise. */
+    resolve: (value: ResultType | PromiseLike<ResultType>) => void;
+    /** Can be called from anywhere; will reject the promise. */
+    reject: (reason?: unknown) => void;
+}