microsoft/FluidFramework client_v2.31.0

Fluid Framework v2.31.0 (minor)

on GitHub

Contents

• ✨ New Features
  • New alpha onAssertionFailure API (#24089)
• 🌳 SharedTree DDS Changes
  • Better type errors for invalid recursive schema (#24080)
  • Improve tree shaking for code which imports SharedTreeAttributes (#24135)
  • Improvements to typing of object node schema (#24143)
  • Improved type checking for recursive object schema Fields (#24113)
  • TreeAlpha.exportConcise now supports undefined (#24187)
  • Performance enhancements in SharedTree branch-related ops processing (#24093)
• Other Changes
  • Simplify experimental tree data object implementation (#23943)

✨ New Features

New alpha onAssertionFailure API (#24089)

A new @alpha API is added called onAssertionFailure which can be used to get a callback when an assertion fails indicating a bug in the Fluid Framework. This callback is invoked before the exception is thrown, reducing the chances of the exception being lost or replaced with a different exception before making it to a catch block which reports it. It can also be used to break into the debugger when the assertion occurs to aid in debugging the cause.

import { onAssertionFailure } from "fluid-framework/alpha";

let firstAssertion: Error | undefined;

onAssertionFailure((error: Error) => {
  const priorErrorNote =
    firstAssertion === undefined
      ? "Please report this bug."
      : `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;
  const message = `Encountered Bug in Fluid Framework: ${error.message}\n${priorErrorNote}\n${error.stack}`;
  console.error(message);

  debugger;
  firstAssertion ??= error;
});

Change details

Commit: 5e933c7

Affected packages:

• @fluidframework/core-utils

⬆️ Table of contents

🌳 SharedTree DDS Changes

Better type errors for invalid recursive schema (#24080)

Constraints have been added to *Recursive SchemaFactory methods to ensure correct use without relying on ValidateRecursiveSchema as much.

Change details

Commit: 8ae8d2c

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Improve tree shaking for code which imports SharedTreeAttributes (#24135)

Bundling code that imports SharedTreeAttributes from @fluidframework/tree/legacy should now better prune out the rest of the tree package's code. This change reduced the dependency on webpack's usedExports when tree shaking, but other bundlers should also benefit.

Change details

Commit: eb46f42

Affected packages:

• @fluidframework/tree

⬆️ Table of contents

Improvements to typing of object node schema (#24143)

Several tweaks to the typing of object node schema have been made to allow exposing an @alpha ObjectNodeSchema type.

SchemaFactoryAlpha's object and objectRecursive now return schema which are compatible with the new ObjectNodeSchema type. This new ObjectNodeSchema type exposes a fields: ReadonlyMap<string, FieldSchemaAlpha & SimpleObjectFieldSchema> property which provides an easy way to get information about the object's fields.

Additionally an alpha ObjectNodeSchema object is added to enable support for schema instanceof ObjectNodeSchema to safely narrow TreeNodeSchema to this new type.

In support of this work, several typing details were fixed including:

• info field of [typeSchemaSymbol] type brand on recursive object schema was specified to match non-recursive variants.
• Type of field metadata was correctly plumbed through optionalReclusive and requiredRecursive.
• When fields object provided to SchemaFactory.object is typed as RestrictiveStringRecord<ImplicitFieldSchema> the resulting TreeObjectNode no longer gets a Record<string, TreeNode | TreeLeafValue> signature which could incorrectly conflict with custom members added to the object. Instead {} is used to provide no information about felids on the type when the schema provides no information about them. Additionally this case is explicitly made non-constructable: the constructor takes in never instead of a Record<string,never> which could be erroneously satisfied with an empty object due to how TypeScript assignability rules consider records to have all allowed fields, but also allow objects missing those fields to be assigned to them.

Lastly, metadata on the various schema types has been made required instead of optional. This does not impact the APIs for constructing schema: when undefined is provided the schema now defaults to {} instead of undefined. This reduces the number of cases code reading metadata from schema has to handle.

Change details

Commit: 02ecf8d

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Improved type checking for recursive object schema Fields (#24113)

Most ways to provide incorrectly typed data for fields of recursive object schema now produce simpler type errors without relying on ValidateRecursiveSchema.

As a side effect of this work, some schema which violated the documented allowed patterns specified by SchemaFactory but used to work (as long as they were not package exported) no longer compile.

The specific case known to break is when:

1. An Object node schema is co-recursive with an Array node schema.
2. The Array does not declare a named subclass.
3. The schema reference from the Object to the Array is not using the lazy syntax.

For example:

class Foo extends sf.objectRecursive("Foo", {
  fooList: sf.arrayRecursive("FooList", [() => Foo]), // Bad
}) {}
{
  type _check = ValidateRecursiveSchema<typeof Foo>;
}

Such a schema is disallowed according to the documentation. See the "recursive schema must explicitly declare a named class" remarks. This restriction is necessary to avoid generated .d.ts files replacing recursive references with any. Fixing this code is now also necessary to avoid a compile error.

// Fixed
class FooList extends sf.arrayRecursive("FooList", [() => Foo]) {}
{
  type _check = ValidateRecursiveSchema<typeof FooList>;
}
class Foo extends sf.objectRecursive("Foo", {
  fooList: FooList,
}) {}
{
  type _check = ValidateRecursiveSchema<typeof Foo>;
}

This change will also result in much nicer IntelliSense and type errors while fixing the typing if the schema is exported.

There are still several cases which compile but violate this policy regarding recursive schema and can cause issues when exporting schema; these should be migrated to the above pattern as well. It is still valid to use non-recursive structurally named array and map schema inline; this change does not impact them.

Change details

Commit: 5b656f5

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

TreeAlpha.exportConcise now supports undefined (#24187)

There is a new overload for TreeAlpha.exportConcise which makes exporting optional fields easier. This overload allows undefined and returns undefined in this case.

Change details

Commit: 958b9fd

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Performance enhancements in SharedTree branch-related ops processing (#24093)

SharedTree leverages the "op bunching" feature where contiguous ops in a grouped batch are bunched and processed together to asymptotically improve the performance of processing ops. This performance enhancement focuses on the scenario where there are one or more commits in the trunk and one or more peer commits are received in a bunch. With 1 trunk commits and 10 peer commits, the performance increases by 57%; with 100 trunk commits and 100 peer commits, the performance increases by 97%.

Some example scenarios where the performance will be improved:

• A client makes some local changes and another client simultaneously makes a large number of changes in a single JavaScript turn. For example, a client is typing into a canvas while another client pastes a large amount of content into a table.

• A client makes a local branch with some changes and rebases it into the trunk. For example, an AI agent makes changes on a local branch which are accepted by a user resulting in the AI's branch being merged into the trunk.

Change details

Commit: 47b275b

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Other Changes

Simplify experimental tree data object implementation (#23943)

The experimental tree data object in tree-react-api has been simplified in a way that is incompatible with its previous version, which used SharedDirectory at the root. The library now leverages a new data object that uses the SharedTree directly at the root. In addition to breaking compatibility with existing documents, these changes include some related simplifications to the APIs which are also breaking:

• Removes the key property from the data object configuration. This key was used to inform where the SharedTree was parented beneath the root SharedDirectory, so it no longer serves a purpose.
• Inlined the ITreeDataObject interface into IReactTreeDataObject.

Change details

Commit: 00a56b7

Affected packages:

• @fluid-experimental/tree-react-api

⬆️ Table of contents

🛠️ Start Building Today!

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