microsoft/FluidFramework client_v2.53.0

Fluid Framework v2.53.0 (minor)

on GitHub

Contents

• ✨ New Features
  • Adds staged allowed types to SchemaFactoryAlpha (#25116)
  • StateFactory.latestMap now accepts a validator parameter (#25172)
• 🌳 SharedTree DDS Changes
  • TableSchema's "removeColumn" API now removes corresponding cells (alpha) (#25213)
  • Export TreeNode not only as a type (#25226)
• 🐛 Bug Fixes
  • Allow edits in arrays to be concurrent to dependent edits of transactions with violated constraints (#25191)
  • Fixed bug in parsing sensitivity label information from the ODSP join session response (#25186)

✨ New Features

Adds staged allowed types to SchemaFactoryAlpha (#25116)

This adds the staged API to SchemaFactoryAlpha. Staged allowed types can be used for schema evolution to add members to an AllowedTypes while supporting cross version collaboration.

Staged allowed types are allowed types that can be upgraded by schema upgrades. Before being upgraded, any attempt to insert or move a node to a location which requires its type to be upgraded to be valid will throw an error.

To add a new member to an AllowedTypes, add the type wrapped by staged. For example, migrating an array which previously supported only numbers to support both numbers and strings would start by deploying a version of the app using staged:

class TestArray extends schemaFactoryAlpha.arrayAlpha("TestArray", [
  SchemaFactoryAlpha.number,
  SchemaFactoryAlpha.staged(SchemaFactoryAlpha.string),
]) {}

Once enough clients have this code update, it is safe to allow writing strings to the array. To allow writing strings to the array, a code change must be made to remove the staged annotation:

class TestArray extends schemaFactoryAlpha.arrayAlpha("TestArray", [
  schemaFactoryAlpha.number,
  schemaFactoryAlpha.string,
]) {}

Then when opening old documents upgradeSchema is used to upgrade the stored schema:

view.upgradeSchema();

The @alpha API extractPersistedSchema now takes the schema as an ImplicitAnnotatedFieldSchema and an additional parameter to filter which staged upgrades it includes.

Below is a full example of how the schema migration process works. This can also be found in the tests.

// Schema A: only number allowed
const schemaA = SchemaFactoryAlpha.optional([SchemaFactoryAlpha.number]);

// Schema B: number or string (string is staged)
const schemaB = SchemaFactoryAlpha.optional([
  SchemaFactoryAlpha.number,
  SchemaFactoryAlpha.staged(SchemaFactoryAlpha.string),
]);

// Schema C: number or string, both fully allowed
const schemaC = SchemaFactoryAlpha.optional([
  SchemaFactoryAlpha.number,
  SchemaFactoryAlpha.string,
]);

// Initialize with schema A.
const configA = new TreeViewConfiguration({
  schema: schemaA,
});
const viewA = treeA.viewWith(configA);
viewA.initialize(5);

// Since we are running all the different versions of the app in the same process making changes synchronously,
// an explicit flush is needed to make them available to each other.
synchronizeTrees();

assert.deepEqual(viewA.root, 5);

// View the same document with a second tree using schema B.
const configB = new TreeViewConfiguration({
  schema: schemaB,
});
const viewB = treeB.viewWith(configB);
// B cannot write strings to the root.
assert.throws(() => (viewB.root = "test"));

// View the same document with a third tree using schema C.
const configC = new TreeViewConfiguration({
  schema: schemaC,
});
const viewC = treeC.viewWith(configC);
// Upgrade to schema C
viewC.upgradeSchema();
// Use the newly enabled schema.
viewC.root = "test";

synchronizeTrees();

// View A is now incompatible with the stored schema:
assert.equal(viewA.compatibility.canView, false);

// View B can still read the document, and now sees the string root which relies on the staged schema.
assert.deepEqual(viewB.root, "test");

Change details

Commit: 59baf03

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

StateFactory.latestMap now accepts a validator parameter (#25172)

The StateFactory.latestMap API now accepts a validator argument. The validator is a function that will be called at runtime to verify that the data is valid. This is especially useful when changing the schema of presence data.

See the presence documentation for more details.

Change details

Commit: cac39eb

Affected packages:

• @fluidframework/presence

⬆️ Table of contents

🌳 SharedTree DDS Changes

TableSchema's "removeColumn" API now removes corresponding cells (alpha) (#25213)

Previously, the removeColumn API on Table nodes derived from TableSchema (alpha) only removed the Column node from the list of columns tracked by the table. To also remove the corresponding cells from the table (which are stored on the Row nodes), the user was required to write a custom transaction that removed the column and cells.

The motivation for this design was due to performance concerns with transactions. Those concerns are still relevant, but the data leak risk of dropping columns without removing corresponding cells seems a greater risk, and we have plans to address the performance issues with transactions.

Change details

Commit: b665ba8

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Export TreeNode not only as a type (#25226)

TreeNode can now be used as a runtime object. This enables checking if an object is a TreeNode with instanceof. TreeNode has customized instanceof support so it can detect TreeNode instances, even if they hide their prototype like POJO mode nodes do.

Change details

Commit: eefb952

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

🐛 Bug Fixes

Allow edits in arrays to be concurrent to dependent edits of transactions with violated constraints (#25191)

Before this release, making concurrent edits to an array could lead to assertion error 0x8a2 being thrown if the following conditions were met:

• Some edit e1 was a transaction with a constraint that turned out to be violated by edits concurrent to (and sequenced before) e1
• Some edit e2 was dependent on e1 (from before the violation of its constraint)
• Some edit e3 was concurrent to and sequenced after both e1 and e2
• e3 was either concurrent to or the revert of some other edit e0 that predated e1, e2, and e3.
• e0 and e2 made edits to the same gap (that is, in the same space between nodes) in the sequence/array.

After this release, these scenarios will work as expected (that is, no assertion error thrown).

Change details

Commit: ef64bae

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Fixed bug in parsing sensitivity label information from the ODSP join session response (#25186)

Fixes parsing of sensitivity label information in the ODSP join session response. If there had been sensitivity label data present in the ODSP response, this data would have been double-parsed, leading to runtime errors. This issue was so far not hit in practice, because ODSP did not roll out sensitivity labels in the response yet. This bug fix gets odsp-driver ready for that rollout, which is planned to happen soon.

Change details

Commit: b74508f

Affected packages:

• @fluidframework/odsp-driver
• @fluidframework/odsp-driver-definitions

⬆️ Table of contents

🛠️ Start Building Today!

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