FluidFramework/RELEASE_NOTES/2.1.0.md

Fluid Framework v2.1.0

✨ New Features

Type guards for DDS types

In the 2.0 release of Fluid, the concrete class implementations for DDSes were hidden from Fluid's API surface. This made instanceof checks fail to work correctly. There were ways to work around this in application code, but they involved boilerplate which required more understanding of Fluid internals than should be necessary.

There is now a drop-in replacement to instanceof: the static .is() method to SharedObjectKind, which is available on all DDSes. For example:

// Works in Fluid Framework 1.0 but not in the initial release of Fluid Framework 2.0:
if (myObject instanceof SharedString) {
  // do something
}

// In Fluid Framework 2.0 and beyond, that code can now be written like so:
if (SharedString.is(myObject)) {
  // do something
}

Packages affected

• @fluidframework/shared-object-base

🌳 SharedTree DDS changes

Using "delete" on tree fields now throws an error instead of not working correctly

TypeScript allows delete on object node optional fields if the exactOptionalPropertyTypes tsconfig setting is not enabled. This does not work correctly at runtime and now produces an informative error.

Packages affected

• fluid-framework
• @fluidframework/tree

Detect arrayNode iterator invalidation

When arrayNodes are edited concurrently during iteration, an error will be thrown.

Packages affected

• @fluidframework/tree
• fluid-framework

SharedTree content that is removed is now deleted

SharedTree now supports garbage collection so that removed content is not retained forever. This is an internal change and users of SharedTree won't need to adapt any existing code.

This change could cause errors with cross-version collaboration where an older client does not send data that a newer version may need. In this case, a "refresher data not found" error will be thrown.

Packages affected

• @fluidframework/tree

tree: Improved performance for accessing identifiers in shortId API

Users should see improved performance when calling the Tree.shortId API. Identifier field keys are now cached in the schema for faster access.

Packages affected

• fluid-framework
• @fluidframework/tree

Improved error reporting

Several cases of invalid usage patterns for tree APIs have gained improved error reporting, as well as improved documentation on the APIs detailing what usage is supported. These improvements include:

• Unsupported usages of schema classes: using more than one schema class derived from a single SchemaFactory generated base class. This used to hit internal asserts, but now has a descriptive user-facing UsageError. Most of this work was done in 9fb3dcf.

• Improved detection of when prior exception may have left SharedTree in an invalid state. These cases now report a UsageError including a reference to the prior exception. This was mainly done in 9fb3dcf and b77d530.

Packages affected

• fluid-framework
• @fluidframework/tree

✨ New! Debug visualizers for TreeNodes in NodeJS and browsers

TreeNodes now have custom debug visualizers to improve the debug experience in NodeJS and in browsers. Note that custom formatters must be enabled in the browser developer tools for that visualizer to be used.

Packages affected

• fluid-framework
• @fluidframework/tree

🐛 Bug Fixes

tinylicious-client: Promote APIs from beta to public

Some tinylicious-client APIs were marked beta in previous releases. These APIs are now correctly marked public and also sealed to indicate they are not to be implemented externally to Fluid Framework and not changed.

Updated APIs:

• ITinyliciousAudience sealed
• TinyliciousClient sealed
• TinyliciousClientProps sealed
• TinyliciousConnectionConfig sealed
• TinyliciousContainerServices sealed
• TinyliciousMember sealed
• TinyliciousUser sealed

Packages affected

• @fluidframework/tinylicious-client

merge-tree: The Marker.fromJSONObject and TextSegment.fromJSONObject argument types have been corrected

Previously, the arguments of Marker.fromJSONObject and TextSegment.fromJSONObject were of type any. However, at runtime only certain types were expected and using other types would cause errors.

Now, the argument for the Marker implementation is of type IJSONSegment and the argument for the TextSegment implementation is of type string | IJSONSegment. This reflects actual runtime support.

This change should have no impact on existing code unless the code is using incorrect types. Such code already does not function and should be corrected.

Packages affected

• @fluidframework/merge-tree

Some SharedDirectory/SharedMap-related APIs have been sealed

Note that this is a documentation only change. There is no runtime or type-level impact.

Some top-level APIs within @fluidframework/map and fluid-framework have been updated to reflect their sealed/readonly nature. That is, they are not to be implemented externally to Fluid Framework and not changed. This was already the case, but the documentation was not clear.

Updated APIs:

• IDirectory sealed
• IDirectoryEvents sealed
• IDirectoryValueChanged sealed and path property is readonly
• ISharedDirectory sealed
• ISharedDirectoryEvents sealed
• IValueChanged sealed

Packages affected

• fluid-framework
• @fluidframework/map

🛠️ Start Building Today!

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