@fluidframework/core-utils 2.0.0-dev-rc.1.0.0.224419

package/dist/promiseCache.js

@@ -0,0 +1,148 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromiseCache = void 0;
+/**
+ * Handles garbage collection of expiring cache entries.
+ * Not exported.
+ */
+class GarbageCollector {
+    constructor(expiry, cleanup) {
+        this.expiry = expiry;
+        this.cleanup = cleanup;
+        this.gcTimeouts = new Map();
+    }
+    /**
+     * Schedule GC for the given key, as applicable
+     */
+    schedule(key) {
+        if (this.expiry.policy !== "indefinite") {
+            this.gcTimeouts.set(key, setTimeout(() => {
+                this.cleanup(key);
+                this.cancel(key);
+            }, this.expiry.durationMs));
+        }
+    }
+    /**
+     * Cancel any pending GC for the given key
+     */
+    cancel(key) {
+        const timeout = this.gcTimeouts.get(key);
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
+            this.gcTimeouts.delete(key);
+        }
+    }
+    /**
+     * Update any pending GC for the given key, as applicable
+     */
+    update(key) {
+        // Cancel/reschedule new GC if the policy is sliding
+        if (this.expiry.policy === "sliding") {
+            this.cancel(key);
+            this.schedule(key);
+        }
+    }
+}
+/**
+ * A specialized cache for async work, allowing you to safely cache the promised result of some async work
+ * without fear of running it multiple times or losing track of errors.
+ * @alpha
+ */
+class PromiseCache {
+    /**
+     * Create the PromiseCache with the given options, with the following defaults:
+     *
+     * expiry: indefinite, removeOnError: true for all errors
+     */
+    constructor({ expiry = { policy: "indefinite" }, removeOnError = () => true, } = {}) {
+        this.cache = new Map();
+        this.removeOnError = removeOnError;
+        this.gc = new GarbageCollector(expiry, (key) => this.remove(key));
+    }
+    /**
+     * Check if there's anything cached at the given key
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Get the Promise for the given key, or undefined if it's not found.
+     * Extend expiry if applicable.
+     */
+    get(key) {
+        if (this.has(key)) {
+            this.gc.update(key);
+        }
+        return this.cache.get(key);
+    }
+    /**
+     * Remove the Promise for the given key, returning true if it was found and removed
+     */
+    remove(key) {
+        this.gc.cancel(key);
+        return this.cache.delete(key);
+    }
+    /**
+     * Try to add the result of the given asyncFn, without overwriting an existing cache entry at that key.
+     * Returns a Promise for the added or existing async work being done at that key.
+     * @param key - key name where to store the async work
+     * @param asyncFn - the async work to do and store, if not already in progress under the given key
+     */
+    async addOrGet(key, asyncFn) {
+        // NOTE: Do not await the Promise returned by asyncFn!
+        // Let the caller do so once we return or after a subsequent call to get
+        let promise = this.get(key);
+        if (promise === undefined) {
+            // Wrap in an async lambda in case asyncFn disabled @typescript-eslint/promise-function-async
+            const safeAsyncFn = async () => asyncFn();
+            // Start the async work and put the Promise in the cache
+            promise = safeAsyncFn();
+            this.cache.set(key, promise);
+            // If asyncFn throws, we may remove the Promise from the cache
+            promise.catch((error) => {
+                if (this.removeOnError(error)) {
+                    this.remove(key);
+                }
+            });
+            this.gc.schedule(key);
+        }
+        return promise;
+    }
+    /**
+     * Try to add the result of the given asyncFn, without overwriting an existing cache entry at that key.
+     * Returns false if the cache already contained an entry at that key, and true otherwise.
+     * @param key - key name where to store the async work
+     * @param asyncFn - the async work to do and store, if not already in progress under the given key
+     */
+    add(key, asyncFn) {
+        const alreadyPresent = this.has(key);
+        // We are blindly adding the Promise to the cache here, which introduces a Promise in this scope.
+        // Swallow Promise rejections here, since whoever gets this out of the cache to use it will await/catch.
+        this.addOrGet(key, asyncFn).catch(() => { });
+        return !alreadyPresent;
+    }
+    /**
+     * Try to add the given value, without overwriting an existing cache entry at that key.
+     * Returns a Promise for the added or existing async work being done at that key.
+     * @param key - key name where to store the async work
+     * @param value - value to store
+     */
+    async addValueOrGet(key, value) {
+        return this.addOrGet(key, async () => value);
+    }
+    /**
+     * Try to add the given value, without overwriting an existing cache entry at that key.
+     * Returns false if the cache already contained an entry at that key, and true otherwise.
+     * @param key - key name where to store the value
+     * @param value - value to store
+     */
+    addValue(key, value) {
+        return this.add(key, async () => value);
+    }
+}
+exports.PromiseCache = PromiseCache;
+//# sourceMappingURL=promiseCache.js.map

