Upcoming Release: FluidFramework v2.4.0

[tylerbutler]

This issue is automatically updated with a preview of the release notes for the upcoming Fluid Framework release.

To generate release notes locally to commit to the RELEASE_NOTES folder in the repo, run the following command:

pnpm flub generate releaseNotes -g client -t minor --outFile RELEASE_NOTES/2.4.0.md

To generate the release notes to paste into the GitHub Release, run the following command:

pnpm flub generate releaseNotes -g client -t minor --headingLinks --excludeH1 --outFile temporary-file.md

You can then copy and paste the contents of the temporary-file.md into the GitHub Release.

---

Fluid Framework v2.4.0

Contents

• ✨ New Features
  • Add (alpha) SharedTree branching APIs (#22594)
• 🌳 SharedTree DDS changes
  • Exposes the view schema from the TreeView interface. (#22594)
  • Allow associating metadata with Field Schema (#22594)
  • RestrictiveReadonlyRecord is deprecated (#22594)
  • Fix .create on structurally named MapNode and ArrayNode schema (#22594)
  • Branch merges generate revertibles (#22644)
  • Unhydrated SharedTree nodes emit change events when edited (#22661)
  • Optimize non-leaf field access (#22717)
  • Add alpha API for providing SharedTree configuration options (#22701)
  • Add alpha API for snapshotting Schema (#22733)
  • Fix reading of null from unhydrated trees (#22748)
• ⚠️ Deprecations
  • Further MergeTree Client Legacy Deprecations (#22629)
• Unknown section: _unknown
  • Expose experimental alpha APIs for producing schema from enums (#20035)

✨ New Features

Add (alpha) SharedTree branching APIs (#22594)

This adds a handful of APIs to allow for creating and coordinating "version-control"-style branches of the SharedTree. Use the getBranch entry point function to acquire a branch. For example:

function makeEditOnBranch(mainView: TreeView<typeof MySchema>) {
  mainView.root.myData = 3;
  const mainBranch = getBranch(mainView); // This function accepts either a view of a SharedTree (acquired e.g. via `sharedTree.viewWith(...)`) or a `SharedTree` directly.
  const forkBranch = mainBranch.branch(); // This creates a new branch based on the existing branch.
  const forkView = forkBranch.viewWith(
    new TreeViewConfiguration({ schema: MySchema }),
  ); // Acquire a view of the forked branch in order to read or edit its tree.
  forkView.root.myData = 4; // Set the value on the fork branch to be 4. The main branch still has a value of 3.
  mainBranch.merge(forkBranch); // Merging the fork changes into the main branch causes the main branch to have a value of 4.

  // Note: The main branch (and therefore, also the `forkView`) is automatically disposed by the merge.
  // To prevent this, use `mainBranch.merge(forkBranch, false)`.
}

Change details

Commit: ff1b2c7

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

🌳 SharedTree DDS changes

Exposes the view schema from the TreeView interface. (#22594)

Users of TreeView can now access the type-safe view schema directly on the view object via TreeView.schema. This allows users to avoid passing the schema around in addition to the view in scenarios where both are needed. It also avoids scenarios in which code wants to accept both a view and its schema and thus must constrain both to be of the same schema type.

Change details

Commit: ff1b2c7

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Allow associating metadata with Field Schema (#22594)

Users of TreeView can now specify metadata when creating Field Schema. This includes system-understood metadata, i.e., description.

Example:

class Point extends schemaFactory.object("Point", {
  x: schemaFactory.required(schemaFactory.number, {
    metadata: { description: "The horizontal component of the point." },
  }),
  y: schemaFactory.required(schemaFactory.number, {
    metadata: { description: "The vertical component of the point." },
  }),
}) {}

Functionality like the experimental conversion of Tree Schema to JSON Schema. (getJsonSchema) can leverage such system-understood metadata to generate useful information. In the case of the description property, this is mapped directly to the description property supported by JSON Schema.

Custom, user-defined properties can also be specified. These properties will not be leveraged by the system by default, but can be used as a handy means of associating common application-specific properties with Field Schema.

Example:

An application is implementing search functionality. By default, the app author wishes for all app content to be potentially indexable by search, unless otherwise specified. They can leverage schema metadata to decorate fields that should be ignored by search, and leverage that information when walking the tree during a search.

interface AppMetadata {
	/**
	 * Whether or not the field should be ignored by search.
	 * @defaultValue `false`
	 */
	searchIgnore?: boolean;
}

class Note extends schemaFactory.object("Note", {
	position: schemaFactory.required(Point, {
		metadata: {
			description: "The position of the upper-left corner of the note."
			custom: {
				// Search doesn't care where the note is on the canvas.
				// It only cares about the text content.
				searchIgnore: true
			}
		}
	}),
	text: schemaFactory.required(schemaFactory.string, {
		metadata: {
			description: "The textual contents of the note."
		}
	}),
}) {}

Search can then be implemented to look for the appropriate metadata, and leverage it to omit the unwanted position data from search.

Change details

Commit: ff1b2c7

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

RestrictiveReadonlyRecord is deprecated (#22594)

RestrictiveReadonlyRecord was an attempt to implement a version of the built-in Record<TKey, TValue> type that would prohibit (instead of leaving unrestricted like Record does) values under keys that do not extend TKey.

The implementation of RestrictiveReadonlyRecord failed to accomplish this except for the edge cases where TKey was exactly string or exactly symbol. Fixing this bug appears to be impossible within the current limitation of TypeScript, however this library does not require any case other than TKey being exactly string.

To reduce the risk of users of the tree library using the problematic RestrictiveReadonlyRecord type, it has been deprecated and replaced with a more specific type that avoids the bug, RestrictiveStringRecord<TValue>.

To highlight that this new type is not intended for direct use by users of tree, and instead is just used as part of the typing of its public API, RestrictiveStringRecord has been tagged with @system. See API Support Levels for more details.

Change details

Commit: ff1b2c7

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Fix .create on structurally named MapNode and ArrayNode schema (#22594)

Constructing a structurally named MapNode or ArrayNode schema (using the overload of SchemaFactory.map or SchemaFactory.array which does not take an explicit name), returned a TreeNodeSchema instead of a TreeNodeSchemaNonClass, which resulted in the create static method not being exposed. This has been fixed, and can now be used as follows:

const MyMap = schemaFactory.map(schemaFactory.number);
type MyMap = NodeFromSchema<typeof MyMap>;
const _fromMap: MyMap = MyMap.create(new MyMap());
const _fromIterable: MyMap = MyMap.create([]);
const _fromObject: MyMap = MyMap.create({});

This change causes some types to reference TreeNodeSchemaNonClass which did not reference it before. While TreeNodeSchemaNonClass is @system (See releases-and-apitags for details) and thus not intended to be referred to by users of Fluid, this change caused the TypeScript compiler to generate references to it in more cases when compiling d.ts files. Since the TypeScript compiler is unable to generate references to TreeNodeSchemaNonClass with how it was nested in internalTypes.js, this change could break the build of packages exporting types referencing structurally named map and array schema. This has been mitigated by moving TreeNodeSchemaNonClass out of internalTypes.js: any code importing TreeNodeSchemaNonClass (and thus disregarding the @system restriction) can be fixed by importing it from the top level instead of the internalTypes.js

Change details

Commit: ff1b2c7

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Branch merges generate revertibles (#22644)

Merging any number of commits into a target branch (via the 'merge' method) now generates a revertible for each commit on the target branch.

Change details

Commit: c168c6f

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Unhydrated SharedTree nodes emit change events when edited (#22661)

Newly-created SharedTree nodes which have not yet been inserted into the tree will now emit nodeChanged and treeChanged events when they are mutated via editing operations.

const node = new Foo({ foo: 3 });
Tree.on(node, "nodeChanged", () => {
  console.log("This will fire even before node is inserted!");
});

node.foo = 4; // log: "This will fire even before node is inserted!";

Change details

Commit: d1eade6

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Optimize non-leaf field access (#22717)

When reading non-leaf children which have been read previously, they are retrieved from cache faster. Several operations on subtrees under arrays have been optimized, including reading of non-leaf nodes for the first time. Overall this showed a roughly 5% speed up in a read heavy test application (the BubbleBench example) but gains are expected to vary a lot based on use-case.

Change details

Commit: 6a2b681

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Add alpha API for providing SharedTree configuration options (#22701)

A new alpha configuredSharedTree had been added. This allows providing configuration options, primarily for debugging, testing and evaluation of upcoming features. The resulting configured SharedTree object can then be used in-place of the regular SharedTree imported from fluid-framework.

import {
  ForestType,
  TreeCompressionStrategy,
  configuredSharedTree,
  typeboxValidator,
} from "@fluid-framework/alpha";
// Maximum debuggability and validation enabled:
const SharedTree = configuredSharedTree({
  forest: ForestType.Expensive,
  jsonValidator: typeboxValidator,
  treeEncodeType: TreeCompressionStrategy.Uncompressed,
});
// Opts into the under development optimized tree storage planned to be the eventual default implementation:
const SharedTree = configuredSharedTree({
  forest: ForestType.Optimized,
});

Change details

Commit: 40d3648

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Add alpha API for snapshotting Schema (#22733)

extractPersistedSchema can now be used to extra a JSON compatible representation of the subset of a schema that gets stored in documents. This can be used write tests which snapshot an applications schema. Such tests can be used to detect schema changes which could would impact document compatibility, and can be combined with the new comparePersistedSchema to measure what kind of compatibility impact the schema change has.

Change details

Commit: 920a65f

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Fix reading of null from unhydrated trees (#22748)

Unhydrated trees containing object nodes with required fields set to null used to throw an error. This was a bug: null is a valid value in tree's whose schema allow it, and this specific case now correctly returns null values when appropriate without erroring.

Change details

Commit: 6a75bd0

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

⚠️ Deprecations

Further MergeTree Client Legacy Deprecations (#22629)

To reduce exposure of the Client class in the merge-tree package, several types have been deprecated. These types directly or indirectly expose the merge-tree Client class.

Most of these types are not meant to be used directly, and direct use is not supported:

• AttributionPolicy
• IClientEvents
• IMergeTreeAttributionOptions
• SharedSegmentSequence
• SharedStringClass

Some of the deprecations are class constructors. In those cases, we plan to replace the class with an interface which has an equivalent API. Direct instantiation of these classes is not currently supported or necessary for any supported scenario, so the change to an interface should not impact usage. This applies to the following types:

• SequenceInterval
• SequenceEvent
• SequenceDeltaEvent
• SequenceMaintenanceEvent

Change details

Commit: 0b59ae8

Affected packages:

• @fluidframework/merge-tree
• @fluidframework/sequence

⬆️ Table of contents

Unknown section: _unknown

Expose experimental alpha APIs for producing schema from enums (#20035)

adaptEnum and enumFromStrings have been added to @fluidframework/tree/alpha and fluid-framework/alpha. These unstable alpha APIs are relatively simple helpers on-top of public APIs (source: schemaCreationUtilities.ts): thus if these change or stable alternatives are needed, an application can replicate this functionality using these implementations as an example.

Change details

Commit: 5f9bbe0

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

🛠️ Start Building Today!

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