@keeex/utils 7.0.1

package/lib/async/deferredpromise.js

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

package/lib/async/keycache.js

@@ -0,0 +1,103 @@
+/**
+ * @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 { dropPromise } from "../promise.js";
+/**
+ * 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 {
+    #cache = {};
+    #keys = [];
+    #maxEntries;
+    #getFunc;
+    /**
+     * 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 = 1000, getFunc) {
+        this.#maxEntries = maxEntries;
+        this.#getFunc = getFunc;
+    }
+    get cache() {
+        return this.#cache;
+    }
+    get keys() {
+        return this.#keys;
+    }
+    /** Return a cache entry if present. */
+    get = async (key) => {
+        if (key in this.#cache)
+            return this.#cache[key];
+        if (this.#getFunc)
+            return this.#addKey(key, this.#getFunc(key));
+    };
+    /** Manually set a cache entry. */
+    set = (key, value) => {
+        dropPromise(this.#addKey(key, value));
+        return this;
+    };
+    /** Remove a stale entry. */
+    remove = (key) => {
+        this.#removeKey(key);
+        return this;
+    };
+    /** Add a cache entry, purging older ones if needed */
+    #addKey = (key, valuePromise) => {
+        const res = async () => {
+            const value = await valuePromise;
+            if (value === undefined) {
+                this.#removeKey(key);
+                return;
+            }
+            return value;
+        };
+        const promise = res();
+        if (!(key in this.#cache))
+            this.#keys.push(key);
+        this.#cache[key] = promise;
+        this.#trim();
+        return promise;
+    };
+    /** Remove a specific key from the cache */
+    #removeKey = (key) => {
+        if (!(key in this.#cache))
+            return;
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete this.#cache[key];
+        this.#keys.splice(this.#keys.indexOf(key), 1);
+    };
+    /** Remove excess entries */
+    #trim = () => {
+        const entriesToTrim = Math.max(0, this.#keys.length - this.#maxEntries);
+        if (entriesToTrim <= 0)
+            return;
+        const keysToTrim = this.#keys.splice(0, entriesToTrim);
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        for (const keyToTrim of keysToTrim)
+            delete this.#cache[keyToTrim];
+    };
+}

package/lib/async/queues.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Task function definition.
+ *
+ * @param params - is the argument passed to the `runTask()` method
+ * @param queueId - The queue identifier, starting at 0
+ *
+ * @public
+ */
+export type TaskFunc<TaskParams, TaskResult> = (params: TaskParams, queueId: number) => Promise<TaskResult>;
+/**
+ * Customizing the handling of a task
+ *
+ * @public
+ */
+export interface TaskOptions {
+    /** Put the task in front of a queue instead of in the back */
+    priority?: boolean;
+    /**
+     * Force using the specified queue.
+     * This bypass the "max queued items" check.
+     */
+    forceQueueId?: number;
+}
+/**
+ * Run asynchronous tasks in controlled queues.
+ *
+ * The task function is shared among all queues.
+ * Each queue runs one operation at a time.
+ * Queued tasks can be run in parallel, and each will be given it's queue ID to distinguish them.
+ *
+ * For example, if you setup 3 queues and schedule 10 tasks, they might run like this (each queue
+ * running only one task at a time)
+ *
+ * - Queue 1: T0, T2, T5, T3
+ * - Queue 2: T1, T3, T6, T7
+ * - Queue 3: T4, T8, T9
+ *
+ * @public
+ */
+export declare class Queues<TaskParams, TaskResult> {
+    #private;
+    /**
+     * @param maxQueuedItems - Maximum number of tasks pending. This is rounded up so that all queues
+     * have the same maximum.
+     */
+    constructor(task: TaskFunc<TaskParams, TaskResult>, queuesCount: number, maxQueuedItems: number);
+    /**
+     * Run a task.
+     * As specified in the description, only one task per queue runs at a time.
+     *
+     * If the maximum queue length is reached, throws.
+     */
+    runTask: (taskParams: TaskParams, options?: TaskOptions) => Promise<TaskResult>;
+}

package/lib/async/queues.js

@@ -0,0 +1,135 @@
+/**
+ * @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 { dropPromise } from "../promise.js";
+import { DeferredPromise } from "./deferredpromise.js";
+/**
+ * Run asynchronous tasks in controlled queues.
+ *
+ * The task function is shared among all queues.
+ * Each queue runs one operation at a time.
+ * Queued tasks can be run in parallel, and each will be given it's queue ID to distinguish them.
+ *
+ * For example, if you setup 3 queues and schedule 10 tasks, they might run like this (each queue
+ * running only one task at a time)
+ *
+ * - Queue 1: T0, T2, T5, T3
+ * - Queue 2: T1, T3, T6, T7
+ * - Queue 3: T4, T8, T9
+ *
+ * @public
+ */
+export class Queues {
+    /** Function to run a single task */
+    #task;
+    /** Maximum length of each queue */
+    #maxQueueLength;
+    /** Pending tasks */
+    #queues;
+    /** Flag to control wether a queue needs to be started or not */
+    #queueRunning;
+    /**
+     * @param maxQueuedItems - Maximum number of tasks pending. This is rounded up so that all queues
+     * have the same maximum.
+     */
+    constructor(task, queuesCount, maxQueuedItems) {
+        this.#task = task;
+        this.#maxQueueLength = Math.ceil(maxQueuedItems / queuesCount);
+        this.#queues = [];
+        this.#queueRunning = [];
+        for (let i = 0; i < queuesCount; ++i) {
+            this.#queues.push([]);
+            this.#queueRunning[i] = false;
+        }
+    }
+    /**
+     * Run a task.
+     * As specified in the description, only one task per queue runs at a time.
+     *
+     * If the maximum queue length is reached, throws.
+     */
+    runTask = (taskParams, options = {}) => {
+        const taskDef = {
+            deferred: new DeferredPromise(),
+            taskOptions: options,
+            taskParams,
+        };
+        this.#addToQueue(taskDef);
+        return taskDef.deferred.promise;
+    };
+    /** Return the queue to use for this task */
+    #getTargetQueue = (taskDef) => {
+        if (taskDef.taskOptions.forceQueueId !== undefined) {
+            const target = taskDef.taskOptions.forceQueueId;
+            if (target < 0 || target >= this.#queues.length) {
+                throw new Error("Forced queue ID is invalid");
+            }
+            return target;
+        }
+        // Find shortest queue
+        let shortestId = null;
+        let shortestLength = this.#maxQueueLength;
+        for (let i = 0; i < this.#queues.length && shortestLength > 0; ++i) {
+            const queueLength = this.#queues[i].length + (this.#queueRunning[i] ? 1 : 0);
+            if (queueLength < shortestLength) {
+                shortestLength = queueLength;
+                shortestId = i;
+            }
+        }
+        if (shortestId === null) {
+            throw new Error("Max queue length exceeded");
+        }
+        return shortestId;
+    };
+    /** Add a task definition to the currently shortest queue */
+    #addToQueue = (taskDef) => {
+        const targetQueue = this.#getTargetQueue(taskDef);
+        if (taskDef.taskOptions.priority) {
+            this.#queues[targetQueue].splice(0, 0, taskDef);
+        }
+        else {
+            this.#queues[targetQueue].push(taskDef);
+        }
+        if (this.#queues[targetQueue].length === 1)
+            dropPromise(this.#runQueue(targetQueue));
+    };
+    /**
+     * Start running a single queue.
+     * The function will keep going until the queue is empty.
+     * It can safely be called multiple time with the same queueId.
+     */
+    #runQueue = async (queueId) => {
+        if (this.#queueRunning[queueId]) {
+            return;
+        }
+        try {
+            this.#queueRunning[queueId] = true;
+            while (this.#queues[queueId].length > 0) {
+                const taskDef = this.#queues[queueId].splice(0, 1)[0];
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const res = await this.#task(taskDef.taskParams, queueId);
+                    taskDef.deferred.resolve(res);
+                }
+                catch (e) {
+                    taskDef.deferred.reject(e);
+                }
+            }
+        }
+        finally {
+            this.#queueRunning[queueId] = false;
+        }
+    };
+}

package/lib/async/timecache.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 refresh a timed cache */
+export type ProbeFunc<T> = () => Awaitable<T>;
+type HandlerFunc<T> = (error?: Error, value?: T) => void;
+/** Constructor parameters for `TimeCache` */
+interface TimeCacheCtor<T> {
+    /** Function used to refresh the cached value */
+    probeFunc: ProbeFunc<T>;
+    /** Duration of the cached result, in ms */
+    cacheDurationMs: number;
+    /**
+     * Set to true to refresh (call the probe function) automatically, even if the value isn't read.
+     *
+     * When false (the default), the probe function will only be called as a result of querying the
+     * cached value outside of its cache duration.
+     */
+    autoProbe: boolean;
+}
+/**
+ * Remember a value for the specified amount of time, and reprobe it when needed.
+ *
+ * This support automatic probing over time and update callbacks.
+ *
+ * @public
+ */
+export default class TimeCache<T> {
+    #private;
+    constructor(params: TimeCacheCtor<T>);
+    get value(): Promise<T>;
+    get autoProbe(): boolean;
+    set autoProbe(value: boolean);
+    /**
+     * Setup a callback triggered when the value is updated.
+     *
+     * When auto-update is disabled, these handler still get called when the value is manually probed.
+     */
+    onUpdate: (handler: HandlerFunc<T>) => void;
+    /**
+     * Remove a callback previously registered with `onUpdate()`.
+     */
+    offUpdate: (handler: HandlerFunc<T>) => void;
+}
+export {};

package/lib/async/timecache.js

@@ -0,0 +1,118 @@
+/**
+ * @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 { asError } from "../error.js";
+/**
+ * Remember a value for the specified amount of time, and reprobe it when needed.
+ *
+ * This support automatic probing over time and update callbacks.
+ *
+ * @public
+ */
+export default class TimeCache {
+    #probeFunction;
+    #cacheDurationMs;
+    #autoProbe;
+    #loadedPromise;
+    #lastRefreshTime;
+    #nextRefreshTimeout;
+    #updateHandlers = [];
+    constructor(params) {
+        this.#probeFunction = params.probeFunc;
+        this.#cacheDurationMs = params.cacheDurationMs;
+        this.#autoProbe = params.autoProbe;
+        if (this.#autoProbe)
+            this.#probeTime();
+    }
+    get value() {
+        if (!this.#autoProbe)
+            this.#manualRefresh();
+        if (!this.#loadedPromise)
+            throw new Error("Unexpected state");
+        return this.#loadedPromise;
+    }
+    get autoProbe() {
+        return this.#autoProbe;
+    }
+    set autoProbe(value) {
+        if (this.#autoProbe === value)
+            return;
+        this.#autoProbe = value;
+        if (this.#autoProbe) {
+            this.#armAutoProbe();
+        }
+        else if (this.#nextRefreshTimeout) {
+            clearTimeout(this.#nextRefreshTimeout);
+            this.#nextRefreshTimeout = undefined;
+        }
+    }
+    /**
+     * Setup a callback triggered when the value is updated.
+     *
+     * When auto-update is disabled, these handler still get called when the value is manually probed.
+     */
+    onUpdate = (handler) => {
+        this.#updateHandlers.push(handler);
+    };
+    /**
+     * Remove a callback previously registered with `onUpdate()`.
+     */
+    offUpdate = (handler) => {
+        const id = this.#updateHandlers.lastIndexOf(handler);
+        if (id !== -1)
+            this.#updateHandlers.splice(id, 1);
+    };
+    /** Helper to setup #loadedPromise */
+    #callProbeFunction = async () => {
+        try {
+            const res = await this.#probeFunction();
+            this.#callHandler(undefined, res);
+            return res;
+        }
+        catch (e) {
+            this.#callHandler(asError(e));
+            throw e;
+        }
+    };
+    #callHandler = (error, value) => {
+        for (const handler of this.#updateHandlers)
+            handler(error, value);
+    };
+    /** Refresh the value */
+    #probeTime = () => {
+        this.#nextRefreshTimeout = undefined;
+        this.#loadedPromise = this.#callProbeFunction();
+        this.#lastRefreshTime = Date.now();
+        if (this.#autoProbe)
+            this.#armAutoProbe();
+    };
+    /** Setup the auto probe */
+    #armAutoProbe = () => {
+        if (this.#nextRefreshTimeout)
+            clearTimeout(this.#nextRefreshTimeout);
+        const remainingTime = this.#getRemainingTime();
+        this.#nextRefreshTimeout = setTimeout(this.#probeTime, remainingTime);
+    };
+    /** Return the remaining time before the next refresh (minimum 0) */
+    #getRemainingTime = () => {
+        const now = Date.now();
+        const nextRefresh = (this.#lastRefreshTime ?? Date.now()) + this.#cacheDurationMs;
+        return Math.max(0, nextRefresh - now);
+    };
+    #manualRefresh = () => {
+        if (this.#getRemainingTime() === 0 || !this.#loadedPromise)
+            this.#probeTime();
+    };
+}

package/lib/base58.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ * 
+ */
+/** @public */
+export declare const encode: (data: Uint8Array) => string;
+/** @public */
+export declare const decode: (b58: string) => Uint8Array;
+/**
+ * Encode a buf8 with base58.
+ *
+ * The output is padded accordingly to always accomodate a buffer of the full length of the input.
+ *
+ * @public
+ */
+export declare const encodePad: (data: Uint8Array) => string;