microsoft/FluidFramework client_v2.118.0

Fluid Framework v2.118.0 (minor)

on GitHub

Contents

• ✨ New Features
  • Enable point-in-time loading on the standard ODSP document service factory (#28152)
• 🌳 SharedTree DDS Changes
  • SharedTree schema errors now explain the mismatch (#28153)
  • TreeViewAlpha can now query whether a staged schema upgrade has been applied (#28154)
  • Preserve enabled staged schema upgrades by default (#28155)
  • Expose schema incompatibility details on TreeViewBeta (#28155)
• Legacy API Changes
  • Make point-in-time support optional and consumer-supplied (#28152)

✨ New Features

Enable point-in-time loading on the standard ODSP document service factory (#28152)

OdspDocumentServiceFactoryCore now exposes the optional createPointInTimeDocumentService capability. OdspDocumentServiceFactory inherits this capability, so hosts can use the standard factory with loadContainerToSequenceNumber for sequence-number-based document loading. Factories that do not support point-in-time loading leave the capability undefined.

const factory = new OdspDocumentServiceFactory(
  getStorageToken,
  getWebsocketToken,
);

if (factory.createPointInTimeDocumentService !== undefined) {
  const documentService = await factory.createPointInTimeDocumentService(
    resolvedUrl,
    targetSequenceNumber,
  );
}

Change details

Commit: 46e6f7f

Affected packages:

• @fluidframework/odsp-driver

⬆️ Table of contents

🌳 SharedTree DDS Changes

SharedTree schema errors now explain the mismatch (#28153)

Schema validation errors now report the mismatch category and attach relevant diagnostic context. Depending on the mismatch, tagged telemetry properties identify the node type, field kind, child count, expected leaf value type, actual value type, unexpected fields, or path, making invalid content easier to diagnose while allowing consumers to filter potentially sensitive user data.

When a view schema cannot access a document's stored schema, the error now reports the first schema mismatch and explains whether to initialize the document, upgrade its stored schema, use a compatible view schema, or explicitly migrate the document.

Change details

Commit: 850aa1f

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

TreeViewAlpha can now query whether a staged schema upgrade has been applied (#28154)

A new isStagedUpgradeEnabled method on TreeViewAlpha checks whether a given SchemaUpgrade token has already been applied to a document's stored schema.

This is useful when gradually rolling out a staged schema upgrade via feature flags — for example, to conditionally include the upgrade token in the view configuration after a flag rollback, or to show UI that depends on the upgraded schema.

const view = tree.viewWith(
  new TreeViewConfigurationAlpha({
    schema: mySchema,
    stagedUpgradePolicy: featureFlag.isEnabled
      ? StagedSchemaUpgradePolicy.enabledStagedUpgrades(myUpgrade)
      : StagedSchemaUpgradePolicy.restrictive,
  }),
);

// Show a "create poll" button only if the document supports the new poll schema
if (view.isStagedUpgradeEnabled(myUpgrade)) {
  showCreatePollButton();
}

Change details

Commit: 0ea7aa8

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Preserve enabled staged schema upgrades by default (#28155)

TreeView.upgradeSchema() now includes staged schema upgrades that are already enabled in the document, even when the view's staged upgrade policy does not select them. This prevents a schema upgrade from accidentally attempting to narrow stored schema enabled by another client.

Set includeAlreadyEnabledUpgrades to false when creating the staged upgrade policy to require upgrades to be selected explicitly:

const config = new TreeViewConfigurationAlpha({
  schema: AppSchema,
  stagedUpgradePolicy: {
    includeAlreadyEnabledUpgrades: false,
    ...StagedSchemaUpgradePolicy.enabledStagedUpgrades(myUpgrade),
  },
});

Change details

Commit: 9b61289

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Expose schema incompatibility details on TreeViewBeta (#28155)

TreeViewBeta.compatibility.discrepancies now provides typed SchemaDiscrepancy objects when a view cannot access a tree because its view schema is incompatible with the stored schema. The readonly array may include application-defined schema identifiers and field keys. Each entry includes a mismatch discriminator so consumers can distinguish allowed-type, field-kind, value-schema, and node-kind differences. Allowed-type discrepancies include staged types that are absent from the stored schema in stagedView, while discrepancies on staged optional fields include viewIsStagedOptional: true. Staged-only differences remain compatible and do not produce discrepancies by themselves.

const sf = new SchemaFactory("com.example");
class Todo extends sf.object("Todo", {
  title: sf.number,
}) {}

const view = asBeta(tree.viewWith(new TreeViewConfiguration({ schema: Todo })));
if (!view.compatibility.canView) {
  console.error(view.compatibility.discrepancies);
}

If the stored schema allows string for Todo.title, the output is:

[
  {
    "mismatch": "allowedTypes",
    "location": { "nodeType": "com.example.Todo", "fieldKey": "title" },
    "view": ["com.fluidframework.leaf.number"],
    "stored": ["com.fluidframework.leaf.string"]
  }
]

Applications can see from mismatch: "allowedTypes" that the schemas differ in their allowed types, compare view with stored to determine which types each schema permits, and use location to find the field where the mismatch occurs.

Change details

Commit: 9b61289

Affected packages:

• @fluidframework/tree
• fluid-framework

⬆️ Table of contents

Legacy API Changes

Make point-in-time support optional and consumer-supplied (#28152)

Point-in-time loading is now an optional implementation supplied by the host. Consumers that do not enable the feature no longer include its implementation in their dependency graph. Hosts can control when the feature is loaded by dynamically importing its dedicated entrypoint:

const factory = createOdspDocumentServiceFactory({
  getStorageToken,
  getWebsocketToken,
  persistedCache,
  hostPolicy,
  pointInTimeDocumentServiceImplementation: async (props) => {
    const { createPointInTimeDocumentService } = await import(
      "@fluidframework/odsp-driver/legacy/point-in-time"
    );
    return createPointInTimeDocumentService(props);
  },
});

The legacy-beta getOdspPointInTimeDocumentServiceFactory helper is deprecated. Point-in-time consumers should migrate to createOdspDocumentServiceFactory, which accepts tokens, cache, host policy, and optional feature implementations in one options object. The deprecated helper now loads the implementation only when point-in-time loading is used. Existing OdspDocumentServiceFactory and OdspDocumentServiceFactoryCore constructor signatures remain unchanged.

Change details

Commit: 46e6f7f

Affected packages:

• @fluidframework/odsp-driver

⬆️ Table of contents

🛠️ Start Building Today!

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