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

package/.eslintrc.js

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+	extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
+
+	parserOptions: {
+		project: ["./tsconfig.json", "./src/test/tsconfig.json"],
+	},
+	rules: {
+		// This library is used in the browser, so we don't want dependencies on most node libraries.
+		"import/no-nodejs-modules": ["error", { allow: ["events"] }],
+
+		// This has been disabled in the next eslint-config-fluid.
+		// Once the dependency here has been updated, this override can be removed.
+		"unicorn/numeric-separators-style": "off",
+	},
+	overrides: [
+		{
+			// Rules only for test files
+			files: ["*.spec.ts", "*.test.ts", "src/test/**"],
+			rules: {
+				// Test files are run in node only so additional node libraries can be used.
+				"import/no-nodejs-modules": [
+					"error",
+					{ allow: ["node:assert", "node:events", "node:process"] },
+				],
+
+				// Does not work well with describe/it block scoping
+				"unicorn/consistent-function-scoping": "off",
+			},
+		},
+	],
+};

package/.mocharc.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+"use strict";
+
+const getFluidTestMochaConfig = require("@fluidframework/mocha-test-setup/mocharc-common");
+
+const packageDir = __dirname;
+const config = getFluidTestMochaConfig(packageDir);
+config.spec = "dist/test";
+module.exports = config;

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# @fluidframework/core-utils
+
+## 2.0.0-internal.8.0.0
+
+Dependency updates only.
+
+## 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.
+
+## 2.0.0-internal.7.1.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.0.0
+
+### Major Changes
+
+-   Minimum TypeScript version now 5.1.6 [871b3493dd](https://github.com/microsoft/FluidFramework/commits/871b3493dd0d7ea3a89be64998ceb6cb9021a04e)
+
+    The minimum supported TypeScript version for Fluid 2.0 clients is now 5.1.6.
+
+## 2.0.0-internal.6.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.3.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.2.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.1.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.0.0
+
+### Major Changes
+
+-   Upgraded typescript transpilation target to ES2020 [8abce8cdb4](https://github.com/microsoft/FluidFramework/commits/8abce8cdb4e2832fb6405fb44e393bef03d5648a)
+
+    Upgraded typescript transpilation target to ES2020. This is done in order to decrease the bundle sizes of Fluid Framework packages. This has provided size improvements across the board for ex. Loader, Driver, Runtime etc. Reduced bundle sizes helps to load lesser code in apps and hence also helps to improve the perf.If any app wants to target any older versions of browsers with which this target version is not compatible, then they can use packages like babel to transpile to a older target.
+
+## 2.0.0-internal.5.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.3.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.2.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.1.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.0.0
+
+Dependency updates only.
+
+## 2.0.0-internal.4.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.4.1.0
+
+Dependency updates only.

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @fluidframework/core-utils
+
+This package is intended for sharing and promoting best-practice implementations of Fluid-agnostic utility functions
+across packages in the Fluid Framework repo.
+
+<!-- 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
+
+As a utility package, this package does not have a strong identity. This means that it's easy to become a "dumping
+ground" for code that we think we should share but doesn't have an obvious home. We try to avoid dumping things into
+utility packages, and this one is no exception.
+
+New code should only be added to this package in rare circumstances. In most cases, the code would be better placed in a
+package with a clear identity (e.g. an "events" package for shared event infrastructure) or not shared at all.
+
+## Requirements
+
+This package has important requirements for the code within it.
+
+1. **Code in this package must have zero dependencies.** That is, it must not depend on other packages, even within the
+   Fluid Framework repo. `devDependencies` are OK.
+1. **All exports must be designated `@internal`.** This code is intended for use within the Fluid Framework only.
+1. This package should **only contain 'implementation' code, not type definitions.** This is the most flexible rule, and
+   there are some exceptions. If the type is _only_ necessary when using this package, then it is probably OK. However,
+   usually such types would be better placed in core-interfaces or in a package that corresponds to the purpose.
+
+If you want to add code that does not meet these requirements, these other packages may be a better choice:
+
+-   **Types and interfaces** that are intended to be broadly shared across the client release group should be put in the
+    **core-interfaces** package.
+-   **Shared implementation code with dependencies** should be put in the **client-utils** package.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_DEPENDENCY_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Using Fluid Framework libraries
+
+When taking a dependency on a Fluid Framework library, we recommend using a `^` (caret) version range, such as `^1.3.4`.
+While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
+library consumers should always prefer `^`.
+
+Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
+you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
+Standard `^` and `~` ranges will not work as expected.
+See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
+package for more information including tools to convert between version schemes.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+<!-- AUTO-GENERATED-CONTENT:START (README_TRADEMARK_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Trademark
+
+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 Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->

package/api-extractor-lint.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json"
+}

package/api-extractor.json

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

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

@@ -0,0 +1,147 @@
+## API Report File for "@fluidframework/core-utils"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @alpha
+export function assert(condition: boolean, message: string | number): asserts condition;
+
+// @alpha
+export const compareArrays: <T>(left: readonly T[], right: readonly T[], comparator?: (leftItem: T, rightItem: T, index: number) => boolean) => boolean;
+
+// @alpha
+export class Deferred<T> {
+    constructor();
+    get isCompleted(): boolean;
+    get promise(): Promise<T>;
+    reject(error: any): void;
+    resolve(value: T | PromiseLike<T>): void;
+}
+
+// @internal
+export const delay: (timeMs: number) => Promise<void>;
+
+// @internal
+export class Heap<T> {
+    constructor(comp: IComparer<T>);
+    add(x: T): IHeapNode<T>;
+    // (undocumented)
+    comp: IComparer<T>;
+    count(): number;
+    get(): T | undefined;
+    peek(): IHeapNode<T> | undefined;
+    remove(node: IHeapNode<T>): void;
+    update(node: IHeapNode<T>): void;
+}
+
+// @internal
+export interface IComparer<T> {
+    compare(a: T, b: T): number;
+    min: T;
+}
+
+// @internal
+export interface IHeapNode<T> {
+    // (undocumented)
+    position: number;
+    // (undocumented)
+    value: T;
+}
+
+// @internal
+export interface IPromiseTimer extends ITimer {
+    start(): Promise<IPromiseTimerResult>;
+}
+
+// @internal (undocumented)
+export interface IPromiseTimerResult {
+    // (undocumented)
+    timerResult: "timeout" | "cancel";
+}
+
+// @internal (undocumented)
+export interface ITimer {
+    clear(): void;
+    readonly hasTimer: boolean;
+    start(): void;
+}
+
+// @internal
+export class Lazy<T> {
+    constructor(valueGenerator: () => T);
+    get evaluated(): boolean;
+    get value(): T;
+}
+
+// @alpha
+export class LazyPromise<T> implements Promise<T> {
+    // (undocumented)
+    get [Symbol.toStringTag](): string;
+    constructor(execute: () => Promise<T>);
+    // (undocumented)
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    // (undocumented)
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    // (undocumented)
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+}
+
+// @internal
+export const NumberComparer: IComparer<number>;
+
+// @alpha
+export class PromiseCache<TKey, TResult> {
+    constructor({ expiry, removeOnError, }?: PromiseCacheOptions);
+    add(key: TKey, asyncFn: () => Promise<TResult>): boolean;
+    addOrGet(key: TKey, asyncFn: () => Promise<TResult>): Promise<TResult>;
+    addValue(key: TKey, value: TResult): boolean;
+    addValueOrGet(key: TKey, value: TResult): Promise<TResult>;
+    get(key: TKey): Promise<TResult> | undefined;
+    has(key: TKey): boolean;
+    remove(key: TKey): boolean;
+}
+
+// @alpha
+export type PromiseCacheExpiry = {
+    policy: "indefinite";
+} | {
+    policy: "absolute" | "sliding";
+    durationMs: number;
+};
+
+// @alpha
+export interface PromiseCacheOptions {
+    expiry?: PromiseCacheExpiry;
+    removeOnError?: (error: any) => boolean;
+}
+
+// @internal
+export class PromiseTimer implements IPromiseTimer {
+    constructor(defaultTimeout: number, defaultHandler: () => void);
+    // (undocumented)
+    clear(): void;
+    get hasTimer(): boolean;
+    start(ms?: number, handler?: () => void): Promise<IPromiseTimerResult>;
+    // (undocumented)
+    protected wrapHandler(handler: () => void): void;
+}
+
+// @internal
+export function setLongTimeout(timeoutFn: () => void, timeoutMs: number, setTimeoutIdFn?: (timeoutId: ReturnType<typeof setTimeout>) => void): ReturnType<typeof setTimeout>;
+
+// @internal
+export class Timer implements ITimer {
+    constructor(defaultTimeout: number, defaultHandler: () => void, getCurrentTick?: () => number);
+    clear(): void;
+    get hasTimer(): boolean;
+    restart(ms?: number, handler?: () => void): void;
+    start(ms?: number, handler?: () => void): void;
+}
+
+// @internal
+export function unreachableCase(_: never, message?: string): never;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/dist/assert.d.ts

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

package/dist/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAMtF"}

package/dist/assert.js

@@ -0,0 +1,25 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assert = void 0;
+/**
+ * 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.
+ * @alpha
+ */
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(typeof message === "number" ? `0x${message.toString(16).padStart(3, "0")}` : message);
+    }
+}
+exports.assert = assert;
+//# sourceMappingURL=assert.js.map

