@keeex/utils 7.0.1

package/web/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/web/array.js

@@ -0,0 +1,34 @@
+/**
+ * @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/web/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/web/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/web/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/web/async/asynctrigger.js

@@ -0,0 +1,106 @@
+/**
+ * @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/web/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;
+}

package/web/async/deferredpromise.js

@@ -0,0 +1,65 @@
+/**
+ * @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.
+ * 
+ */
+/* eslint-disable no-console */
+// Heavily based on https://stackoverflow.com/a/34637436/2059163
+/**
+ * Allows returning a promise and resolving it in another scope
+ *
+ * @public
+ */
+export class DeferredPromise {
+  /** The actual promise that can be awaited */
+  promise;
+  #resolveFunc;
+  #rejectFunc;
+  #resolved = false;
+  constructor() {
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let resolveFunc;
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let rejectFunc;
+    // eslint-disable-next-line promise/avoid-new
+    this.promise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+    if (!resolveFunc || !rejectFunc) throw new Error("Unexpected state");
+    this.#resolveFunc = resolveFunc;
+    this.#rejectFunc = rejectFunc;
+  }
+  /** Indicate if the promise already resolved or rejected. */
+  get resolved() {
+    return this.#resolved;
+  }
+  /** Can be called from anywhere; will resolve the promise. */
+  resolve = value => {
+    if (this.#resolved) {
+      console.warn("Promise resolved multiple time; ignoring");
+      return;
+    }
+    this.#resolved = true;
+    this.#resolveFunc(value);
+  };
+  /** Can be called from anywhere; will reject the promise. */
+  reject = reason => {
+    if (this.#resolved) {
+      console.warn("Promise resolved multiple time; ignoring");
+      return;
+    }
+    this.#resolved = true;
+    this.#rejectFunc(reason);
+  };
+}

package/web/async/keycache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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 { Awaitable } from "../types/types.js";
+/**
+ * Function used to fill a cache entry on a cache miss.
+ *
+ * @param key - The requested key
+ *
+ * @returns
+ * The requested entry, or undefined if the value does not exist.
+ */
+export type CacheGetFunc<ValueType> = (key: string) => Awaitable<ValueType | undefined>;
+/**
+ * Basic key-value cache mechanism.
+ *
+ * Discards old data based on last access.
+ * Cache entries can be fetched asynchronously; multiple fetch on the same value will share the same
+ * promise.
+ *
+ * @public
+ */
+export default class KeyCache<ValueType = string> {
+    #private;
+    /**
+     * Constructor.
+     *
+     * @param maxEntries - Maximum number of entries kept. Once more entries are added, oldest entries
+     * are discarded based on last access time.
+     *
+     * @param getFunc - A function to fetch missing cache entries.
+     * If the function returns undefined, the value is not cached. If the function throws, the error
+     * is kept (and requesting this entry again will return the rejected promise.
+     */
+    constructor(maxEntries?: number, getFunc?: CacheGetFunc<ValueType>);
+    get cache(): Record<string, Promise<ValueType | undefined>>;
+    get keys(): Array<string>;
+    /** Return a cache entry if present. */
+    get: (key: string) => Promise<ValueType | undefined>;
+    /** Manually set a cache entry. */
+    set: (key: string, value: Awaitable<ValueType>) => this;
+    /** Remove a stale entry. */
+    remove: (key: string) => this;
+}