build(client): Generate release notes for 2.4.0

[tylerbutler]

Generated release notes for the 2.4 release. A preview of the generated notes is below. The notes were generated using the following command:

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

---

Fluid Framework v2.4.0

Contents

• 🌳 SharedTree DDS changes
  • ✨ New! Alpha SharedTree branching APIs (#22550)
  • ✨ New! Alpha API for providing SharedTree configuration options (#22701)
  • ✨ New! Alpha APIs for producing SharedTree schema from enums (#20035)
  • ✨ New! Alpha API for snapshotting Schema (#22733)
  • Expose the view schema from the TreeView interface (#22547)
  • Metadata can now be associated with Field Schema (#22564)
  • Unhydrated SharedTree nodes now emit change events when edited (#22661)
  • Non-leaf field access has been optimized (#22717)
• 🐛 Bug Fixes
  • Fix .create on structurally named MapNode and ArrayNode schema (#22522)
  • Fix reading of null from unhydrated trees (#22748)
• ⚠️ Deprecations
  • SharedTree's RestrictiveReadonlyRecord is deprecated (#22479)
  • Several MergeTree Client Legacy APIs are now deprecated (#22629)
  • The op.contents member on ContainerRuntime's batchBegin/batchEnd event args is deprecated (#22750)

🌳 SharedTree DDS changes

✨ New! Alpha SharedTree branching APIs (#22550)

Several APIs have been added 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)`.
}

Merging any number of commits into a target branch (via the TreeBranch.merge method) generates a revertible for each commit on the target branch. See #22644 for more information about revertible support in the branching APIs.

Change details

Commit: 8f4587c

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

✨ New! 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

✨ New! Alpha APIs for producing SharedTree 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

✨ New! 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

Expose the view schema from the TreeView interface (#22547)

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: 2aa29d9

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Metadata can now be associated with Field Schema (#22564)

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 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: 1d9f4c9

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Unhydrated SharedTree nodes now 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

Non-leaf field access has been optimized (#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

🐛 Bug Fixes

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

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 Fluid Releases and API Support Levels 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: b3f91ae

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

SharedTree's RestrictiveReadonlyRecord is deprecated (#22479)

RestrictiveReadonlyRecord was an attempt to implement a version of TypeScript's 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: 8be73d3

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Several MergeTree Client Legacy APIs are now deprecated (#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

The op.contents member on ContainerRuntime's batchBegin/batchEnd event args is deprecated (#22750)

The batchBegin/batchEnd events on ContainerRuntime indicate when a batch is beginning/finishing being processed. The events include an argument of type ISequencedDocumentMessage which is the first or last message of the batch.

The contents property of the op argument should not be used when reasoning over the begin/end of a batch. If you want to look at the contents of an op, wait for the op event.

Change details

Commit: de6928b

Affected packages:

• @fluidframework/container-runtime

⬆️ Table of contents

🛠️ Start Building Today!

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

[tylerbutler]

@noencke Is this referring to the alpha branching APIs that were added in this same release? I'm wondering if we should collapse this information into the announcement of the new APIs rather than a separate item. What do you think?

[noencke]

Good question. Yes - merges cannot be accomplished without the alpha branching API, so this is only relevant for that API. I think you're right that they would be best combined.

[alexvy86]

Nit: I'd update line 10 to read "via the TreeBranch.merge method".

[alexvy86]

Didn't go through every line of the 2.4.0.md file but skimmed it and looks fine to me. Left one small nit as a comment above.