@fluidframework/core-utils 2.0.0-internal.5.2.0 → 2.0.0-internal.5.3.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluidframework/core-utils
 
+## 2.0.0-internal.5.3.0
+
+Dependency updates only.
+
 ## 2.0.0-internal.5.2.0
 
 Dependency updates only.

package/dist/index.d.ts

@@ -3,4 +3,6 @@
  * Licensed under the MIT License.
  */
 export { compareArrays } from "./compare";
+export { Lazy, LazyPromise } from "./lazy";
+export { PromiseCache, PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -4,7 +4,12 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.compareArrays = void 0;
+exports.PromiseCache = exports.LazyPromise = exports.Lazy = exports.compareArrays = void 0;
 var compare_1 = require("./compare");
 Object.defineProperty(exports, "compareArrays", { enumerable: true, get: function () { return compare_1.compareArrays; } });
+var lazy_1 = require("./lazy");
+Object.defineProperty(exports, "Lazy", { enumerable: true, get: function () { return lazy_1.Lazy; } });
+Object.defineProperty(exports, "LazyPromise", { enumerable: true, get: function () { return lazy_1.LazyPromise; } });
+var promiseCache_1 = require("./promiseCache");
+Object.defineProperty(exports, "PromiseCache", { enumerable: true, get: function () { return promiseCache_1.PromiseCache; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,qCAA0C;AAAjC,wGAAA,aAAa,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { compareArrays } from \"./compare\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,+BAA2C;AAAlC,4FAAA,IAAI,OAAA;AAAE,mGAAA,WAAW,OAAA;AAC1B,+CAAuF;AAA9E,4GAAA,YAAY,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { compareArrays } from \"./compare\";\nexport { Lazy, LazyPromise } from \"./lazy\";\nexport { PromiseCache, PromiseCacheExpiry, PromiseCacheOptions } from \"./promiseCache\";\n"]}

package/dist/lazy.d.ts

@@ -0,0 +1,42 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ */
+export declare class Lazy<T> {
+    private readonly valueGenerator;
+    private _value;
+    private _evaluated;
+    /**
+     * Instantiates an instance of Lazy<T>.
+     * @param valueGenerator - The function that will generate the value when value is accessed the first time.
+     */
+    constructor(valueGenerator: () => T);
+    /**
+     * Return true if the value as been generated, otherwise false.
+     */
+    get evaluated(): boolean;
+    /**
+     * Get the value. If this is the first call the value will be generated.
+     */
+    get value(): T;
+}
+/**
+ * A lazy evaluated promise. The execute function is delayed until
+ * the promise is used, e.g. await, then, catch ...
+ * The execute function is only called once.
+ * All calls are then proxied to the promise returned by the execute method.
+ */
+export declare class LazyPromise<T> implements Promise<T> {
+    private readonly execute;
+    get [Symbol.toStringTag](): string;
+    private result;
+    constructor(execute: () => Promise<T>);
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    private getPromise;
+}
+//# sourceMappingURL=lazy.d.ts.map

package/dist/lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../src/lazy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,qBAAa,IAAI,CAAC,CAAC;IAON,OAAO,CAAC,QAAQ,CAAC,cAAc;IAN3C,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAkB;IACpC;;;OAGG;gBAC0B,cAAc,EAAE,MAAM,CAAC;IAEpD;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,CAAC,CAOpB;CACD;AAED;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;IAOpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,IAAW,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAExC;IAED,OAAO,CAAC,MAAM,CAAyB;gBAEV,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAEzC,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,EAE/C,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAEjF,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GACjF,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAKlB,KAAK,CAAC,OAAO,GAAG,KAAK,EAEjC,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/E,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC;IAMV,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC;YAK/D,UAAU;CAMxB"}

package/dist/lazy.js

@@ -0,0 +1,79 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LazyPromise = exports.Lazy = void 0;
+/**
+ * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ */
+class Lazy {
+    /**
+     * Instantiates an instance of Lazy<T>.
+     * @param valueGenerator - The function that will generate the value when value is accessed the first time.
+     */
+    constructor(valueGenerator) {
+        this.valueGenerator = valueGenerator;
+        this._evaluated = false;
+    }
+    /**
+     * Return true if the value as been generated, otherwise false.
+     */
+    get evaluated() {
+        return this._evaluated;
+    }
+    /**
+     * Get the value. If this is the first call the value will be generated.
+     */
+    get value() {
+        if (!this._evaluated) {
+            this._evaluated = true;
+            this._value = this.valueGenerator();
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return this._value;
+    }
+}
+exports.Lazy = Lazy;
+/**
+ * A lazy evaluated promise. The execute function is delayed until
+ * the promise is used, e.g. await, then, catch ...
+ * The execute function is only called once.
+ * All calls are then proxied to the promise returned by the execute method.
+ */
+class LazyPromise {
+    constructor(execute) {
+        this.execute = execute;
+    }
+    get [Symbol.toStringTag]() {
+        return this.getPromise()[Symbol.toStringTag];
+    }
+    async then(
+    // eslint-disable-next-line @rushstack/no-new-null
+    onfulfilled, 
+    // eslint-disable-next-line @rushstack/no-new-null
+    onrejected) {
+        // eslint-disable-next-line prefer-rest-params
+        return this.getPromise().then(...arguments);
+    }
+    async catch(
+    // eslint-disable-next-line @rushstack/no-new-null
+    onrejected) {
+        // eslint-disable-next-line prefer-rest-params
+        return this.getPromise().catch(...arguments);
+    }
+    // eslint-disable-next-line @rushstack/no-new-null
+    async finally(onfinally) {
+        // eslint-disable-next-line prefer-rest-params
+        return this.getPromise().finally(...arguments);
+    }
+    async getPromise() {
+        if (this.result === undefined) {
+            this.result = this.execute();
+        }
+        return this.result;
+    }
+}
+exports.LazyPromise = LazyPromise;
+//# sourceMappingURL=lazy.js.map

package/dist/lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../src/lazy.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;GAEG;AACH,MAAa,IAAI;IAGhB;;;OAGG;IACH,YAA6B,cAAuB;QAAvB,mBAAc,GAAd,cAAc,CAAS;QAL5C,eAAU,GAAY,KAAK,CAAC;IAKmB,CAAC;IAExD;;OAEG;IACH,IAAW,SAAS;QACnB,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,IAAW,KAAK;QACf,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;SACpC;QACD,oEAAoE;QACpE,OAAO,IAAI,CAAC,MAAO,CAAC;IACrB,CAAC;CACD;AA3BD,oBA2BC;AAED;;;;;GAKG;AACH,MAAa,WAAW;IAOvB,YAA6B,OAAyB;QAAzB,YAAO,GAAP,OAAO,CAAkB;IAAG,CAAC;IAN1D,IAAW,CAAC,MAAM,CAAC,WAAW,CAAC;QAC9B,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IAMM,KAAK,CAAC,IAAI;IAChB,kDAAkD;IAClD,WAAiF;IACjF,kDAAkD;IAClD,UAAmF;QAEnF,8CAA8C;QAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAqB,GAAG,SAAS,CAAC,CAAC;IACjE,CAAC;IAEM,KAAK,CAAC,KAAK;IACjB,kDAAkD;IAClD,UAAiF;QAEjF,8CAA8C;QAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAU,GAAG,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,kDAAkD;IAC3C,KAAK,CAAC,OAAO,CAAC,SAA2C;QAC/D,8CAA8C;QAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,UAAU;QACvB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE;YAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;SAC7B;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;CACD;AAvCD,kCAuCC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.\n */\nexport class Lazy<T> {\n\tprivate _value: T | undefined;\n\tprivate _evaluated: boolean = false;\n\t/**\n\t * Instantiates an instance of Lazy<T>.\n\t * @param valueGenerator - The function that will generate the value when value is accessed the first time.\n\t */\n\tconstructor(private readonly valueGenerator: () => T) {}\n\n\t/**\n\t * Return true if the value as been generated, otherwise false.\n\t */\n\tpublic get evaluated(): boolean {\n\t\treturn this._evaluated;\n\t}\n\n\t/**\n\t * Get the value. If this is the first call the value will be generated.\n\t */\n\tpublic get value(): T {\n\t\tif (!this._evaluated) {\n\t\t\tthis._evaluated = true;\n\t\t\tthis._value = this.valueGenerator();\n\t\t}\n\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\treturn this._value!;\n\t}\n}\n\n/**\n * A lazy evaluated promise. The execute function is delayed until\n * the promise is used, e.g. await, then, catch ...\n * The execute function is only called once.\n * All calls are then proxied to the promise returned by the execute method.\n */\nexport class LazyPromise<T> implements Promise<T> {\n\tpublic get [Symbol.toStringTag](): string {\n\t\treturn this.getPromise()[Symbol.toStringTag];\n\t}\n\n\tprivate result: Promise<T> | undefined;\n\n\tconstructor(private readonly execute: () => Promise<T>) {}\n\n\tpublic async then<TResult1 = T, TResult2 = never>(\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\tonfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\tonrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined,\n\t): Promise<TResult1 | TResult2> {\n\t\t// eslint-disable-next-line prefer-rest-params\n\t\treturn this.getPromise().then<TResult1, TResult2>(...arguments);\n\t}\n\n\tpublic async catch<TResult = never>(\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\tonrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined,\n\t): Promise<T | TResult> {\n\t\t// eslint-disable-next-line prefer-rest-params\n\t\treturn this.getPromise().catch<TResult>(...arguments);\n\t}\n\n\t// eslint-disable-next-line @rushstack/no-new-null\n\tpublic async finally(onfinally?: (() => void) | null | undefined): Promise<T> {\n\t\t// eslint-disable-next-line prefer-rest-params\n\t\treturn this.getPromise().finally(...arguments);\n\t}\n\n\tprivate async getPromise(): Promise<T> {\n\t\tif (this.result === undefined) {\n\t\t\tthis.result = this.execute();\n\t\t}\n\t\treturn this.result;\n\t}\n}\n"]}

package/dist/promiseCache.d.ts

@@ -0,0 +1,82 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Three supported expiry policies:
+ * - indefinite: entries don't expire and must be explicitly removed
+ * - absolute: entries expire after the given duration in MS, even if accessed multiple times in the mean time
+ * - sliding: entries expire after the given duration in MS of inactivity (i.e. get resets the clock)
+ */
+export declare type PromiseCacheExpiry = {
+    policy: "indefinite";
+} | {
+    policy: "absolute" | "sliding";
+    durationMs: number;
+};
+/**
+ * Options for configuring the {@link PromiseCache}
+ */
+export interface PromiseCacheOptions {
+    /** Common expiration policy for all items added to this cache */
+    expiry?: PromiseCacheExpiry;
+    /** If the stored Promise is rejected with a particular error, should the given key be removed? */
+    removeOnError?: (e: any) => boolean;
+}
+/**
+ * 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.
+ */
+export declare class PromiseCache<TKey, TResult> {
+    private readonly cache;
+    private readonly gc;
+    private readonly removeOnError;
+    /**
+     * Create the PromiseCache with the given options, with the following defaults:
+     *
+     * expiry: indefinite, removeOnError: true for all errors
+     */
+    constructor({ expiry, removeOnError, }?: PromiseCacheOptions);
+    /**
+     * Check if there's anything cached at the given key
+     */
+    has(key: TKey): boolean;
+    /**
+     * Get the Promise for the given key, or undefined if it's not found.
+     * Extend expiry if applicable.
+     */
+    get(key: TKey): Promise<TResult> | undefined;
+    /**
+     * Remove the Promise for the given key, returning true if it was found and removed
+     */
+    remove(key: TKey): boolean;
+    /**
+     * 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
+     */
+    addOrGet(key: TKey, asyncFn: () => Promise<TResult>): Promise<TResult>;
+    /**
+     * 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: TKey, asyncFn: () => Promise<TResult>): boolean;
+    /**
+     * 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
+     */
+    addValueOrGet(key: TKey, value: TResult): Promise<TResult>;
+    /**
+     * 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: TKey, value: TResult): boolean;
+}
+//# sourceMappingURL=promiseCache.d.ts.map

package/dist/promiseCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promiseCache.d.ts","sourceRoot":"","sources":["../src/promiseCache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,oBAAY,kBAAkB,GAC3B;IACA,MAAM,EAAE,YAAY,CAAC;CACpB,GACD;IACA,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;CAClB,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,iEAAiE;IACjE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,kGAAkG;IAClG,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACpC;AAoDD;;;GAGG;AACH,qBAAa,YAAY,CAAC,IAAI,EAAE,OAAO;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAyB;IAE5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IAExD;;;;OAIG;gBACS,EACX,MAAiC,EACjC,aAAmC,GACnC,GAAE,mBAAwB;IAK3B;;OAEG;IACI,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO;IAI9B;;;OAGG;IACI,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS;IAOnD;;OAEG;IACI,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO;IAKjC;;;;;OAKG;IACU,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBnF;;;;;OAKG;IACI,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO;IAU/D;;;;;OAKG;IACU,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvE;;;;;OAKG;IACI,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;CAGnD"}

package/dist/promiseCache.js

@@ -0,0 +1,147 @@
+"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.
+ */
+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 */\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 */\nexport interface PromiseCacheOptions {\n\t/** Common expiration policy for all items added to this cache */\n\texpiry?: PromiseCacheExpiry;\n\t/** If the stored Promise is rejected with a particular error, should the given key be removed? */\n\tremoveOnError?: (e: 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\tconstructor(\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 */\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: any) => 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\tconstructor({\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/lib/index.d.ts

@@ -3,4 +3,6 @@
  * Licensed under the MIT License.
  */
 export { compareArrays } from "./compare";
+export { Lazy, LazyPromise } from "./lazy";
+export { PromiseCache, PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/index.js

@@ -3,4 +3,6 @@
  * Licensed under the MIT License.
  */
 export { compareArrays } from "./compare";
+export { Lazy, LazyPromise } from "./lazy";
+export { PromiseCache } from "./promiseCache";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { compareArrays } from \"./compare\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,YAAY,EAA2C,MAAM,gBAAgB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { compareArrays } from \"./compare\";\nexport { Lazy, LazyPromise } from \"./lazy\";\nexport { PromiseCache, PromiseCacheExpiry, PromiseCacheOptions } from \"./promiseCache\";\n"]}

package/lib/lazy.d.ts

@@ -0,0 +1,42 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ */
+export declare class Lazy<T> {
+    private readonly valueGenerator;
+    private _value;
+    private _evaluated;
+    /**
+     * Instantiates an instance of Lazy<T>.
+     * @param valueGenerator - The function that will generate the value when value is accessed the first time.
+     */
+    constructor(valueGenerator: () => T);
+    /**
+     * Return true if the value as been generated, otherwise false.
+     */
+    get evaluated(): boolean;
+    /**
+     * Get the value. If this is the first call the value will be generated.
+     */
+    get value(): T;
+}
+/**
+ * A lazy evaluated promise. The execute function is delayed until
+ * the promise is used, e.g. await, then, catch ...
+ * The execute function is only called once.
+ * All calls are then proxied to the promise returned by the execute method.
+ */
+export declare class LazyPromise<T> implements Promise<T> {
+    private readonly execute;
+    get [Symbol.toStringTag](): string;
+    private result;
+    constructor(execute: () => Promise<T>);
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    private getPromise;
+}
+//# sourceMappingURL=lazy.d.ts.map

package/lib/lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../src/lazy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,qBAAa,IAAI,CAAC,CAAC;IAON,OAAO,CAAC,QAAQ,CAAC,cAAc;IAN3C,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAkB;IACpC;;;OAGG;gBAC0B,cAAc,EAAE,MAAM,CAAC;IAEpD;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,CAAC,CAOpB;CACD;AAED;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;IAOpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,IAAW,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAExC;IAED,OAAO,CAAC,MAAM,CAAyB;gBAEV,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAEzC,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,EAE/C,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAEjF,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GACjF,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAKlB,KAAK,CAAC,OAAO,GAAG,KAAK,EAEjC,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/E,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC;IAMV,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC;YAK/D,UAAU;CAMxB"}

package/lib/lazy.js

@@ -0,0 +1,74 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ */
+export class Lazy {
+    /**
+     * Instantiates an instance of Lazy<T>.
+     * @param valueGenerator - The function that will generate the value when value is accessed the first time.
+     */
+    constructor(valueGenerator) {
+        this.valueGenerator = valueGenerator;
+        this._evaluated = false;
+    }
+    /**
+     * Return true if the value as been generated, otherwise false.
+     */
+    get evaluated() {
+        return this._evaluated;
+    }
+    /**
+     * Get the value. If this is the first call the value will be generated.
+     */
+    get value() {
+        if (!this._evaluated) {
+            this._evaluated = true;
+            this._value = this.valueGenerator();
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return this._value;
+    }
+}
+/**
+ * A lazy evaluated promise. The execute function is delayed until
+ * the promise is used, e.g. await, then, catch ...
+ * The execute function is only called once.
+ * All calls are then proxied to the promise returned by the execute method.
+ */
+export class LazyPromise {
+    constructor(execute) {
+        this.execute = execute;
+    }
+    get [Symbol.toStringTag]() {
+        return this.getPromise()[Symbol.toStringTag];
+    }
+    async then(
+    // eslint-disable-next-line @rushstack/no-new-null
+    onfulfilled, 
+    // eslint-disable-next-line @rushstack/no-new-null
+    onrejected) {
+        // eslint-disable-next-line prefer-rest-params
+        return this.getPromise().then(...arguments);
+    }
+    async catch(
+    // eslint-disable-next-line @rushstack/no-new-null
+    onrejected) {
+        // eslint-disable-next-line prefer-rest-params
+        return this.getPromise().catch(...arguments);
+    }
+    // eslint-disable-next-line @rushstack/no-new-null
+    async finally(onfinally) {
+        // eslint-disable-next-line prefer-rest-params
+        return this.getPromise().finally(...arguments);
+    }
+    async getPromise() {
+        if (this.result === undefined) {
+            this.result = this.execute();
+        }
+        return this.result;
+    }
+}
+//# sourceMappingURL=lazy.js.map

package/lib/lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../src/lazy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,OAAO,IAAI;IAGhB;;;OAGG;IACH,YAA6B,cAAuB;QAAvB,mBAAc,GAAd,cAAc,CAAS;QAL5C,eAAU,GAAY,KAAK,CAAC;IAKmB,CAAC;IAExD;;OAEG;IACH,IAAW,SAAS;QACnB,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,IAAW,KAAK;QACf,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;SACpC;QACD,oEAAoE;QACpE,OAAO,IAAI,CAAC,MAAO,CAAC;IACrB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IAOvB,YAA6B,OAAyB;QAAzB,YAAO,GAAP,OAAO,CAAkB;IAAG,CAAC;IAN1D,IAAW,CAAC,MAAM,CAAC,WAAW,CAAC;QAC9B,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IAMM,KAAK,CAAC,IAAI;IAChB,kDAAkD;IAClD,WAAiF;IACjF,kDAAkD;IAClD,UAAmF;QAEnF,8CAA8C;QAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAqB,GAAG,SAAS,CAAC,CAAC;IACjE,CAAC;IAEM,KAAK,CAAC,KAAK;IACjB,kDAAkD;IAClD,UAAiF;QAEjF,8CAA8C;QAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAU,GAAG,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,kDAAkD;IAC3C,KAAK,CAAC,OAAO,CAAC,SAA2C;QAC/D,8CAA8C;QAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,UAAU;QACvB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE;YAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;SAC7B;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.\n */\nexport class Lazy<T> {\n\tprivate _value: T | undefined;\n\tprivate _evaluated: boolean = false;\n\t/**\n\t * Instantiates an instance of Lazy<T>.\n\t * @param valueGenerator - The function that will generate the value when value is accessed the first time.\n\t */\n\tconstructor(private readonly valueGenerator: () => T) {}\n\n\t/**\n\t * Return true if the value as been generated, otherwise false.\n\t */\n\tpublic get evaluated(): boolean {\n\t\treturn this._evaluated;\n\t}\n\n\t/**\n\t * Get the value. If this is the first call the value will be generated.\n\t */\n\tpublic get value(): T {\n\t\tif (!this._evaluated) {\n\t\t\tthis._evaluated = true;\n\t\t\tthis._value = this.valueGenerator();\n\t\t}\n\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\treturn this._value!;\n\t}\n}\n\n/**\n * A lazy evaluated promise. The execute function is delayed until\n * the promise is used, e.g. await, then, catch ...\n * The execute function is only called once.\n * All calls are then proxied to the promise returned by the execute method.\n */\nexport class LazyPromise<T> implements Promise<T> {\n\tpublic get [Symbol.toStringTag](): string {\n\t\treturn this.getPromise()[Symbol.toStringTag];\n\t}\n\n\tprivate result: Promise<T> | undefined;\n\n\tconstructor(private readonly execute: () => Promise<T>) {}\n\n\tpublic async then<TResult1 = T, TResult2 = never>(\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\tonfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\tonrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined,\n\t): Promise<TResult1 | TResult2> {\n\t\t// eslint-disable-next-line prefer-rest-params\n\t\treturn this.getPromise().then<TResult1, TResult2>(...arguments);\n\t}\n\n\tpublic async catch<TResult = never>(\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\tonrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined,\n\t): Promise<T | TResult> {\n\t\t// eslint-disable-next-line prefer-rest-params\n\t\treturn this.getPromise().catch<TResult>(...arguments);\n\t}\n\n\t// eslint-disable-next-line @rushstack/no-new-null\n\tpublic async finally(onfinally?: (() => void) | null | undefined): Promise<T> {\n\t\t// eslint-disable-next-line prefer-rest-params\n\t\treturn this.getPromise().finally(...arguments);\n\t}\n\n\tprivate async getPromise(): Promise<T> {\n\t\tif (this.result === undefined) {\n\t\t\tthis.result = this.execute();\n\t\t}\n\t\treturn this.result;\n\t}\n}\n"]}

package/lib/promiseCache.d.ts

@@ -0,0 +1,82 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Three supported expiry policies:
+ * - indefinite: entries don't expire and must be explicitly removed
+ * - absolute: entries expire after the given duration in MS, even if accessed multiple times in the mean time
+ * - sliding: entries expire after the given duration in MS of inactivity (i.e. get resets the clock)
+ */
+export declare type PromiseCacheExpiry = {
+    policy: "indefinite";
+} | {
+    policy: "absolute" | "sliding";
+    durationMs: number;
+};
+/**
+ * Options for configuring the {@link PromiseCache}
+ */
+export interface PromiseCacheOptions {
+    /** Common expiration policy for all items added to this cache */
+    expiry?: PromiseCacheExpiry;
+    /** If the stored Promise is rejected with a particular error, should the given key be removed? */
+    removeOnError?: (e: any) => boolean;
+}
+/**
+ * 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.
+ */
+export declare class PromiseCache<TKey, TResult> {
+    private readonly cache;
+    private readonly gc;
+    private readonly removeOnError;
+    /**
+     * Create the PromiseCache with the given options, with the following defaults:
+     *
+     * expiry: indefinite, removeOnError: true for all errors
+     */
+    constructor({ expiry, removeOnError, }?: PromiseCacheOptions);
+    /**
+     * Check if there's anything cached at the given key
+     */
+    has(key: TKey): boolean;
+    /**
+     * Get the Promise for the given key, or undefined if it's not found.
+     * Extend expiry if applicable.
+     */
+    get(key: TKey): Promise<TResult> | undefined;
+    /**
+     * Remove the Promise for the given key, returning true if it was found and removed
+     */
+    remove(key: TKey): boolean;
+    /**
+     * 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
+     */
+    addOrGet(key: TKey, asyncFn: () => Promise<TResult>): Promise<TResult>;
+    /**
+     * 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: TKey, asyncFn: () => Promise<TResult>): boolean;
+    /**
+     * 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
+     */
+    addValueOrGet(key: TKey, value: TResult): Promise<TResult>;
+    /**
+     * 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: TKey, value: TResult): boolean;
+}
+//# sourceMappingURL=promiseCache.d.ts.map

package/lib/promiseCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promiseCache.d.ts","sourceRoot":"","sources":["../src/promiseCache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,oBAAY,kBAAkB,GAC3B;IACA,MAAM,EAAE,YAAY,CAAC;CACpB,GACD;IACA,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;CAClB,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,iEAAiE;IACjE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,kGAAkG;IAClG,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACpC;AAoDD;;;GAGG;AACH,qBAAa,YAAY,CAAC,IAAI,EAAE,OAAO;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAyB;IAE5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IAExD;;;;OAIG;gBACS,EACX,MAAiC,EACjC,aAAmC,GACnC,GAAE,mBAAwB;IAK3B;;OAEG;IACI,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO;IAI9B;;;OAGG;IACI,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS;IAOnD;;OAEG;IACI,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO;IAKjC;;;;;OAKG;IACU,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBnF;;;;;OAKG;IACI,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO;IAU/D;;;;;OAKG;IACU,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvE;;;;;OAKG;IACI,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;CAGnD"}

package/lib/promiseCache.js

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * 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.
+ */
+export 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);
+    }
+}
+//# sourceMappingURL=promiseCache.js.map

package/lib/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 */\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 */\nexport interface PromiseCacheOptions {\n\t/** Common expiration policy for all items added to this cache */\n\texpiry?: PromiseCacheExpiry;\n\t/** If the stored Promise is rejected with a particular error, should the given key be removed? */\n\tremoveOnError?: (e: 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\tconstructor(\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 */\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: any) => 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\tconstructor({\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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-utils",
-  "version": "2.0.0-internal.5.2.0",
+  "version": "2.0.0-internal.5.3.0",
   "description": "Not intended for use outside the Fluid client repo.",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -36,14 +36,15 @@
   },
   "devDependencies": {
     "@fluid-tools/benchmark": "^0.48.0",
-    "@fluid-tools/build-cli": "^0.20.0",
+    "@fluid-tools/build-cli": "^0.21.0",
     "@fluidframework/build-common": "^1.2.0",
-    "@fluidframework/build-tools": "^0.20.0",
+    "@fluidframework/build-tools": "^0.21.0",
     "@fluidframework/eslint-config-fluid": "^2.0.0",
-    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.5.2.0 <2.0.0-internal.5.3.0",
+    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.5.3.0 <2.0.0-internal.5.4.0",
     "@microsoft/api-extractor": "^7.34.4",
     "@types/mocha": "^9.1.1",
     "@types/node": "^14.18.38",
+    "@types/sinon": "^7.0.13",
     "concurrently": "^7.6.0",
     "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
@@ -56,6 +57,7 @@
     "nyc": "^15.1.0",
     "prettier": "~2.6.2",
     "rimraf": "^4.4.0",
+    "sinon": "^7.4.2",
     "source-map-support": "^0.5.16",
     "typescript": "~4.5.5"
   },
@@ -89,6 +91,6 @@
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "tsc": "tsc",
     "typetests:gen": "fluid-type-test-generator",
-    "typetests:prepare": "flub generate typetests --prepare --dir . --pin"
+    "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
   }
 }

package/src/index.ts

@@ -4,3 +4,5 @@
  */
 
 export { compareArrays } from "./compare";
+export { Lazy, LazyPromise } from "./lazy";
+export { PromiseCache, PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache";

package/src/lazy.ts

@@ -0,0 +1,83 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ */
+export class Lazy<T> {
+	private _value: T | undefined;
+	private _evaluated: boolean = false;
+	/**
+	 * Instantiates an instance of Lazy<T>.
+	 * @param valueGenerator - The function that will generate the value when value is accessed the first time.
+	 */
+	constructor(private readonly valueGenerator: () => T) {}
+
+	/**
+	 * Return true if the value as been generated, otherwise false.
+	 */
+	public get evaluated(): boolean {
+		return this._evaluated;
+	}
+
+	/**
+	 * Get the value. If this is the first call the value will be generated.
+	 */
+	public get value(): T {
+		if (!this._evaluated) {
+			this._evaluated = true;
+			this._value = this.valueGenerator();
+		}
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return this._value!;
+	}
+}
+
+/**
+ * A lazy evaluated promise. The execute function is delayed until
+ * the promise is used, e.g. await, then, catch ...
+ * The execute function is only called once.
+ * All calls are then proxied to the promise returned by the execute method.
+ */
+export class LazyPromise<T> implements Promise<T> {
+	public get [Symbol.toStringTag](): string {
+		return this.getPromise()[Symbol.toStringTag];
+	}
+
+	private result: Promise<T> | undefined;
+
+	constructor(private readonly execute: () => Promise<T>) {}
+
+	public async then<TResult1 = T, TResult2 = never>(
+		// eslint-disable-next-line @rushstack/no-new-null
+		onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
+		// eslint-disable-next-line @rushstack/no-new-null
+		onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined,
+	): Promise<TResult1 | TResult2> {
+		// eslint-disable-next-line prefer-rest-params
+		return this.getPromise().then<TResult1, TResult2>(...arguments);
+	}
+
+	public async catch<TResult = never>(
+		// eslint-disable-next-line @rushstack/no-new-null
+		onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined,
+	): Promise<T | TResult> {
+		// eslint-disable-next-line prefer-rest-params
+		return this.getPromise().catch<TResult>(...arguments);
+	}
+
+	// eslint-disable-next-line @rushstack/no-new-null
+	public async finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+		// eslint-disable-next-line prefer-rest-params
+		return this.getPromise().finally(...arguments);
+	}
+
+	private async getPromise(): Promise<T> {
+		if (this.result === undefined) {
+			this.result = this.execute();
+		}
+		return this.result;
+	}
+}

package/src/promiseCache.ts

@@ -0,0 +1,196 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Three supported expiry policies:
+ * - indefinite: entries don't expire and must be explicitly removed
+ * - absolute: entries expire after the given duration in MS, even if accessed multiple times in the mean time
+ * - sliding: entries expire after the given duration in MS of inactivity (i.e. get resets the clock)
+ */
+export type PromiseCacheExpiry =
+	| {
+			policy: "indefinite";
+	  }
+	| {
+			policy: "absolute" | "sliding";
+			durationMs: number;
+	  };
+
+/**
+ * Options for configuring the {@link PromiseCache}
+ */
+export interface PromiseCacheOptions {
+	/** Common expiration policy for all items added to this cache */
+	expiry?: PromiseCacheExpiry;
+	/** If the stored Promise is rejected with a particular error, should the given key be removed? */
+	removeOnError?: (e: any) => boolean;
+}
+
+/**
+ * Handles garbage collection of expiring cache entries.
+ * Not exported.
+ */
+class GarbageCollector<TKey> {
+	private readonly gcTimeouts = new Map<TKey, ReturnType<typeof setTimeout>>();
+
+	constructor(
+		private readonly expiry: PromiseCacheExpiry,
+		private readonly cleanup: (key: TKey) => void,
+	) {}
+
+	/**
+	 * Schedule GC for the given key, as applicable
+	 */
+	public schedule(key: TKey): void {
+		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
+	 */
+	public cancel(key: TKey): void {
+		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
+	 */
+	public update(key: TKey): void {
+		// 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.
+ */
+export class PromiseCache<TKey, TResult> {
+	private readonly cache = new Map<TKey, Promise<TResult>>();
+	private readonly gc: GarbageCollector<TKey>;
+
+	private readonly removeOnError: (error: any) => boolean;
+
+	/**
+	 * Create the PromiseCache with the given options, with the following defaults:
+	 *
+	 * expiry: indefinite, removeOnError: true for all errors
+	 */
+	constructor({
+		expiry = { policy: "indefinite" },
+		removeOnError = (): boolean => true,
+	}: PromiseCacheOptions = {}) {
+		this.removeOnError = removeOnError;
+		this.gc = new GarbageCollector<TKey>(expiry, (key) => this.remove(key));
+	}
+
+	/**
+	 * Check if there's anything cached at the given key
+	 */
+	public has(key: TKey): boolean {
+		return this.cache.has(key);
+	}
+
+	/**
+	 * Get the Promise for the given key, or undefined if it's not found.
+	 * Extend expiry if applicable.
+	 */
+	public get(key: TKey): Promise<TResult> | undefined {
+		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
+	 */
+	public remove(key: TKey): boolean {
+		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
+	 */
+	public async addOrGet(key: TKey, asyncFn: () => Promise<TResult>): Promise<TResult> {
+		// 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 (): Promise<TResult> => 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
+	 */
+	public add(key: TKey, asyncFn: () => Promise<TResult>): boolean {
+		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
+	 */
+	public async addValueOrGet(key: TKey, value: TResult): Promise<TResult> {
+		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
+	 */
+	public addValue(key: TKey, value: TResult): boolean {
+		return this.add(key, async () => value);
+	}
+}