fluid-framework 2.72.0 → 2.73.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # fluid-framework
 
+## 2.73.0
+
+### Minor Changes
+
+- Schema snapshot compatibility checker ([#25861](https://github.com/microsoft/FluidFramework/pull/25861)) [e5be416321](https://github.com/microsoft/FluidFramework/commit/e5be4163210ef68b7f8a7c10502f4871c30ec9f3)
+
+  This change adds alpha APIs for creating snapshots of view schema and testing their compatibility for the purposes
+  of schema migrations.
+
+  New APIs:
+  - `checkCompatibility` - Checks the compatibility of the view schema which created the document against the view schema
+    being used to open it.
+  - `importCompatibilitySchemaSnapshot` - Parse a JSON representation of a tree schema into a concrete schema.
+  - `exportCompatibilitySchemaSnapshot` - Returns a JSON representation of the tree schema for snapshot compatibility checking.
+
+  #### Example: Current view schema vs. historical view schema
+
+  An application author is developing an app that has a schema for storing 2D Points.
+  They wish to maintain backwards compatibility in future versions and avoid changing their view schema in a way that breaks
+  this behavior.
+  When introducing a new initial schema, they persists a snapshot using `exportCompatibilitySchemaSnapshot`:
+
+  ```ts
+  const factory = new SchemaFactory("test");
+
+  // The past view schema, for the purposes of illustration. This wouldn't normally appear as a concrete schema in the test
+  // checking compatibility, but rather would be loaded from a snapshot.
+  class Point2D extends factory.object("Point", {
+    x: factory.number,
+    y: factory.number,
+  }) {}
+  const viewSchema = new TreeViewConfiguration({ schema: Point2D });
+  const encodedSchema = JSON.stringify(
+    exportCompatibilitySchemaSnapshot(viewSchema),
+  );
+  fs.writeFileSync("PointSchema.json", encodedSchema);
+  ```
+
+  Next they create a regression test to ensure that the current view schema can read content written by the original view
+  schema (`SchemaCompatibilityStatus.canUpgrade`). Initially `currentViewSchema === Point2D`:
+
+  ```ts
+  const encodedSchema = JSON.parse(fs.readFileSync("PointSchema.json", "utf8"));
+  const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);
+
+  // Check to see if the document created by the historical view schema can be opened with the current view schema
+  const compatibilityStatus = checkCompatibility(
+    oldViewSchema,
+    currentViewSchema,
+  );
+
+  // Check to see if the document created by the historical view schema can be opened with the current view schema
+  const backwardsCompatibilityStatus = checkCompatibility(
+    oldViewSchema,
+    currentViewSchema,
+  );
+
+  // z is not present in Point2D, so the schema must be upgraded
+  assert.equal(backwardsCompatibilityStatus.canView, false);
+
+  // The schema can be upgraded to add the new optional field
+  assert.equal(backwardsCompatibilityStatus.canUpgrade, true);
+  ```
+
+  Additionally, they a regression test to ensure that older view schemas can read content written by the current view
+  schema (`SchemaCompatibilityStatus.canView`):
+
+  ```ts
+  // Test what the old version of the application would do with a tree using the new schema:
+  const forwardsCompatibilityStatus = checkCompatibility(
+    currentViewSchema,
+    oldViewSchema,
+  );
+
+  // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,
+  // this assert will fail, detecting the forwards compatibility break:
+  // this means these two versions of the application cannot collaborate on content using these schema.
+  assert.equal(forwardsCompatibilityStatus.canView, true);
+  ```
+
+  Later in the application development cycle, the application author decides they want to change their Point2D to
+  a Point3D, adding an extra field:
+
+  ```ts
+  // Build the current view schema
+  const schemaFactory = new SchemaFactory("test");
+  class Point3D extends schemaFactory.object("Point", {
+    x: factory.number,
+    y: factory.number,
+
+    // The current schema has a new optional field that was not present on Point2D
+    z: factory.optional(factory.number),
+  }) {}
+  ```
+
+  The test first compatibility test will pass as the Point2D schema is upgradeable to a Point3D schema.
+  However, the second compatibility test fill fail as an application using the Point2D view schema cannot collaborate on
+  content authored using the Point3D schema.
+
 ## 2.72.0
 
 ### Minor Changes

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

@@ -117,6 +117,9 @@ export const ArrayNodeSchema: {
 // @alpha
 export function asAlpha<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewAlpha<TSchema>;
 
+// @alpha
+export function asAlpha<TSchema extends ImplicitFieldSchema>(view: TreeViewConfiguration<TSchema>): TreeViewConfigurationAlpha<TSchema>;
+
 // @beta
 export function asBeta<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewBeta<TSchema>;
 
@@ -138,6 +141,9 @@ export interface BranchableTree extends ViewableTree {
     rebase(branch: TreeBranchFork): void;
 }
 
+// @alpha
+export function checkCompatibility(viewWhichCreatedStoredSchema: TreeViewConfiguration, view: TreeViewConfiguration): Omit<SchemaCompatibilityStatus, "canInitialize">;
+
 // @alpha
 export function cloneWithReplacements(root: unknown, rootKey: string, replacer: (key: string, value: unknown) => {
     clone: boolean;
@@ -287,6 +293,9 @@ export abstract class ErasedType<out Name = unknown> {
 // @alpha
 export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>): T;
 
+// @alpha
+export function exportCompatibilitySchemaSnapshot(config: Pick<TreeViewConfiguration, "schema">): JsonCompatibleReadOnly;
+
 // @public @system
 type ExtractItemType<Item extends LazyItem> = Item extends () => infer Result ? Result : Item;
 
@@ -382,6 +391,7 @@ export const FluidClientVersion: {
     readonly v2_0: "2.0.0";
     readonly v2_43: "2.43.0";
     readonly v2_52: "2.52.0";
+    readonly v2_73: "2.73.0";
 };
 
 // @public
@@ -728,6 +738,9 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 // @public
 export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;
 
+// @alpha
+export function importCompatibilitySchemaSnapshot(config: JsonCompatibleReadOnly): TreeViewConfiguration;
+
 // @alpha
 export function independentInitializedView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & ICodecOptions, content: ViewContent): TreeViewAlpha<TSchema>;
 
@@ -1387,18 +1400,6 @@ export interface SharedTreeFormatOptions {
     treeEncodeType: TreeCompressionStrategy;
 }
 
-// @alpha
-export const SharedTreeFormatVersion: {
-    readonly v1: 1;
-    readonly v2: 2;
-    readonly v3: 3;
-    readonly v5: 5;
-    readonly vSharedBranches: 100;
-};
-
-// @alpha
-export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
-
 // @alpha @input
 export interface SharedTreeOptions extends Partial<CodecWriteOptions>, Partial<SharedTreeFormatOptions>, SharedTreeOptionsBeta {
     readonly enableSharedBranches?: boolean;
@@ -1409,7 +1410,7 @@ export type SharedTreeOptionsBeta = ForestOptions;
 
 // @alpha @sealed
 export interface SimpleAllowedTypeAttributes {
-    readonly isStaged: boolean | undefined;
+    readonly isStaged: false | SchemaUpgrade | undefined;
 }
 
 // @alpha @sealed
@@ -1486,7 +1487,7 @@ export namespace System_TableSchema {
     // @system
     export type CreateColumnOptionsBase<TSchemaFactory extends SchemaFactoryBeta = SchemaFactoryBeta, TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory<TSchemaFactory> & OptionsWithCellSchema<TCell>;
     // @system
-    export function createColumnSchema<const TInputScope extends string | undefined, const TCellSchema extends ImplicitAllowedTypes, const TPropsSchema extends ImplicitFieldSchema>(inputSchemaFactory: SchemaFactoryBeta<TInputScope>, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Column">, NodeKind.Object, TreeNode & TableSchema.Column<TCellSchema, TPropsSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Column">, NodeKind, unknown>, object & {
+    export function createColumnSchema<const TInputScope extends string | undefined, const TCellSchema extends ImplicitAllowedTypes, const TPropsSchema extends ImplicitFieldSchema>(inputSchemaFactory: SchemaFactoryBeta<TInputScope>, propsSchema: TPropsSchema): TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Column">, NodeKind.Object, TreeNode & TableSchema.Column<TCellSchema, TPropsSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Column">, NodeKind, unknown>, object & {
         readonly id?: string | undefined;
     } & (FieldHasDefault<TPropsSchema> extends true ? {
         props?: InsertableTreeFieldFromImplicitField<TPropsSchema> | undefined;
@@ -1501,7 +1502,7 @@ export namespace System_TableSchema {
     // @sealed
     export function createRowSchema<const TInputScope extends string | undefined, const TCellSchema extends ImplicitAllowedTypes, const TPropsSchema extends ImplicitFieldSchema>(inputSchemaFactory: SchemaFactoryBeta<TInputScope>, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row">, NodeKind.Object, TreeNode & TableSchema.Row<TCellSchema, TPropsSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row">, NodeKind, unknown>, object & {
         readonly id?: string | undefined;
-        readonly cells: (InsertableTypedNode_2<TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode_2<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2<TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode_2<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined, unknown>>;
+        readonly cells: (InsertableTypedNode_2<TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2<TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined, unknown>>;
     } & (FieldHasDefault<TPropsSchema> extends true ? {
         props?: InsertableTreeFieldFromImplicitField<TPropsSchema> | undefined;
     } : {
@@ -1509,7 +1510,7 @@ export namespace System_TableSchema {
     }), true, {
         readonly props: TPropsSchema;
         readonly id: FieldSchema_2<FieldKind_2.Identifier, LeafSchema_2<"string", string>, unknown>;
-        readonly cells: FieldSchema_2<FieldKind_2.Required, TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode_2<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined, unknown>, unknown>;
+        readonly cells: FieldSchema_2<FieldKind_2.Required, TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined, unknown>, unknown>;
     }>;
     // @system
     export function createTableSchema<const TInputScope extends string | undefined, const TCellSchema extends ImplicitAllowedTypes, const TColumnSchema extends ColumnSchemaBase<TInputScope, TCellSchema>, const TRowSchema extends RowSchemaBase<TInputScope, TCellSchema>>(inputSchemaFactory: SchemaFactoryBeta<TInputScope>, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): TreeNodeSchemaCore_2<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Table">, NodeKind.Object, true, {
@@ -1636,10 +1637,6 @@ export namespace TableSchema {
     }
     // @sealed
     export interface Column<TCell extends ImplicitAllowedTypes, TProps extends ImplicitFieldSchema = ImplicitFieldSchema> {
-        getCells(): readonly {
-            rowId: string;
-            cell: TreeNodeFromImplicitAllowedTypes<TCell>;
-        }[];
         readonly id: string;
         get props(): TreeFieldFromImplicitField<TProps>;
         set props(value: InsertableTreeFieldFromImplicitField<TProps>);
@@ -1658,19 +1655,9 @@ export namespace TableSchema {
     }
     // @sealed
     export interface Row<TCell extends ImplicitAllowedTypes, TProps extends ImplicitFieldSchema = ImplicitFieldSchema> {
-        getCell(column: Column<TCell>): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-        getCell(columnId: string): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-        getCells(): readonly {
-            columnId: string;
-            cell: TreeNodeFromImplicitAllowedTypes<TCell>;
-        }[];
         readonly id: string;
         get props(): TreeFieldFromImplicitField<TProps>;
         set props(value: InsertableTreeFieldFromImplicitField<TProps>);
-        removeCell(column: Column<TCell>): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-        removeCell(columnId: string): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-        setCell(column: Column<TCell>, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
-        setCell(columnId: string, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
     }
     export function row<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes>(params: System_TableSchema.CreateRowOptionsBase<SchemaFactoryBeta<TScope>, TCell>): System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>;
     export function row<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes, const TProps extends ImplicitFieldSchema>(params: System_TableSchema.CreateRowOptionsBase<SchemaFactoryBeta<TScope>, TCell> & {

package/dist/alpha.d.ts

@@ -250,7 +250,6 @@ export {
 	RunTransactionParams, 
 	SchemaFactoryAlpha, 
 	SharedTreeFormatOptions, 
-	SharedTreeFormatVersion, 
 	SharedTreeOptions, 
 	SimpleAllowedTypeAttributes, 
 	SimpleArrayNodeSchema, 
@@ -294,6 +293,7 @@ export {
 	allowUnused, 
 	asAlpha, 
 	asTreeViewAlpha, 
+	checkCompatibility, 
 	cloneWithReplacements, 
 	comparePersistedSchema, 
 	configuredSharedTree, 
@@ -304,11 +304,13 @@ export {
 	decodeSimpleSchema, 
 	encodeSimpleSchema, 
 	evaluateLazySchema, 
+	exportCompatibilitySchemaSnapshot, 
 	extractPersistedSchema, 
 	generateSchemaFromSimpleSchema, 
 	getBranch, 
 	getJsonSchema, 
 	getSimpleSchema, 
+	importCompatibilitySchemaSnapshot, 
 	independentInitializedView, 
 	independentView, 
 	normalizeAllowedTypes, 

package/lib/alpha.d.ts

@@ -250,7 +250,6 @@ export {
 	RunTransactionParams, 
 	SchemaFactoryAlpha, 
 	SharedTreeFormatOptions, 
-	SharedTreeFormatVersion, 
 	SharedTreeOptions, 
 	SimpleAllowedTypeAttributes, 
 	SimpleArrayNodeSchema, 
@@ -294,6 +293,7 @@ export {
 	allowUnused, 
 	asAlpha, 
 	asTreeViewAlpha, 
+	checkCompatibility, 
 	cloneWithReplacements, 
 	comparePersistedSchema, 
 	configuredSharedTree, 
@@ -304,11 +304,13 @@ export {
 	decodeSimpleSchema, 
 	encodeSimpleSchema, 
 	evaluateLazySchema, 
+	exportCompatibilitySchemaSnapshot, 
 	extractPersistedSchema, 
 	generateSchemaFromSimpleSchema, 
 	getBranch, 
 	getJsonSchema, 
 	getSimpleSchema, 
+	importCompatibilitySchemaSnapshot, 
 	independentInitializedView, 
 	independentView, 
 	normalizeAllowedTypes, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluid-framework",
-  "version": "2.72.0",
+  "version": "2.73.0",
   "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.72.0",
-    "@fluidframework/container-loader": "~2.72.0",
-    "@fluidframework/core-interfaces": "~2.72.0",
-    "@fluidframework/core-utils": "~2.72.0",
-    "@fluidframework/driver-definitions": "~2.72.0",
-    "@fluidframework/fluid-static": "~2.72.0",
-    "@fluidframework/map": "~2.72.0",
-    "@fluidframework/runtime-utils": "~2.72.0",
-    "@fluidframework/sequence": "~2.72.0",
-    "@fluidframework/shared-object-base": "~2.72.0",
-    "@fluidframework/tree": "~2.72.0"
+    "@fluidframework/container-definitions": "~2.73.0",
+    "@fluidframework/container-loader": "~2.73.0",
+    "@fluidframework/core-interfaces": "~2.73.0",
+    "@fluidframework/core-utils": "~2.73.0",
+    "@fluidframework/driver-definitions": "~2.73.0",
+    "@fluidframework/fluid-static": "~2.73.0",
+    "@fluidframework/map": "~2.73.0",
+    "@fluidframework/runtime-utils": "~2.73.0",
+    "@fluidframework/sequence": "~2.73.0",
+    "@fluidframework/shared-object-base": "~2.73.0",
+    "@fluidframework/tree": "~2.73.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
@@ -75,7 +75,7 @@
     "@fluid-tools/build-cli": "^0.60.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.60.0",
-    "@fluidframework/eslint-config-fluid": "~2.72.0",
+    "@fluidframework/eslint-config-fluid": "~2.73.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/node": "^18.19.0",
     "concurrently": "^8.2.1",