@fluidframework/tree 2.91.0 → 2.92.0

package/src/shared-tree/sharedTree.ts

@@ -60,33 +60,29 @@ import {
 	forestCodecBuilder,
 	jsonableTreeFromFieldCursor,
 	makeMitigatedChangeFamily,
-	makeSchemaCodec,
 	makeTreeChunker,
 	type IncrementalEncodingPolicy,
 } from "../feature-libraries/index.js";
-// eslint-disable-next-line import-x/no-internal-modules
-import { schemaCodecBuilder, type FormatV1 } from "../feature-libraries/schema-index/index.js";
+import { schemaCodecBuilder } from "../feature-libraries/index.js";
 import {
 	type BranchId,
-	clientVersionToEditManagerFormatVersion,
-	clientVersionToMessageFormatVersion,
 	type ClonableSchemaAndPolicy,
 	getCodecTreeForEditManagerFormatWithChange,
 	getCodecTreeForMessageFormatWithChange,
+	makeMessageCodecBuilder,
 	type SharedTreeCoreOptionsInternal,
 	MessageFormatVersion,
 	SharedTreeCore,
 	EditManagerFormatVersion,
+	makeEditManagerCodecBuilder,
 } from "../shared-tree-core/index.js";
 import {
-	type ITree,
 	type ImplicitFieldSchema,
 	NodeKind,
 	type ReadSchema,
 	type SimpleFieldSchema,
 	type SimpleTreeSchema,
 	type TreeView,
-	type TreeViewAlpha,
 	type TreeViewConfiguration,
 	type UnsafeUnknownSchema,
 	type VerboseTree,
@@ -105,7 +101,7 @@ import {
 	throwIfBroken,
 } from "../util/index.js";
 
-import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import type { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import {
 	getCodecTreeForChangeFormat,
 	SharedTreeChangeFormatVersion,
@@ -113,7 +109,7 @@ import {
 import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
-import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
+import { type TreeCheckout, createTreeCheckout } from "./treeCheckout.js";
 
 /**
  * Copy of data from an {@link ITreePrivate} at some point in time.
@@ -231,7 +227,7 @@ export class SharedTreeKernel
 			idCompressor,
 			options,
 		);
-		const schemaCodec = makeSchemaCodec(options);
+		const schemaCodec = schemaCodecBuilder.build(options);
 		const schemaSummarizer = new SchemaSummarizer(
 			schema,
 			{
@@ -404,7 +400,7 @@ export class SharedTreeKernel
 	}
 
 	private checkoutBranch(branchId: BranchId): TreeCheckout {
-		const checkout = this.checkout.branch();
+		const checkout = this.checkout.fork();
 		checkout.switchBranch(this.getSharedBranch(branchId));
 		this.registerSharedBranchForEditing(branchId, checkout);
 		this.registerCheckout(branchId, checkout);
@@ -498,56 +494,17 @@ export function persistedToSimpleSchema(
 	persisted: JsonCompatible,
 	options: ICodecOptions,
 ): SimpleTreeSchema {
-	// Any version can be passed down to makeSchemaCodec here.
-	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
-	const schemaCodec = makeSchemaCodec({
-		...options,
-		minVersionForCollab: FluidClientVersion.v2_0,
-	});
-	const stored = schemaCodec.decode(persisted as FormatV1);
+	const schemaCodec = schemaCodecBuilder.buildDecoder(options);
+	const stored = schemaCodec.decode(persisted);
 	return exportSimpleSchema(stored);
 }
 
-/**
- * Get a {@link BranchableTree} from a {@link ITree}.
- * @remarks The branch can be used for "version control"-style coordination of edits on the tree.
- * @privateRemarks This function will be removed if/when the branching API becomes public,
- * but it (or something like it) is necessary in the meantime to prevent the alpha types from being exposed as public.
- * @alpha
- * @deprecated This API is superseded by {@link TreeBranch}, which should be used instead.
- */
-export function getBranch(tree: ITree): BranchableTree;
-/**
- * Get a {@link BranchableTree} from a {@link TreeView}.
- * @remarks The branch can be used for "version control"-style coordination of edits on the tree.
- * Branches are currently an unstable "alpha" API and are subject to change in the future.
- * @privateRemarks This function will be removed if/when the branching API becomes public,
- * but it (or something like it) is necessary in the meantime to prevent the alpha types from being exposed as public.
- * @alpha
- * @deprecated This API is superseded by {@link TreeBranch}, which should be used instead.
- */
-export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
-	view: TreeViewAlpha<T>,
-): BranchableTree;
-export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
-	treeOrView: ITree | TreeViewAlpha<T>,
-): BranchableTree {
-	if (treeOrView instanceof SchematizingSimpleTreeView) {
-		return treeOrView.checkout as unknown as BranchableTree;
-	}
-	const kernel = (treeOrView as ITree as ITreePrivate).kernel;
-	assert(kernel instanceof SharedTreeKernel, 0xb56 /* Invalid ITree */);
-	// This cast is safe so long as TreeCheckout supports all the operations on the branch interface.
-	return kernel.checkout as unknown as BranchableTree;
-}
-
 /**
  * Defines for each EditManagerFormatVersion the SharedTreeChangeFormatVersion to use.
  * This is an arbitrary mapping that is injected in the EditManger codec.
  * Once an entry is defined and used in production, it cannot be changed.
  * This is because the format for SharedTree changes are not explicitly versioned.
  */
-// eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison -- intentional comparison
 export const changeFormatVersionForEditManager = DependentFormatVersion.fromPairs<
 	EditManagerFormatVersion,
 	SharedTreeChangeFormatVersion
@@ -575,17 +532,19 @@ export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs<
 ]);
 
 function getCodecTreeForEditManagerFormat(clientVersion: MinimumVersionForCollab): CodecTree {
-	const change = changeFormatVersionForEditManager.lookup(
-		clientVersionToEditManagerFormatVersion(clientVersion),
-	);
+	const editManagerVersion = makeEditManagerCodecBuilder().getCodecTree(clientVersion).version;
+	const change = changeFormatVersionForEditManager.lookup(editManagerVersion);
 	const changeCodecTree = getCodecTreeForChangeFormat(change, clientVersion);
 	return getCodecTreeForEditManagerFormatWithChange(clientVersion, changeCodecTree);
 }
 
 function getCodecTreeForMessageFormat(clientVersion: MinimumVersionForCollab): CodecTree {
-	const change = changeFormatVersionForMessage.lookup(
-		clientVersionToMessageFormatVersion(clientVersion),
+	const messageVersion = makeMessageCodecBuilder().getCodecTree(clientVersion).version;
+	assert(
+		messageVersion !== undefined,
+		0xce3 /* Deprecated 'undefined' version shouldn't be selected */,
 	);
+	const change = changeFormatVersionForMessage.lookup(messageVersion);
 	const changeCodecTree = getCodecTreeForChangeFormat(change, clientVersion);
 	return getCodecTreeForMessageFormatWithChange(clientVersion, changeCodecTree);
 }
@@ -764,8 +723,6 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	disposeForksAfterTransaction: true,
 	shouldEncodeIncrementally: defaultIncrementalEncodingPolicy,
-	editManagerFormatSelector: clientVersionToEditManagerFormatVersion,
-	messageFormatSelector: clientVersionToMessageFormatVersion,
 	enableSharedBranches: false,
 	writeVersionOverrides: new Map(),
 	allowPossiblyIncompatibleWriteVersionOverrides: false,

package/src/shared-tree/sharedTreeChangeCodecs.ts

@@ -12,24 +12,18 @@ import {
 	DiscriminatedUnionDispatcher,
 	type FormatVersion,
 	type ICodecFamily,
-	type ICodecOptions,
 	type IJsonCodec,
 	makeCodecFamily,
 	withSchemaValidation,
 } from "../codec/index.js";
-import {
-	type ChangeEncodingContext,
-	SchemaFormatVersion,
-	type TreeStoredSchema,
-} from "../core/index.js";
+import type { ChangeEncodingContext, TreeStoredSchema } from "../core/index.js";
 import {
 	ModularChangeFormatVersion,
 	type ModularChangeset,
-	type SchemaChange,
 	defaultSchemaPolicy,
 	getCodecTreeForModularChangeFormat,
-	getCodecTreeForSchemaChangeFormat,
-	makeSchemaChangeCodecs,
+	makeSchemaChangeCodec,
+	schemaCodecBuilder,
 } from "../feature-libraries/index.js";
 import {
 	strictEnum,
@@ -48,7 +42,6 @@ export function makeSharedTreeChangeCodecFamily(
 	modularChangeCodecFamily: ICodecFamily<ModularChangeset, ChangeEncodingContext>,
 	options: CodecWriteOptions,
 ): ICodecFamily<SharedTreeChange, ChangeEncodingContext> {
-	const schemaChangeCodecs = makeSchemaChangeCodecs(options);
 	const versions: [
 		FormatVersion,
 		IJsonCodec<
@@ -57,22 +50,15 @@ export function makeSharedTreeChangeCodecFamily(
 			EncodedSharedTreeChange,
 			ChangeEncodingContext
 		>,
-	][] = [...dependenciesForChangeFormat.entries()].map(
-		([format, { modularChange, schemaChange }]) => [
-			format,
-			makeSharedTreeChangeCodec(
-				modularChangeCodecFamily.resolve(modularChange),
-				schemaChangeCodecs.resolve(schemaChange),
-				options,
-			),
-		],
-	);
+	][] = [...dependenciesForChangeFormat.entries()].map(([format, { modularChange }]) => [
+		format,
+		makeSharedTreeChangeCodec(modularChangeCodecFamily.resolve(modularChange), options),
+	]);
 	return makeCodecFamily(versions);
 }
 
 interface ChangeFormatDependencies {
 	readonly modularChange: ModularChangeFormatVersion;
-	readonly schemaChange: SchemaFormatVersion;
 }
 
 /**
@@ -107,6 +93,8 @@ export type SharedTreeChangeFormatVersion = Values<typeof SharedTreeChangeFormat
  * This is an arbitrary mapping that is injected in the SharedTree change codec.
  * Once an entry is defined and used in production, it cannot be changed.
  * This is because the format for the dependent formats are not explicitly versioned.
+ * @remarks
+ * SchemaFormatVersion (used by SchemaChangeFormat) is not included here since it is explicitly versioned.
  */
 export const dependenciesForChangeFormat = new Map<
 	SharedTreeChangeFormatVersion,
@@ -114,15 +102,21 @@ export const dependenciesForChangeFormat = new Map<
 >([
 	[
 		SharedTreeChangeFormatVersion.v3,
-		{ modularChange: ModularChangeFormatVersion.v3, schemaChange: SchemaFormatVersion.v1 },
+		{
+			modularChange: ModularChangeFormatVersion.v3,
+		},
 	],
 	[
 		SharedTreeChangeFormatVersion.v4,
-		{ modularChange: ModularChangeFormatVersion.v4, schemaChange: SchemaFormatVersion.v1 },
+		{
+			modularChange: ModularChangeFormatVersion.v4,
+		},
 	],
 	[
 		SharedTreeChangeFormatVersion.v5,
-		{ modularChange: ModularChangeFormatVersion.v5, schemaChange: SchemaFormatVersion.v1 },
+		{
+			modularChange: ModularChangeFormatVersion.v5,
+		},
 	],
 ]);
 
@@ -130,14 +124,14 @@ export function getCodecTreeForChangeFormat(
 	version: SharedTreeChangeFormatVersion,
 	clientVersion: MinimumVersionForCollab,
 ): CodecTree {
-	const { modularChange, schemaChange } =
+	const { modularChange } =
 		dependenciesForChangeFormat.get(version) ?? fail(0xc78 /* Unknown change format */);
 	return {
 		name: "SharedTreeChange",
 		version,
 		children: [
 			getCodecTreeForModularChangeFormat(modularChange),
-			getCodecTreeForSchemaChangeFormat(schemaChange, clientVersion),
+			schemaCodecBuilder.getCodecTree(clientVersion),
 		],
 	};
 }
@@ -149,14 +143,14 @@ function makeSharedTreeChangeCodec(
 		JsonCompatibleReadOnly,
 		ChangeEncodingContext
 	>,
-	schemaChangeCodec: IJsonCodec<SchemaChange>,
-	codecOptions: ICodecOptions,
+	codecOptions: CodecWriteOptions,
 ): IJsonCodec<
 	SharedTreeChange,
 	EncodedSharedTreeChange,
 	EncodedSharedTreeChange,
 	ChangeEncodingContext
 > {
+	const schemaChangeCodec = makeSchemaChangeCodec(codecOptions);
 	const decoderLibrary = new DiscriminatedUnionDispatcher<
 		EncodedSharedTreeInnerChange,
 		[context: ChangeEncodingContext],
@@ -177,7 +171,7 @@ function makeSharedTreeChangeCodec(
 	});
 
 	return withSchemaValidation(
-		EncodedSharedTreeChange,
+		EncodedSharedTreeChange(schemaChangeCodec.encodedSchema),
 		{
 			encode: (change, context) => {
 				const changes: EncodedSharedTreeInnerChange[] = [];

package/src/shared-tree/sharedTreeChangeEnricher.ts

@@ -7,7 +7,6 @@ import { unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
-	AnchorSet,
 	type DeltaDetachedNodeId,
 	type DetachedFieldIndex,
 	type IEditableForest,
@@ -118,7 +117,7 @@ export class SharedTreeChangeEnricher {
 		if (this.owned === undefined) {
 			this.onForkState?.();
 			this.owned = {
-				forest: this.borrowed.forest.clone(this.schema, new AnchorSet()),
+				forest: this.borrowed.forest.clone(this.schema),
 				removedRoots: this.borrowed.removedRoots.clone(),
 			};
 		}

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -168,6 +168,7 @@ export class SharedTreeChangeFamily
 		change: TaggedChange<SharedTreeChange>,
 		over: TaggedChange<SharedTreeChange>,
 		revisionMetadata: RevisionMetadataSource,
+		ignoreNoChangeViolation?: boolean,
 	): SharedTreeChange {
 		if (change.change.changes.length === 0 || over.change.changes.length === 0) {
 			return change.change;
@@ -204,6 +205,7 @@ export class SharedTreeChangeFamily
 						mapTaggedChange(change, dataChangeIntention.innerChange),
 						mapTaggedChange(over, dataChangeOver.innerChange),
 						revisionMetadata,
+						ignoreNoChangeViolation,
 					),
 				},
 			],

package/src/shared-tree/sharedTreeChangeFormat.ts

@@ -3,17 +3,32 @@
  * Licensed under the MIT License.
  */
 
-import { type Static, Type } from "@sinclair/typebox";
+import { type Static, type TSchema, Type } from "@sinclair/typebox";
 
+import type { EncodedSchemaChange } from "../feature-libraries/index.js";
 import { JsonCompatibleReadOnlySchema } from "../util/index.js";
 
-export const EncodedSharedTreeInnerChange = Type.Object({
-	schema: Type.Optional(JsonCompatibleReadOnlySchema),
-	data: Type.Optional(JsonCompatibleReadOnlySchema),
-});
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function EncodedSharedTreeInnerChange<TEncodedSchema extends TSchema>(
+	encodedSchemaSchema: TEncodedSchema,
+) {
+	return Type.Object({
+		schema: Type.Optional(encodedSchemaSchema),
+		data: Type.Optional(JsonCompatibleReadOnlySchema),
+	});
+}
 
-export type EncodedSharedTreeInnerChange = Static<typeof EncodedSharedTreeInnerChange>;
+export type EncodedSharedTreeInnerChange<
+	TEncodedSchema extends TSchema = typeof EncodedSchemaChange,
+> = Static<ReturnType<typeof EncodedSharedTreeInnerChange<TEncodedSchema>>>;
 
-export const EncodedSharedTreeChange = Type.Array(EncodedSharedTreeInnerChange);
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function EncodedSharedTreeChange<TEncodedSchema extends TSchema>(
+	encodedSchemaSchema: TEncodedSchema,
+) {
+	return Type.Array(EncodedSharedTreeInnerChange(encodedSchemaSchema));
+}
 
-export type EncodedSharedTreeChange = Static<typeof EncodedSharedTreeChange>;
+export type EncodedSharedTreeChange<
+	TEncodedSchema extends TSchema = typeof EncodedSchemaChange,
+> = Static<ReturnType<typeof EncodedSharedTreeChange<TEncodedSchema>>>;

package/src/shared-tree/tree.ts

@@ -18,11 +18,8 @@ import {
 	type TransactionConstraint,
 } from "../simple-tree/index.js";
 
-import {
-	addConstraintsToTransaction,
-	SchematizingSimpleTreeView,
-} from "./schematizingTreeView.js";
-import type { ITreeCheckout } from "./treeCheckout.js";
+import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import { addConstraintsToTransaction, type ITreeCheckout } from "./treeCheckout.js";
 
 /**
  * Provides various functions for interacting with {@link TreeNode}s.

package/src/shared-tree/treeAlpha.ts

@@ -75,6 +75,7 @@ import {
 	toInitialSchema,
 	type TreeParsingOptions,
 	type NodeChangedData,
+	type TreeChangeEventsAlpha,
 	type ConciseTree,
 	importConcise,
 	exportConcise,
@@ -231,6 +232,23 @@ export interface TreeIdentifierUtils {
  * @sealed @alpha
  */
 export interface TreeAlpha {
+	/**
+	 * Register an event listener on the given node.
+	 * @param node - The node whose events should be subscribed to.
+	 * @param eventName - Which event to subscribe to.
+	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
+	 * @returns A callback function which will deregister the event.
+	 * This callback should be called only once.
+	 * @remarks
+	 * Provides a richer `nodeChanged` event than {@link (TreeBeta:interface).on} — for array nodes the
+	 * event data includes a {@link NodeChangedDataDelta.delta | delta} payload.
+	 */
+	on<K extends keyof TreeChangeEventsAlpha<TNode>, TNode extends TreeNode>(
+		node: TNode,
+		eventName: K,
+		listener: NoInfer<TreeChangeEventsAlpha<TNode>[K]>,
+	): () => void;
+
 	/**
 	 * Retrieve the {@link TreeBranch | branch}, if any, for the given node.
 	 * @param node - The node to query
@@ -787,6 +805,14 @@ function trackObservations<TResult>(
  * @alpha
  */
 export const TreeAlpha: TreeAlpha = {
+	on<K extends keyof TreeChangeEventsAlpha<TNode>, TNode extends TreeNode>(
+		node: TNode,
+		eventName: K,
+		listener: NoInfer<TreeChangeEventsAlpha<TNode>[K]>,
+	): () => void {
+		return treeNodeApi.on(node, eventName, listener);
+	},
+
 	trackObservations<TResult>(
 		onInvalidation: () => void,
 		trackDuring: () => TResult,