Upcoming Release: FluidFramework v2.11.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.11.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

This should happen automatically as part of the release process, but if you need to generate the release notes manually, you can use the above command.

---

Fluid Framework v2.11.0

Contents

• ✨ New Features
  • Enable Synchronous Child Datastore Creation (#23143)
• Overview
• Key Benefits
• Use Cases
  • Example 1: Creating a Child Datastore
• 🌳 SharedTree DDS Changes
  • Providing unused properties in object literals for building empty ObjectNodes no longer compiles (#23162)
  • Enables Revertible objects to be cloned using RevertibleAlpha.clone() (#23044)
• Other Changes
  • Mark APIs as @sealed and @system as appropriate, and make interface properties readonly (#23165)
  • Relocating Events Library to @fluidframework/core-interfaces and @fluid-internal/client-utils (#23141)

✨ New Features

Enable Synchronous Child Datastore Creation (#23143)

Overview

This feature introduces a new pattern for creating datastores synchronously within the Fluid Framework. It allows for the synchronous creation of a child datastore from an existing datastore, provided that the child datastore is available synchronously via the existing datastore's registry and that the child's factory supports synchronous creation. This method also ensures strong typing for the consumer.

In this context, "child" refers specifically to the organization of factories and registries, not to any hierarchical or hosting relationship between datastores. The parent datastore does not control the runtime behaviors of the child datastore beyond its creation.

The synchronous creation of child datastores enhances the flexibility of datastore management within the Fluid Framework. It ensures type safety and provides a different way to manage datastores within a container. However, it is important to consider the overhead associated with datastores, as they are stored, summarized, garbage collected, loaded, and referenced independently. This overhead should be justified by the scenario's requirements.

Datastores offer increased capabilities, such as the ability to reference them via handles, allowing multiple references to exist and enabling those references to be moved, swapped, or changed. Additionally, datastores are garbage collected after becoming unreferenced, which can simplify final cleanup across clients. This is in contrast to subdirectories in a shared directory, which do not have native capabilities for referencing or garbage collection but are very low overhead to create.

Synchronous creation relies on both the factory and the datastore to support it. This means that asynchronous operations, such as resolving handles, some browser API calls, consensus-based operations, or other asynchronous tasks, cannot be performed during the creation flow. Therefore, synchronous child datastore creation is best limited to scenarios where the existing asynchronous process cannot be used, such as when a new datastore must be created in direct response to synchronous user input.

Key Benefits

• Synchronous Creation: Allows for the immediate creation of child datastores without waiting for asynchronous operations.
• Strong Typing: Ensures type safety and better developer experience by leveraging TypeScript's type system.

Use Cases

Example 1: Creating a Child Datastore

In this example, we demonstrate how to support creating a child datastore synchronously from a parent datastore.

/**
 * This is the parent DataObject, which is also a datastore. It has a
 * synchronous method to create child datastores, which could be called
 * in response to synchronous user input, like a key press.
 */
class ParentDataObject extends DataObject {
  createChild(name: string): ChildDataStore {
    assert(
      this.context.createChildDataStore !== undefined,
      "this.context.createChildDataStore",
    );

    const { entrypoint } = this.context.createChildDataStore(
      ChildDataStoreFactory.instance,
    );
    const dir = this.root.createSubDirectory("children");
    dir.set(name, entrypoint.handle);
    entrypoint.setProperty("childValue", name);

    return entrypoint;
  }

  getChild(name: string): IFluidHandle<ChildDataStore> | undefined {
    const dir = this.root.getSubDirectory("children");
    return dir?.get<IFluidHandle<ChildDataStore>>(name);
  }
}

For a complete example see the following test: https://github.com/microsoft/FluidFramework/blob/main/packages/test/local-server-tests/src/test/synchronousDataStoreCreation.spec.ts

Change details

Commit: 3426b43

Affected packages:

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

⬆️ Table of contents

🌳 SharedTree DDS Changes

Providing unused properties in object literals for building empty ObjectNodes no longer compiles (#23162)

ObjectNodes with no fields will now emit a compiler error if constructed from an object literal with fields. This matches the behavior of non-empty ObjectNodes which already gave errors when unexpected properties were provided.

class A extends schemaFactory.object("A", {}) {}
const a = new A({ thisDoesNotExist: 5 }); // This now errors.

Change details

Commit: dc3c300

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Enables Revertible objects to be cloned using RevertibleAlpha.clone() (#23044)

Replaced DisposableRevertible with RevertibleAlpha. The new RevertibleAlpha interface extends Revertible and includes a clone(branch: TreeBranch) method to facilitate cloning a Revertible to a specified target branch. The source branch where the RevertibleAlpha was created must share revision logs with the target branch where the RevertibleAlpha is being cloned. If this condition is not met, the operation will throw an error.

Change details

Commit: 5abfa01

Affected packages:

• fluid-framework
• @fluidframework/tree

⬆️ Table of contents

Other Changes

Mark APIs as @sealed and @system as appropriate, and make interface properties readonly (#23165)

APIs that were never intended for direct consumer use have been marked as @system. These are:

• HasContainerKey

APIs that were not intended to be extended by consumers have been marked as @sealed. These are:

• ContainerDevtoolsProps
• DevtoolsProps
• HasContainerKey
• IDevtools

Additionally, interface properties have been marked as readonly.

Change details

Commit: cea34d1

Affected packages:

• @fluidframework/devtools
• @fluidframework/devtools-core

⬆️ Table of contents

Relocating Events Library to @fluidframework/core-interfaces and @fluid-internal/client-utils (#23141)

The events library's types and interfaces are moved to @fluidframework/core-interfaces, while its implementation is relocated to @fluid-internal/client-utils. There are no changes to how the events library is used; the relocation simply organizes the library into more appropriate packages. This change has no impact on external consumers of Fluid.

Change details

Commit: cae07b5

Affected packages:

• @fluidframework/core-interfaces
• @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!