fluid-framework 2.112.0 → 2.113.1

package/CHANGELOG.md

@@ -1,5 +1,179 @@
 # fluid-framework
 
+## 2.113.0
+
+### Minor Changes
+
+- Enable select staged schema upgrades at runtime via view configuration ([#27542](https://github.com/microsoft/FluidFramework/pull/27542)) [44f40e8411](https://github.com/microsoft/FluidFramework/commit/44f40e8411d53bc22939a8f53343863f420bb0de)
+
+  SharedTree now supports enabling selected staged schema upgrades when initializing or upgrading a document's stored schema.
+  This lets applications deploy code that understands a schema change before enabling that change in documents.
+  It separates code rollout from feature rollout.
+
+  #### API
+
+  Pass `stagedUpgradePolicy` in the configuration object to
+  [`ITreeAlpha.viewWith`](https://fluidframework.com/docs/api/tree/viewabletree-interface#viewwith-methodsignature)
+  to select which schema upgrades to enable at runtime.
+
+  Use `StagedSchemaUpgradePolicy.enabledStagedUpgrades(...)` with `SchemaUpgrade` objects from
+  [`SchemaFactoryBeta.staged`](https://fluidframework.com/docs/api/tree/schemastaticsbeta-interface#staged-propertysignature)
+  or [`SchemaFactoryAlpha.stagedOptional`](https://fluidframework.com/docs/api/tree/schemafactoryalpha-class#stagedoptional-property):
+
+  The following example defines a staged type, extracts its `SchemaUpgrade` token, and passes it to the view configuration so the staged type is enabled when the schema is upgraded:
+
+  ```typescript
+  const sf = new SchemaFactoryBeta("my-app");
+
+  class ChecklistItem extends sf.object("ChecklistItem", { text: sf.string }) {}
+
+  // `staged` wraps the type so it can be enabled at runtime.
+  const stagedChecklist = SchemaFactoryBeta.staged(ChecklistItem);
+  // The SchemaUpgrade token identifies this staged type.
+  const checklistUpgrade = stagedChecklist.metadata.stagedSchemaUpgrade;
+
+  class AppSchema extends sf.object("AppSchema", {
+    items: sf.array([sf.string, stagedChecklist]),
+  }) {}
+
+  const view = tree.viewWith(
+    new TreeViewConfigurationAlpha({
+      schema: AppSchema,
+      stagedUpgradePolicy:
+        StagedSchemaUpgradePolicy.enabledStagedUpgrades(checklistUpgrade),
+    }),
+  );
+  ```
+
+  When `stagedUpgradePolicy` is omitted or `undefined`, the default is
+  `StagedSchemaUpgradePolicy.restrictive`.
+  This excludes all staged schema upgrades, producing the most conservative stored schema.
+
+  Advanced callers can provide a custom `StagedSchemaUpgradePolicy` object:
+
+  ```typescript
+  const enabledFeatures = new Set<SchemaUpgrade>([checklistUpgrade]);
+
+  const view = tree.viewWith(
+    new TreeViewConfigurationAlpha({
+      schema: AppSchema,
+      stagedUpgradePolicy: {
+        includeStaged: (upgrade) => enabledFeatures.has(upgrade),
+        includeStagedOptional: (upgrade) => enabledFeatures.has(upgrade),
+      },
+    }),
+  );
+  ```
+
+  This is useful for fine-grained rollout control or integration tests.
+
+  #### Pre-built Policies
+
+  The `StagedSchemaUpgradePolicy` namespace provides convenient pre-built policies:
+  - **`restrictive`** (default): excludes all staged upgrades.
+  - **`permissive`**: includes all staged upgrades. Useful in tests.
+  - **`enabledStagedUpgrades(...)`**: includes only the specified upgrades.
+
+  #### Production
+
+  Applications can use feature flags to control when staged schema upgrades are enabled.
+  Previously, enabling a staged schema required a code change that removed the staged wrapper.
+  With this API, the staged wrapper stays in code while `stagedUpgradePolicy` decides at runtime which documents enable it.
+
+  For example, an application adding checklist items can deploy clients that understand the new schema first,
+  then enable the stored-schema upgrade only where a feature flag is active:
+
+  ```typescript
+  const sf = new SchemaFactoryBeta("example-app");
+
+  class ChecklistItem extends sf.object("ChecklistItem", {
+    text: sf.string,
+  }) {}
+
+  const stagedChecklistItem = SchemaFactoryBeta.staged(ChecklistItem);
+  const checklistItemSchemaUpgrade =
+    stagedChecklistItem.metadata.stagedSchemaUpgrade;
+
+  class AppSchema extends sf.object("AppSchema", {
+    // `taskItem` allows plain text today; the staged type is added for future rollout.
+    taskItem: sf.optional([sf.string, stagedChecklistItem]),
+  }) {}
+
+  const enableChecklistItems = featureFlags.enableChecklistItems;
+
+  const view = tree.viewWith(
+    new TreeViewConfigurationAlpha({
+      schema: AppSchema,
+      stagedUpgradePolicy: enableChecklistItems
+        ? StagedSchemaUpgradePolicy.enabledStagedUpgrades(
+            checklistItemSchemaUpgrade,
+          )
+        : undefined,
+    }),
+  );
+
+  if (view.compatibility.canInitialize) {
+    // New documents include the checklist schema only while the rollout is enabled.
+    view.initialize(initialContent);
+  } else if (view.compatibility.canUpgrade) {
+    // Writes the staged type into the stored schema for this document.
+    view.upgradeSchema();
+  }
+  ```
+
+  Once a staged schema upgrade has been written to a document's stored schema, that change is permanent.
+  If `upgradeSchema` is later called from a view that does not include the previously enabled token,
+  it throws a `UsageError` because the new target would narrow the stored schema.
+
+  In practice, keep the upgrade token configured for as long as any document may have been upgraded.
+  Once the staged wrapper is removed from the code, the token is no longer needed.
+
+  #### Testing
+
+  Tests can verify that the current application version handles documents with staged types enabled.
+  Without such testing, it is hard to confirm that staging prepared the application—not just the schema—for the new types.
+
+  ```typescript
+  const currentView = currentAppTree.viewWith(
+    new TreeViewConfiguration({ schema: CurrentAppSchema }),
+  );
+  currentView.initialize(existingTaskDocument);
+  await ensureSynchronized();
+
+  const nextView = asAlpha(nextAppTree).viewWith(
+    new TreeViewConfigurationAlpha({
+      schema: AppSchemaWithStagedChecklist,
+      stagedUpgradePolicy: StagedSchemaUpgradePolicy.enabledStagedUpgrades(
+        checklistItemSchemaUpgrade,
+      ),
+    }),
+  );
+
+  // The next version can read the document, but the checklist shape is not yet
+  // in stored schema and cannot be written.
+  assert.throws(() =>
+    addChecklistItem(nextView.root, { text: "Review rollout" }),
+  );
+
+  nextView.upgradeSchema();
+  await ensureSynchronized();
+
+  // Older clients are now incompatible; the next version can use the staged shape.
+  assert.equal(currentView.compatibility.canView, false);
+  addChecklistItem(nextView.root, { text: "Review rollout" });
+  await validateChecklistScenario(nextView);
+  ```
+
+- Fix assert when inserting the same node multiple times ([#27734](https://github.com/microsoft/FluidFramework/pull/27734)) [b509d00166](https://github.com/microsoft/FluidFramework/commit/b509d00166773585c42c60e97ec30a86fbd20cd5)
+
+  When inserting the same node multiple times in a single array insertion, a `UsageError` is now thrown instead of an assert `0xa2b`.
+
+  For example, this now throws a `UsageError` with message `A "ArrayNodeTest.Item" node was provided more than once in a single insertion. A node may not be in more than one place in the tree.`:
+
+  ```TypeScript
+  array.insertAtEnd(item, item);
+  ```
+
 ## 2.112.0
 
 ### Minor Changes

package/api-report/fluid-framework.alpha.api.md

@@ -1102,6 +1102,11 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @alpha
+export interface ITreeViewConfigurationAlpha<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> extends ITreeViewConfiguration<TSchema> {
+    readonly stagedUpgradePolicy?: StagedSchemaUpgradePolicy;
+}
+
 // @alpha @sealed
 export interface JsonArrayNodeSchema extends JsonNodeSchemaBase<NodeKind.Array, "array"> {
     readonly items: JsonFieldSchema;
@@ -1850,6 +1855,22 @@ export interface SnapshotSchemaCompatibilityOptions {
     readonly versionComparer?: (a: string, b: string) => number;
 }
 
+// @alpha @input
+export interface StagedSchemaUpgradePolicy {
+    includeStaged(upgrade: SchemaUpgrade): boolean;
+    includeStagedOptional(upgrade: SchemaUpgrade): boolean;
+}
+
+// @alpha
+export const StagedSchemaUpgradePolicy: StagedSchemaUpgradePolicyFactory;
+
+// @alpha @sealed
+export interface StagedSchemaUpgradePolicyFactory {
+    enabledStagedUpgrades(...upgrades: SchemaUpgrade[]): StagedSchemaUpgradePolicy;
+    readonly permissive: StagedSchemaUpgradePolicy;
+    readonly restrictive: StagedSchemaUpgradePolicy;
+}
+
 // @beta @system
 export namespace System_TableSchema {
     // @sealed @system
@@ -2489,7 +2510,6 @@ export interface TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | Unsa
     readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;
     // (undocumented)
     fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
-    // (undocumented)
     initialize(content: InsertableField<TSchema>): void;
     // (undocumented)
     get root(): ReadableField<TSchema>;
@@ -2516,11 +2536,12 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
 
 // @alpha @sealed
 export class TreeViewConfigurationAlpha<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> extends TreeViewConfiguration<TSchema> implements TreeSchema {
-    constructor(props: ITreeViewConfiguration<TSchema>);
+    constructor(props: ITreeViewConfigurationAlpha<TSchema>);
     // (undocumented)
     readonly definitions: ReadonlyMap<string, SimpleNodeSchema<SchemaType.View> & TreeNodeSchema>;
     // (undocumented)
     readonly root: FieldSchemaAlpha;
+    readonly stagedUpgradePolicy: StagedSchemaUpgradePolicy;
 }
 
 // @public @sealed

package/dist/alpha.d.ts

@@ -258,6 +258,7 @@ export {
 	HandleConverter, 
 	ICodecOptions, 
 	ITreeAlpha, 
+	ITreeViewConfigurationAlpha, 
 	IncrementalEncodingPolicy, 
 	IndependentViewOptions, 
 	IndependentViewTelemetryOptions, 
@@ -326,6 +327,8 @@ export {
 	SimpleObjectNodeSchema, 
 	SimpleRecordNodeSchema, 
 	SimpleTreeSchema, 
+	StagedSchemaUpgradePolicy, 
+	StagedSchemaUpgradePolicyFactory, 
 	TextAsTree, 
 	TransactionCallbackStatusAlpha, 
 	TransactionConstraintAlpha, 

package/lib/alpha.d.ts

@@ -258,6 +258,7 @@ export {
 	HandleConverter, 
 	ICodecOptions, 
 	ITreeAlpha, 
+	ITreeViewConfigurationAlpha, 
 	IncrementalEncodingPolicy, 
 	IndependentViewOptions, 
 	IndependentViewTelemetryOptions, 
@@ -326,6 +327,8 @@ export {
 	SimpleObjectNodeSchema, 
 	SimpleRecordNodeSchema, 
 	SimpleTreeSchema, 
+	StagedSchemaUpgradePolicy, 
+	StagedSchemaUpgradePolicyFactory, 
 	TextAsTree, 
 	TransactionCallbackStatusAlpha, 
 	TransactionConstraintAlpha, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluid-framework",
-  "version": "2.112.0",
+  "version": "2.113.1",
   "description": "The main entry point into Fluid Framework public packages",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -57,17 +57,17 @@
   "main": "lib/index.js",
   "types": "lib/public.d.ts",
   "dependencies": {
-    "@fluidframework/container-definitions": "~2.112.0",
-    "@fluidframework/container-loader": "~2.112.0",
-    "@fluidframework/core-interfaces": "~2.112.0",
-    "@fluidframework/core-utils": "~2.112.0",
-    "@fluidframework/driver-definitions": "~2.112.0",
-    "@fluidframework/fluid-static": "~2.112.0",
-    "@fluidframework/map": "~2.112.0",
-    "@fluidframework/runtime-utils": "~2.112.0",
-    "@fluidframework/sequence": "~2.112.0",
-    "@fluidframework/shared-object-base": "~2.112.0",
-    "@fluidframework/tree": "~2.112.0"
+    "@fluidframework/container-definitions": "~2.113.1",
+    "@fluidframework/container-loader": "~2.113.1",
+    "@fluidframework/core-interfaces": "~2.113.1",
+    "@fluidframework/core-utils": "~2.113.1",
+    "@fluidframework/driver-definitions": "~2.113.1",
+    "@fluidframework/fluid-static": "~2.113.1",
+    "@fluidframework/map": "~2.113.1",
+    "@fluidframework/runtime-utils": "~2.113.1",
+    "@fluidframework/sequence": "~2.113.1",
+    "@fluidframework/shared-object-base": "~2.113.1",
+    "@fluidframework/tree": "~2.113.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",