FluidFramework/RELEASE_NOTES/2.2.0.md

Fluid Framework v2.2.0

Contents

• ✨ New Features
  • New isFluidHandle type guard to check if an object is an IFluidHandle (#22029)
• 🌳 SharedTree DDS changes
  • ✨ New! When unambiguous, ArrayNodes can now be constructed from Maps and MapNodes from arrays (#22036)
  • ✨ New! Record-typed objects can now be used to construct MapNodes (#22042)
  • Implicit TreeNode construction improvements (#21995)
  • Fix document-corrupting bug when rebasing over move compositions (#21993)
  • Enforce use of TreeViewConfiguration's constructor (#22055)
  • New SharedTree configuration option: ITreeConfigurationOptions.preventAmbiguity (#22048)
  • Add @alpha API FixRecursiveArraySchema as a workaround around an issue with recursive ArrayNode schema (#22122)
  • Support generation of JSON Schema from Shared Tree view schema (alpha) (#21984)
  • Tree.schema now returns TreeNodeSchema (#22185)
  • Compile-time type narrowing based on a TreeNode's NodeKind (#22222)
• 🐛 Bug Fixes
  • Recursive SharedTree schemas using MapNodes no longer produce invalid d.ts files (#22106)
• ⚠️ Deprecations
  • container-loader: summarizeProtocolTree and its corresponding duplicate ILoaderOptions definition is deprecated (#21999)
  • gcThrowOnTombstoneUsage and gcTombstoneEnforcementAllowed are deprecated (#21992)
  • InactiveResponseHeaderKey header is deprecated (#22107)
  • The PropertyManager class and related functions and properties are deprecated (#22183)
  • Deprecate segmentGroups and ack on ISegment (#22183)
• Other Changes
  • Remove PropertyDDS/SharedTree Schema Converter (#22111)

✨ New Features

New isFluidHandle type guard to check if an object is an IFluidHandle (#22029)

The isFluidHandle type guard function is now exported and can be used to detect which objects are IFluidHandles. Since IFluidHandle often needs special handling (for example when serializing since it's not JSON compatible), having a dedicated detection function for it is useful. Doing this detection was possible previously using the tree package's schema system via Tree.is(value, new SchemaFactory("").handle), but can now be done with just isFluidHandle(value).

Change details

Commit: 7827d10

Affected packages:

• fluid-framework
• @fluidframework/runtime-utils

🌳 SharedTree DDS changes

✨ New! When unambiguous, ArrayNodes can now be constructed from Maps and MapNodes from arrays (#22036)

Since the types for ArrayNodes and MapNodes indicate they can be constructed from iterables, it should work, even if those iterables are themselves arrays or maps. To avoid this being a breaking change, a priority system was introduced. ArrayNodes will only be implicitly constructable from JavaScript Map objects in contexts where no MapNodes are allowed. Similarly MapNodes will only be implicitly constructable from JavaScript Array objects in contexts where no ArrayNodes are allowed.

In practice, the main case in which this is likely to matter is when implicitly constructing a map node. If you provide an array of key value pairs, this now works instead of erroring, as long as no ArrayNode is valid at that location in the tree.

class MyMapNode extends schemaFactory.map("x", schemaFactory.number) {}
class Root extends schemaFactory.object("root", { data: MyMapNode }) {}
// This now works (before it compiled, but error at runtime):
const fromArray = new Root({ data: [["x", 5]] });

Prior versions used to have to do:

new Root({ data: new MyMapNode([["x", 5]]) });

or:

new Root({ data: new Map([["x", 5]]) });

Both of these options still work: strictly more cases are allowed with this change.

Change details

Commit: 25e74f9

Affected packages:

• @fluidframework/tree
• fluid-framework

✨ New! Record-typed objects can now be used to construct MapNodes (#22042)

You can now construct MapNodes from Record typed objects, similar to how maps are expressed in JSON.

Before this change, an Iterable<string, Child> was required, but now an object like {key1: Child1, key2: Child2} is allowed.

Full example using this new API:

class Schema extends schemaFactory.map("ExampleMap", schemaFactory.number) {}
const fromRecord = new Schema({ x: 5 });

This new feature makes it possible for schemas to construct a tree entirely from JSON-compatible objects using their constructors, as long as they do not require unhydrated nodes to differentiate ambiguous unions, or IFluidHandles (which themselves are not JSON compatible).

Due to limitations of TypeScript and recursive types, recursive maps do not advertise support for this feature in their typing, but it works at runtime.

Change details

Commit: 25deff3

Affected packages:

• fluid-framework
• @fluidframework/tree

Implicit TreeNode construction improvements (#21995)

ArrayNodes and MapNodes could always be explicitly constructed (using new) from iterables. The types also allowed using of iterables to implicitly construct array nodes and map nodes, but this did not work at runtime. This has been fixed for all cases except implicitly constructing an ArrayNode form an Iterable that is actually a Map, and implicitly constructing a MapNode from an Iterable that is actually an Array. These cases may be fixed in the future, but require additional work to ensure unions of array nodes and map nodes work correctly.

Additionally MapNodes can now be constructed from Iterator<readonly [string, content]> where previously the inner arrays had to be mutable.

Change details

Commit: 977f96c

Affected packages:

• fluid-framework
• @fluidframework/tree

Fix document-corrupting bug when rebasing over move compositions (#21993)

Before this fix, if multiple users concurrently performed moves (possibly by reverting prior moves), there was a chance that the document would become corrupted.

Change details

Commit: f3af9d1

Affected packages:

• @fluidframework/tree

Enforce use of TreeViewConfiguration's constructor (#22055)

TreeViewConfiguration is @sealed, meaning creating custom implementations of it such as assigning object literals to a TreeViewConfiguration or sub-classing it are not supported. This reserved the ability for the Fluid Framework to add members to this class over time, informing users that they must use it in such a way where such changes are non-breaking. However, there was no compiler-based enforcement of this expectation. It was only indicated via documentation and an implicit assumption that when an API takes in a typed defined as a class, that an instance of that class must be used rather than an arbitrary object of a similar shape.

With this change, the TypeScript compiler will now inform users when they invalidly provide an object literal as a TreeViewConfiguration.

More specifically this causes code like this to produce a compile error:

// Don't do this!
const view = tree.viewWith({ schema: TestNode, enableSchemaValidation: false });

The above was never intended to work, and is not a supported use of the viewWith since it requires a TreeViewConfiguration which is sealed. Any code using the above pattern will break in Fluid Framework 2.2 and above. Such code will need to be updated to the pattern shown below. Any code broken by this change is technically unsupported and only worked due to a gap in the type checking. This is not considered a breaking change. The correct way to get a TreeViewConfiguration is by using its constructor:

// This pattern correctly initializes default values and validates input.
const view = tree.viewWith(new TreeViewConfiguration({ schema: TestNode }));

Skipping the constructor causes the following problems:

1. TreeViewConfiguration does validation in its constructor, so skipping it also skips the validation which leads to much less friendly error messages for invalid schema.
2. Skipping the constructor also discards any default values for options like enableSchemaValidation. This means that code written in that style would break if more options were added. Since such changes are planned, it is not practical to support this pattern.

Change details

Commit: e895557

Affected packages:

• fluid-framework
• @fluidframework/tree

New SharedTree configuration option: ITreeConfigurationOptions.preventAmbiguity (#22048)

The new ITreeConfigurationOptions.preventAmbiguity flag can be set to true to enable checking of some additional rules when constructing the TreeViewConfiguration.

This example shows an ambiguous schema:

const schemaFactory = new SchemaFactory("com.example");
class Feet extends schemaFactory.object("Feet", {
  length: schemaFactory.number,
}) {}
class Meters extends schemaFactory.object("Meters", {
  length: schemaFactory.number,
}) {}
const config = new TreeViewConfiguration({
  // This combination of schema can lead to ambiguous cases, and will error since preventAmbiguity is true.
  schema: [Feet, Meters],
  preventAmbiguity: true,
});
const view = tree.viewWith(config);
// This is invalid since it is ambiguous which type of node is being constructed.
// The error thrown above when constructing the TreeViewConfiguration is because of this ambiguous case:
view.initialize({ length: 5 });

See the documentation on ITreeConfigurationOptions.preventAmbiguity for a more complete example and more details.

Change details

Commit: 966906a

Affected packages:

• fluid-framework
• @fluidframework/tree

Add @alpha API FixRecursiveArraySchema as a workaround around an issue with recursive ArrayNode schema (#22122)

Importing a recursive ArrayNode schema via a d.ts file can produce an error like error TS2310: Type 'RecursiveArray' recursively references itself as a base type. if using a tsconfig with "skipLibCheck": false.

This error occurs due to the TypeScript compiler splitting the class definition into two separate declarations in the d.ts file (one for the base, and one for the actual class). For unknown reasons, splitting the class declaration in this way breaks the recursive type handling, leading to the mentioned error.

Since recursive type handling in TypeScript is order dependent, putting just the right kind of usages of the type before the declarations can cause it to not hit this error. For the case of ArrayNodes, this can be done via usage that looks like this:

/**
 * Workaround to avoid
 * `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.` in the d.ts file.
 */
export declare const _RecursiveArrayWorkaround: FixRecursiveArraySchema<
  typeof RecursiveArray
>;
export class RecursiveArray extends schema.arrayRecursive("RA", [
  () => RecursiveArray,
]) {}
{
  type _check = ValidateRecursiveSchema<typeof RecursiveArray>;
}

Change details

Commit: 9ceacf9

Affected packages:

• @fluidframework/tree

Support generation of JSON Schema from Shared Tree view schema (alpha) (#21984)

WARNING

This API is alpha quality and may change at any time.

Adds alpha-quality support for canonical JSON Schema representation of Shared Tree schema and adds a getJsonSchema function for getting that representation for a given TreeNodeSchema. This JSON Schema representation can be used to describe schema requirements to external systems, and can be used with validation tools like ajv to validate data before inserting it into a SharedTree.

Example

Given a SharedTree schema like the following:

class MyObject extends schemaFactory.object("MyObject", {
	foo: schemaFactory.number,
	bar: schemaFactory.optional(schemaFactory.string),
});

JSON Schema like the following would be produced:

{
  "$defs": {
    "com.fluidframework.leaf.string": {
      "type": "string"
    },
    "com.fluidframework.leaf.number": {
      "type": "number"
    },
    "com.myapp.MyObject": {
      "type": "object",
      "properties": {
        "foo": { "$ref": "com.fluidframework.leaf.number" },
        "bar": { "$ref": "com.fluidframework.leaf.string" }
      },
      "required": ["foo"]
    }
  },
  "anyOf": [{ "$ref": "#/$defs/com.myapp.MyObject" }]
}

Change details

Commit: 9097bf8

Affected packages:

• @fluidframework/tree

Tree.schema now returns TreeNodeSchema (#22185)

The typing of Tree.schema has changed from:

schema<T extends TreeNode | TreeLeafValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T>;

to:

schema(node: TreeNode | TreeLeafValue): TreeNodeSchema;

The runtime behavior is unaffected: any code which worked and still compiles is fine and does not need changes.

Tree.schema was changed to mitigate two different issues:

1. It tried to give a more specific type based on the type of the passed in value. When the type of the input is not known precisely (for example it is a union of node types like Foo | Bar, or TreeNode or even TreeNode | TreeLeafValue), this was fine since schema are covariant over their node type. However when the input was more specific that the schema type, for example the type is simply 0, this would result in unsound typing, since the create function could actually return values that did not conform with that schema (for example schema.create(1) for the number schema typed with 0 would return 1 with type 0).
2. The node type was provided to the incorrect type parameter of TreeNodeSchema. The TNode parameter is the third one, not the fourth. The fourth is TBuild which sets the input accepted to its create function or constructor. Thus this code accidentally left TNode unset (which is good due to the above issue), but invalidly set TBuild. TBuild is contravariant, so it has the opposite issue that setting TNode would have: if your input is simply typed as something general like TreeNode, then the returned schema would claim to be able to construct an instance given any TreeNode. This is incorrect, and this typing has been removed.

Fortunately it should be rare for code to be impacted by this issue. Any code which manually specified a generic type parameter to Tree.schema() will break, as well as code which assigned its result to an overly specifically typed variable. Code which used typeof on the returned schema could also break, though there are few use-cases for this so such code is not expected to exist. Currently it's very difficult to invoke the create function or constructor associated with a TreeNodeSchema as doing so already requires narrowing to TreeNodeSchemaClass or TreeNodeSchemaNonClass. It is possible some such code exists which will need to have an explicit cast added because it happened to work with the more specific (but incorrect) constructor input type.

Change details

Commit: bfe8310

Affected packages:

• fluid-framework
• @fluidframework/tree

Compile-time type narrowing based on a TreeNode's NodeKind (#22222)

TreeNode's schema-aware APIs implement WithType, which now has a NodeKind parameter that can be used to narrow TreeNodes based on NodeKind.

Example:

function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];
function getKeys(
  node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>,
): string[];
function getKeys(node: TreeNode): string[] | number[];
function getKeys(node: TreeNode): string[] | number[] {
  const schema = Tree.schema(node);
  switch (schema.kind) {
    case NodeKind.Array: {
      const arrayNode = node as TreeArrayNode;
      const keys: number[] = [];
      for (let index = 0; index < arrayNode.length; index++) {
        keys.push(index);
      }
      return keys;
    }
    case NodeKind.Map:
      return [...(node as TreeMapNode).keys()];
    case NodeKind.Object:
      return Object.keys(node);
    default:
      throw new Error("Unsupported Kind");
  }
}

Change details

Commit: 4d3bc87

Affected packages:

• fluid-framework
• @fluidframework/tree

🐛 Bug Fixes

Recursive SharedTree schemas using MapNodes no longer produce invalid d.ts files (#22106)

Consider a recursive SharedTree schema like the following, which follows all our recommended best practices:

export class RecursiveMap extends schema.mapRecursive("RM", [
  () => RecursiveMap,
]) {}
{
  type _check = ValidateRecursiveSchema<typeof RecursiveMap>;
}

This schema would work when used from within its compilation unit, but would generate d.ts that fails to compile when exporting it:

declare const RecursiveMap_base: import("@fluidframework/tree").TreeNodeSchemaClass<
  "com.example.RM",
  import("@fluidframework/tree").NodeKind.Map,
  import("@fluidframework/tree").TreeMapNodeUnsafe<
    readonly [() => typeof RecursiveMap]
  > &
    import("@fluidframework/tree").WithType<"com.example.RM">,
  {
    [Symbol.iterator](): Iterator<[string, RecursiveMap], any, undefined>;
  },
  false,
  readonly [() => typeof RecursiveMap]
>;
export declare class RecursiveMap extends RecursiveMap_base {}

This results in the compile error in TypeScript 5.4.5:

error TS2310: Type 'RecursiveMap' recursively references itself as a base type.

With this change, that error is fixed by modifying the TreeMapNodeUnsafe type it references to inline the definition of ReadonlyMap instead of using the one from the TypeScript standard library.

Change details

Commit: 554fc5a

Affected packages:

• fluid-framework
• @fluidframework/tree

⚠️ Deprecations

container-loader: summarizeProtocolTree and its corresponding duplicate ILoaderOptions definition is deprecated (#21999)

The summarizeProtocolTree property in ILoaderOptions was added to test single-commit summaries during the initial implementation phase. The flag is no longer required and should no longer be used, and is now marked deprecated. If a driver needs to enable or disable single-commit summaries, it can do so via IDocumentServicePolicies.

Change details

Commit: 11ccda1

Affected packages:

• @fluidframework/container-loader

gcThrowOnTombstoneUsage and gcTombstoneEnforcementAllowed are deprecated (#21992)

These properties gcThrowOnTombstoneUsage and gcTombstoneEnforcementAllowed have been deprecated in IFluidParentContext and ContainerRuntime. These were included in certain garbage collection (GC) telemetry to identify whether the corresponding features have been enabled. These features are now enabled by default and this information is added to the "GarbageCollectorLoaded" telemetry.

Also, the following Garbage collection runtime options and configs have been removed. They were added during GC feature development to roll out and control functionalities. The corresponding features are on by default and can no longer be disabled or controlled:

GC runtime options removed:

• gcDisableThrowOnTombstoneLoad
• disableDataStoreSweep

GC configs removed:

• "Fluid.GarbageCollection.DisableTombstone"
• "Fluid.GarbageCollection.ThrowOnTombstoneUsage"
• "Fluid.GarbageCollection.DisableDataStoreSweep"

Change details

Commit: b2bfed3

Affected packages:

• @fluidframework/container-runtime
• @fluidframework/runtime-definitions

InactiveResponseHeaderKey header is deprecated (#22107)

The header InactiveResponseHeaderKey is deprecated and will be removed in the future. It was part of an experimental feature where loading an inactive data store would result in returning a 404 with this header set to true. This feature is no longer supported.

Change details

Commit: 2e4e9b2

Affected packages:

• @fluidframework/container-runtime

The PropertyManager class and related functions and properties are deprecated (#22183)

The PropertyManager class, along with the propertyManager properties and addProperties functions on segments and intervals, are not intended for external use. These elements will be removed in a future release for the following reasons:

• There are no scenarios where they need to be used directly.
• Using them directly will cause eventual consistency problems.
• Upcoming features will require modifications to these mechanisms.

Change details

Commit: cbba695

Affected packages:

• fluid-framework
• @fluidframework/merge-tree
• @fluidframework/sequence
• @fluid-experimental/sequence-deprecated

Deprecate segmentGroups and ack on ISegment (#22183)

The SegmentGroupCollection class, along with the segmentGroups property and ack function on segments, are not intended for external use. These elements will be removed in a future release for the following reasons:

• There are no scenarios where they need to be used directly.
• Using them directly will cause eventual consistency problems.
• Upcoming features will require modifications to these mechanisms.

Change details

Commit: cbba695

Affected packages:

• @fluidframework/merge-tree

Other Changes

Remove PropertyDDS/SharedTree Schema Converter (#22111)

This schema converter had several known issues and has been removed. Read the schema converter section of the package readme for more details.

Change details

Commit: 54e4b5e

Affected packages:

• @fluid-experimental/property-shared-tree-interop

🛠️ Start Building Today!

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