@fluidframework/core-utils 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @fluidframework/core-utils
 
+## 2.0.0-rc.3.0.0
+
+### Major Changes
+
+-   Packages now use package.json "exports" and require modern module resolution [97d68aa06b](https://github.com/microsoft/FluidFramework/commit/97d68aa06bd5c022ecb026655814aea222a062ae)
+
+    Fluid Framework packages have been updated to use the [package.json "exports"
+    field](https://nodejs.org/docs/latest-v18.x/api/packages.html#exports) to define explicit entry points for both
+    TypeScript types and implementation code.
+
+    This means that using Fluid Framework packages require the following TypeScript settings in tsconfig.json:
+
+    -   `"moduleResolution": "Node16"` with `"module": "Node16"`
+    -   `"moduleResolution": "Bundler"` with `"module": "ESNext"`
+
+    We recommend using Node16/Node16 unless absolutely necessary. That will produce transpiled JavaScript that is suitable
+    for use with modern versions of Node.js _and_ Bundlers.
+    [See the TypeScript documentation](https://www.typescriptlang.org/tsconfig#moduleResolution) for more information
+    regarding the module and moduleResolution options.
+
+    **Node10 moduleResolution is not supported; it does not support Fluid Framework's API structuring pattern that is used
+    to distinguish stable APIs from those that are in development.**
+
 ## 2.0.0-rc.2.0.0
 
 Dependency updates only.

package/dist/legacy.d.ts

@@ -0,0 +1,20 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluidframework/build-tools.
+ */
+
+export {
+	// alpha APIs
+	Deferred, 
+	LazyPromise, 
+	PromiseCache, 
+	PromiseCacheExpiry, 
+	PromiseCacheOptions, 
+	assert, 
+	compareArrays
+} from "./index.js";

package/dist/public.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluidframework/build-tools.
+ */
+
+export {}
+

package/internal.d.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluidframework/build-tools.
+ */
+
+export * from "./lib/index.js";

package/legacy.d.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluidframework/build-tools.
+ */
+
+export * from "./lib/legacy.js";

package/lib/legacy.d.ts

@@ -0,0 +1,20 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluidframework/build-tools.
+ */
+
+export {
+	// alpha APIs
+	Deferred, 
+	LazyPromise, 
+	PromiseCache, 
+	PromiseCacheExpiry, 
+	PromiseCacheOptions, 
+	assert, 
+	compareArrays
+} from "./index.js";

package/lib/public.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluidframework/build-tools.
+ */
+
+export {}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-utils",
-  "version": "2.0.0-rc.2.0.2",
+  "version": "2.0.0-rc.3.0.0",
   "description": "Not intended for use outside the Fluid client repo.",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -15,31 +15,21 @@
   "exports": {
     ".": {
       "import": {
-        "types": "./lib/index.d.ts",
-        "default": "./lib/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
-    },
-    "./public": {
-      "import": {
-        "types": "./lib/core-utils-public.d.ts",
+        "types": "./lib/public.d.ts",
         "default": "./lib/index.js"
       },
       "require": {
-        "types": "./dist/core-utils-public.d.ts",
+        "types": "./dist/public.d.ts",
         "default": "./dist/index.js"
       }
     },
-    "./alpha": {
+    "./legacy": {
       "import": {
-        "types": "./lib/core-utils-alpha.d.ts",
+        "types": "./lib/legacy.d.ts",
         "default": "./lib/index.js"
       },
       "require": {
-        "types": "./dist/core-utils-alpha.d.ts",
+        "types": "./dist/legacy.d.ts",
         "default": "./dist/index.js"
       }
     },
@@ -54,8 +44,8 @@
       }
     }
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "lib/index.js",
+  "types": "lib/public.d.ts",
   "c8": {
     "all": true,
     "cache-dir": "nyc/.cache",
@@ -77,13 +67,14 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.13.3",
-    "@fluid-internal/mocha-test-setup": ">=2.0.0-rc.2.0.2 <2.0.0-rc.2.1.0",
+    "@arethetypeswrong/cli": "^0.15.2",
+    "@biomejs/biome": "^1.6.2",
+    "@fluid-internal/mocha-test-setup": ">=2.0.0-rc.3.0.0 <2.0.0-rc.3.1.0",
     "@fluid-tools/benchmark": "^0.47.0",
-    "@fluid-tools/build-cli": "^0.34.0",
+    "@fluid-tools/build-cli": "^0.37.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.34.0",
-    "@fluidframework/eslint-config-fluid": "^4.0.0",
+    "@fluidframework/build-tools": "^0.37.0",
+    "@fluidframework/eslint-config-fluid": "^5.1.0",
     "@microsoft/api-extractor": "^7.42.3",
     "@types/mocha": "^9.1.1",
     "@types/node": "^18.19.0",
@@ -102,47 +93,35 @@
     "sinon": "^17.0.1",
     "typescript": "~5.1.6"
   },
-  "fluidBuild": {
-    "tasks": {
-      "build:docs": {
-        "dependsOn": [
-          "...",
-          "api-extractor:commonjs",
-          "api-extractor:esnext"
-        ],
-        "script": false
-      }
-    }
-  },
   "typeValidation": {
     "disabled": true,
     "broken": {}
   },
   "scripts": {
     "api": "fluid-build . --task api",
-    "api-extractor:commonjs": "api-extractor run --config ./api-extractor-cjs.json",
-    "api-extractor:esnext": "api-extractor run --local",
+    "api-extractor:commonjs": "flub generate entrypoints --outFileAlpha legacy --outDir ./dist",
+    "api-extractor:esnext": "flub generate entrypoints --outFileAlpha legacy --outDir ./lib --node10TypeCompat",
     "bench": "mocha --recursive \"lib/test/**/*.spec.*js\" --timeout 999999 --perfMode --parentProcess --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js",
     "bench:profile": "mocha --recursive \"lib/test/**/*.spec.*js\" --v8-prof --v8-logfile=profile.log --v8-no-logfile-per-isolate --timeout 999999 --perfMode --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js && node --prof-process profile.log > profile.txt && rimraf profile.log && echo See results in profile.txt",
     "build": "fluid-build . --task build",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "fluid-build . --task api",
+    "build:docs": "api-extractor run --local",
     "build:esnext": "tsc --project ./tsconfig.json",
     "build:test": "npm run build:test:esm && npm run build:test:cjs",
     "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
     "build:test:esm": "tsc --project ./src/test/tsconfig.json",
-    "check:are-the-types-wrong": "attw --pack . --entrypoints .",
+    "check:are-the-types-wrong": "attw --pack .",
+    "check:prettier": "prettier --check . --cache --ignore-path ../../../.prettierignore",
     "check:release-tags": "api-extractor run --local --config ./api-extractor-lint.json",
     "ci:build:docs": "api-extractor run",
-    "clean": "rimraf --glob dist lib \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "clean": "rimraf --glob dist lib \"*.d.ts\" \"**/*.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",
-    "lint": "npm run prettier && npm run check:release-tags && npm run eslint",
-    "lint:fix": "npm run prettier:fix && npm run eslint:fix",
-    "prettier": "prettier --check . --cache --ignore-path ../../../.prettierignore",
-    "prettier:fix": "prettier --write . --cache --ignore-path ../../../.prettierignore",
+    "format": "fluid-build --task format .",
+    "format:prettier": "prettier --write . --cache --ignore-path ../../../.prettierignore",
+    "lint": "fluid-build . --task lint",
+    "lint:fix": "fluid-build . --task eslint:fix --task format",
     "test": "npm run test:mocha",
     "test:benchmark:report": "mocha --recursive \"lib/test/**/*.spec.*js\" --node-option unhandled-rejections=strict,expose-gc --exit --perfMode --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js --timeout 60000",
     "test:coverage": "c8 npm test",

package/api-extractor-cjs.json

@@ -1,8 +0,0 @@
-{
-	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.cjs.primary.json",
-	// CJS is actually secondary; so, no report.
-	"apiReport": {
-		"enabled": false
-	}
-}

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

@@ -1,195 +0,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
- */
-export declare function assert(condition: boolean, message: string | number): asserts condition;
-
-/**
- * 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;
-
-/**
- * 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: isObject */
-
-/* Excluded from this release type: isPromiseLike */
-
-/* Excluded from this release type: ITimer */
-
-/* Excluded from this release type: Lazy */
-
-/**
- * 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.
- * @alpha
- */
-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;
-}
-
-/* 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

@@ -1,45 +0,0 @@
-/* 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: isObject */
-
-/* Excluded from this release type: isPromiseLike */
-
-/* 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

@@ -1,45 +0,0 @@
-/* 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: isObject */
-
-/* Excluded from this release type: isPromiseLike */
-
-/* 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 { }