fluid-framework 2.82.0 → 2.83.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # fluid-framework
 
+## 2.83.0
+
+### Minor Changes
+
+- Fix false positive error from FormatValidator ([#26372](https://github.com/microsoft/FluidFramework/pull/26372)) [adad917d30](https://github.com/microsoft/FluidFramework/commit/adad917d30e251f4bfd510e7a1ebc4a73bd1f7ee)
+
+  Users of the alpha API [FormatValidatorBasic](https://fluidframework.com/docs/api/fluid-framework/#formatvalidatorbasic-variable)
+  could hit an "Invalid JSON." error when parsing data.
+  This would occur where the result of evaluating "[MinimumVersionForCollab](https://fluidframework.com/docs/api/runtime-definitions/minimumversionforcollab-typealias) \< 2.74.0"
+  differed between the client encoding the data and the client decoding it.
+  For example opening an old document with a new client that sets `MinimumVersionForCollab = 2.74.0` would throw this error.
+  This has been fixed: this case will no longer throw.
+
+- New beta ExtensibleUnionNode API ([#26438](https://github.com/microsoft/FluidFramework/pull/26438)) [05f716ffb5](https://github.com/microsoft/FluidFramework/commit/05f716ffb56e280624e65853dd9291411ee752ff)
+
+  The new `ExtensibleUnionNode` API allows for creation of unions which can tolerate future additions not yet known to the current code.
+
+  ```typescript
+  const sf = new SchemaFactoryBeta("extensibleUnionNodeExample.items");
+  class ItemA extends sf.object("A", { x: sf.string }) {}
+  class ItemB extends sf.object("B", { x: sf.number }) {}
+
+  class AnyItem extends ExtensibleUnionNode.createSchema(
+    [ItemA, ItemB], // Future versions may add more members here
+    sf,
+    "ExtensibleUnion",
+  ) {}
+  // Instances of the union are created using `create`.
+  const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
+  // Reading the content from the union is done via the `union` property,
+  // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
+  const childNode: ItemA | ItemB | undefined = anyItem.union;
+  // To determine which member of the union was present, its schema can be inspected:
+  const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
+  assert.equal(aSchema, ItemA);
+  ```
+
+- Improve error messages when failing to construct nodes ([#26433](https://github.com/microsoft/FluidFramework/pull/26433)) [8c612c6f2b](https://github.com/microsoft/FluidFramework/commit/8c612c6f2bc04a1fc1cdc54e620c2180eb73b107)
+
+  The error messages when constructing tree nodes have been improved.
+  Several cases now list not only the schema identifiers, but also schema names which can help when there are identifier collisions and make it easier to find the implementations.
+  Additionally some cases which did not include what schema were encountered and which were allowed now include both.
+
 ## 2.82.0
 
 ### Minor Changes

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

@@ -152,9 +152,6 @@ export type ChangeMetadata = LocalChangeMetadata | RemoteChangeMetadata;
 // @alpha
 export function checkCompatibility(viewWhichCreatedStoredSchema: TreeViewConfiguration, view: TreeViewConfiguration): Omit<SchemaCompatibilityStatus, "canInitialize">;
 
-// @alpha
-export function checkSchemaCompatibilitySnapshots(options: SchemaCompatibilitySnapshotsOptions): void;
-
 // @alpha
 export function cloneWithReplacements(root: unknown, rootKey: string, replacer: (key: string, value: unknown) => {
     clone: boolean;
@@ -328,11 +325,12 @@ export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>)
 // @alpha
 export function exportCompatibilitySchemaSnapshot(config: Pick<TreeViewConfiguration, "schema">): JsonCompatibleReadOnly;
 
-// @alpha
-export namespace ExtensibleSchemaUnion {
-    export function extensibleSchemaUnion<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, NodeKind_2, unknown>);
+// @beta
+export namespace ExtensibleUnionNode {
+    export function createSchema<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, unknown>);
     export interface Members<T> {
-        readonly child: T | undefined;
+        isValid(): boolean;
+        readonly union: T | undefined;
     }
     export interface Statics<T extends readonly TreeNodeSchema[]> {
         create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;
@@ -1346,17 +1344,6 @@ export interface RunTransactionParams {
     readonly preconditions?: readonly TransactionConstraintAlpha[];
 }
 
-// @alpha @input
-export interface SchemaCompatibilitySnapshotsOptions {
-    readonly fileSystem: SnapshotFileSystem;
-    readonly minVersionForCollaboration: string;
-    readonly mode: "test" | "update";
-    readonly schema: TreeViewConfiguration;
-    readonly snapshotDirectory: string;
-    readonly snapshotUnchangedVersions?: true;
-    readonly version: string;
-}
-
 // @public @sealed
 export interface SchemaCompatibilityStatus {
     readonly canInitialize: boolean;
@@ -1601,6 +1588,23 @@ export interface SnapshotFileSystem {
     }): void;
 }
 
+// @alpha
+export function snapshotSchemaCompatibility(options: SnapshotSchemaCompatibilityOptions): void;
+
+// @alpha @input
+export interface SnapshotSchemaCompatibilityOptions {
+    readonly fileSystem: SnapshotFileSystem;
+    readonly minVersionForCollaboration: string;
+    readonly mode: "assert" | "update";
+    readonly rejectSchemaChangesWithNoVersionChange?: true;
+    readonly rejectVersionsWithNoSchemaChange?: true;
+    readonly schema: TreeViewConfiguration;
+    readonly snapshotDirectory: string;
+    readonly snapshotUnchangedVersions?: true;
+    readonly version: string;
+    readonly versionComparer?: (a: string, b: string) => number;
+}
+
 // @beta @system
 export namespace System_TableSchema {
     // @sealed @system
@@ -1879,7 +1883,7 @@ export interface TransactionResultSuccess<TSuccessValue> {
 // @public
 export type TransformedEvent<TThis, E, A extends any[]> = (event: E, listener: (...args: ReplaceIEventThisPlaceHolder<A, TThis>) => void) => TThis;
 
-// @public @sealed @system
+// @public @sealed
 export interface Tree extends TreeNodeApi {
     contains(node: TreeNode, other: TreeNode): boolean;
     readonly runTransaction: RunTransaction;
@@ -1888,7 +1892,7 @@ export interface Tree extends TreeNodeApi {
 // @public
 export const Tree: Tree;
 
-// @alpha @sealed @system
+// @alpha @sealed
 export interface TreeAlpha {
     branch(node: TreeNode): TreeBranchAlpha | undefined;
     child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;
@@ -1943,7 +1947,7 @@ export const TreeArrayNode: {
     readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent<T>;
 };
 
-// @beta @sealed @system
+// @beta @sealed
 export interface TreeBeta {
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
     create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

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

@@ -184,6 +184,18 @@ export abstract class ErasedType<out Name = unknown> {
     protected abstract brand(dummy: never): Name;
 }
 
+// @beta
+export namespace ExtensibleUnionNode {
+    export function createSchema<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, unknown>);
+    export interface Members<T> {
+        isValid(): boolean;
+        readonly union: T | undefined;
+    }
+    export interface Statics<T extends readonly TreeNodeSchema[]> {
+        create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;
+    }
+}
+
 // @public @system
 type ExtractItemType<Item extends LazyItem> = Item extends () => infer Result ? Result : Item;
 
@@ -1195,7 +1207,7 @@ export type TransactionConstraint = NodeInDocumentConstraint;
 // @public
 export type TransformedEvent<TThis, E, A extends any[]> = (event: E, listener: (...args: ReplaceIEventThisPlaceHolder<A, TThis>) => void) => TThis;
 
-// @public @sealed @system
+// @public @sealed
 export interface Tree extends TreeNodeApi {
     contains(node: TreeNode, other: TreeNode): boolean;
     readonly runTransaction: RunTransaction;
@@ -1232,7 +1244,7 @@ export const TreeArrayNode: {
     readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent<T>;
 };
 
-// @beta @sealed @system
+// @beta @sealed
 export interface TreeBeta {
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
     create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

package/api-report/fluid-framework.legacy.beta.api.md

@@ -187,6 +187,18 @@ export abstract class ErasedType<out Name = unknown> {
     protected abstract brand(dummy: never): Name;
 }
 
+// @beta
+export namespace ExtensibleUnionNode {
+    export function createSchema<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & TreeNodeSchemaCore_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, false, unknown, never, unknown> & (new (data: InternalTreeNode_2) => Members<TreeNodeFromImplicitAllowedTypes<T>> & TreeNode_2 & WithType_2<ScopedSchemaName_2<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, NodeKind_2, unknown>);
+    export interface Members<T> {
+        isValid(): boolean;
+        readonly union: T | undefined;
+    }
+    export interface Statics<T extends readonly TreeNodeSchema[]> {
+        create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;
+    }
+}
+
 // @public @system
 type ExtractItemType<Item extends LazyItem> = Item extends () => infer Result ? Result : Item;
 
@@ -1555,7 +1567,7 @@ export type TransactionConstraint = NodeInDocumentConstraint;
 // @public
 export type TransformedEvent<TThis, E, A extends any[]> = (event: E, listener: (...args: ReplaceIEventThisPlaceHolder<A, TThis>) => void) => TThis;
 
-// @public @sealed @system
+// @public @sealed
 export interface Tree extends TreeNodeApi {
     contains(node: TreeNode, other: TreeNode): boolean;
     readonly runTransaction: RunTransaction;
@@ -1592,7 +1604,7 @@ export const TreeArrayNode: {
     readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent<T>;
 };
 
-// @beta @sealed @system
+// @beta @sealed
 export interface TreeBeta {
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
     create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

package/api-report/fluid-framework.legacy.public.api.md

@@ -864,7 +864,7 @@ export type TransactionConstraint = NodeInDocumentConstraint;
 // @public
 export type TransformedEvent<TThis, E, A extends any[]> = (event: E, listener: (...args: ReplaceIEventThisPlaceHolder<A, TThis>) => void) => TThis;
 
-// @public @sealed @system
+// @public @sealed
 export interface Tree extends TreeNodeApi {
     contains(node: TreeNode, other: TreeNode): boolean;
     readonly runTransaction: RunTransaction;

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

@@ -830,7 +830,7 @@ export type TransactionConstraint = NodeInDocumentConstraint;
 // @public
 export type TransformedEvent<TThis, E, A extends any[]> = (event: E, listener: (...args: ReplaceIEventThisPlaceHolder<A, TThis>) => void) => TThis;
 
-// @public @sealed @system
+// @public @sealed
 export interface Tree extends TreeNodeApi {
     contains(node: TreeNode, other: TreeNode): boolean;
     readonly runTransaction: RunTransaction;

package/dist/alpha.d.ts

@@ -152,6 +152,7 @@ export {
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ErasedBaseType, 
+	ExtensibleUnionNode, 
 	FixRecursiveArraySchema, 
 	FluidSerializableAsTree, 
 	ForestOptions, 
@@ -205,7 +206,6 @@ export {
 	CreateIndependentTreeAlphaOptions, 
 	DirtyTreeMap, 
 	DirtyTreeStatus, 
-	ExtensibleSchemaUnion, 
 	FactoryContent, 
 	FactoryContentObject, 
 	FieldPropsAlpha, 
@@ -262,7 +262,6 @@ export {
 	RevertibleAlpha, 
 	RevertibleAlphaFactory, 
 	RunTransactionParams, 
-	SchemaCompatibilitySnapshotsOptions, 
 	SchemaFactoryAlpha, 
 	SchemaType, 
 	SharedTreeFormatOptions, 
@@ -280,6 +279,7 @@ export {
 	SimpleTreeIndex, 
 	SimpleTreeSchema, 
 	SnapshotFileSystem, 
+	SnapshotSchemaCompatibilityOptions, 
 	TransactionCallbackStatus, 
 	TransactionConstraintAlpha, 
 	TransactionResult, 
@@ -310,7 +310,6 @@ export {
 	asAlpha, 
 	asTreeViewAlpha, 
 	checkCompatibility, 
-	checkSchemaCompatibilitySnapshots, 
 	cloneWithReplacements, 
 	comparePersistedSchema, 
 	configuredSharedTree, 
@@ -342,6 +341,7 @@ export {
 	replaceConciseTreeHandles, 
 	replaceHandles, 
 	replaceVerboseTreeHandles, 
+	snapshotSchemaCompatibility, 
 	trackDirtyNodes
 	// #endregion
 } from "./index.js";

package/dist/beta.d.ts

@@ -152,6 +152,7 @@ export {
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ErasedBaseType, 
+	ExtensibleUnionNode, 
 	FixRecursiveArraySchema, 
 	FluidSerializableAsTree, 
 	ForestOptions, 

package/dist/legacy.d.ts

@@ -159,6 +159,7 @@ export {
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ErasedBaseType, 
+	ExtensibleUnionNode, 
 	FixRecursiveArraySchema, 
 	FluidSerializableAsTree, 
 	ForestOptions, 

package/lib/alpha.d.ts

@@ -152,6 +152,7 @@ export {
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ErasedBaseType, 
+	ExtensibleUnionNode, 
 	FixRecursiveArraySchema, 
 	FluidSerializableAsTree, 
 	ForestOptions, 
@@ -205,7 +206,6 @@ export {
 	CreateIndependentTreeAlphaOptions, 
 	DirtyTreeMap, 
 	DirtyTreeStatus, 
-	ExtensibleSchemaUnion, 
 	FactoryContent, 
 	FactoryContentObject, 
 	FieldPropsAlpha, 
@@ -262,7 +262,6 @@ export {
 	RevertibleAlpha, 
 	RevertibleAlphaFactory, 
 	RunTransactionParams, 
-	SchemaCompatibilitySnapshotsOptions, 
 	SchemaFactoryAlpha, 
 	SchemaType, 
 	SharedTreeFormatOptions, 
@@ -280,6 +279,7 @@ export {
 	SimpleTreeIndex, 
 	SimpleTreeSchema, 
 	SnapshotFileSystem, 
+	SnapshotSchemaCompatibilityOptions, 
 	TransactionCallbackStatus, 
 	TransactionConstraintAlpha, 
 	TransactionResult, 
@@ -310,7 +310,6 @@ export {
 	asAlpha, 
 	asTreeViewAlpha, 
 	checkCompatibility, 
-	checkSchemaCompatibilitySnapshots, 
 	cloneWithReplacements, 
 	comparePersistedSchema, 
 	configuredSharedTree, 
@@ -342,6 +341,7 @@ export {
 	replaceConciseTreeHandles, 
 	replaceHandles, 
 	replaceVerboseTreeHandles, 
+	snapshotSchemaCompatibility, 
 	trackDirtyNodes
 	// #endregion
 } from "./index.js";

package/lib/beta.d.ts

@@ -152,6 +152,7 @@ export {
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ErasedBaseType, 
+	ExtensibleUnionNode, 
 	FixRecursiveArraySchema, 
 	FluidSerializableAsTree, 
 	ForestOptions, 

package/lib/legacy.d.ts

@@ -159,6 +159,7 @@ export {
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ErasedBaseType, 
+	ExtensibleUnionNode, 
 	FixRecursiveArraySchema, 
 	FluidSerializableAsTree, 
 	ForestOptions, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluid-framework",
-  "version": "2.82.0",
+  "version": "2.83.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.82.0",
-    "@fluidframework/container-loader": "~2.82.0",
-    "@fluidframework/core-interfaces": "~2.82.0",
-    "@fluidframework/core-utils": "~2.82.0",
-    "@fluidframework/driver-definitions": "~2.82.0",
-    "@fluidframework/fluid-static": "~2.82.0",
-    "@fluidframework/map": "~2.82.0",
-    "@fluidframework/runtime-utils": "~2.82.0",
-    "@fluidframework/sequence": "~2.82.0",
-    "@fluidframework/shared-object-base": "~2.82.0",
-    "@fluidframework/tree": "~2.82.0"
+    "@fluidframework/container-definitions": "~2.83.0",
+    "@fluidframework/container-loader": "~2.83.0",
+    "@fluidframework/core-interfaces": "~2.83.0",
+    "@fluidframework/core-utils": "~2.83.0",
+    "@fluidframework/driver-definitions": "~2.83.0",
+    "@fluidframework/fluid-static": "~2.83.0",
+    "@fluidframework/map": "~2.83.0",
+    "@fluidframework/runtime-utils": "~2.83.0",
+    "@fluidframework/sequence": "~2.83.0",
+    "@fluidframework/shared-object-base": "~2.83.0",
+    "@fluidframework/tree": "~2.83.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
@@ -75,7 +75,7 @@
     "@fluid-tools/build-cli": "^0.63.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.63.0",
-    "@fluidframework/eslint-config-fluid": "~2.82.0",
+    "@fluidframework/eslint-config-fluid": "~2.83.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/node": "~20.19.30",
     "concurrently": "^9.2.1",

package/api-extractor-lint.json

@@ -1,4 +0,0 @@
-{
-	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-lint.esm.primary.json"
-}