@fluidframework/core-utils 2.0.0-internal.6.1.1 → 2.0.0-internal.6.3.0

package/lib/unreachable.js

@@ -0,0 +1,23 @@
+/*!
+ * 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);
+ * }
+ * ```
+ */
+export function unreachableCase(_, message = "Unreachable Case") {
+    throw new Error(message);
+}
+//# sourceMappingURL=unreachable.js.map

package/lib/unreachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.js","sourceRoot":"","sources":["../src/unreachable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,CAAQ,EAAE,OAAO,GAAG,kBAAkB;IACrE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * This function can be used to assert at compile time that a given value has type never.\n * One common usage is in the default case of a switch block,\n * to ensure that all cases are explicitly handled.\n *\n * Example:\n * ```typescript\n * const bool: true | false = ...;\n * switch(bool) {\n *   case true: {...}\n *   case false: {...}\n *   default: unreachableCase(bool);\n * }\n * ```\n */\nexport function unreachableCase(_: never, message = \"Unreachable Case\"): never {\n\tthrow new Error(message);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-utils",
-  "version": "2.0.0-internal.6.1.1",
+  "version": "2.0.0-internal.6.3.0",
   "description": "Not intended for use outside the Fluid client repo.",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -14,7 +14,7 @@
   "main": "dist/index.js",
   "module": "lib/index.js",
   "types": "dist/index.d.ts",
-  "nyc": {
+  "c8": {
     "all": true,
     "cache-dir": "nyc/.cache",
     "exclude": [
@@ -39,13 +39,13 @@
     "@fluid-tools/build-cli": "^0.22.0",
     "@fluidframework/build-common": "^2.0.0",
     "@fluidframework/build-tools": "^0.22.0",
-    "@fluidframework/eslint-config-fluid": "^2.0.0",
-    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.6.1.1 <2.0.0-internal.6.2.0",
+    "@fluidframework/eslint-config-fluid": "^2.1.0",
+    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.6.3.0 <2.0.0-internal.6.4.0",
     "@microsoft/api-extractor": "^7.34.4",
     "@types/mocha": "^9.1.1",
     "@types/node": "^16.18.38",
     "@types/sinon": "^7.0.13",
-    "concurrently": "^7.6.0",
+    "c8": "^7.7.1",
     "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
     "eslint": "~8.6.0",
@@ -54,7 +54,6 @@
     "mocha-json-output-reporter": "^2.0.1",
     "mocha-multi-reporters": "^1.5.1",
     "moment": "^2.21.0",
-    "nyc": "^15.1.0",
     "prettier": "~2.6.2",
     "rimraf": "^4.4.0",
     "sinon": "^7.4.2",
@@ -75,7 +74,7 @@
     "build:esnext": "tsc --project ./tsconfig.esnext.json",
     "build:test": "tsc --project ./src/test/tsconfig.json",
     "ci:build:docs": "api-extractor run --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/* ../../../_api-extractor-temp/",
-    "clean": "rimraf --glob \"dist\" \"lib\" \"*.tsbuildinfo\" \"*.build.log\"",
+    "clean": "rimraf --glob 'dist' 'lib' '*.tsbuildinfo' '*.build.log' '_api-extractor-temp' 'nyc'",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "format": "npm run prettier:fix",
@@ -85,9 +84,8 @@
     "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore",
     "test": "npm run test:mocha",
     "test:benchmark:report": "mocha --node-option unhandled-rejections=strict,expose-gc --exit --perfMode --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js --timeout 60000",
-    "test:coverage": "nyc npm test -- --reporter xunit --reporter-option output=nyc/junit-report.xml",
+    "test:coverage": "c8 npm test",
     "test:mocha": "mocha",
-    "test:mocha:multireport": "cross-env FLUID_TEST_MULTIREPORT=1 npm run test:mocha",
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "tsc": "tsc",
     "typetests:gen": "fluid-type-test-generator",

package/src/assert.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * A browser friendly assert library.
+ * Use this instead of the 'assert' package, which has a big impact on bundle sizes.
+ * @param condition - The condition that should be true, if the condition is false an error will be thrown.
+ * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.
+ * @param message - The message to include in the error when the condition does not hold.
+ * A number should not be specified manually: use a string.
+ * Before a release, policy-check should be run, which will convert any asserts still using strings to
+ * use numbered error codes instead.
+ */
+export function assert(condition: boolean, message: string | number): asserts condition {
+	if (!condition) {
+		throw new Error(
+			typeof message === "number" ? `0x${message.toString(16).padStart(3, "0")}` : message,
+		);
+	}
+}

package/src/delay.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Returns a promise that resolves after `timeMs`.
+ * @param timeMs - Time in milliseconds to wait.
+ */
+export const delay = async (timeMs: number): Promise<void> =>
+	new Promise((resolve) => setTimeout(() => resolve(), timeMs));

package/src/heap.ts

@@ -0,0 +1,174 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Interface for a comparer.
+ */
+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.
+ */
+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}.
+ */
+export interface IHeapNode<T> {
+	value: T;
+	position: number;
+}
+
+/**
+ * Ordered {@link https://en.wikipedia.org/wiki/Heap_(data_structure) | Heap} data structure implementation.
+ */
+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> {
+		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 {
+		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(this.L.length - 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

@@ -3,6 +3,19 @@
  * 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/promises.ts

@@ -0,0 +1,60 @@
+/*!
+ * 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
+ */
+export class Deferred<T> {
+	private readonly p: Promise<T>;
+	private res: ((value: T | PromiseLike<T>) => void) | undefined;
+	private rej: ((reason?: any) => void) | undefined;
+	private completed: boolean = false;
+
+	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
+	 */
+	public reject(error: any): void {
+		if (this.rej !== undefined) {
+			this.completed = true;
+			this.rej(error);
+		}
+	}
+}

package/src/timer.ts

@@ -0,0 +1,279 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "./assert";
+import { Deferred } from "./promises";
+
+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;
+}
+
+interface ITimeout {
+	/**
+	 * Tick that timeout was started.
+	 */
+	startTick: number;
+
+	/**
+	 * Timeout duration in ms.
+	 */
+	duration: number;
+
+	/**
+	 * Handler to execute when timeout ends.
+	 */
+	handler: () => void;
+}
+
+interface IRunningTimerState extends ITimeout {
+	/**
+	 * JavaScript Timeout object.
+	 */
+	timeout: ReturnType<typeof setTimeout>;
+
+	/**
+	 * Intended duration in ms.
+	 */
+	intendedDuration: number;
+
+	/**
+	 * Intended restart timeout.
+	 */
+	restart?: ITimeout;
+}
+
+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
+ */
+export function setLongTimeout(
+	timeoutFn: () => void,
+	timeoutMs: number,
+	setTimeoutIdFn?: (timeoutId: ReturnType<typeof setTimeout>) => void,
+): ReturnType<typeof setTimeout> {
+	// The setTimeout max is 24.8 days before looping occurs.
+	let timeoutId: ReturnType<typeof setTimeout>;
+	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;
+}
+
+/**
+ * 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.
+ */
+export class Timer implements ITimer {
+	/**
+	 * Returns true if the timer is running.
+	 */
+	public get hasTimer(): boolean {
+		return !!this.runningState;
+	}
+
+	private runningState: IRunningTimerState | undefined;
+
+	constructor(
+		private readonly defaultTimeout: number,
+		private readonly defaultHandler: () => void,
+		private readonly getCurrentTick: () => number = (): number => Date.now(),
+	) {}
+
+	/**
+	 * Calls setTimeout and tracks the resulting timeout.
+	 * @param ms - overrides default timeout in ms
+	 * @param handler - overrides default handler
+	 */
+	public start(
+		ms: number = this.defaultTimeout,
+		handler: () => void = this.defaultHandler,
+	): void {
+		this.startCore(ms, handler, ms);
+	}
+
+	/**
+	 * Calls clearTimeout on the underlying timeout if running.
+	 */
+	public clear(): void {
+		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
+	 */
+	public restart(ms?: number, handler?: () => void): void {
+		if (!this.runningState) {
+			// If restart is called first, it behaves as a call to start
+			this.start(ms, handler);
+		} else {
+			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,
+				};
+			}
+		}
+	}
+
+	private startCore(duration: number, handler: () => void, intendedDuration: number): void {
+		this.clear();
+		this.runningState = {
+			startTick: this.getCurrentTick(),
+			duration,
+			intendedDuration,
+			handler,
+			timeout: setLongTimeout(
+				() => this.handler(),
+				duration,
+				(timer: number) => {
+					if (this.runningState !== undefined) {
+						this.runningState.timeout = timer;
+					}
+				},
+			),
+		};
+	}
+
+	private handler(): void {
+		assert(!!this.runningState, 0x764 /* Running timer missing handler */);
+		const restart = this.runningState.restart;
+		if (restart !== undefined) {
+			// Restart with remaining time
+			const remainingTime = this.calculateRemainingTime(restart);
+			this.startCore(remainingTime, () => restart.handler(), restart.duration);
+		} else {
+			// Run clear first, in case the handler decides to start again
+			const handler = this.runningState.handler;
+			this.clear();
+			handler();
+		}
+	}
+
+	private calculateRemainingTime(runningTimeout: ITimeout): number {
+		const elapsedTime = this.getCurrentTick() - runningTimeout.startTick;
+		return runningTimeout.duration - elapsedTime;
+	}
+}
+
+export interface IPromiseTimerResult {
+	timerResult: "timeout" | "cancel";
+}
+
+/**
+ * Timer which offers a promise that fulfills when the timer
+ * completes.
+ */
+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.
+ */
+export class PromiseTimer implements IPromiseTimer {
+	private deferred?: Deferred<IPromiseTimerResult>;
+	private readonly timer: Timer;
+
+	/**
+	 * {@inheritDoc Timer.hasTimer}
+	 */
+	public get hasTimer(): boolean {
+		return this.timer.hasTimer;
+	}
+
+	constructor(defaultTimeout: number, defaultHandler: () => void) {
+		this.timer = new Timer(defaultTimeout, () => this.wrapHandler(defaultHandler));
+	}
+
+	/**
+	 * {@inheritDoc IPromiseTimer.start}
+	 */
+	public async start(ms?: number, handler?: () => void): Promise<IPromiseTimerResult> {
+		this.clear();
+		this.deferred = new Deferred<IPromiseTimerResult>();
+		this.timer.start(ms, handler ? (): void => this.wrapHandler(handler) : undefined);
+		return this.deferred.promise;
+	}
+
+	public clear(): void {
+		this.timer.clear();
+		if (this.deferred) {
+			this.deferred.resolve({ timerResult: "cancel" });
+			this.deferred = undefined;
+		}
+	}
+
+	protected wrapHandler(handler: () => void): void {
+		handler();
+		assert(!!this.deferred, 0x765 /* Handler executed without deferred */);
+		this.deferred.resolve({ timerResult: "timeout" });
+		this.deferred = undefined;
+	}
+}

package/src/unreachable.ts

@@ -0,0 +1,23 @@
+/*!
+ * 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);
+ * }
+ * ```
+ */
+export function unreachableCase(_: never, message = "Unreachable Case"): never {
+	throw new Error(message);
+}