microsoft/FluidFramework client_v2.43.0

Fluid Framework v2.43.0 (minor)

on GitHub

Contents

• 🚨 Breaking Changes
  • The reason parameter on the disconnect event is now optional to allow for clean, non-error disconnections (#24840)
• ✨ New Features
  • Persisted metadata for Shared Tree schemas (Alpha) (#24812)
• 🌳 SharedTree DDS Changes
  • Tree's enum schema utility are now beta (#24749)
  • Add TreeAlpha.child and TreeAlpha.children APIs for generic tree traversal (#24723)
  • Improved Schema Validation (#24866)
  • Rename and change type of annotatedAllowedTypeSet on FieldSchemaAlpha to more closely align with allowedTypesSet (#24820)
• ⚠️ Deprecations
  • Deprecate unnecessary and internal APIs in ISequenceIntervalCollection and related interval types (#24792)
• Legacy API Changes
  • Added an optional boolean parameter "fullTree" to SharedObject's summarizeCore method (#24761)

🚨 Breaking Changes

The reason parameter on the disconnect event now accepts undefined to allow for clean, non-error disconnections (#24840)

To enable better handling of intentional disconnects (for example Container.dispose()), the reason parameter of the disconnect event on IDocumentDeltaConnectionEvents now accepts undefined as a valid value.

Old signature:

listener: (reason: IAnyDriverError) => void

New signature:

listener: (reason: IAnyDriverError | undefined) => 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

Affected packages:

• @fluidframework/container-loader
• @fluidframework/driver-base
• @fluidframework/driver-definitions

⬆️ Table of contents

✨ New Features

Persisted metadata for Shared Tree schemas (Alpha) (#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:

// 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.:

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:

const tree = configuredSharedTree({
  formatVersion: SharedTreeFormatVersion.v5,
}).create(runtime);

export const MyContainerSchema = {
  initialObjects: {
    appData: tree,
  },
} satisfies ContainerSchema;

Examples

Field schemas with persisted metadata

// 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

// 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

// 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

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

🌳 SharedTree DDS Changes

Tree's enum schema utility are now beta (#24749)

The functions singletonSchema, adaptEnum and enumFromStrings are now @beta instead of @alpha.

Change details

Commit: a23bc9e

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Add TreeAlpha.child and TreeAlpha.children APIs for generic tree traversal (#24723)

TreeAlpha.child

Access a child node or value of a TreeNode by its property key.

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

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.

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]]

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

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Improved Schema Validation (#24866)

When constructing a TreeViewConfiguration, the same schema listed more than once in a given AllowedTypes is now an error even when preventAmbiguity is false. Previously a bug resulted in this only being rejected when preventAmbiguity was true.

Change details

Commit: caae4ae

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Rename and change type of annotatedAllowedTypeSet on FieldSchemaAlpha to more closely align with allowedTypesSet (#24820)

This changes the annotatedAllowedTypeSet property on FieldSchemaAlpha. 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

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

⚠️ Deprecations

Deprecate unnecessary and internal APIs in ISequenceIntervalCollection and related interval types (#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

Affected packages:

• @fluidframework/sequence

⬆️ Table of contents

Legacy API Changes

Added an optional boolean parameter "fullTree" to SharedObject's summarizeCore method (#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

Affected packages:

• @fluidframework/shared-object-base

⬆️ Table of contents

🛠️ Start Building Today!

Please continue to engage with us on GitHub Discussion and Issue pages as you adopt Fluid Framework!