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

package/src/heap.ts

@@ -0,0 +1,182 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Interface for a comparer.
+ * @internal
+ */
+export interface IComparer<T> {
+	/**
+	 * The minimum value of type T.
+	 */
+	min: T;
+
+	/**
+	 * Compare the two value
+	 *
+	 * @returns 0 if the value is equal, negative number if a is smaller then b, positive number otherwise
+	 */
+	compare(a: T, b: T): number;
+}
+
+/**
+ * A comparer for numbers.
+ * @internal
+ */
+export const NumberComparer: IComparer<number> = {
+	/**
+	 * The compare function for numbers.
+	 * @returns The difference of the two numbers.
+	 */
+	compare: (a, b): number => a - b,
+
+	/**
+	 * The minimum value of a JavaScript number, which is `Number.MIN_VALUE`.
+	 */
+	min: Number.MIN_VALUE,
+};
+
+/**
+ * Interface to a node in {@link Heap}.
+ * @internal
+ */
+export interface IHeapNode<T> {
+	value: T;
+	position: number;
+}
+
+/**
+ * Ordered {@link https://en.wikipedia.org/wiki/Heap_(data_structure) | Heap} data structure implementation.
+ * @internal
+ */
+export class Heap<T> {
+	private L: IHeapNode<T>[];
+
+	/**
+	 * Creates an instance of `Heap` with comparer.
+	 * @param comp - A comparer that specify how elements are ordered.
+	 */
+	constructor(public comp: IComparer<T>) {
+		this.L = [{ value: comp.min, position: 0 }];
+	}
+
+	/**
+	 * Return the smallest element in the heap as determined by the order of the comparer
+	 *
+	 * @returns Heap node containing the smallest element
+	 */
+	public peek(): IHeapNode<T> | undefined {
+		return this.L[1];
+	}
+
+	/**
+	 * Get and remove the smallest element in the heap as determined by the order of the comparer
+	 *
+	 * @returns The smallest value in the heap
+	 */
+	public get(): T | undefined {
+		if (this.L.length === 0) {
+			return undefined;
+		}
+
+		this.swap(1, this.count());
+		const x = this.L.pop();
+		this.fixdown(1);
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return x!.value;
+	}
+
+	/**
+	 * Add a value to the heap
+	 *
+	 * @param x - value to add
+	 * @returns The heap node that contains the value
+	 */
+	public add(x: T): IHeapNode<T> {
+		const node = { value: x, position: this.L.length };
+		this.L.push(node);
+		this.fixup(this.count());
+
+		return node;
+	}
+
+	/**
+	 * Allows for the Heap to be updated after a node's value changes.
+	 */
+	public update(node: IHeapNode<T>): void {
+		const k = node.position;
+		if (this.isGreaterThanParent(k)) {
+			this.fixup(k);
+		} else {
+			this.fixdown(k);
+		}
+	}
+
+	/**
+	 * Removes the given node from the heap.
+	 *
+	 * @param node - The node to remove from the heap.
+	 */
+	public remove(node: IHeapNode<T>): void {
+		// Move the node we want to remove to the end of the array
+		const position = node.position;
+		this.swap(node.position, this.L.length - 1);
+		this.L.splice(-1);
+
+		// Update the swapped node assuming we didn't remove the end of the list
+		if (position !== this.L.length) {
+			this.update(this.L[position]);
+		}
+	}
+
+	/**
+	 * Get the number of elements in the Heap.
+	 *
+	 * @returns The number of elements in the Heap.
+	 */
+	public count(): number {
+		return this.L.length - 1;
+	}
+
+	private fixup(pos: number): void {
+		let k = pos;
+		while (this.isGreaterThanParent(k)) {
+			// eslint-disable-next-line no-bitwise
+			const parent = k >> 1;
+			this.swap(k, parent);
+			k = parent;
+		}
+	}
+
+	private isGreaterThanParent(k: number): boolean {
+		// eslint-disable-next-line no-bitwise
+		return k > 1 && this.comp.compare(this.L[k >> 1].value, this.L[k].value) > 0;
+	}
+
+	private fixdown(pos: number): void {
+		let k = pos;
+		// eslint-disable-next-line no-bitwise
+		while (k << 1 <= this.count()) {
+			// eslint-disable-next-line no-bitwise
+			let j = k << 1;
+			if (j < this.count() && this.comp.compare(this.L[j].value, this.L[j + 1].value) > 0) {
+				j++;
+			}
+			if (this.comp.compare(this.L[k].value, this.L[j].value) <= 0) {
+				break;
+			}
+			this.swap(k, j);
+			k = j;
+		}
+	}
+
+	private swap(k: number, j: number): void {
+		const tmp = this.L[k];
+		this.L[k] = this.L[j];
+		this.L[k].position = k;
+		this.L[j] = tmp;
+		this.L[j].position = j;
+	}
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { assert } from "./assert";
+export { compareArrays } from "./compare";
+export { delay } from "./delay";
+export { Heap, IComparer, IHeapNode, NumberComparer } from "./heap";
+export { Lazy, LazyPromise } from "./lazy";
+export { PromiseCache, PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache";
+export { Deferred } from "./promises";
+export {
+	IPromiseTimer,
+	IPromiseTimerResult,
+	ITimer,
+	PromiseTimer,
+	setLongTimeout,
+	Timer,
+} from "./timer";
+export { unreachableCase } from "./unreachable";

package/src/lazy.ts

@@ -0,0 +1,88 @@
+/*!
+ * 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.
+ * @internal
+ */
+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.
+	 */
+	public 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.
+ * @alpha
+ */
+export class LazyPromise<T> implements Promise<T> {
+	public get [Symbol.toStringTag](): string {
+		return this.getPromise()[Symbol.toStringTag];
+	}
+
+	private result: Promise<T> | undefined;
+
+	public constructor(private readonly execute: () => Promise<T>) {}
+
+	// eslint-disable-next-line unicorn/no-thenable
+	public async then<TResult1 = T, TResult2 = never>(
+		// eslint-disable-next-line @rushstack/no-new-null
+		onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
+		// TODO: Use `unknown` instead (API breaking)
+		// eslint-disable-next-line @rushstack/no-new-null, @typescript-eslint/no-explicit-any
+		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>(
+		// TODO: Use `unknown` instead (API breaking)
+		// eslint-disable-next-line @rushstack/no-new-null, @typescript-eslint/no-explicit-any
+		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,205 @@
+/*!
+ * 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)
+ * @alpha
+ */
+export type PromiseCacheExpiry =
+	| {
+			policy: "indefinite";
+	  }
+	| {
+			policy: "absolute" | "sliding";
+			durationMs: number;
+	  };
+
+/**
+ * Options for configuring the {@link PromiseCache}
+ * @alpha
+ */
+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?
+	 */
+	// TODO: Use `unknown` instead (API breaking)
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	removeOnError?: (error: any) => boolean;
+}
+
+/**
+ * Handles garbage collection of expiring cache entries.
+ * Not exported.
+ */
+class GarbageCollector<TKey> {
+	private readonly gcTimeouts = new Map<TKey, ReturnType<typeof setTimeout>>();
+
+	public 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.
+ * @alpha
+ */
+export class PromiseCache<TKey, TResult> {
+	private readonly cache = new Map<TKey, Promise<TResult>>();
+	private readonly gc: GarbageCollector<TKey>;
+
+	private readonly removeOnError: (error: unknown) => boolean;
+
+	/**
+	 * Create the PromiseCache with the given options, with the following defaults:
+	 *
+	 * expiry: indefinite, removeOnError: true for all errors
+	 */
+	public 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);
+	}
+}

package/src/promises.ts

@@ -0,0 +1,63 @@
+/*!
+ * 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 class Deferred<T> {
+	private readonly p: Promise<T>;
+	private res: ((value: T | PromiseLike<T>) => void) | undefined;
+	private rej: ((reason?: unknown) => void) | undefined;
+	private completed: boolean = false;
+
+	public constructor() {
+		this.p = new Promise<T>((resolve, reject) => {
+			this.res = resolve;
+			this.rej = reject;
+		});
+	}
+	/**
+	 * Returns whether the underlying promise has been completed
+	 */
+	public get isCompleted(): boolean {
+		return this.completed;
+	}
+
+	/**
+	 * Retrieves the underlying promise for the deferred
+	 *
+	 * @returns the underlying promise
+	 */
+	public get promise(): Promise<T> {
+		return this.p;
+	}
+
+	/**
+	 * Resolves the promise
+	 *
+	 * @param value - the value to resolve the promise with
+	 */
+	public resolve(value: T | PromiseLike<T>): void {
+		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
+	public reject(error: any): void {
+		if (this.rej !== undefined) {
+			this.completed = true;
+			this.rej(error);
+		}
+	}
+}