package/dist/assert.js.map

@@ -0,0 +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 * @alpha\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/compare.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Compare two arrays.  Returns true if their elements are equivalent and in the same order.
+ *
+ * @alpha
+ *
+ * @param left - The first array to compare
+ * @param right - The second array to compare
+ * @param comparator - The function used to check if two `T`s are equivalent.
+ * Defaults to `Object.is()` equality (a shallow compare where NaN = NaN and -0 ≠ 0)
+ */
+export declare const compareArrays: <T>(left: readonly T[], right: readonly T[], comparator?: (leftItem: T, rightItem: T, index: number) => boolean) => boolean;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,+FAGsB,MAAM,KAAK,OAAO,KAI/D,OAUF,CAAC"}

package/dist/compare.js

@@ -0,0 +1,28 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareArrays = void 0;
+/**
+ * Compare two arrays.  Returns true if their elements are equivalent and in the same order.
+ *
+ * @alpha
+ *
+ * @param left - The first array to compare
+ * @param right - The second array to compare
+ * @param comparator - The function used to check if two `T`s are equivalent.
+ * Defaults to `Object.is()` equality (a shallow compare where NaN = NaN and -0 ≠ 0)
+ */
+const compareArrays = (left, right, comparator = (leftItem, rightItem) => Object.is(leftItem, rightItem)) => {
+    // PERF: 'for-loop' and 'Array.every()' tied.
+    //       '===' and 'Object.is()' tied.
+    //       Trivial acceptance adds no measurable overhead.
+    //       30% penalty vs. baseline for exported function [node 14 x64].
+    return (left === right || // Trivial acceptance: 'left' and 'right' are the same instance
+        (left.length === right.length && // Trivial rejection: 'left' and 'right' are different lengths
+            left.every((leftItem, index) => comparator(leftItem, right[index], index))));
+};
+exports.compareArrays = compareArrays;
+//# sourceMappingURL=compare.js.map

