@fluidframework/core-utils 2.0.0-internal.7.2.2 → 2.0.0-internal.7.3.0

package/CHANGELOG.md

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

package/README.md

@@ -3,7 +3,12 @@
 This package is intended for sharing and promoting best-practice implementations of Fluid-agnostic utility functions
 across packages in the Fluid Framework repo.
 
-Use outside of the Fluid Framework repo is not supported or recommended.
+<!-- AUTO-GENERATED-CONTENT:START (README_PACKAGE_SCOPE_NOTICE:scopeKind=INTERNAL) -->
+
+**IMPORTANT: This package is intended strictly as an implementation detail of the Fluid Framework and is not intended for public consumption.**
+**We make no stability guarantees regarding its APIs.**
+
+<!-- AUTO-GENERATED-CONTENT:END -->
 
 ## Adding code to this package
 
@@ -61,8 +66,7 @@ package for more information including tools to convert between version schemes.
 
 This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
 
-Use of these trademarks or logos must follow Microsoft's [Trademark & Brand
-Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
 
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 

package/api-extractor.json

@@ -1,4 +1,7 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "@fluidframework/build-common/api-extractor-base.json"
+	"extends": "@fluidframework/build-common/api-extractor-base.json",
+	"dtsRollup": {
+		"enabled": true
+	}
 }

package/dist/core-utils-alpha.d.ts

