github microsoft/FluidFramework client_v3.13.0
Fluid Framework v3.13.0 (minor)

27 minutes ago

Contents

  • ✨ New Features
    • Capture reusable container state (#28703)
    • Add dataStoreRegistryFromIterable (#28727)
  • 🌳 SharedTree DDS Changes
    • Optimize tree decoding (#28664)
    • Type-checking schemas that use large enums from enumFromStrings is much faster (#28497)
    • Improve SharedTree decoding performance (#28708)
    • Customizable record nodes work when JavaScript private fields are transpiled to symbol-keyed properties (#28684)
    • Schema upgrades preserve already-enabled staged changes (#28695)
    • Refactor detached changeset model (#28667)
  • 🐛 Bug Fixes
    • Datastore attachment no longer emits duplicate attached notifications (#28740)
    • Keep unreferenced flags on the correct snapshot trees (#28680)
  • Legacy API Changes
    • Legacy data-store factories can now be used with the alpha ServiceClient APIs (#28723)
    • Container state capture is available on the legacy beta API surface (#28272)
    • Preserve unreferenced data stores and attachments in captured container state (#28680)
  • Other Changes
    • Reduce the memory used by event emitters with one listener per event (#28719)

✨ New Features

Capture reusable container state (#28703)

The new ContainerAlpha.serializeAttached method makes capturing an attached container's state more convenient. For attached containers, callers explicitly choose whether to include unsequenced local changes. With includePendingLocalState: false, serializeAttached omits local changes and session-specific state and the returned state can safely be used to load multiple containers connected to the original document. includePendingLocalState: true has the same behavior and restrictions as getPendingLocalState: close the source container before loading the state, never load the same state more than once, and replace stored state after each reconnect. In both cases, pending-state capture must be enabled when the container is created or loaded: the client must be interactive, and the Fluid.Container.enableOfflineFull configuration flag must not be false (it defaults to true). Otherwise, serializeAttached throws a UsageError.

import { asLegacyAlpha } from "@fluidframework/container-loader/legacy/alpha";

const containerAlpha = asLegacyAlpha(container);
const state = await containerAlpha.serializeAttached({
  includePendingLocalState: false,
});
// Safe: reuse the serialized state for multiple instances of the same document.
const first = await loader.resolve(request, state);
const second = await loader.resolve(request, state);

For detached or attaching containers, continue to use the existing serialize() method. Serialization while attaching is not supported by serializeAttached.

Change details

Commit: de4a4dd

Affected packages:

  • @fluidframework/container-loader

⬆️ Table of contents

Add dataStoreRegistryFromIterable (#28727)

The alpha dataStoreRegistryFromIterable utility makes it easier to create a DataStoreRegistry from an iterable of existing DataStoreKind objects and lazy loaders.

import { dataStoreRegistryFromIterable } from "fluid-framework/alpha";
import { rootKind } from "./root.js";

const registry = dataStoreRegistryFromIterable([
  rootKind,
  {
    type: "com.example.details",
    kind: async () => (await import("./details.js")).detailsKind,
  },
]);

const detailsKind = await registry("com.example.details");

In this example, rootKind and detailsKind are existing data store kinds, and detailsKind.type is "com.example.details". The helper calls the details loader only when its type is requested and caches the result, including failures.

Change details

Commit: 35cc5be

Affected packages:

  • fluid-framework

⬆️ Table of contents

🌳 SharedTree DDS Changes

Optimize tree decoding (#28664)

SharedTree now better preserves compression when decoding subtrees. This improves performance for loads and remote inserts, and additionally saves memory if using ForestTypeOptimized.

Example measurements

In a local benchmark with 10,000-character documents using ForestTypeOptimized, the median results before and after this change were:

Metric Formatted text, before to after Plain text, before to after
Retained tree heap after loading 30.6 MiB to 25.4 MiB (17% less) 2.72 MiB to 0.316 MiB (88% less)
Retained attached-content heap after loading 10.5 MiB to 10.5 MiB (about the same) 0.114 MiB to 0.0778 MiB (32% less)
Summary load time 214 ms to 210 ms (about the same) 33.5 ms to 17.4 ms (48% faster)
Receive insertion time 431 ms to 428 ms (about the same) 72.0 ms to 65.6 ms (9% faster)
Local insertion time 1,335 ms to 1,332 ms (about the same) 146 ms to 150 ms (about the same)

These measurements use Node.js 22.23.2, in-memory summary storage, and a mocked runtime, with 18 timed samples per case after warmup across two process orders. Both variants include the existing optimized-forest compaction; the comparison includes the decoding optimization and its accompanying editing fixes. Summary load times include mock runtime and storage setup but exclude subsequent content verification. Receive insertion times include message synchronization and the sender's acknowledgement.

Heap measurements report median per-document retained heap from six batches of four loaded documents after garbage collection, with separate heap warmups. The attached-content measurement retains only the root-field chunks, excluding the tree and checkout. Shared summary fixtures and their ID compressor are excluded from heap deltas. These measurements do not measure peak memory.

Both document types use less memory in these scenarios. Plain-text summary loading is faster, while formatted-text timing differences are small and vary between process runs. Formatted-text attached-content heap is essentially unchanged because its enclosing polymorphic structures do not use the fixed-shape sequence path. Small timing differences can be noise, and preparing a decoder for a custom leaf type can cost more than the general path for a tiny batch. Results depend on the document schema, workload, and environment.

Change details

Commit: b73dd7c

Affected packages:

  • @fluidframework/tree
  • fluid-framework

⬆️ Table of contents

Type-checking schemas that use large enums from enumFromStrings is much faster (#28497)

The type of the schema property returned by enumFromStrings is now computed by mapping the provided array of members directly, instead of converting the union of members back into a tuple. The cost of type-checking code that uses schema (for example, as a field's allowed types) now grows linearly with the number of members rather than roughly quadratically.

For example, type-checking a field whose allowed types are a 250-member enum created with enumFromStrings takes about 1.4 seconds instead of about 19 seconds with TypeScript 6, and requires about 8 times fewer type instantiations.

schema is still a tuple with one entry per member, and its entries are in the same order as the members passed to enumFromStrings. When the members are not a tuple type (for example, a string[]), schema is typed as an array instead of a single-element tuple, matching its runtime value.

Change details

Commit: 99c7028

Affected packages:

  • @fluidframework/tree
  • fluid-framework

⬆️ Table of contents

Improve SharedTree decoding performance (#28708)

SharedTree decoding has been optimized. Formatted-text benchmarks measured the following median decoding times on Node.js 22:

Document size Before After Time reduction
1,000 characters 1.665 ms 1.637 ms 1.7%
10,000 characters 17.298 ms 16.648 ms 3.8%

Change details

Commit: 3968eef

Affected packages:

  • @fluidframework/tree
  • fluid-framework

⬆️ Table of contents

Customizable record nodes work when JavaScript private fields are transpiled to symbol-keyed properties (#28684)

Fluid Framework targets ES2022, which supports JavaScript private fields (#field) natively. Some tools transpile them to symbol-keyed properties for older runtimes, for example Babel with its privateFieldsAsSymbols assumption. Fluid doesn't directly support those runtimes, but such tools are used to bundle applications. With them, every tree node gets a non-configurable symbol-keyed property in place of a private field that the node's base class declares.

Previously, Object.keys, Reflect.ownKeys, object spread and similar operations threw a TypeError on a customizable record node (one declared as a class extending SchemaFactory.record) that had such a property. A customizable record node now reports its symbol-keyed own properties to these operations. Reading or writing a symbol-keyed property through the node is unchanged.

Object.keys still reports only the record's entries, since symbol-keyed properties are not string keys. Transpiled private fields are not enumerable, so object spread still copies only the record's entries.

Change details

Commit: 31505b4

Affected packages:

  • @fluidframework/tree
  • fluid-framework

⬆️ Table of contents

Schema upgrades preserve already-enabled staged changes (#28695)

Schema upgrades now preserve already-enabled staged allowed types and optionality at each stored location, even when the view's staged-upgrade policy does not enable those changes. Previously, the default restrictive policy could cause an upgrade to be rejected because its proposed schema excluded changes already enabled in the document. The policy now controls only which new staged changes are introduced when upgrading a schema.

Preservation does not enable a shared upgrade token at additional locations. If a token is only partially enabled, explicitly enable it with StagedSchemaUpgradePolicy.enabledStagedUpgrades(token) to apply it at the remaining locations.

The alpha StagedSchemaUpgradePolicy.includeAlreadyEnabledUpgrades option has been removed because preservation is now automatic.

Change details

Commit: ebac344

Affected packages:

  • @fluidframework/tree
  • fluid-framework

⬆️ Table of contents

Refactor detached changeset model (#28667)

This change is a stepping stone toward future SharedTree features.

This change is expected to have zero impact on existing APIs, persisted/wire formats, or execution behaviors. However, because of the large amount of code changes, it is worth calling out in case these changes cause unexpected issues.

Change details

Commit: 34ab100

Affected packages:

  • fluid-framework
  • @fluidframework/tree

⬆️ Table of contents

🐛 Bug Fixes

Datastore attachment no longer emits duplicate attached notifications (#28740)

The container runtime now calls a local datastore channel's setAttachState(Attached) once when the datastore becomes attached, instead of twice. This prevents duplicate "attached" events from the standard datastore runtime. Repeated requests to mark the same datastore as attached continue to produce no additional notifications.

Change details

Commit: 30ac74f

Affected packages:

  • @fluidframework/container-runtime

⬆️ Table of contents

Keep unreferenced flags on the correct snapshot trees (#28680)

Binary snapshot decoding assigns each unreferenced flag to the tree named by its record instead of that tree's parent. This keeps snapshot metadata consistent with JSON decoding and corrects datastore reachability counts reported at load. The change does not alter runtime garbage collection decisions.

Change details

Commit: 606251d

Affected packages:

  • @fluidframework/odsp-driver

⬆️ Table of contents

Legacy API Changes

Legacy data-store factories can now be used with the alpha ServiceClient APIs (#28723)

Two new @legacy @alpha APIs have been added to help existing users of the @legacy API surface incrementally adopt the new @alpha ServiceClient APIs.

The new dataStoreKindFromFactory function in @fluidframework/runtime-utils/legacy/alpha lets you use an existing data-store factory as an alpha DataStoreKind. It preserves the original factory, child registry, entry point, and persisted representation without adding persisted objects. This includes factories that create registered child data stores during initialization. Repeated calls with the same factory return the same kind. Supply the factory's entry-point type as the generic type argument when needed. The function does not validate that type or change the container's root-discovery convention.

For applications with other root-discovery conventions, fluidContainerFromLegacy exposes an attached legacy container and an application-selected root value through the alpha container API. Pass the service-facing reload ID explicitly; a driver's resolved URL ID may instead be an internal identifier such as an ODSP document hash. Factories used for alpha creation must already be registered in the existing runtime. Closing the returned view closes the original container.

import {
  dataStoreKindFromFactory,
  fluidContainerFromLegacy,
} from "@fluidframework/runtime-utils/legacy/alpha";

// Use your existing factory, attached container, root value, and service reload ID.
const kind = dataStoreKindFromFactory<typeof root>(factory);
const registry = async (type: string) => {
  if (type !== kind.type) {
    throw new Error(`Unknown data-store type: ${type}`);
  }
  return kind;
};
const container = fluidContainerFromLegacy(
  legacyContainer,
  root,
  registry,
  reloadId,
);
const newDataStore = await container.createDataStore(kind);

Change details

Commit: 5452cc6

Affected packages:

  • @fluidframework/runtime-utils

⬆️ Table of contents

Container state capture is available on the legacy beta API surface (#28272)

You can now import captureFullContainerState and ICaptureFullContainerStateProps from @fluidframework/container-loader/legacy. These APIs capture container state using driver services without loading a runtime. Their behavior is unchanged, and they remain available from the legacy alpha entrypoint.

import {
  captureFullContainerState,
  type ICaptureFullContainerStateProps,
} from "@fluidframework/container-loader/legacy";

// ...
const options: ICaptureFullContainerStateProps = {
  urlResolver,
  documentServiceFactory,
  request,
};
const pendingLocalState = await captureFullContainerState(options);

Change details

Commit: be01c89

Affected packages:

  • @fluidframework/container-loader

⬆️ Table of contents

Preserve unreferenced data stores and attachments in captured container state (#28680)

With the default "inline" blob capture mode, captureFullContainerState retains all structural snapshot contents, including unreferenced data stores and their DDSs. This lets a resumed session process operations that reference these stores again without fetching historical structural blobs from storage. Default inline capture also retains GC-unreferenced attachment payloads, since restoring a data store reference does not emit another BlobAttach operation. Capture does not reliably omit attachment blobs that garbage collection has tombstoned or deleted; their contents may still be included, so do not rely on capture to remove them.

In both "inline" and "reference" modes, captureFullContainerState now rejects containers that declare loading groups anywhere in the snapshot, including in unreferenced subtrees; previously those subtrees were ignored. If capture is rejected for loading groups, use a regular online container load instead; this capture API does not yet support those containers.

Change details

Commit: 606251d

Affected packages:

  • @fluidframework/container-loader

⬆️ Table of contents

Other Changes

Reduce the memory used by event emitters with one listener per event (#28719)

An event emitter now keeps an event's only listener directly, and creates a set of listeners only when the event has a second one. Most emitters have one listener per event: for example, a tree node with a nodeChanged listener uses about 300 bytes less memory.

Change details

Commit: d7730b8

Affected packages:

  • @fluid-internal/client-utils

⬆️ Table of contents

🛠️ Start Building Today!

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

Don't miss a new FluidFramework release

NewReleases is sending notifications on new releases.