package/dist/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;GASG;AACI,MAAM,aAAa,GAAG,CAC5B,IAAkB,EAClB,KAAmB,EACnB,aAAoE,CACnE,QAAW,EACX,SAAY,EACF,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC,EAClC,EAAE;IACZ,6CAA6C;IAC7C,sCAAsC;IACtC,wDAAwD;IACxD,sEAAsE;IACtE,OAAO,CACN,IAAI,KAAK,KAAK,IAAI,+DAA+D;QACjF,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,IAAI,8DAA8D;YAC9F,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAC5E,CAAC;AACH,CAAC,CAAC;AAjBW,QAAA,aAAa,iBAiBxB","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Compare two arrays.  Returns true if their elements are equivalent and in the same order.\n *\n * @alpha\n *\n * @param left - The first array to compare\n * @param right - The second array to compare\n * @param comparator - The function used to check if two `T`s are equivalent.\n * Defaults to `Object.is()` equality (a shallow compare where NaN = NaN and -0 ≠ 0)\n */\nexport const compareArrays = <T>(\n\tleft: readonly T[],\n\tright: readonly T[],\n\tcomparator: (leftItem: T, rightItem: T, index: number) => boolean = (\n\t\tleftItem: T,\n\t\trightItem: T,\n\t): boolean => Object.is(leftItem, rightItem),\n): boolean => {\n\t// PERF: 'for-loop' and 'Array.every()' tied.\n\t//       '===' and 'Object.is()' tied.\n\t//       Trivial acceptance adds no measurable overhead.\n\t//       30% penalty vs. baseline for exported function [node 14 x64].\n\treturn (\n\t\tleft === right || // Trivial acceptance: 'left' and 'right' are the same instance\n\t\t(left.length === right.length && // Trivial rejection: 'left' and 'right' are different lengths\n\t\t\tleft.every((leftItem, index) => comparator(leftItem, right[index], index)))\n\t);\n};\n"]}