@fluidframework/tree 2.81.1 → 2.82.0

package/src/shared-tree/schematizingTreeView.ts

@@ -227,21 +227,20 @@ export class SchematizingSimpleTreeView<
 				},
 			);
 
-			this.checkout.transaction.start();
-
-			initialize(
-				this.checkout,
-				schema,
-				initializerFromChunk(this.checkout, () => {
-					// This must be done after initial schema is set!
-					return combineChunks(
-						this.checkout.forest.chunkField(
-							cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
-						),
-					);
-				}),
-			);
-			this.checkout.transaction.commit();
+			this.runTransaction(() => {
+				initialize(
+					this.checkout,
+					schema,
+					initializerFromChunk(this.checkout, () => {
+						// This must be done after initial schema is set!
+						return combineChunks(
+							this.checkout.forest.chunkField(
+								cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
+							),
+						);
+					}),
+				);
+			});
 		});
 	}
 
@@ -294,9 +293,43 @@ export class SchematizingSimpleTreeView<
 			| void,
 		params?: RunTransactionParams,
 	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
+		this.mountTransaction(params, false);
+		const transactionCallbackStatus = transaction();
+		return this.unmountTransaction(transactionCallbackStatus, params);
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/shared-tree#TreeViewAlpha.runTransactionAsync}
+	 */
+	public runTransactionAsync<TSuccessValue, TFailureValue>(
+		transaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;
+	/**
+	 * {@inheritDoc @fluidframework/shared-tree#TreeViewAlpha.runTransactionAsync}
+	 */
+	public runTransactionAsync(
+		transaction: () => Promise<VoidTransactionCallbackStatus | void>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResult>;
+	public async runTransactionAsync<TSuccessValue, TFailureValue>(
+		transaction: () => Promise<
+			| TransactionCallbackStatus<TSuccessValue, TFailureValue>
+			| VoidTransactionCallbackStatus
+			| void
+		>,
+		params: RunTransactionParams | undefined,
+	): Promise<TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult> {
+		this.mountTransaction(params, true);
+		const transactionCallbackStatus = await transaction();
+		return this.unmountTransaction(transactionCallbackStatus, params);
+	}
+
+	private mountTransaction(params: RunTransactionParams | undefined, isAsync: boolean): void {
+		this.ensureUndisposed();
 		const { checkout } = this;
 
-		checkout.transaction.start();
+		checkout.transaction.start(isAsync);
 
 		// Validate preconditions before running the transaction callback.
 		addConstraintsToTransaction(
@@ -304,7 +337,17 @@ export class SchematizingSimpleTreeView<
 			false /* constraintsOnRevert */,
 			params?.preconditions,
 		);
-		const transactionCallbackStatus = transaction();
+	}
+
+	private unmountTransaction<TSuccessValue, TFailureValue>(
+		transactionCallbackStatus:
+			| TransactionCallbackStatus<TSuccessValue, TFailureValue>
+			| VoidTransactionCallbackStatus
+			| void,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
+		this.ensureUndisposed();
+		const { checkout } = this;
 		const rollback = transactionCallbackStatus?.rollback;
 		const value = (
 			transactionCallbackStatus as TransactionCallbackStatus<TSuccessValue, TFailureValue>
@@ -324,7 +367,9 @@ export class SchematizingSimpleTreeView<
 			transactionCallbackStatus?.preconditionsOnRevert,
 		);
 
-		checkout.transaction.commit();
+		checkout.runWithTransactionLabel(() => {
+			checkout.transaction.commit();
+		}, params?.label);
 		return value === undefined
 			? { success: true }
 			: { success: true, value: value as TSuccessValue };

package/src/shared-tree/sharedTree.ts

@@ -21,6 +21,7 @@ import {
 import {
 	type CodecTree,
 	type CodecWriteOptions,
+	type CodecWriteOptionsBeta,
 	DependentFormatVersion,
 	FluidClientVersion,
 	FormatValidatorNoOp,
@@ -99,7 +100,6 @@ import {
 	type SchemaType,
 } from "../simple-tree/index.js";
 import {
-	brand,
 	type Breakable,
 	breakingClass,
 	type JsonCompatible,
@@ -109,7 +109,7 @@ import {
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import {
 	getCodecTreeForChangeFormat,
-	type SharedTreeChangeFormatVersion,
+	SharedTreeChangeFormatVersion,
 } from "./sharedTreeChangeCodecs.js";
 import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
@@ -550,23 +550,14 @@ export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
  * 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([
-	[
-		brand<EditManagerFormatVersion>(EditManagerFormatVersion.v3),
-		brand<SharedTreeChangeFormatVersion>(3),
-	],
-	[
-		brand<EditManagerFormatVersion>(EditManagerFormatVersion.v4),
-		brand<SharedTreeChangeFormatVersion>(4),
-	],
-	[
-		brand<EditManagerFormatVersion>(EditManagerFormatVersion.vSharedBranches),
-		brand<SharedTreeChangeFormatVersion>(4),
-	],
-	[
-		brand<EditManagerFormatVersion>(EditManagerFormatVersion.v6),
-		brand<SharedTreeChangeFormatVersion>(5),
-	],
+export const changeFormatVersionForEditManager = DependentFormatVersion.fromPairs<
+	EditManagerFormatVersion,
+	SharedTreeChangeFormatVersion
+>([
+	[EditManagerFormatVersion.v3, SharedTreeChangeFormatVersion.v3],
+	[EditManagerFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
+	[EditManagerFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
+	[EditManagerFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
 ]);
 
 /**
@@ -575,23 +566,14 @@ export const changeFormatVersionForEditManager = DependentFormatVersion.fromPair
  * 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.
  */
-export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs([
-	[
-		brand<MessageFormatVersion>(MessageFormatVersion.v3),
-		brand<SharedTreeChangeFormatVersion>(3),
-	],
-	[
-		brand<MessageFormatVersion>(MessageFormatVersion.v4),
-		brand<SharedTreeChangeFormatVersion>(4),
-	],
-	[
-		brand<MessageFormatVersion>(MessageFormatVersion.vSharedBranches),
-		brand<SharedTreeChangeFormatVersion>(4),
-	],
-	[
-		brand<MessageFormatVersion>(MessageFormatVersion.v6),
-		brand<SharedTreeChangeFormatVersion>(5),
-	],
+export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs<
+	MessageFormatVersion,
+	SharedTreeChangeFormatVersion
+>([
+	[MessageFormatVersion.v3, SharedTreeChangeFormatVersion.v3],
+	[MessageFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
+	[MessageFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
+	[MessageFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
 ]);
 
 function getCodecTreeForEditManagerFormat(clientVersion: MinimumVersionForCollab): CodecTree {
@@ -631,7 +613,7 @@ export function getCodecTreeForSharedTreeFormat(
  * Configuration options for SharedTree.
  * @beta @input
  */
-export type SharedTreeOptionsBeta = ForestOptions;
+export type SharedTreeOptionsBeta = ForestOptions & Partial<CodecWriteOptionsBeta>;
 
 /**
  * Configuration options for SharedTree with alpha features.

package/src/shared-tree/sharedTreeChangeCodecs.ts

@@ -23,7 +23,7 @@ import {
 	type TreeStoredSchema,
 } from "../core/index.js";
 import {
-	type ModularChangeFormatVersion,
+	ModularChangeFormatVersion,
 	type ModularChangeset,
 	type SchemaChange,
 	defaultSchemaPolicy,
@@ -32,10 +32,10 @@ import {
 	makeSchemaChangeCodecs,
 } from "../feature-libraries/index.js";
 import {
-	brand,
-	type Brand,
+	strictEnum,
 	type JsonCompatibleReadOnly,
 	type Mutable,
+	type Values,
 } from "../util/index.js";
 
 import {
@@ -75,7 +75,32 @@ interface ChangeFormatDependencies {
 	readonly schemaChange: SchemaFormatVersion;
 }
 
-export type SharedTreeChangeFormatVersion = Brand<3 | 4 | 5, "SharedTreeChangeFormatVersion">;
+/**
+ * The format version for `SharedTreeChange`.
+ */
+export const SharedTreeChangeFormatVersion = strictEnum("SharedTreeChangeFormatVersion", {
+	/**
+	 * Introduced prior to 2.0 and used beyond.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability needs to be maintained so long as {@link lowestMinVersionForCollab} is less than 2.2.0.
+	 */
+	v3: 3,
+	/**
+	 * Introduced in 2.2.0.
+	 * Was inadvertently made usable for writing in 2.43.0 (through configuredSharedTree) and remains available.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability could be dropped in favor of {@link SharedTreeChangeFormatVersion.v3},
+	 * but doing so would make the pattern of writable versions more complex and gain little
+	 * because the logic for this format is shared with {@link SharedTreeChangeFormatVersion.v3}.
+	 */
+	v4: 4,
+	/**
+	 * Introduced and made available for writing in 2.80.0
+	 * Adds support for "no change" constraints.
+	 */
+	v5: 5,
+});
+export type SharedTreeChangeFormatVersion = Values<typeof SharedTreeChangeFormatVersion>;
 
 /**
  * Defines for each SharedTree change format the corresponding dependent formats to use.
@@ -83,13 +108,22 @@ export type SharedTreeChangeFormatVersion = Brand<3 | 4 | 5, "SharedTreeChangeFo
  * 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.
  */
-export const dependenciesForChangeFormat: Map<
+export const dependenciesForChangeFormat = new Map<
 	SharedTreeChangeFormatVersion,
 	ChangeFormatDependencies
-> = new Map([
-	[brand(3), { modularChange: brand(3), schemaChange: SchemaFormatVersion.v1 }],
-	[brand(4), { modularChange: brand(4), schemaChange: SchemaFormatVersion.v1 }],
-	[brand(5), { modularChange: brand(5), schemaChange: SchemaFormatVersion.v1 }],
+>([
+	[
+		SharedTreeChangeFormatVersion.v3,
+		{ modularChange: ModularChangeFormatVersion.v3, schemaChange: SchemaFormatVersion.v1 },
+	],
+	[
+		SharedTreeChangeFormatVersion.v4,
+		{ modularChange: ModularChangeFormatVersion.v4, schemaChange: SchemaFormatVersion.v1 },
+	],
+	[
+		SharedTreeChangeFormatVersion.v5,
+		{ modularChange: ModularChangeFormatVersion.v5, schemaChange: SchemaFormatVersion.v1 },
+	],
 ]);
 
 export function getCodecTreeForChangeFormat(

package/src/shared-tree/tree.ts

@@ -467,7 +467,7 @@ function runTransactionInCheckout<TResult>(
 	transaction: () => TResult | typeof rollback,
 	preconditions: readonly TransactionConstraint[],
 ): TResult | typeof rollback {
-	checkout.transaction.start();
+	checkout.transaction.start(false);
 	addConstraintsToTransaction(checkout, false, preconditions);
 
 	let result: ReturnType<typeof transaction>;

package/src/shared-tree/treeCheckout.ts

@@ -388,6 +388,14 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	private editLock: EditLock;
 
+	/**
+	 * User-defined label associated with the transaction whose commit is currently being produced for this checkout.
+	 *
+	 * @remarks
+	 * This label is used to implement {@link TreeCheckout.runWithTransactionLabel}.
+	 */
+	private transactionLabel?: unknown;
+
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
 	/**
@@ -439,6 +447,34 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.registerForBranchEvents();
 	}
 
+	/**
+	 * Helper method for {@link SchematizingSimpleTreeView.runTransaction} to properly clear transaction labels once the function completes.
+	 *
+	 * @remarks
+	 * The label is stored during the execution of the function and will be included in the {@link ChangeMetadata} of the transaction.
+	 *
+	 * Labels supplied to nested transactions are ignored - only the outermost transaction label is ever used.
+	 *
+	 * @param fn - The function to execute. It receives the user provided transaction label as an optional parameter.
+	 * @param label - The label to associate with the outermost transaction.
+	 * @returns The result of executing `fn`.
+	 */
+	public runWithTransactionLabel<TLabel, TResult>(
+		fn: (label?: TLabel) => TResult,
+		label: TLabel | undefined,
+	): TResult {
+		// If a transaction label is already set, nesting is occurring, so we should not override it.
+		if (this.transactionLabel !== undefined) {
+			return fn(this.transactionLabel as TLabel);
+		}
+		this.transactionLabel = label;
+		try {
+			return fn(this.transactionLabel as TLabel);
+		} finally {
+			this.transactionLabel = undefined;
+		}
+	}
+
 	public get removedRoots(): ReadOnlyDetachedFieldIndex {
 		return this._removedRoots;
 	}
@@ -464,16 +500,23 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				: undefined;
 			// When each transaction is started, make a restorable checkpoint of the current state of removed roots
 			const restoreRemovedRoots = this._removedRoots.createCheckpoint();
-			return (result) => {
+			return (result, viewUpdate: SharedTreeChange | undefined) => {
+				const newHead = this.#transaction.branch.getHead();
 				switch (result) {
 					case TransactionResult.Abort: {
 						restoreRemovedRoots();
+						if (viewUpdate !== undefined) {
+							this.applyChange(viewUpdate, newHead.revision);
+						}
 						break;
 					}
 					case TransactionResult.Commit: {
+						if (viewUpdate !== undefined) {
+							this.applyChange(viewUpdate, newHead.revision);
+						}
 						if (!this.transaction.isInProgress()) {
 							// The changes in a transaction squash commit have already applied to the checkout and are known to be valid, so we can validate the squash commit automatically.
-							this.validateCommit(this.#transaction.branch.getHead());
+							this.validateCommit(newHead);
 						}
 						break;
 					}
@@ -570,6 +613,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 						} satisfies SerializedChange;
 					},
 					getRevertible: (onDisposed) => getRevertible?.(onDisposed),
+					label: this.transactionLabel,
 				};
 
 				this.#events.emit("changed", metadata, getRevertible);
@@ -577,7 +621,10 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			}
 		} else if (this.isRemoteChangeEvent(event)) {
 			// TODO: figure out how to plumb through commit kind info for remote changes
-			this.#events.emit("changed", { isLocal: false, kind: CommitKind.Default });
+			this.#events.emit("changed", {
+				isLocal: false,
+				kind: CommitKind.Default,
+			});
 		}
 	};
 

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

@@ -126,7 +126,7 @@ export class EditManagerSummarizer<TChangeset>
 			0x42c /* There should not already be stored EditManager data when loading from summary */,
 		);
 
-		const summary = parse(bufferToString(schemaBuffer, "utf-8")) as JsonCompatibleReadOnly;
+		const summary = parse(bufferToString(schemaBuffer, "utf8")) as JsonCompatibleReadOnly;
 		const data = this.codec.decode(summary, { idCompressor: this.idCompressor });
 		this.editManager.loadSummaryData(data);
 	}

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

@@ -4,7 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { type TAnySchema, Type } from "@sinclair/typebox";
+import type { TAnySchema } from "@sinclair/typebox";
 
 import { type ICodecOptions, type IJsonCodec, withSchemaValidation } from "../codec/index.js";
 import type {
@@ -14,6 +14,7 @@ import type {
 	RevisionTag,
 } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
+import { JsonCompatibleReadOnlySchema } from "../util/index.js";
 
 import type { MessageEncodingContext } from "./messageCodecs.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
@@ -43,12 +44,12 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 > {
 	return withSchemaValidation<
 		DecodedMessage<TChangeset>,
-		TAnySchema,
+		TAnySchema | typeof JsonCompatibleReadOnlySchema,
 		JsonCompatibleReadOnly,
 		JsonCompatibleReadOnly,
 		MessageEncodingContext
 	>(
-		Message(changeCodec.encodedSchema ?? Type.Any()),
+		Message(changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema),
 		{
 			encode: (decoded: DecodedMessage<TChangeset>, context: MessageEncodingContext) => {
 				assert(decoded.type === "commit", 0xc68 /* Only commit messages are supported */);