# Fluid Framework v2.43.0 ## Contents - [🚨 Breaking Changes](#-breaking-changes) - [The reason parameter on the disconnect event is now optional to allow for clean, non-error disconnections (#24840)](#the-reason-parameter-on-the-disconnect-event-is-now-optional-to-allow-for-clean-non-error-disconnections-24840) - [✨ New Features](#-new-features) - [Persisted metadata for Shared Tree schemas (Alpha) (#24812)](#persisted-metadata-for-shared-tree-schemas-alpha-24812) - [🌳 SharedTree DDS Changes](#-sharedtree-dds-changes) - [Tree's enum schema utility are now beta (#24749)](#trees-enum-schema-utility-are-now-beta-24749) - [Add TreeAlpha.child and TreeAlpha.children APIs for generic tree traversal (#24723)](#add-treealphachild-and-treealphachildren-apis-for-generic-tree-traversal-24723) - [Improved Schema Validation (#24866)](#improved-schema-validation-24866) - [Rename and change type of annotatedAllowedTypeSet on FieldSchemaAlpha to more closely align with allowedTypesSet (#24820)](#rename-and-change-type-of-annotatedallowedtypeset-on-fieldschemaalpha-to-more-closely-align-with-allowedtypesset-24820) - [⚠️ Deprecations](#️-deprecations) - [Deprecate unnecessary and internal APIs in `ISequenceIntervalCollection` and related interval types (#24792)](#deprecate-unnecessary-and-internal-apis-in-isequenceintervalcollection-and-related-interval-types-24792) - [Legacy API Changes](#legacy-api-changes) - [Added an optional boolean parameter "fullTree" to SharedObject's summarizeCore method (#24761)](#added-an-optional-boolean-parameter-fulltree-to-sharedobjects-summarizecore-method-24761) ## 🚨 Breaking Changes ### The reason parameter on the disconnect event is now optional to allow for clean, non-error disconnections ([#24840](https://github.com/microsoft/FluidFramework/issues/24840)) To enable better handling of intentional disconnects (for example [`Container.dispose()`](https://fluidframework.com/docs/api/container-loader/container/dispose)), the `reason` parameter of the `disconnect` event on [`IDocumentDeltaConnectionEvents`](https://fluidframework.com/docs/api/driver-definitions/idocumentdeltaconnectionevents) is being deprecated as a required parameter. In a future release, the `reason` parameter will become optional. **Old signature:** ```typescript listener: (reason: IAnyDriverError) => void ``` **New signature:** ```typescript listener: (reason?: IAnyDriverError) => void ``` Developers with listeners for the `disconnect` event should update their implementations to handle cases where the `reason` parameter is `undefined`. This indicates a clean disconnect, which should not be treated as an error. The breaking change is scheduled to be released in version **2.60**. #### Change details Commit: [`82a1c5a`](https://github.com/microsoft/FluidFramework/commit/82a1c5a1362d3362886bdcc12859ce60a2744bdb) Affected packages: - @fluidframework/container-loader - @fluidframework/driver-base - @fluidframework/driver-definitions [⬆️ Table of contents](#contents) ## ✨ New Features ### Persisted metadata for Shared Tree schemas (Alpha) ([#24812](https://github.com/microsoft/FluidFramework/issues/24812)) The persisted metadata feature for Shared Tree allows an application author to write document-persisted metadata along with the schema. This feature is supported for both node and field schemas. #### Using the persisted metadata feature As of now, persisted metadata support is available via the SchemaFactoryAlpha API: ```ts // Construct a schema factory with alpha APIs const schemaFactory = new SchemaFactoryAlpha("com.example"); ``` Persisted metadata can take the shape of any JSON-serializable object, e.g.: ```ts const persistedMetadata = { a: 2 }; ``` #### Feature flag To enable persisted metadata, use `configuredSharedTree` to specify the format version. The tree that is returned can be substituted in place of the default `SharedTree` object exported by the Fluid Framework. For example: ```ts const tree = configuredSharedTree({ formatVersion: SharedTreeFormatVersion.v5, }).create(runtime); export const MyContainerSchema = { initialObjects: { appData: tree, }, } satisfies ContainerSchema; ``` #### Examples ##### Field schemas with persisted metadata ```ts // Construct a schema factory with alpha APIs const schemaFactory = new SchemaFactoryAlpha("com.example"); // Define metadata. This can take the shape of any JSON-serializable object. const persistedMetadata = { a: 2 }; // Foo is an object type with metadata class Foo extends schemaFactory.objectAlpha( "Foo", { // Metadata for a required number field bar: schemaFactory.required(schemaFactory.number, { persistedMetadata }), // Metadata for an optional string field baz: schemaFactory.optional(schemaFactory.string, { persistedMetadata }), // Metadata for the object type Foo }, { persistedMetadata }, ) {} ``` ##### Recursive field schemas ```ts // Construct a schema factory with alpha APIs const schemaFactory = new SchemaFactoryAlpha("com.example"); // Define metadata. This can take the shape of any JSON-serializable object. const persistedMetadata = { a: 2 }; // Recursive object schema with persisted metadata class RecursiveObject extends schemaFactory.objectRecursive( "RecursiveObject", { x: [() => RecursiveObject, schemaFactory.number], }, { persistedMetadata }, ) {} // Recursive field schema with metadata const recursiveField = schemaFactory.optionalRecursive( [() => RecursiveObject, schemaFactory.number], { persistedMetadata }, ); ``` ##### Recursive object schemas ```ts // Construct a schema factory with alpha APIs const schemaFactory = new SchemaFactoryAlpha("com.example"); // Define metadata. This can take the shape of any JSON-serializable object. const persistedMetadata = { a: 2 }; // Recursive array schema class Foos extends schemaFactory.arrayRecursive("FooList", [() => Foo], { persistedMetadata, }) {} // Recursive object schema class Foo extends schemaFactory.objectRecursive( "Foo", { fooList: Foos }, { persistedMetadata }, ) {} // Recursive map schema class FooMap extends schemaFactory.mapRecursive("FooMap", [() => Foo], { persistedMetadata, }) {} ``` #### Change details Commit: [`3f81ab5`](https://github.com/microsoft/FluidFramework/commit/3f81ab52ff7265a8533c0e192c8b77d298b70eea) Affected packages: - fluid-framework - @fluidframework/tree [⬆️ Table of contents](#contents) ## 🌳 SharedTree DDS Changes ### Tree's enum schema utility are now beta ([#24749](https://github.com/microsoft/FluidFramework/issues/24749)) The functions [singletonSchema](https://fluidframework.com/docs/api/tree/#singletonschema-function), [adaptEnum](https://fluidframework.com/docs/api/tree/#adaptenum-function) and [enumFromStrings](https://fluidframework.com/docs/api/tree/#enumfromstrings-function) are now `@beta` instead of `@alpha`. #### Change details Commit: [`a23bc9e`](https://github.com/microsoft/FluidFramework/commit/a23bc9e4d025f0925d09daadc2952bf0bfacc06b) Affected packages: - fluid-framework - @fluidframework/tree [⬆️ Table of contents](#contents) ### Add TreeAlpha.child and TreeAlpha.children APIs for generic tree traversal ([#24723](https://github.com/microsoft/FluidFramework/issues/24723)) #### TreeAlpha.child Access a child node or value of a `TreeNode` by its property key. ```typescript class MyObject extends schemaFactory.object("MyObject", { foo: schemaFactory.string; bar: schemaFactory.optional(schemaFactory.string); }) {} const myObject = new MyObject({ foo: "Hello world!" }); const foo = TreeAlpha.child(myObject, "foo"); // "Hello world!" const bar = TreeAlpha.child(myObject, "bar"); // undefined const baz = TreeAlpha.child(myObject, "baz"); // undefined ``` ```typescript class MyArray extends schemaFactory.array("MyArray", schemaFactory.string) {} const myArray = new MyArray("Hello", "World"); const child0 = TreeAlpha.child(myArray, 0); // "Hello" const child1 = TreeAlpha.child(myArray, 1); // "World const child2 = TreeAlpha.child(myArray, 2); // undefined ``` #### TreeAlpha.children Get all child nodes / values of a `TreeNode`, keyed by their property keys. ```typescript class MyObject extends schemaFactory.object("MyObject", { foo: schemaFactory.string; bar: schemaFactory.optional(schemaFactory.string); baz: schemaFactory.optional(schemaFactory.number); }) {} const myObject = new MyObject({ foo: "Hello world!", baz: 42, }); const children = TreeAlpha.children(myObject); // [["foo", "Hello world!"], ["baz", 42]] ``` ```typescript class MyArray extends schemaFactory.array("MyArray", schemaFactory.string) {} const myArray = new MyArray("Hello", "World"); const children = TreeAlpha.children(myObject); // [[0, "Hello"], [1, "World"]] ``` #### Change details Commit: [`87941b7`](https://github.com/microsoft/FluidFramework/commit/87941b7fa0575e030344079a25f65d25d8457367) Affected packages: - @fluidframework/tree - fluid-framework [⬆️ Table of contents](#contents) ### Improved Schema Validation ([#24866](https://github.com/microsoft/FluidFramework/issues/24866)) When constructing a [`TreeViewConfiguration`](https://fluidframework.com/docs/api/fluid-framework/treeviewconfiguration-class), the same schema listed more than once in a given [`AllowedTypes`](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias) is now an error even when [`preventAmbiguity`](https://fluidframework.com/docs/api/fluid-framework/treeviewconfiguration-class#preventambiguity-property) is false. Previously a bug resulted in this only being rejected when `preventAmbiguity` was true. #### Change details Commit: [`caae4ae`](https://github.com/microsoft/FluidFramework/commit/caae4ae15edeb8aeae33b0520b18dbb1993965f6) Affected packages: - fluid-framework - @fluidframework/tree [⬆️ Table of contents](#contents) ### Rename and change type of annotatedAllowedTypeSet on FieldSchemaAlpha to more closely align with allowedTypesSet ([#24820](https://github.com/microsoft/FluidFramework/issues/24820)) This changes the `annotatedAllowedTypeSet` property on [`FieldSchemaAlpha`](https://fluidframework.com/docs/api/fluid-framework/fieldschemaalpha-class). It is now called `annotatedAllowedTypesNormalized` and stores evaluated schemas along with their annotations in a list of objects rather than as a mapping from the schemas to their annotations. This makes the API easier to use and better aligns with the current public APIs. #### Change details Commit: [`f4e8dc8`](https://github.com/microsoft/FluidFramework/commit/f4e8dc8cd09f052f21e436e2c0584a1a34d2be77) Affected packages: - fluid-framework - @fluidframework/tree [⬆️ Table of contents](#contents) ## ⚠️ Deprecations ### Deprecate unnecessary and internal APIs in `ISequenceIntervalCollection` and related interval types ([#24792](https://github.com/microsoft/FluidFramework/issues/24792)) The following APIs are now deprecated and will be removed in a future release: - `IInterval.clone` - `IInterval.modify` - `IInterval.union` - `ISerializableInterval` - `SequenceInterval.clone` - `SequenceInterval.modify` - `SequenceInterval.union` - `SequenceInterval.serialize` - `SequenceInterval.addPositionChangeListeners` - `SequenceInterval.removePositionChangeListeners` These APIs were never intended for public use. There is no migration path, and any usage is strongly discouraged, as it may result in severe errors or data corruption. Please remove any dependencies on these APIs as soon as possible. #### Change details Commit: [`8acc591`](https://github.com/microsoft/FluidFramework/commit/8acc59162acb0f12f996d756111ae3cb79ea6104) Affected packages: - @fluidframework/sequence [⬆️ Table of contents](#contents) ## Legacy API Changes ### Added an optional boolean parameter "fullTree" to SharedObject's summarizeCore method ([#24761](https://github.com/microsoft/FluidFramework/issues/24761)) This parameter tells the shared object that it should generate a full tree summary, i.e., it must not summarize incrementally. Currently no known `SharedObject`'s do incremental summaries; however, any that do exist or are made in the future must take this "fullTree" parameter into consideration to function correctly. #### Change details Commit: [`1e24967`](https://github.com/microsoft/FluidFramework/commit/1e24967a8f943b0616d765c253fe079fc9c43619) Affected packages: - @fluidframework/shared-object-base [⬆️ Table of contents](#contents) ### 🛠️ Start Building Today! Please continue to engage with us on GitHub [Discussion](https://github.com/microsoft/FluidFramework/discussions) and [Issue](https://github.com/microsoft/FluidFramework/issues) pages as you adopt Fluid Framework!