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!