fluid-framework 2.1.0-276326 → 2.1.0-281041

package/README.md

@@ -9,6 +9,40 @@ There are some packages there are not included as part of this `fluid-framework`
 -   Fluid Framework [developer tools](https://github.com/microsoft/FluidFramework/tree/main/packages/tools/devtools/devtools).
 -   `@fluidframework/app-insights-logger`: to route Fluid telemetry to Azure App Insights.
 
+<!-- AUTO-GENERATED-CONTENT:START (LIBRARY_PACKAGE_README_HEADER) -->
+
+<!-- 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's public APIs, 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 `^`.
+
+If using any of Fluid Framework's unstable APIs (for example, its `beta` APIs), we recommend using a more constrained version range, such as `~`.
+
+## Installation
+
+To get started, install the package by running the following command:
+
+```bash
+npm i fluid-framework
+```
+
+## Importing from this package
+
+This package leverages [package.json exports](https://nodejs.org/api/packages.html#exports) to separate its APIs by support level.
+For more information on the related support guarantees, see [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
+
+To access the `public` ([SemVer](https://semver.org/)) APIs, import via `fluid-framework` like normal.
+
+To access the `legacy` APIs, import via `fluid-framework/legacy`.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
 ## Contents
 
 The `fluid-framework` package consists primarily of two portions: the `IFluidContainer` and a selection of distributed data structures (DDSes).
@@ -31,37 +65,58 @@ The `fluid-framework` package offers the following data structures:
 
 Check out the [Hello World tutorial](https://fluidframework.com/docs/start/tutorial/) using `fluid-framework`.
 
-<!-- AUTO-GENERATED-CONTENT:START (LIBRARY_PACKAGE_README:scripts=FALSE) -->
+<!-- AUTO-GENERATED-CONTENT:START (LIBRARY_PACKAGE_README_FOOTER) -->
 
 <!-- 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
+## API Documentation
 
-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 `^`.
+API documentation for **fluid-framework** is available at <https://fluidframework.com/docs/apis/fluid-framework>.
 
-## Installation
+## Minimum Client Requirements
 
-To get started, install the package by running the following command:
+These are the platform requirements for the current version of Fluid Framework Client Packages.
+These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter.
+For Long Term Support (LTS) versions this can require supporting these platforms for several years.
 
-```bash
-npm i fluid-framework
-```
+It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug.
+If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request.
+When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working.
 
-## Importing from this package
+### Supported Runtimes
 
-This package leverages [package.json exports](https://nodejs.org/api/packages.html#exports) to separate its APIs by support level.
-For more information on the related support guarantees, see [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
+-   NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30).
+-   Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards).
 
-To access the `public` ([SemVer](https://semver.org/)) APIs, import via `fluid-framework` like normal.
+### Supported Tools
 
-To access the `legacy` APIs, import via `fluid-framework/legacy`.
+-   TypeScript 5.4:
+    -   All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported.
+    -   [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required.
+    -   [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported.
+    -   `exactOptionalPropertyTypes` is currently not fully supported.
+        If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases.
+-   [webpack](https://webpack.js.org/) 5
+    -   We are not intending to be prescriptive about what bundler to use.
+        Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test.
 
-## API Documentation
+### Module Resolution
 
-API documentation for **fluid-framework** is available at <https://fluidframework.com/docs/apis/fluid-framework>.
+[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
+Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development.
+
+### Module Formats
+
+-   ES Modules:
+    ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported.
+-   CommonJs:
+    Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below.
+    This is done to accommodate some workflows without good ES Module support.
+    If you have a workflow you would like included in this list, file an issue.
+    Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here.
+
+    -   Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648))
 
 ## Contribution Guidelines
 
@@ -83,11 +138,9 @@ Use of Microsoft trademarks or logos in modified versions of this project must n
 
 ## Help
 
-Not finding what you're looking for in this README? Check out our [GitHub
-Wiki](https://github.com/microsoft/FluidFramework/wiki) or [fluidframework.com](https://fluidframework.com/docs/).
+Not finding what you're looking for in this README? Check out [fluidframework.com](https://fluidframework.com/docs/).
 
-Still not finding what you're looking for? Please [file an
-issue](https://github.com/microsoft/FluidFramework/wiki/Submitting-Bugs-and-Feature-Requests).
+Still not finding what you're looking for? Please [file an issue](https://github.com/microsoft/FluidFramework/wiki/Submitting-Bugs-and-Feature-Requests).
 
 Thank you!
 

package/api-extractor/api-extractor-lint-legacy.cjs.json

@@ -1,5 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/dist/legacy.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/dist/legacy.d.ts",
+	"bundledPackages": ["@fluidframework/*"]
 }

package/api-extractor/api-extractor-lint-legacy.esm.json

@@ -1,5 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/legacy.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/legacy.d.ts",
+	"bundledPackages": ["@fluidframework/*"]
 }

package/api-extractor/api-extractor-lint-public.cjs.json

@@ -1,5 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/dist/public.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/dist/public.d.ts",
+	"bundledPackages": ["@fluidframework/*"]
 }

package/api-extractor/api-extractor-lint-public.esm.json

@@ -1,5 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts",
+	"bundledPackages": ["@fluidframework/*"]
 }

package/api-extractor/api-extractor.current.json

@@ -0,0 +1,6 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.current.json",
+	"mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts",
+	"bundledPackages": ["@fluidframework/*"]
+}

package/api-extractor/api-extractor.legacy.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-base.esm.legacy.json",
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.legacy.json",
 	"bundledPackages": ["@fluidframework/*"]
 }

package/api-extractor.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json",
+	"extends": "../../../common/build/build-common/api-extractor-model.esm.json",
 	"bundledPackages": ["@fluidframework/*"],
 	"messages": {
 		"extractorMessageReporting": {

package/api-report/fluid-framework.beta.api.md

@@ -682,6 +682,7 @@ type ScopedSchemaName<TScope extends string | undefined, TName extends number |
 
 // @public @sealed
 export interface SharedObjectKind<out TSharedObject = unknown> extends ErasedType<readonly ["SharedObjectKind", TSharedObject]> {
+    is(value: IFluidLoadable): value is IFluidLoadable & TSharedObject;
 }
 
 // @public
@@ -741,6 +742,7 @@ interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom> extends ReadonlyArray<
     moveToStart(sourceIndex: number, source: TMoveFrom): void;
     removeAt(index: number): void;
     removeRange(start?: number, end?: number): void;
+    values(): IterableIterator<T>;
 }
 
 // @public @sealed

package/api-report/fluid-framework.legacy.alpha.api.md

@@ -148,7 +148,7 @@ export interface IConnection {
 // @public
 export type ICriticalContainerError = IErrorBase;
 
-// @alpha
+// @public @sealed
 export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryEvents>, Partial<IDisposable> {
     readonly absolutePath: string;
     countSubDirectory?(): number;
@@ -162,7 +162,7 @@ export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryE
     subdirectories(): IterableIterator<[string, IDirectory]>;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectoryEvents extends IEvent {
     (event: "containedValueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
     (event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
@@ -171,7 +171,7 @@ export interface IDirectoryEvents extends IEvent {
     (event: "undisposed", listener: (target: IEventThisPlaceHolder) => void): any;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectoryValueChanged extends IValueChanged {
     path: string;
 }
@@ -682,7 +682,7 @@ export interface IServiceAudienceEvents<M extends IMember> extends IEvent {
     (event: "memberRemoved", listener: MemberChangedListener<M>): void;
 }
 
-// @alpha
+// @alpha @sealed
 export interface ISharedDirectory extends ISharedObject<ISharedDirectoryEvents & IDirectoryEvents>, Omit<IDirectory, "on" | "once" | "off"> {
     // (undocumented)
     [Symbol.iterator](): IterableIterator<[string, any]>;
@@ -690,7 +690,7 @@ export interface ISharedDirectory extends ISharedObject<ISharedDirectoryEvents &
     readonly [Symbol.toStringTag]: string;
 }
 
-// @alpha
+// @alpha @sealed
 export interface ISharedDirectoryEvents extends ISharedObjectEvents {
     (event: "valueChanged", listener: (changed: IDirectoryValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
     (event: "clear", listener: (local: boolean, target: IEventThisPlaceHolder) => void): any;
@@ -830,7 +830,7 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
-// @alpha @sealed
+// @public @sealed
 export interface IValueChanged {
     readonly key: string;
     readonly previousValue: any;
@@ -1075,6 +1075,7 @@ export type SharedMap = ISharedMap;
 
 // @public @sealed
 export interface SharedObjectKind<out TSharedObject = unknown> extends ErasedType<readonly ["SharedObjectKind", TSharedObject]> {
+    is(value: IFluidLoadable): value is IFluidLoadable & TSharedObject;
 }
 
 // @alpha
@@ -1151,6 +1152,7 @@ interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom> extends ReadonlyArray<
     moveToStart(sourceIndex: number, source: TMoveFrom): void;
     removeAt(index: number): void;
     removeRange(start?: number, end?: number): void;
+    values(): IterableIterator<T>;
 }
 
 // @public @sealed
@@ -1301,6 +1303,4 @@ export interface WithType<TName extends string = string> {
     get [typeNameSymbol](): TName;
 }
 
-// (No @packageDocumentation comment for this package)
-
 ```