@@ -0,0 +1,404 @@
+/**
+ * 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.
+ * @public
+ */
+export declare function assert(condition: boolean, message: string | number): asserts condition;
+
+/* Excluded from this release type: compareArrays */
+
+/**
+ * A deferred creates a promise and the ability to resolve or reject it
+ * @public
+ */
+export declare class Deferred<T> {
+    private readonly p;
+    private res;
+    private rej;
+    private completed;
+    constructor();
+    /**
+     * Returns whether the underlying promise has been completed
+     */
+    get isCompleted(): boolean;
+    /**
+     * Retrieves the underlying promise for the deferred
+     *
+     * @returns the underlying promise
+     */
+    get promise(): Promise<T>;
+    /**
+     * Resolves the promise
+     *
+     * @param value - the value to resolve the promise with
+     */
+    resolve(value: T | PromiseLike<T>): void;
+    /**
+     * Rejects the promise
+     *
+     * @param value - the value to reject the promise with
+     */
+    reject(error: any): void;
+}
+
+/**
+ * Returns a promise that resolves after `timeMs`.
+ * @param timeMs - Time in milliseconds to wait.
+ * @public
+ */
+export declare const delay: (timeMs: number) => Promise<void>;
+
+/**
+ * Ordered {@link https://en.wikipedia.org/wiki/Heap_(data_structure) | Heap} data structure implementation.
+ * @public
+ */
+export declare class Heap<T> {
+    comp: IComparer<T>;
+    private L;
+    /**
+     * Creates an instance of `Heap` with comparer.
+     * @param comp - A comparer that specify how elements are ordered.
+     */
+    constructor(comp: IComparer<T>);
+    /**
+     * Return the smallest element in the heap as determined by the order of the comparer
+     *
+     * @returns Heap node containing the smallest element
+     */
+    peek(): IHeapNode<T>;
+    /**
+     * Get and remove the smallest element in the heap as determined by the order of the comparer
+     *
+     * @returns The smallest value in the heap
+     */
+    get(): T;
+    /**
+     * Add a value to the heap
+     *
+     * @param x - value to add
+     * @returns The heap node that contains the value
+     */
+    add(x: T): IHeapNode<T>;
+    /**
+     * Allows for the Heap to be updated after a node's value changes.
+     */
+    update(node: IHeapNode<T>): void;
+    /**
+     * Removes the given node from the heap.
+     *
+     * @param node - The node to remove from the heap.
+     */
+    remove(node: IHeapNode<T>): void;
+    /**
+     * Get the number of elements in the Heap.
+     *
+     * @returns The number of elements in the Heap.
+     */
+    count(): number;
+    private fixup;
+    private isGreaterThanParent;
+    private fixdown;
+    private swap;
+}
+
+/**
+ * Interface for a comparer.
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * Interface to a node in {@link Heap}.
+ * @public
+ */
+export declare interface IHeapNode<T> {
+    value: T;
+    position: number;
+}
+
+/**
+ * Timer which offers a promise that fulfills when the timer
+ * completes.
+ * @public
+ */
+export declare interface IPromiseTimer extends ITimer {
+    /**
+     * Starts the timer and returns a promise that
+     * resolves when the timer times out or is canceled.
+     */
+    start(): Promise<IPromiseTimerResult>;
+}
+
+/**
+ * @public
+ */
+export declare interface IPromiseTimerResult {
+    timerResult: "timeout" | "cancel";
+}
+
+/**
+ * @public
+ */
+export declare interface ITimer {
+    /**
+     * True if timer is currently running
+     */
+    readonly hasTimer: boolean;
+    /**
+     * Starts the timer
+     */
+    start(): void;
+    /**
+     * Cancels the timer if already running
+     */
+    clear(): void;
+}
+
+/**
+ * Helper class for lazy initialized values. Ensures the value is only generated once, and remain immutable.
+ * @public
+ */
+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.
+ * @public
+ */
+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;
+}
+
+/**
+ * A comparer for numbers.
+ * @public
+ */
+export declare const NumberComparer: IComparer<number>;
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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)
+ * @public
+ */
+export declare type PromiseCacheExpiry = {
+    policy: "indefinite";
+} | {
+    policy: "absolute" | "sliding";
+    durationMs: number;
+};
+
+/**
+ * Options for configuring the {@link PromiseCache}
+ * @public
+ */
+export declare 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?: (error: any) => boolean;
+}
+
+/**
+ * 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.
+ * @public
+ */
+export declare class PromiseTimer implements IPromiseTimer {
+    private deferred?;
+    private readonly timer;
+    /**
+     * {@inheritDoc Timer.hasTimer}
+     */
+    get hasTimer(): boolean;
+    constructor(defaultTimeout: number, defaultHandler: () => void);
+    /**
+     * {@inheritDoc IPromiseTimer.start}
+     */
+    start(ms?: number, handler?: () => void): Promise<IPromiseTimerResult>;
+    clear(): void;
+    protected wrapHandler(handler: () => void): void;
+}
+
+/**
+ * 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
+ * @public
+ */
+export declare function setLongTimeout(timeoutFn: () => void, timeoutMs: number, setTimeoutIdFn?: (timeoutId: ReturnType<typeof setTimeout>) => void): ReturnType<typeof setTimeout>;
+
+/**
+ * This class is a thin wrapper over setTimeout and clearTimeout which
+ * makes it simpler to keep track of recurring timeouts with the same
+ * or similar handlers and timeouts. This class supports long timeouts
+ * or timeouts exceeding (2^31)-1 ms or approximately 24.8 days.
+ * @public
+ */
+export declare class Timer implements ITimer {
+    private readonly defaultTimeout;
+    private readonly defaultHandler;
+    private readonly getCurrentTick;
+    /**
+     * Returns true if the timer is running.
+     */
+    get hasTimer(): boolean;
+    private runningState;
+    constructor(defaultTimeout: number, defaultHandler: () => void, getCurrentTick?: () => number);
+    /**
+     * Calls setTimeout and tracks the resulting timeout.
+     * @param ms - overrides default timeout in ms
+     * @param handler - overrides default handler
+     */
+    start(ms?: number, handler?: () => void): void;
+    /**
+     * Calls clearTimeout on the underlying timeout if running.
+     */
+    clear(): void;
+    /**
+     * Restarts the timer with the new handler and duration.
+     * If a new handler is passed, the original handler may
+     * never execute.
+     * This is a potentially more efficient way to clear and start
+     * a new timer.
+     * @param ms - overrides previous or default timeout in ms
+     * @param handler - overrides previous or default handler
+     */
+    restart(ms?: number, handler?: () => void): void;
+    private startCore;
+    private handler;
+    private calculateRemainingTime;
+}
+
+/**
+ * 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);
+ * }
+ * ```
+ * @public
+ */
+export declare function unreachableCase(_: never, message?: string): never;
+
+export { }