package/dist/promiseCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promiseCache.js","sourceRoot":"","sources":["../src/promiseCache.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Three supported expiry policies:\n * - indefinite: entries don't expire and must be explicitly removed\n * - absolute: entries expire after the given duration in MS, even if accessed multiple times in the mean time\n * - sliding: entries expire after the given duration in MS of inactivity (i.e. get resets the clock)\n * @alpha\n */\nexport type PromiseCacheExpiry =\n\t| {\n\t\t\tpolicy: \"indefinite\";\n\t  }\n\t| {\n\t\t\tpolicy: \"absolute\" | \"sliding\";\n\t\t\tdurationMs: number;\n\t  };\n\n/**\n * Options for configuring the {@link PromiseCache}\n * @alpha\n */\nexport interface PromiseCacheOptions {\n\t/**\n\t * Common expiration policy for all items added to this cache\n\t */\n\texpiry?: PromiseCacheExpiry;\n\t/**\n\t * If the stored Promise is rejected with a particular error, should the given key be removed?\n\t */\n\t// TODO: Use `unknown` instead (API breaking)\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tremoveOnError?: (error: any) => boolean;\n}\n\n/**\n * Handles garbage collection of expiring cache entries.\n * Not exported.\n */\nclass GarbageCollector<TKey> {\n\tprivate readonly gcTimeouts = new Map<TKey, ReturnType<typeof setTimeout>>();\n\n\tpublic constructor(\n\t\tprivate readonly expiry: PromiseCacheExpiry,\n\t\tprivate readonly cleanup: (key: TKey) => void,\n\t) {}\n\n\t/**\n\t * Schedule GC for the given key, as applicable\n\t */\n\tpublic schedule(key: TKey): void {\n\t\tif (this.expiry.policy !== \"indefinite\") {\n\t\t\tthis.gcTimeouts.set(\n\t\t\t\tkey,\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tthis.cleanup(key);\n\t\t\t\t\tthis.cancel(key);\n\t\t\t\t}, this.expiry.durationMs),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Cancel any pending GC for the given key\n\t */\n\tpublic cancel(key: TKey): void {\n\t\tconst timeout = this.gcTimeouts.get(key);\n\t\tif (timeout !== undefined) {\n\t\t\tclearTimeout(timeout);\n\t\t\tthis.gcTimeouts.delete(key);\n\t\t}\n\t}\n\n\t/**\n\t * Update any pending GC for the given key, as applicable\n\t */\n\tpublic update(key: TKey): void {\n\t\t// Cancel/reschedule new GC if the policy is sliding\n\t\tif (this.expiry.policy === \"sliding\") {\n\t\t\tthis.cancel(key);\n\t\t\tthis.schedule(key);\n\t\t}\n\t}\n}\n\n/**\n * A specialized cache for async work, allowing you to safely cache the promised result of some async work\n * without fear of running it multiple times or losing track of errors.\n * @alpha\n */\nexport class PromiseCache<TKey, TResult> {\n\tprivate readonly cache = new Map<TKey, Promise<TResult>>();\n\tprivate readonly gc: GarbageCollector<TKey>;\n\n\tprivate readonly removeOnError: (error: unknown) => boolean;\n\n\t/**\n\t * Create the PromiseCache with the given options, with the following defaults:\n\t *\n\t * expiry: indefinite, removeOnError: true for all errors\n\t */\n\tpublic constructor({\n\t\texpiry = { policy: \"indefinite\" },\n\t\tremoveOnError = (): boolean => true,\n\t}: PromiseCacheOptions = {}) {\n\t\tthis.removeOnError = removeOnError;\n\t\tthis.gc = new GarbageCollector<TKey>(expiry, (key) => this.remove(key));\n\t}\n\n\t/**\n\t * Check if there's anything cached at the given key\n\t */\n\tpublic has(key: TKey): boolean {\n\t\treturn this.cache.has(key);\n\t}\n\n\t/**\n\t * Get the Promise for the given key, or undefined if it's not found.\n\t * Extend expiry if applicable.\n\t */\n\tpublic get(key: TKey): Promise<TResult> | undefined {\n\t\tif (this.has(key)) {\n\t\t\tthis.gc.update(key);\n\t\t}\n\t\treturn this.cache.get(key);\n\t}\n\n\t/**\n\t * Remove the Promise for the given key, returning true if it was found and removed\n\t */\n\tpublic remove(key: TKey): boolean {\n\t\tthis.gc.cancel(key);\n\t\treturn this.cache.delete(key);\n\t}\n\n\t/**\n\t * Try to add the result of the given asyncFn, without overwriting an existing cache entry at that key.\n\t * Returns a Promise for the added or existing async work being done at that key.\n\t * @param key - key name where to store the async work\n\t * @param asyncFn - the async work to do and store, if not already in progress under the given key\n\t */\n\tpublic async addOrGet(key: TKey, asyncFn: () => Promise<TResult>): Promise<TResult> {\n\t\t// NOTE: Do not await the Promise returned by asyncFn!\n\t\t// Let the caller do so once we return or after a subsequent call to get\n\t\tlet promise = this.get(key);\n\t\tif (promise === undefined) {\n\t\t\t// Wrap in an async lambda in case asyncFn disabled @typescript-eslint/promise-function-async\n\t\t\tconst safeAsyncFn = async (): Promise<TResult> => asyncFn();\n\n\t\t\t// Start the async work and put the Promise in the cache\n\t\t\tpromise = safeAsyncFn();\n\t\t\tthis.cache.set(key, promise);\n\n\t\t\t// If asyncFn throws, we may remove the Promise from the cache\n\t\t\tpromise.catch((error) => {\n\t\t\t\tif (this.removeOnError(error)) {\n\t\t\t\t\tthis.remove(key);\n\t\t\t\t}\n\t\t\t});\n\n\t\t\tthis.gc.schedule(key);\n\t\t}\n\n\t\treturn promise;\n\t}\n\n\t/**\n\t * Try to add the result of the given asyncFn, without overwriting an existing cache entry at that key.\n\t * Returns false if the cache already contained an entry at that key, and true otherwise.\n\t * @param key - key name where to store the async work\n\t * @param asyncFn - the async work to do and store, if not already in progress under the given key\n\t */\n\tpublic add(key: TKey, asyncFn: () => Promise<TResult>): boolean {\n\t\tconst alreadyPresent = this.has(key);\n\n\t\t// We are blindly adding the Promise to the cache here, which introduces a Promise in this scope.\n\t\t// Swallow Promise rejections here, since whoever gets this out of the cache to use it will await/catch.\n\t\tthis.addOrGet(key, asyncFn).catch(() => {});\n\n\t\treturn !alreadyPresent;\n\t}\n\n\t/**\n\t * Try to add the given value, without overwriting an existing cache entry at that key.\n\t * Returns a Promise for the added or existing async work being done at that key.\n\t * @param key - key name where to store the async work\n\t * @param value - value to store\n\t */\n\tpublic async addValueOrGet(key: TKey, value: TResult): Promise<TResult> {\n\t\treturn this.addOrGet(key, async () => value);\n\t}\n\n\t/**\n\t * Try to add the given value, without overwriting an existing cache entry at that key.\n\t * Returns false if the cache already contained an entry at that key, and true otherwise.\n\t * @param key - key name where to store the value\n\t * @param value - value to store\n\t */\n\tpublic addValue(key: TKey, value: TResult): boolean {\n\t\treturn this.add(key, async () => value);\n\t}\n}\n"]}

package/dist/promises.d.ts

@@ -0,0 +1,38 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * A deferred creates a promise and the ability to resolve or reject it
+ * @alpha
+ */
+export declare class Deferred<T> {
+    private readonly p;
+    private res;
+    private rej;
+    private completed;
+    constructor();
+    /**
+     * Returns whether the underlying promise has been completed
+     */
+    get isCompleted(): boolean;
+    /**
+     * Retrieves the underlying promise for the deferred
+     *
+     * @returns the underlying promise
+     */
+    get promise(): Promise<T>;
+    /**
+     * Resolves the promise
+     *
+     * @param value - the value to resolve the promise with
+     */
+    resolve(value: T | PromiseLike<T>): void;
+    /**
+     * Rejects the promise
+     *
+     * @param value - the value to reject the promise with
+     */
+    reject(error: any): void;
+}
+//# sourceMappingURL=promises.d.ts.map

package/dist/promises.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promises.d.ts","sourceRoot":"","sources":["../src/promises.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAa;IAC/B,OAAO,CAAC,GAAG,CAAoD;IAC/D,OAAO,CAAC,GAAG,CAA2C;IACtD,OAAO,CAAC,SAAS,CAAkB;;IAQnC;;OAEG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;OAIG;IACH,IAAW,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,CAE/B;IAED;;;;OAIG;IACI,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI;IAO/C;;;;OAIG;IAGI,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;CAM/B"}

package/dist/promises.js

@@ -0,0 +1,60 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deferred = void 0;
+/**
+ * A deferred creates a promise and the ability to resolve or reject it
+ * @alpha
+ */
+class Deferred {
+    constructor() {
+        this.completed = false;
+        this.p = new Promise((resolve, reject) => {
+            this.res = resolve;
+            this.rej = reject;
+        });
+    }
+    /**
+     * Returns whether the underlying promise has been completed
+     */
+    get isCompleted() {
+        return this.completed;
+    }
+    /**
+     * Retrieves the underlying promise for the deferred
+     *
+     * @returns the underlying promise
+     */
+    get promise() {
+        return this.p;
+    }
+    /**
+     * Resolves the promise
+     *
+     * @param value - the value to resolve the promise with
+     */
+    resolve(value) {
+        if (this.res !== undefined) {
+            this.completed = true;
+            this.res(value);
+        }
+    }
+    /**
+     * Rejects the promise
+     *
+     * @param value - the value to reject the promise with
+     */
+    // TODO: Use `unknown` instead (API breaking)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
+    reject(error) {
+        if (this.rej !== undefined) {
+            this.completed = true;
+            this.rej(error);
+        }
+    }
+}
+exports.Deferred = Deferred;
+//# sourceMappingURL=promises.js.map

package/dist/promises.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promises.js","sourceRoot":"","sources":["../src/promises.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;GAGG;AACH,MAAa,QAAQ;IAMpB;QAFQ,cAAS,GAAY,KAAK,CAAC;QAGlC,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC;YACnB,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC;QACnB,CAAC,CAAC,CAAC;IACJ,CAAC;IACD;;OAEG;IACH,IAAW,WAAW;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,IAAW,OAAO;QACjB,OAAO,IAAI,CAAC,CAAC,CAAC;IACf,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,KAAyB;QACvC,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE;YAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;SAChB;IACF,CAAC;IAED;;;;OAIG;IACH,6CAA6C;IAC7C,iHAAiH;IAC1G,MAAM,CAAC,KAAU;QACvB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE;YAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;SAChB;IACF,CAAC;CACD;AArDD,4BAqDC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A deferred creates a promise and the ability to resolve or reject it\n * @alpha\n */\nexport class Deferred<T> {\n\tprivate readonly p: Promise<T>;\n\tprivate res: ((value: T | PromiseLike<T>) => void) | undefined;\n\tprivate rej: ((reason?: unknown) => void) | undefined;\n\tprivate completed: boolean = false;\n\n\tpublic constructor() {\n\t\tthis.p = new Promise<T>((resolve, reject) => {\n\t\t\tthis.res = resolve;\n\t\t\tthis.rej = reject;\n\t\t});\n\t}\n\t/**\n\t * Returns whether the underlying promise has been completed\n\t */\n\tpublic get isCompleted(): boolean {\n\t\treturn this.completed;\n\t}\n\n\t/**\n\t * Retrieves the underlying promise for the deferred\n\t *\n\t * @returns the underlying promise\n\t */\n\tpublic get promise(): Promise<T> {\n\t\treturn this.p;\n\t}\n\n\t/**\n\t * Resolves the promise\n\t *\n\t * @param value - the value to resolve the promise with\n\t */\n\tpublic resolve(value: T | PromiseLike<T>): void {\n\t\tif (this.res !== undefined) {\n\t\t\tthis.completed = true;\n\t\t\tthis.res(value);\n\t\t}\n\t}\n\n\t/**\n\t * Rejects the promise\n\t *\n\t * @param value - the value to reject the promise with\n\t */\n\t// TODO: Use `unknown` instead (API breaking)\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types\n\tpublic reject(error: any): void {\n\t\tif (this.rej !== undefined) {\n\t\t\tthis.completed = true;\n\t\t\tthis.rej(error);\n\t\t}\n\t}\n}\n"]}

package/dist/timer.d.ts

@@ -0,0 +1,115 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * @internal
+ */
+export interface ITimer {
+    /**
+     * True if timer is currently running
+     */
+    readonly hasTimer: boolean;
+    /**
+     * Starts the timer
+     */
+    start(): void;
+    /**
+     * Cancels the timer if already running
+     */
+    clear(): void;
+}
+/**
+ * Sets timeouts like the setTimeout function allowing timeouts to exceed the setTimeout's max timeout limit.
+ * Timeouts may not be exactly accurate due to browser implementations and the OS.
+ * https://stackoverflow.com/questions/21097421/what-is-the-reason-javascript-settimeout-is-so-inaccurate
+ * @param timeoutFn - Executed when the timeout expires
+ * @param timeoutMs - Duration of the timeout in milliseconds
+ * @param setTimeoutIdFn - Executed to update the timeout if multiple timeouts are required when
+ * timeoutMs greater than maxTimeout
+ * @returns The initial timeout
+ * @internal
+ */
+export declare function setLongTimeout(timeoutFn: () => void, timeoutMs: number, setTimeoutIdFn?: (timeoutId: ReturnType<typeof setTimeout>) => void): ReturnType<typeof setTimeout>;
+/**
+ * This class is a thin wrapper over setTimeout and clearTimeout which
+ * makes it simpler to keep track of recurring timeouts with the same
+ * or similar handlers and timeouts. This class supports long timeouts
+ * or timeouts exceeding (2^31)-1 ms or approximately 24.8 days.
+ * @internal
+ */
+export declare class Timer implements ITimer {
+    private readonly defaultTimeout;
+    private readonly defaultHandler;
+    private readonly getCurrentTick;
+    /**
+     * Returns true if the timer is running.
+     */
+    get hasTimer(): boolean;
+    private runningState;
+    constructor(defaultTimeout: number, defaultHandler: () => void, getCurrentTick?: () => number);
+    /**
+     * Calls setTimeout and tracks the resulting timeout.
+     * @param ms - overrides default timeout in ms
+     * @param handler - overrides default handler
+     */
+    start(ms?: number, handler?: () => void): void;
+    /**
+     * Calls clearTimeout on the underlying timeout if running.
+     */
+    clear(): void;
+    /**
+     * Restarts the timer with the new handler and duration.
+     * If a new handler is passed, the original handler may
+     * never execute.
+     * This is a potentially more efficient way to clear and start
+     * a new timer.
+     * @param ms - overrides previous or default timeout in ms
+     * @param handler - overrides previous or default handler
+     */
+    restart(ms?: number, handler?: () => void): void;
+    private startCore;
+    private handler;
+    private calculateRemainingTime;
+}
+/**
+ * @internal
+ */
+export interface IPromiseTimerResult {
+    timerResult: "timeout" | "cancel";
+}
+/**
+ * Timer which offers a promise that fulfills when the timer
+ * completes.
+ * @internal
+ */
+export interface IPromiseTimer extends ITimer {
+    /**
+     * Starts the timer and returns a promise that
+     * resolves when the timer times out or is canceled.
+     */
+    start(): Promise<IPromiseTimerResult>;
+}
+/**
+ * This class is a wrapper over setTimeout and clearTimeout which
+ * makes it simpler to keep track of recurring timeouts with the
+ * same handlers and timeouts, while also providing a promise that
+ * resolves when it times out.
+ * @internal
+ */
+export declare class PromiseTimer implements IPromiseTimer {
+    private deferred?;
+    private readonly timer;
+    /**
+     * {@inheritDoc Timer.hasTimer}
+     */
+    get hasTimer(): boolean;
+    constructor(defaultTimeout: number, defaultHandler: () => void);
+    /**
+     * {@inheritDoc IPromiseTimer.start}
+     */
+    start(ms?: number, handler?: () => void): Promise<IPromiseTimerResult>;
+    clear(): void;
+    protected wrapHandler(handler: () => void): void;
+}
+//# sourceMappingURL=timer.d.ts.map

package/dist/timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.d.ts","sourceRoot":"","sources":["../src/timer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACd;AAsCD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC7B,SAAS,EAAE,MAAM,IAAI,EACrB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,GACjE,UAAU,CAAC,OAAO,UAAU,CAAC,CAe/B;AAED;;;;;;GAMG;AACH,qBAAa,KAAM,YAAW,MAAM;IAWlC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAZhC;;OAEG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,OAAO,CAAC,YAAY,CAAiC;gBAGnC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,IAAI,EAC1B,cAAc,GAAE,MAAM,MAAiC;IAGzE;;;;OAIG;IACI,KAAK,CACX,EAAE,GAAE,MAA4B,EAChC,OAAO,GAAE,MAAM,IAA0B,GACvC,IAAI;IAIP;;OAEG;IACI,KAAK,IAAI,IAAI;IAQpB;;;;;;;;OAQG;IACI,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IA+BvD,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,sBAAsB;CAI9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC5C;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtC;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,aAAa;IACjD,OAAO,CAAC,QAAQ,CAAC,CAAgC;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAE9B;;OAEG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;gBAEkB,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,IAAI;IAIrE;;OAEG;IACU,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAO5E,KAAK,IAAI,IAAI;IAQpB,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;CAMhD"}

package/dist/timer.js

@@ -0,0 +1,189 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromiseTimer = exports.Timer = exports.setLongTimeout = void 0;
+const assert_1 = require("./assert");
+const promises_1 = require("./promises");
+const maxSetTimeoutMs = 0x7fffffff; // setTimeout limit is MAX_INT32=(2^31-1).
+/**
+ * Sets timeouts like the setTimeout function allowing timeouts to exceed the setTimeout's max timeout limit.
+ * Timeouts may not be exactly accurate due to browser implementations and the OS.
+ * https://stackoverflow.com/questions/21097421/what-is-the-reason-javascript-settimeout-is-so-inaccurate
+ * @param timeoutFn - Executed when the timeout expires
+ * @param timeoutMs - Duration of the timeout in milliseconds
+ * @param setTimeoutIdFn - Executed to update the timeout if multiple timeouts are required when
+ * timeoutMs greater than maxTimeout
+ * @returns The initial timeout
+ * @internal
+ */
+function setLongTimeout(timeoutFn, timeoutMs, setTimeoutIdFn) {
+    // The setTimeout max is 24.8 days before looping occurs.
+    let timeoutId;
+    if (timeoutMs > maxSetTimeoutMs) {
+        const newTimeoutMs = timeoutMs - maxSetTimeoutMs;
+        timeoutId = setTimeout(() => setLongTimeout(timeoutFn, newTimeoutMs, setTimeoutIdFn), maxSetTimeoutMs);
+    }
+    else {
+        timeoutId = setTimeout(() => timeoutFn(), Math.max(timeoutMs, 0));
+    }
+    setTimeoutIdFn?.(timeoutId);
+    return timeoutId;
+}
+exports.setLongTimeout = setLongTimeout;
+/**
+ * This class is a thin wrapper over setTimeout and clearTimeout which
+ * makes it simpler to keep track of recurring timeouts with the same
+ * or similar handlers and timeouts. This class supports long timeouts
+ * or timeouts exceeding (2^31)-1 ms or approximately 24.8 days.
+ * @internal
+ */
+class Timer {
+    /**
+     * Returns true if the timer is running.
+     */
+    get hasTimer() {
+        return !!this.runningState;
+    }
+    constructor(defaultTimeout, defaultHandler, getCurrentTick = () => Date.now()) {
+        this.defaultTimeout = defaultTimeout;
+        this.defaultHandler = defaultHandler;
+        this.getCurrentTick = getCurrentTick;
+    }
+    /**
+     * Calls setTimeout and tracks the resulting timeout.
+     * @param ms - overrides default timeout in ms
+     * @param handler - overrides default handler
+     */
+    start(ms = this.defaultTimeout, handler = this.defaultHandler) {
+        this.startCore(ms, handler, ms);
+    }
+    /**
+     * Calls clearTimeout on the underlying timeout if running.
+     */
+    clear() {
+        if (!this.runningState) {
+            return;
+        }
+        clearTimeout(this.runningState.timeout);
+        this.runningState = undefined;
+    }
+    /**
+     * Restarts the timer with the new handler and duration.
+     * If a new handler is passed, the original handler may
+     * never execute.
+     * This is a potentially more efficient way to clear and start
+     * a new timer.
+     * @param ms - overrides previous or default timeout in ms
+     * @param handler - overrides previous or default handler
+     */
+    restart(ms, handler) {
+        if (this.runningState) {
+            const duration = ms ?? this.runningState.intendedDuration;
+            const handlerToUse = handler ?? this.runningState.restart?.handler ?? this.runningState.handler;
+            const remainingTime = this.calculateRemainingTime(this.runningState);
+            if (duration < remainingTime) {
+                // If remaining time exceeds restart duration, do a hard restart.
+                // The existing timeout time is too long.
+                this.start(duration, handlerToUse);
+            }
+            else if (duration === remainingTime) {
+                // The existing timeout time is perfect, just update handler and data.
+                this.runningState.handler = handlerToUse;
+                this.runningState.restart = undefined;
+                this.runningState.intendedDuration = duration;
+            }
+            else {
+                // If restart duration exceeds remaining time, set restart info.
+                // Existing timeout will start a new timeout for remaining time.
+                this.runningState.restart = {
+                    startTick: this.getCurrentTick(),
+                    duration,
+                    handler: handlerToUse,
+                };
+            }
+        }
+        else {
+            // If restart is called first, it behaves as a call to start
+            this.start(ms, handler);
+        }
+    }
+    startCore(duration, handler, intendedDuration) {
+        this.clear();
+        this.runningState = {
+            startTick: this.getCurrentTick(),
+            duration,
+            intendedDuration,
+            handler,
+            timeout: setLongTimeout(() => this.handler(), duration, (timer) => {
+                if (this.runningState !== undefined) {
+                    this.runningState.timeout = timer;
+                }
+            }),
+        };
+    }
+    handler() {
+        (0, assert_1.assert)(!!this.runningState, 0x764 /* Running timer missing handler */);
+        const restart = this.runningState.restart;
+        if (restart === undefined) {
+            // Run clear first, in case the handler decides to start again
+            const handler = this.runningState.handler;
+            this.clear();
+            handler();
+        }
+        else {
+            // Restart with remaining time
+            const remainingTime = this.calculateRemainingTime(restart);
+            this.startCore(remainingTime, () => restart.handler(), restart.duration);
+        }
+    }
+    calculateRemainingTime(runningTimeout) {
+        const elapsedTime = this.getCurrentTick() - runningTimeout.startTick;
+        return runningTimeout.duration - elapsedTime;
+    }
+}
+exports.Timer = Timer;
+/**
+ * This class is a wrapper over setTimeout and clearTimeout which
+ * makes it simpler to keep track of recurring timeouts with the
+ * same handlers and timeouts, while also providing a promise that
+ * resolves when it times out.
+ * @internal
+ */
+class PromiseTimer {
+    /**
+     * {@inheritDoc Timer.hasTimer}
+     */
+    get hasTimer() {
+        return this.timer.hasTimer;
+    }
+    constructor(defaultTimeout, defaultHandler) {
+        this.timer = new Timer(defaultTimeout, () => this.wrapHandler(defaultHandler));
+    }
+    /**
+     * {@inheritDoc IPromiseTimer.start}
+     */
+    async start(ms, handler) {
+        this.clear();
+        this.deferred = new promises_1.Deferred();
+        this.timer.start(ms, handler ? () => this.wrapHandler(handler) : undefined);
+        return this.deferred.promise;
+    }
+    clear() {
+        this.timer.clear();
+        if (this.deferred) {
+            this.deferred.resolve({ timerResult: "cancel" });
+            this.deferred = undefined;
+        }
+    }
+    wrapHandler(handler) {
+        handler();
+        (0, assert_1.assert)(!!this.deferred, 0x765 /* Handler executed without deferred */);
+        this.deferred.resolve({ timerResult: "timeout" });
+        this.deferred = undefined;
+    }
+}
+exports.PromiseTimer = PromiseTimer;
+//# sourceMappingURL=timer.js.map

package/dist/timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.js","sourceRoot":"","sources":["../src/timer.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"./assert\";\nimport { Deferred } from \"./promises\";\n\n/**\n * @internal\n */\nexport interface ITimer {\n\t/**\n\t * True if timer is currently running\n\t */\n\treadonly hasTimer: boolean;\n\n\t/**\n\t * Starts the timer\n\t */\n\tstart(): void;\n\n\t/**\n\t * Cancels the timer if already running\n\t */\n\tclear(): void;\n}\n\ninterface ITimeout {\n\t/**\n\t * Tick that timeout was started.\n\t */\n\tstartTick: number;\n\n\t/**\n\t * Timeout duration in ms.\n\t */\n\tduration: number;\n\n\t/**\n\t * Handler to execute when timeout ends.\n\t */\n\thandler: () => void;\n}\n\ninterface IRunningTimerState extends ITimeout {\n\t/**\n\t * JavaScript Timeout object.\n\t */\n\ttimeout: ReturnType<typeof setTimeout>;\n\n\t/**\n\t * Intended duration in ms.\n\t */\n\tintendedDuration: number;\n\n\t/**\n\t * Intended restart timeout.\n\t */\n\trestart?: ITimeout;\n}\n\nconst maxSetTimeoutMs = 0x7fffffff; // setTimeout limit is MAX_INT32=(2^31-1).\n\n/**\n * Sets timeouts like the setTimeout function allowing timeouts to exceed the setTimeout's max timeout limit.\n * Timeouts may not be exactly accurate due to browser implementations and the OS.\n * https://stackoverflow.com/questions/21097421/what-is-the-reason-javascript-settimeout-is-so-inaccurate\n * @param timeoutFn - Executed when the timeout expires\n * @param timeoutMs - Duration of the timeout in milliseconds\n * @param setTimeoutIdFn - Executed to update the timeout if multiple timeouts are required when\n * timeoutMs greater than maxTimeout\n * @returns The initial timeout\n * @internal\n */\nexport function setLongTimeout(\n\ttimeoutFn: () => void,\n\ttimeoutMs: number,\n\tsetTimeoutIdFn?: (timeoutId: ReturnType<typeof setTimeout>) => void,\n): ReturnType<typeof setTimeout> {\n\t// The setTimeout max is 24.8 days before looping occurs.\n\tlet timeoutId: ReturnType<typeof setTimeout>;\n\tif (timeoutMs > maxSetTimeoutMs) {\n\t\tconst newTimeoutMs = timeoutMs - maxSetTimeoutMs;\n\t\ttimeoutId = setTimeout(\n\t\t\t() => setLongTimeout(timeoutFn, newTimeoutMs, setTimeoutIdFn),\n\t\t\tmaxSetTimeoutMs,\n\t\t);\n\t} else {\n\t\ttimeoutId = setTimeout(() => timeoutFn(), Math.max(timeoutMs, 0));\n\t}\n\n\tsetTimeoutIdFn?.(timeoutId);\n\treturn timeoutId;\n}\n\n/**\n * This class is a thin wrapper over setTimeout and clearTimeout which\n * makes it simpler to keep track of recurring timeouts with the same\n * or similar handlers and timeouts. This class supports long timeouts\n * or timeouts exceeding (2^31)-1 ms or approximately 24.8 days.\n * @internal\n */\nexport class Timer implements ITimer {\n\t/**\n\t * Returns true if the timer is running.\n\t */\n\tpublic get hasTimer(): boolean {\n\t\treturn !!this.runningState;\n\t}\n\n\tprivate runningState: IRunningTimerState | undefined;\n\n\tpublic constructor(\n\t\tprivate readonly defaultTimeout: number,\n\t\tprivate readonly defaultHandler: () => void,\n\t\tprivate readonly getCurrentTick: () => number = (): number => Date.now(),\n\t) {}\n\n\t/**\n\t * Calls setTimeout and tracks the resulting timeout.\n\t * @param ms - overrides default timeout in ms\n\t * @param handler - overrides default handler\n\t */\n\tpublic start(\n\t\tms: number = this.defaultTimeout,\n\t\thandler: () => void = this.defaultHandler,\n\t): void {\n\t\tthis.startCore(ms, handler, ms);\n\t}\n\n\t/**\n\t * Calls clearTimeout on the underlying timeout if running.\n\t */\n\tpublic clear(): void {\n\t\tif (!this.runningState) {\n\t\t\treturn;\n\t\t}\n\t\tclearTimeout(this.runningState.timeout);\n\t\tthis.runningState = undefined;\n\t}\n\n\t/**\n\t * Restarts the timer with the new handler and duration.\n\t * If a new handler is passed, the original handler may\n\t * never execute.\n\t * This is a potentially more efficient way to clear and start\n\t * a new timer.\n\t * @param ms - overrides previous or default timeout in ms\n\t * @param handler - overrides previous or default handler\n\t */\n\tpublic restart(ms?: number, handler?: () => void): void {\n\t\tif (this.runningState) {\n\t\t\tconst duration = ms ?? this.runningState.intendedDuration;\n\t\t\tconst handlerToUse =\n\t\t\t\thandler ?? this.runningState.restart?.handler ?? this.runningState.handler;\n\t\t\tconst remainingTime = this.calculateRemainingTime(this.runningState);\n\n\t\t\tif (duration < remainingTime) {\n\t\t\t\t// If remaining time exceeds restart duration, do a hard restart.\n\t\t\t\t// The existing timeout time is too long.\n\t\t\t\tthis.start(duration, handlerToUse);\n\t\t\t} else if (duration === remainingTime) {\n\t\t\t\t// The existing timeout time is perfect, just update handler and data.\n\t\t\t\tthis.runningState.handler = handlerToUse;\n\t\t\t\tthis.runningState.restart = undefined;\n\t\t\t\tthis.runningState.intendedDuration = duration;\n\t\t\t} else {\n\t\t\t\t// If restart duration exceeds remaining time, set restart info.\n\t\t\t\t// Existing timeout will start a new timeout for remaining time.\n\t\t\t\tthis.runningState.restart = {\n\t\t\t\t\tstartTick: this.getCurrentTick(),\n\t\t\t\t\tduration,\n\t\t\t\t\thandler: handlerToUse,\n\t\t\t\t};\n\t\t\t}\n\t\t} else {\n\t\t\t// If restart is called first, it behaves as a call to start\n\t\t\tthis.start(ms, handler);\n\t\t}\n\t}\n\n\tprivate startCore(duration: number, handler: () => void, intendedDuration: number): void {\n\t\tthis.clear();\n\t\tthis.runningState = {\n\t\t\tstartTick: this.getCurrentTick(),\n\t\t\tduration,\n\t\t\tintendedDuration,\n\t\t\thandler,\n\t\t\ttimeout: setLongTimeout(\n\t\t\t\t() => this.handler(),\n\t\t\t\tduration,\n\t\t\t\t(timer: number) => {\n\t\t\t\t\tif (this.runningState !== undefined) {\n\t\t\t\t\t\tthis.runningState.timeout = timer;\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t),\n\t\t};\n\t}\n\n\tprivate handler(): void {\n\t\tassert(!!this.runningState, 0x764 /* Running timer missing handler */);\n\t\tconst restart = this.runningState.restart;\n\t\tif (restart === undefined) {\n\t\t\t// Run clear first, in case the handler decides to start again\n\t\t\tconst handler = this.runningState.handler;\n\t\t\tthis.clear();\n\t\t\thandler();\n\t\t} else {\n\t\t\t// Restart with remaining time\n\t\t\tconst remainingTime = this.calculateRemainingTime(restart);\n\t\t\tthis.startCore(remainingTime, () => restart.handler(), restart.duration);\n\t\t}\n\t}\n\n\tprivate calculateRemainingTime(runningTimeout: ITimeout): number {\n\t\tconst elapsedTime = this.getCurrentTick() - runningTimeout.startTick;\n\t\treturn runningTimeout.duration - elapsedTime;\n\t}\n}\n\n/**\n * @internal\n */\nexport interface IPromiseTimerResult {\n\ttimerResult: \"timeout\" | \"cancel\";\n}\n\n/**\n * Timer which offers a promise that fulfills when the timer\n * completes.\n * @internal\n */\nexport interface IPromiseTimer extends ITimer {\n\t/**\n\t * Starts the timer and returns a promise that\n\t * resolves when the timer times out or is canceled.\n\t */\n\tstart(): Promise<IPromiseTimerResult>;\n}\n\n/**\n * This class is a wrapper over setTimeout and clearTimeout which\n * makes it simpler to keep track of recurring timeouts with the\n * same handlers and timeouts, while also providing a promise that\n * resolves when it times out.\n * @internal\n */\nexport class PromiseTimer implements IPromiseTimer {\n\tprivate deferred?: Deferred<IPromiseTimerResult>;\n\tprivate readonly timer: Timer;\n\n\t/**\n\t * {@inheritDoc Timer.hasTimer}\n\t */\n\tpublic get hasTimer(): boolean {\n\t\treturn this.timer.hasTimer;\n\t}\n\n\tpublic constructor(defaultTimeout: number, defaultHandler: () => void) {\n\t\tthis.timer = new Timer(defaultTimeout, () => this.wrapHandler(defaultHandler));\n\t}\n\n\t/**\n\t * {@inheritDoc IPromiseTimer.start}\n\t */\n\tpublic async start(ms?: number, handler?: () => void): Promise<IPromiseTimerResult> {\n\t\tthis.clear();\n\t\tthis.deferred = new Deferred<IPromiseTimerResult>();\n\t\tthis.timer.start(ms, handler ? (): void => this.wrapHandler(handler) : undefined);\n\t\treturn this.deferred.promise;\n\t}\n\n\tpublic clear(): void {\n\t\tthis.timer.clear();\n\t\tif (this.deferred) {\n\t\t\tthis.deferred.resolve({ timerResult: \"cancel\" });\n\t\t\tthis.deferred = undefined;\n\t\t}\n\t}\n\n\tprotected wrapHandler(handler: () => void): void {\n\t\thandler();\n\t\tassert(!!this.deferred, 0x765 /* Handler executed without deferred */);\n\t\tthis.deferred.resolve({ timerResult: \"timeout\" });\n\t\tthis.deferred = undefined;\n\t}\n}\n"]}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.38.3"
+    }
+  ]
+}

package/dist/unreachable.d.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * This function can be used to assert at compile time that a given value has type never.
+ * One common usage is in the default case of a switch block,
+ * to ensure that all cases are explicitly handled.
+ *
+ * Example:
+ * ```typescript
+ * const bool: true | false = ...;
+ * switch(bool) {
+ *   case true: {...}
+ *   case false: {...}
+ *   default: unreachableCase(bool);
+ * }
+ * ```
+ * @internal
+ */
+export declare function unreachableCase(_: never, message?: string): never;
+//# sourceMappingURL=unreachable.d.ts.map

package/dist/unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../src/unreachable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,SAAqB,GAAG,KAAK,CAE7E"}