@fluidframework/tree 2.117.0 → 3.0.0

package/src/shared-tree-core/editManagerCodecsCommons.ts

@@ -15,6 +15,7 @@ import type {
 	SchemaAndPolicy,
 } from "../core/index.js";
 import {
+	copyProperty,
 	mapIterable,
 	type IdentifierHealingConfig,
 	type JsonCompatibleReadOnly,
@@ -56,7 +57,6 @@ export interface EditManagerDecodingContext {
 	readonly healing?: IdentifierHealingConfig;
 }
 
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 function encodeCommit<TChangeset, T extends Commit<TChangeset>>(
 	changeCodec: IJsonCodec<
 		TChangeset,
@@ -73,27 +73,21 @@ function encodeCommit<TChangeset, T extends Commit<TChangeset>>(
 	commit: T,
 	context: ChangeEncodingContext,
 	includeCustomMetadata: boolean,
-) {
-	const encoded = {
-		...commit,
+): Mutable<EncodedCommit<JsonCompatibleReadOnly>> {
+	const encoded: Mutable<EncodedCommit<JsonCompatibleReadOnly>> = {
+		change: changeCodec.encode(commit.change, { ...context, revision: commit.revision }),
 		revision: revisionTagCodec.encode(commit.revision, {
 			originatorId: commit.sessionId,
 			idCompressor: context.idCompressor,
 			revision: undefined,
 			isSummary: context.isSummary,
 		}),
-		change: changeCodec.encode(commit.change, { ...context, revision: commit.revision }),
+		sessionId: commit.sessionId,
 	};
-	// Rebuilt rather than spread through, both to convert it to the persisted form and so that a client
-	// writing an older format never emits a field that format does not define.
-	if (encoded.customMetadata === undefined) {
-		const { customMetadata: _, ...withoutMetadata } = encoded;
-		return withoutMetadata;
+	if (includeCustomMetadata && commit.customMetadata !== undefined) {
+		encoded.customMetadata = encodeCustomMetadataTree(commit.customMetadata);
 	}
-	const { customMetadata, ...rest } = encoded;
-	return includeCustomMetadata
-		? { ...rest, customMetadata: encodeCustomMetadataTree(customMetadata) }
-		: rest;
+	return encoded;
 }
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -121,7 +115,7 @@ function decodeCommit<TChangeset, T extends EncodedCommit<JsonCompatibleReadOnly
 	});
 
 	return {
-		...commit,
+		sessionId: commit.sessionId,
 		revision,
 		change: changeCodec.decode(commit.change, { ...context, revision }),
 		customMetadata: decodeCustomMetadataTree(commit.customMetadata),
@@ -145,10 +139,10 @@ export function encodeSharedBranch<TChangeset>(
 	context: EditManagerEncodingContext,
 	originatorId: SessionId | undefined,
 	includeCustomMetadata: boolean,
-): EncodedSharedBranch<TChangeset> {
-	const json: Mutable<EncodedSharedBranch<TChangeset>> = {
-		trunk: data.trunk.map((commit) =>
-			encodeCommit(
+): EncodedSharedBranch<JsonCompatibleReadOnly> {
+	const json: Mutable<EncodedSharedBranch<JsonCompatibleReadOnly>> = {
+		trunk: data.trunk.map((commit) => {
+			const encoded = encodeCommit(
 				changeCodec,
 				revisionTagCodec,
 				commit,
@@ -160,8 +154,11 @@ export function encodeSharedBranch<TChangeset>(
 					isSummary: context.isSummary,
 				},
 				includeCustomMetadata,
-			),
-		),
+			);
+			copyProperty(commit, "sequenceNumber", encoded);
+			copyProperty(commit, "indexInBatch", encoded);
+			return encoded;
+		}),
 		peers: Array.from(data.peerLocalBranches.entries(), ([sessionId, branch]) => [
 			sessionId,
 			{
@@ -233,20 +230,20 @@ export function decodeSharedBranch<TChangeset>(
 	context: EditManagerDecodingContext,
 	originatorId: SessionId | undefined,
 ): SharedBranchSummaryData<TChangeset> {
-	// TODO: sort out EncodedCommit vs Commit, and make this type check without type assertion.
 	const trunk = json.trunk as readonly (EncodedCommit<JsonCompatibleReadOnly> & SequenceId)[];
 	const data: Mutable<SharedBranchSummaryData<TChangeset>> = {
-		trunk: trunk.map(
-			(commit): SequencedCommit<TChangeset> =>
-				// TODO: sort out EncodedCommit vs Commit, and make this type check without `as`.
-				decodeCommit(changeCodec, revisionTagCodec, commit, {
-					originatorId: commit.sessionId,
-					idCompressor: context.idCompressor,
-					revision: undefined,
-					isSummary: context.isSummary,
-					healing: context.healing,
-				}),
-		),
+		trunk: trunk.map((commit): SequencedCommit<TChangeset> => {
+			const decoded = decodeCommit(changeCodec, revisionTagCodec, commit, {
+				originatorId: commit.sessionId,
+				idCompressor: context.idCompressor,
+				revision: undefined,
+				isSummary: context.isSummary,
+				healing: context.healing,
+			});
+			copyProperty(commit, "sequenceNumber", decoded);
+			copyProperty(commit, "indexInBatch", decoded);
+			return decoded;
+		}),
 		peerLocalBranches: new Map(
 			mapIterable(json.peers, ([sessionId, branch]) => [
 				sessionId,
@@ -258,7 +255,6 @@ export function decodeSharedBranch<TChangeset>(
 						isSummary: context.isSummary,
 					}),
 					commits: branch.commits.map((commit) =>
-						// TODO: sort out EncodedCommit vs Commit, and make this type check without `as`.
 						decodeCommit(
 							changeCodec,
 							revisionTagCodec,

package/src/shared-tree-core/editManagerCodecsV1toV4.ts

@@ -72,7 +72,7 @@ export function makeV1toV4andV6CodecWithVersion<TChangeset>(
 				data.originator,
 				includeCustomMetadata,
 			);
-			const encoded: EncodedEditManager<TChangeset> = {
+			const encoded: EncodedEditManager<JsonCompatibleReadOnly> = {
 				trunk: mainBranch.trunk,
 				branches: mainBranch.peers,
 				version,

package/src/shared-tree-core/editManagerCodecsVSharedBranches.ts

@@ -65,13 +65,13 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 				data.originator !== undefined,
 				0xca5 /* Cannot encode vSharedBranches summary without originator */,
 			);
-			const json: Mutable<EncodedEditManager<TChangeset>> = {
+			const json: Mutable<EncodedEditManager<JsonCompatibleReadOnly>> = {
 				main: mainBranch,
 				originator: data.originator,
 				version,
 			};
 			if (data.branches !== undefined && data.branches.size > 0) {
-				const branches: EncodedSharedBranch<TChangeset>[] = [];
+				const branches: EncodedSharedBranch<JsonCompatibleReadOnly>[] = [];
 				for (const [_, branch] of data.branches) {
 					branches.push(
 						encodeSharedBranch(

package/src/simple-tree/api/cloneTree.ts

@@ -0,0 +1,47 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TreeFieldStoredSchema } from "../../core/index.js";
+import { defaultSchemaPolicy, FieldKinds } from "../../feature-libraries/index.js";
+import { brand } from "../../util/index.js";
+import {
+	Context,
+	getKernel,
+	isTreeNode,
+	UnhydratedContext,
+	type Unhydrated,
+} from "../core/index.js";
+import { getUnhydratedContext } from "../createContext.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
+
+import { createFromCursor } from "./create.js";
+
+/**
+ * Clones the persisted data associated with a node.
+ */
+export function cloneTree<const TSchema extends ImplicitFieldSchema>(
+	node: TreeFieldFromImplicitField<TSchema>,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+	if (!isTreeNode(node)) {
+		return node;
+	}
+
+	const kernel = getKernel(node);
+	const cursor = kernel.getInnerNode().borrowCursor();
+	const flexContext = new UnhydratedContext(
+		defaultSchemaPolicy,
+		kernel.context.flexContext.schema,
+	);
+	const context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);
+
+	const fieldSchema: TreeFieldStoredSchema = {
+		kind: FieldKinds.required.identifier,
+		types: new Set([brand(kernel.schema.identifier)]),
+		persistedMetadata: undefined,
+	};
+	return createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<
+		TreeFieldFromImplicitField<TSchema>
+	>;
+}

package/src/simple-tree/api/configuration.ts

@@ -158,22 +158,22 @@ export interface ITreeViewConfiguration<
 
 /**
  * Property-bag configuration for {@link TreeViewConfigurationAlpha} construction.
+ * @input
  * @alpha
  */
 export interface ITreeViewConfigurationAlpha<
 	TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
 > extends ITreeViewConfiguration<TSchema> {
 	/**
-	 * Policy for generating stored schema from the view schema.
+	 * Policy for generating stored schema from the view schema during staged schema upgrades.
 	 *
 	 * @remarks
-	 * If omitted or `undefined`, defaults to {@link StagedSchemaUpgradePolicyFactory.restrictive}
-	 * which does not enable any staged schema upgrades.
-	 *
 	 * If provided, this policy is used when generating stored schema to include in documents via
 	 * `initialize` / `upgradeSchema` as well as in {@link snapshotSchemaCompatibility} to validate
 	 * the compatibility of such documents.
 	 *
+	 * @defaultValue {@link StagedSchemaUpgradePolicyFactory.restrictive}
+	 *
 	 * @example Enabling specific staged upgrades
 	 * ```typescript
 	 * const config = new TreeViewConfigurationAlpha({

package/src/simple-tree/api/discrepancies.ts

@@ -27,6 +27,7 @@ import {
 	NodeKind,
 	normalizeAndEvaluateAnnotatedAllowedTypes,
 	type AnnotatedAllowedType,
+	type SchemaUpgrade,
 	type TreeNodeSchema,
 } from "../core/index.js";
 import {
@@ -48,6 +49,25 @@ import type { TreeSchema } from "../treeSchema.js";
 
 import { tryStoredSchemaAsArray } from "./customTree.js";
 
+/**
+ * Collects upgrade location data during a schema walk.
+ * @remarks Called for each staged type or staged optional field encountered.
+ */
+export interface UpgradeLocationCollector {
+	/**
+	 * Record a staged allowed type location.
+	 * @param upgrade - The upgrade token guarding this type.
+	 * @param isEnabled - Whether this type is present in stored schema.
+	 */
+	allowedType(upgrade: SchemaUpgrade, isEnabled: boolean): void;
+	/**
+	 * Record a staged optional field location.
+	 * @param upgrade - The upgrade token guarding this field.
+	 * @param isEnabled - Whether the stored field is already optional.
+	 */
+	optionalField(upgrade: SchemaUpgrade, isEnabled: boolean): void;
+}
+
 /**
  * Discriminated union (keyed on `mismatch`) of discrepancies between a view and stored schema which
  * make it possible for content matching the stored schema to be incompatible with the view schema.
@@ -79,6 +99,11 @@ export interface FieldDiscrepancyLocation {
 	 * - the discrepancy is for 'all fields' of a map node
 	 */
 	readonly fieldKey: FieldKey | undefined;
+	/**
+	 * Whether the view field is a staged optional field.
+	 * Omitted when false.
+	 */
+	readonly viewIsStagedOptional?: true;
 }
 
 /**
@@ -94,6 +119,13 @@ export interface AllowedTypeDiscrepancy extends FieldDiscrepancyLocation {
 	 * (excluding {@link SchemaStaticsBeta.staged | staged} schema) which are not allowed in stored schema.
 	 */
 	readonly view: readonly AnnotatedAllowedType<TreeNodeSchema>[];
+	/**
+	 * Staged allowed types in the view schema which are not allowed in stored schema.
+	 *
+	 * @remarks
+	 * These types do not cause the discrepancy and are omitted when there are none.
+	 */
+	readonly stagedView?: readonly AnnotatedAllowedType<TreeNodeSchema>[];
 	/**
 	 * Allowed type identifiers in stored schema which are not allowed in view schema
 	 * (including the view schema's {@link SchemaStaticsBeta.staged | staged} schema).
@@ -174,15 +206,25 @@ function doesNodeKindMatchStoredNodeKind(
 
 /**
  * Finds and reports discrepancies between a view schema and a stored schema which make "canView" false.
+ *
+ * Optionally collects upgrade location information for staged schema upgrades during the same walk.
+ *
  * @remarks
  * See documentation on {@link Discrepancy} and its subtypes for details of possible discrepancies.
  */
 export function* getDiscrepanciesInAllowedContent(
 	view: TreeSchema,
 	stored: TreeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<Discrepancy> {
 	// check root field discrepancies
-	yield* getFieldDiscrepancies(view.root, stored.rootFieldSchema, undefined, undefined);
+	yield* getFieldDiscrepancies(
+		view.root,
+		stored.rootFieldSchema,
+		undefined,
+		undefined,
+		upgradeCollector,
+	);
 
 	// Check all of the stored nodes, including their fields for discrepancies.
 	for (const [identifier, storedSchema] of stored.nodeSchema) {
@@ -190,7 +232,7 @@ export function* getDiscrepanciesInAllowedContent(
 
 		// if the view schema has a node that's also in the stored schema, check it.
 		if (viewSchema !== undefined) {
-			yield* getNodeDiscrepancies(identifier, viewSchema, storedSchema);
+			yield* getNodeDiscrepancies(identifier, viewSchema, storedSchema, upgradeCollector);
 		}
 		// Note that nodes that are missing in the view schema are only a problem if other stored schema nodes actually reference them which will produce its own discrepancy, so we can rely on that to produce any needed discrepancies.
 	}
@@ -200,6 +242,7 @@ function* getNodeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier,
 	view: TreeNodeSchema,
 	stored: TreeNodeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<Discrepancy> {
 	if (!doesNodeKindMatchStoredNodeKind(view.kind, getStoredNodeSchemaType(stored))) {
 		yield {
@@ -221,6 +264,7 @@ function* getNodeDiscrepancies(
 				identifier,
 				view,
 				stored as ObjectNodeStoredSchema,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -246,6 +290,8 @@ function* getNodeDiscrepancies(
 				arrayStoredSchema,
 				brand(view.identifier),
 				EmptyKey,
+				false,
+				upgradeCollector,
 			);
 
 			break;
@@ -261,6 +307,7 @@ function* getNodeDiscrepancies(
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
 				undefined,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -275,6 +322,7 @@ function* getNodeDiscrepancies(
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
 				undefined,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -308,7 +356,7 @@ function* getNodeDiscrepancies(
 export function findExtraAllowedTypes(
 	viewAllowedTypes: readonly AnnotatedAllowedType<TreeNodeSchema>[],
 	storedAllowedTypes: TreeTypeSet,
-): Pick<AllowedTypeDiscrepancy, "view" | "stored"> {
+): Pick<AllowedTypeDiscrepancy, "view" | "stagedView" | "stored"> {
 	const viewNodeSchemaIdentifiers = new Set(
 		viewAllowedTypes.map((value) => value.type.identifier),
 	);
@@ -322,10 +370,19 @@ export function findExtraAllowedTypes(
 			!storedAllowedTypes.has(brand(value.type.identifier)) &&
 			value.metadata.stagedSchemaUpgrade === undefined,
 	);
+	const stagedView = viewAllowedTypes.filter(
+		(value) =>
+			!storedAllowedTypes.has(brand(value.type.identifier)) &&
+			value.metadata.stagedSchemaUpgrade !== undefined,
+	);
 	const stored = [...storedAllowedTypes].filter(
 		(value) => !viewNodeSchemaIdentifiers.has(value),
 	);
-	return { view, stored };
+	return {
+		view,
+		...(stagedView.length === 0 ? {} : { stagedView }),
+		stored,
+	};
 }
 
 /**
@@ -346,16 +403,28 @@ function* getFieldDiscrepancies(
 	stored: TreeFieldStoredSchema,
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
 	assert(
 		view instanceof FieldSchemaAlpha,
 		0xbee /* all field schema should be FieldSchemaAlpha */,
 	);
+
+	// Collect staged-optional upgrade location if present.
+	if (upgradeCollector !== undefined && view.isStagedOptional !== false) {
+		upgradeCollector.optionalField(
+			view.isStagedOptional,
+			stored.kind === FieldKinds.optional.identifier,
+		);
+	}
+
 	yield* getAllowedTypeDiscrepancies(
 		view.allowedTypesFull.evaluate().types,
 		stored.types,
 		identifier,
 		fieldKey,
+		view.isStagedOptional !== false,
+		upgradeCollector,
 	);
 
 	const viewKind =
@@ -375,6 +444,7 @@ function* getFieldDiscrepancies(
 			mismatch: "fieldKind",
 			view: viewKind.identifier,
 			stored: stored.kind,
+			...(view.isStagedOptional === false ? {} : { viewIsStagedOptional: true }),
 		} satisfies FieldKindDiscrepancy;
 	}
 }
@@ -396,7 +466,21 @@ function* getAllowedTypeDiscrepancies(
 	stored: TreeTypeSet,
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
+	viewIsStagedOptional: boolean,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
+	// Collect staged allowed type upgrade locations if present.
+	if (upgradeCollector !== undefined) {
+		for (const allowedType of view) {
+			if (allowedType.metadata.stagedSchemaUpgrade !== undefined) {
+				upgradeCollector.allowedType(
+					allowedType.metadata.stagedSchemaUpgrade,
+					stored.has(brand(allowedType.type.identifier)),
+				);
+			}
+		}
+	}
+
 	const discrepancies = findExtraAllowedTypes(view, stored);
 	if (discrepancies.view.length > 0 || discrepancies.stored.length > 0) {
 		yield {
@@ -404,6 +488,7 @@ function* getAllowedTypeDiscrepancies(
 			identifier,
 			fieldKey,
 			mismatch: "allowedTypes",
+			...(viewIsStagedOptional ? { viewIsStagedOptional: true } : {}),
 		} satisfies AllowedTypeDiscrepancy;
 	}
 }
@@ -424,6 +509,7 @@ function* computeObjectNodeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier,
 	view: ObjectNodeSchemaPrivate,
 	stored: ObjectNodeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
 	/**
 	 * Similar to the logic used for tracking discrepancies between two node schemas, we will identify
@@ -453,9 +539,18 @@ function* computeObjectNodeDiscrepancies(
 				mismatch: "fieldKind",
 				view: viewKind.identifier,
 				stored: storedEmptyFieldSchema.kind,
+				...(fieldSchema instanceof FieldSchemaAlpha && fieldSchema.isStagedOptional !== false
+					? { viewIsStagedOptional: true }
+					: {}),
 			} satisfies FieldKindDiscrepancy;
 		} else {
-			yield* getFieldDiscrepancies(fieldSchema, storedSchema, identifier, fieldKey);
+			yield* getFieldDiscrepancies(
+				fieldSchema,
+				storedSchema,
+				identifier,
+				fieldKey,
+				upgradeCollector,
+			);
 		}
 	}
 

package/src/simple-tree/api/index.ts

@@ -19,6 +19,8 @@ export type {
 	ViewableTree,
 	TreeViewEvents,
 	SchemaCompatibilityStatus,
+	SchemaCompatibilityStatusBeta,
+	SchemaDiscrepancy,
 	TreeViewAlpha,
 	TreeViewBeta,
 	UntypedTreeView,
@@ -28,6 +30,7 @@ export type {
 	TreeBranchEvents,
 	TreeBranchCommitMetadata,
 	TreeBranchHistory,
+	TreeContextBeta,
 	TreeContextAlpha,
 	ITreeAlpha,
 } from "./tree.js";
@@ -105,7 +108,11 @@ export {
 export type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
-export { checkSchemaCompatibility } from "./schemaCompatibilityTester.js";
+export {
+	checkSchemaCompatibility,
+	getSchemaIncompatibilityDetails,
+} from "./schemaCompatibilityTester.js";
+export { type StagedUpgradeStatus } from "./schemaCompatibilityTester.js";
 export type {
 	Unenforced,
 	FieldSchemaAlphaUnsafe,
@@ -151,27 +158,20 @@ export {
 	replaceConciseTreeHandles,
 } from "./conciseTree.js";
 
-export {
-	borrowCursorFromTreeNodeOrValue,
-	exportConcise,
-	importConcise,
-	type NodeChangedData,
-	TreeBeta,
-	type TreeChangeEventsBeta,
-} from "./treeBeta.js";
-export {
-	type ArrayNodeDeltaOp,
-	type ArrayNodeInsertOp,
-	type ArrayNodeRemoveOp,
-	type ArrayNodeRetainOp,
-	type ArrayNodeTreeChangedDeltaOp,
-	type ArrayNodeTreeChangedRetainOp,
-	type NodeChangedDataAlpha,
-	type NodeChangedDataDelta,
-	type NodeChangedDataProperties,
-	type NodeChangedDataTreeDelta,
-	type TreeChangeEventsAlpha,
-} from "./treeAlpha.js";
+export { cloneTree } from "./cloneTree.js";
+export type {
+	ArrayNodeDeltaOp,
+	ArrayNodeInsertOp,
+	ArrayNodeRemoveOp,
+	ArrayNodeRetainOp,
+	ArrayNodeTreeChangedDeltaOp,
+	ArrayNodeTreeChangedRetainOp,
+	NodeChangedData,
+	NodeChangedDataDelta,
+	NodeChangedDataProperties,
+	NodeChangedDataTreeDelta,
+	TreeChangeEventsBeta,
+} from "./treeChangeEventsBeta.js";
 export { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 export {
 	createIdentifierIndex,