@fluidframework/core-utils 2.0.0-dev.6.4.0.191515 → 2.0.0-dev.7.2.0.203917

package/src/lazy.ts

@@ -5,6 +5,7 @@
 
 /**
  * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ * @public
  */
 export class Lazy<T> {
 	private _value: T | undefined;
@@ -13,7 +14,7 @@ export class Lazy<T> {
 	 * 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) {}
+	public constructor(private readonly valueGenerator: () => T) {}
 
 	/**
 	 * Return true if the value as been generated, otherwise false.
@@ -40,6 +41,7 @@ export class Lazy<T> {
  * 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.
+ * @public
  */
 export class LazyPromise<T> implements Promise<T> {
 	public get [Symbol.toStringTag](): string {
@@ -48,12 +50,14 @@ export class LazyPromise<T> implements Promise<T> {
 
 	private result: Promise<T> | undefined;
 
-	constructor(private readonly execute: () => Promise<T>) {}
+	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,
-		// eslint-disable-next-line @rushstack/no-new-null
+		// 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
@@ -61,7 +65,8 @@ export class LazyPromise<T> implements Promise<T> {
 	}
 
 	public async catch<TResult = never>(
-		// eslint-disable-next-line @rushstack/no-new-null
+		// 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

package/src/promiseCache.ts

@@ -8,6 +8,7 @@
  * - 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)
+ * @public
  */
 export type PromiseCacheExpiry =
 	| {
@@ -20,12 +21,19 @@ export type PromiseCacheExpiry =
 
 /**
  * Options for configuring the {@link PromiseCache}
+ * @public
  */
 export interface PromiseCacheOptions {
-	/** Common expiration policy for all items added to this cache */
+	/**
+	 * 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;
+	/**
+	 * 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;
 }
 
 /**
@@ -35,7 +43,7 @@ export interface PromiseCacheOptions {
 class GarbageCollector<TKey> {
 	private readonly gcTimeouts = new Map<TKey, ReturnType<typeof setTimeout>>();
 
-	constructor(
+	public constructor(
 		private readonly expiry: PromiseCacheExpiry,
 		private readonly cleanup: (key: TKey) => void,
 	) {}
@@ -81,19 +89,20 @@ class GarbageCollector<TKey> {
 /**
  * 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.
+ * @public
  */
 export class PromiseCache<TKey, TResult> {
 	private readonly cache = new Map<TKey, Promise<TResult>>();
 	private readonly gc: GarbageCollector<TKey>;
 
-	private readonly removeOnError: (error: any) => boolean;
+	private readonly removeOnError: (error: unknown) => boolean;
 
 	/**
 	 * Create the PromiseCache with the given options, with the following defaults:
 	 *
 	 * expiry: indefinite, removeOnError: true for all errors
 	 */
-	constructor({
+	public constructor({
 		expiry = { policy: "indefinite" },
 		removeOnError = (): boolean => true,
 	}: PromiseCacheOptions = {}) {

package/src/promises.ts

@@ -5,14 +5,15 @@
 
 /**
  * A deferred creates a promise and the ability to resolve or reject it
+ * @public
  */
 export class Deferred<T> {
 	private readonly p: Promise<T>;
 	private res: ((value: T | PromiseLike<T>) => void) | undefined;
-	private rej: ((reason?: any) => void) | undefined;
+	private rej: ((reason?: unknown) => void) | undefined;
 	private completed: boolean = false;
 
-	constructor() {
+	public constructor() {
 		this.p = new Promise<T>((resolve, reject) => {
 			this.res = resolve;
 			this.rej = reject;
@@ -51,6 +52,8 @@ export class Deferred<T> {
 	 *
 	 * @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;

package/src/timer.ts

@@ -6,6 +6,9 @@
 import { assert } from "./assert";
 import { Deferred } from "./promises";
 
+/**
+ * @public
+ */
 export interface ITimer {
 	/**
 	 * True if timer is currently running
@@ -68,6 +71,7 @@ const maxSetTimeoutMs = 0x7fffffff; // setTimeout limit is MAX_INT32=(2^31-1).
  * @param setTimeoutIdFn - Executed to update the timeout if multiple timeouts are required when
  * timeoutMs greater than maxTimeout
  * @returns The initial timeout
+ * @public
  */
 export function setLongTimeout(
 	timeoutFn: () => void,
@@ -95,6 +99,7 @@ export function setLongTimeout(
  * 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.
+ * @public
  */
 export class Timer implements ITimer {
 	/**
@@ -106,7 +111,7 @@ export class Timer implements ITimer {
 
 	private runningState: IRunningTimerState | undefined;
 
-	constructor(
+	public constructor(
 		private readonly defaultTimeout: number,
 		private readonly defaultHandler: () => void,
 		private readonly getCurrentTick: () => number = (): number => Date.now(),
@@ -145,10 +150,7 @@ export class Timer implements ITimer {
 	 * @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 {
+		if (this.runningState) {
 			const duration = ms ?? this.runningState.intendedDuration;
 			const handlerToUse =
 				handler ?? this.runningState.restart?.handler ?? this.runningState.handler;
@@ -172,6 +174,9 @@ export class Timer implements ITimer {
 					handler: handlerToUse,
 				};
 			}
+		} else {
+			// If restart is called first, it behaves as a call to start
+			this.start(ms, handler);
 		}
 	}
 
@@ -197,15 +202,15 @@ export class Timer implements ITimer {
 	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 {
+		if (restart === undefined) {
 			// Run clear first, in case the handler decides to start again
 			const handler = this.runningState.handler;
 			this.clear();
 			handler();
+		} else {
+			// Restart with remaining time
+			const remainingTime = this.calculateRemainingTime(restart);
+			this.startCore(remainingTime, () => restart.handler(), restart.duration);
 		}
 	}
 
@@ -215,6 +220,9 @@ export class Timer implements ITimer {
 	}
 }
 
+/**
+ * @public
+ */
 export interface IPromiseTimerResult {
 	timerResult: "timeout" | "cancel";
 }
@@ -222,6 +230,7 @@ export interface IPromiseTimerResult {
 /**
  * Timer which offers a promise that fulfills when the timer
  * completes.
+ * @public
  */
 export interface IPromiseTimer extends ITimer {
 	/**
@@ -236,6 +245,7 @@ export interface IPromiseTimer extends ITimer {
  * 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.
+ * @public
  */
 export class PromiseTimer implements IPromiseTimer {
 	private deferred?: Deferred<IPromiseTimerResult>;
@@ -248,7 +258,7 @@ export class PromiseTimer implements IPromiseTimer {
 		return this.timer.hasTimer;
 	}
 
-	constructor(defaultTimeout: number, defaultHandler: () => void) {
+	public constructor(defaultTimeout: number, defaultHandler: () => void) {
 		this.timer = new Timer(defaultTimeout, () => this.wrapHandler(defaultHandler));
 	}
 

package/src/unreachable.ts

@@ -17,6 +17,7 @@
  *   default: unreachableCase(bool);
  * }
  * ```
+ * @public
  */
 export function unreachableCase(_: never, message = "Unreachable Case"): never {
 	throw new Error(message);