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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @fluidframework/core-utils
 
+## 2.0.0-internal.7.4.0
+
+Dependency updates only.
+
+## 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-lint.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json",
+	"messages": {
+		"extractorMessageReporting": {
+			// TODO: remove once base config has this enabled as an error
+			"ae-incompatible-release-tags": {
+				"logLevel": "error",
+				"addToApiReportFile": false
+			}
+		}
+	}
+}

package/api-extractor.json

@@ -1,4 +1,12 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "@fluidframework/build-common/api-extractor-base.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.json",
+	"messages": {
+		"extractorMessageReporting": {
+			// TODO: Add missing documentation and remove this rule override
+			"ae-undocumented": {
+				"logLevel": "none"
+			}
+		}
+	}
 }

package/api-report/core-utils.api.md

@@ -4,13 +4,13 @@
 
 ```ts
 
-// @public
+// @internal
 export function assert(condition: boolean, message: string | number): asserts condition;
 
 // @internal
 export const compareArrays: <T>(left: readonly T[], right: readonly T[], comparator?: (leftItem: T, rightItem: T, index: number) => boolean) => boolean;
 
-// @public
+// @alpha
 export class Deferred<T> {
     constructor();
     get isCompleted(): boolean;
@@ -19,10 +19,10 @@ export class Deferred<T> {
     resolve(value: T | PromiseLike<T>): void;
 }
 
-// @public
+// @internal
 export const delay: (timeMs: number) => Promise<void>;
 
-// @public
+// @internal
 export class Heap<T> {
     constructor(comp: IComparer<T>);
     add(x: T): IHeapNode<T>;
@@ -35,13 +35,13 @@ export class Heap<T> {
     update(node: IHeapNode<T>): void;
 }
 
-// @public
+// @internal
 export interface IComparer<T> {
     compare(a: T, b: T): number;
     min: T;
 }
 
-// @public
+// @internal
 export interface IHeapNode<T> {
     // (undocumented)
     position: number;
@@ -49,32 +49,32 @@ export interface IHeapNode<T> {
     value: T;
 }
 
-// @public
+// @internal
 export interface IPromiseTimer extends ITimer {
     start(): Promise<IPromiseTimerResult>;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface IPromiseTimerResult {
     // (undocumented)
     timerResult: "timeout" | "cancel";
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface ITimer {
     clear(): void;
     readonly hasTimer: boolean;
     start(): void;
 }
 
-// @public
+// @internal
 export class Lazy<T> {
     constructor(valueGenerator: () => T);
     get evaluated(): boolean;
     get value(): T;
 }
 
-// @public
+// @internal
 export class LazyPromise<T> implements Promise<T> {
     // (undocumented)
     get [Symbol.toStringTag](): string;
@@ -87,10 +87,10 @@ export class LazyPromise<T> implements 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>;
 }
 
-// @public
+// @internal
 export const NumberComparer: IComparer<number>;
 
-// @public
+// @alpha
 export class PromiseCache<TKey, TResult> {
     constructor({ expiry, removeOnError, }?: PromiseCacheOptions);
     add(key: TKey, asyncFn: () => Promise<TResult>): boolean;
@@ -102,7 +102,7 @@ export class PromiseCache<TKey, TResult> {
     remove(key: TKey): boolean;
 }
 
-// @public
+// @alpha
 export type PromiseCacheExpiry = {
     policy: "indefinite";
 } | {
@@ -110,13 +110,13 @@ export type PromiseCacheExpiry = {
     durationMs: number;
 };
 
-// @public
+// @alpha
 export interface PromiseCacheOptions {
     expiry?: PromiseCacheExpiry;
     removeOnError?: (error: any) => boolean;
 }
 
-// @public
+// @internal
 export class PromiseTimer implements IPromiseTimer {
     constructor(defaultTimeout: number, defaultHandler: () => void);
     // (undocumented)
@@ -127,10 +127,10 @@ export class PromiseTimer implements IPromiseTimer {
     protected wrapHandler(handler: () => void): void;
 }
 
-// @public
+// @internal
 export function setLongTimeout(timeoutFn: () => void, timeoutMs: number, setTimeoutIdFn?: (timeoutId: ReturnType<typeof setTimeout>) => void): ReturnType<typeof setTimeout>;
 
-// @public
+// @internal
 export class Timer implements ITimer {
     constructor(defaultTimeout: number, defaultHandler: () => void, getCurrentTick?: () => number);
     clear(): void;
@@ -139,7 +139,7 @@ export class Timer implements ITimer {
     start(ms?: number, handler?: () => void): void;
 }
 
-// @public
+// @internal
 export function unreachableCase(_: never, message?: string): never;
 
 // (No @packageDocumentation comment for this package)

package/dist/assert.d.ts

@@ -11,7 +11,7 @@
  * 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
+ * @internal
  */
 export declare function assert(condition: boolean, message: string | number): asserts condition;
 //# sourceMappingURL=assert.d.ts.map

package/dist/assert.js

@@ -14,7 +14,7 @@ exports.assert = void 0;
  * 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
+ * @internal
  */
 function assert(condition, message) {
     if (!condition) {

package/dist/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;;GAUG;AACH,SAAgB,MAAM,CAAC,SAAkB,EAAE,OAAwB;IAClE,IAAI,CAAC,SAAS,EAAE;QACf,MAAM,IAAI,KAAK,CACd,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,CAAC;KACF;AACF,CAAC;AAND,wBAMC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A browser friendly assert library.\n * Use this instead of the 'assert' package, which has a big impact on bundle sizes.\n * @param condition - The condition that should be true, if the condition is false an error will be thrown.\n * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.\n * @param message - The message to include in the error when the condition does not hold.\n * A number should not be specified manually: use a string.\n * Before a release, policy-check should be run, which will convert any asserts still using strings to\n * use numbered error codes instead.\n * @public\n */\nexport function assert(condition: boolean, message: string | number): asserts condition {\n\tif (!condition) {\n\t\tthrow new Error(\n\t\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message,\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;;GAUG;AACH,SAAgB,MAAM,CAAC,SAAkB,EAAE,OAAwB;IAClE,IAAI,CAAC,SAAS,EAAE;QACf,MAAM,IAAI,KAAK,CACd,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,CAAC;KACF;AACF,CAAC;AAND,wBAMC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A browser friendly assert library.\n * Use this instead of the 'assert' package, which has a big impact on bundle sizes.\n * @param condition - The condition that should be true, if the condition is false an error will be thrown.\n * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.\n * @param message - The message to include in the error when the condition does not hold.\n * A number should not be specified manually: use a string.\n * Before a release, policy-check should be run, which will convert any asserts still using strings to\n * use numbered error codes instead.\n * @internal\n */\nexport function assert(condition: boolean, message: string | number): asserts condition {\n\tif (!condition) {\n\t\tthrow new Error(\n\t\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message,\n\t\t);\n\t}\n}\n"]}

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

@@ -0,0 +1,154 @@
+/* Excluded from this release type: assert */
+
+/* Excluded from this release type: compareArrays */
+
+/**
+ * A deferred creates a promise and the ability to resolve or reject it
+ * @alpha
+ */
+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;
+}
+
+/* Excluded from this release type: delay */
+
+/* Excluded from this release type: Heap */
+
+/* Excluded from this release type: IComparer */
+
+/* Excluded from this release type: IHeapNode */
+
+/* Excluded from this release type: IPromiseTimer */
+
+/* Excluded from this release type: IPromiseTimerResult */
+
+/* Excluded from this release type: ITimer */
+
+/* Excluded from this release type: Lazy */
+
+/* Excluded from this release type: LazyPromise */
+
+/* Excluded from this release type: NumberComparer */
+
+/**
+ * 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 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)
+ * @alpha
+ */
+export declare type PromiseCacheExpiry = {
+    policy: "indefinite";
+} | {
+    policy: "absolute" | "sliding";
+    durationMs: number;
+};
+
+/**
+ * Options for configuring the {@link PromiseCache}
+ * @alpha
+ */
+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;
+}
+
+/* Excluded from this release type: PromiseTimer */
+
+/* Excluded from this release type: setLongTimeout */
+
+/* Excluded from this release type: Timer */
+
+/* Excluded from this release type: unreachableCase */
+
+export { }

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

@@ -0,0 +1,41 @@
+/* Excluded from this release type: assert */
+
+/* Excluded from this release type: compareArrays */
+
+/* Excluded from this release type: Deferred */
+
+/* Excluded from this release type: delay */
+
+/* Excluded from this release type: Heap */
+
+/* Excluded from this release type: IComparer */
+
+/* Excluded from this release type: IHeapNode */
+
+/* Excluded from this release type: IPromiseTimer */
+
+/* Excluded from this release type: IPromiseTimerResult */
+
+/* Excluded from this release type: ITimer */
+
+/* Excluded from this release type: Lazy */
+
+/* Excluded from this release type: LazyPromise */
+
+/* Excluded from this release type: NumberComparer */
+
+/* Excluded from this release type: PromiseCache */
+
+/* Excluded from this release type: PromiseCacheExpiry */
+
+/* Excluded from this release type: PromiseCacheOptions */
+
+/* Excluded from this release type: PromiseTimer */
+
+/* Excluded from this release type: setLongTimeout */
+
+/* Excluded from this release type: Timer */
+
+/* Excluded from this release type: unreachableCase */
+
+export { }

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

@@ -0,0 +1,41 @@
+/* Excluded from this release type: assert */
+
+/* Excluded from this release type: compareArrays */
+
+/* Excluded from this release type: Deferred */
+
+/* Excluded from this release type: delay */
+
+/* Excluded from this release type: Heap */
+
+/* Excluded from this release type: IComparer */
+
+/* Excluded from this release type: IHeapNode */
+
+/* Excluded from this release type: IPromiseTimer */
+
+/* Excluded from this release type: IPromiseTimerResult */
+
+/* Excluded from this release type: ITimer */
+
+/* Excluded from this release type: Lazy */
+
+/* Excluded from this release type: LazyPromise */
+
+/* Excluded from this release type: NumberComparer */
+
+/* Excluded from this release type: PromiseCache */
+
+/* Excluded from this release type: PromiseCacheExpiry */
+
+/* Excluded from this release type: PromiseCacheOptions */
+
+/* Excluded from this release type: PromiseTimer */
+
+/* Excluded from this release type: setLongTimeout */
+
+/* Excluded from this release type: Timer */
+
+/* Excluded from this release type: unreachableCase */
+
+export { }