@fluidframework/tree 2.118.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/index.ts

@@ -30,6 +30,7 @@ export type {
 	TreeBranchEvents,
 	TreeBranchCommitMetadata,
 	TreeBranchHistory,
+	TreeContextBeta,
 	TreeContextAlpha,
 	ITreeAlpha,
 } from "./tree.js";
@@ -157,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,

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

@@ -53,7 +53,7 @@ import {
 } from "./schemaFactory.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 import { schemaStatics } from "./schemaStatics.js";
-import { TreeBeta } from "./treeBeta.js";
+import { cloneTree } from "./cloneTree.js";
 import type {
 	ArrayNodeCustomizableSchemaUnsafe,
 	FieldSchemaAlphaUnsafe,
@@ -297,7 +297,7 @@ const withDefault = <
 		// This prevents multi-parenting errors.
 		if (isTreeNode(insertableValue)) {
 			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			insertableValue = TreeBeta.clone(insertableValue as any);
+			insertableValue = cloneTree(insertableValue as any);
 		}
 
 		// For optional fields with an undefined default, return an empty array (no value).

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

@@ -256,13 +256,40 @@ export interface SnapshotSchemaCompatibilityOptions {
 	 * and not erased when regenerating snapshots.
 	 *
 	 * This directory will be created if it does not already exist.
-	 * All ".json" files in this directory will be treated as schema snapshots.
+	 * By default, all ".json" files in this directory will be treated as schema snapshots.
+	 * When {@link SnapshotSchemaCompatibilityOptions.snapshotFileNameFormat} is provided,
+	 * only JSON files matching that format will be treated as schema snapshots.
 	 * It is recommended to use a dedicated directory for each {@link snapshotSchemaCompatibility} powered test.
 	 *
 	 * This can use any path syntax supported by the provided {@link SnapshotSchemaCompatibilityOptions.fileSystem}.
 	 */
 	readonly snapshotDirectory: string;
 
+	/**
+	 * Customizes the names of schema snapshot files.
+	 * @remarks
+	 * Snapshot files are named by surrounding the version with the provided strings, followed by the ".json" extension.
+	 * For example, `{ prefix: "schema-", suffix: "-snapshot" }` produces `schema-1.0.0-snapshot.json` for version `1.0.0`.
+	 *
+	 * Only JSON files matching this format are treated as schema snapshots.
+	 * The prefix and suffix must not contain ASCII control characters or characters that are invalid in cross-platform file names.
+	 */
+	readonly snapshotFileNameFormat?: {
+		/**
+		 * Text to include before the version.
+		 *
+		 * @defaultValue `""`
+		 */
+		readonly prefix?: string;
+
+		/**
+		 * Text to include after the version and before the ".json" extension.
+		 *
+		 * @defaultValue `""`
+		 */
+		readonly suffix?: string;
+	};
+
 	/**
 	 * How the `snapshotDirectory` is accessed.
 	 */
@@ -492,6 +519,7 @@ export function snapshotSchemaCompatibility(
 	const checker = new SnapshotCompatibilityChecker(
 		options.snapshotDirectory,
 		options.fileSystem,
+		options.snapshotFileNameFormat,
 	);
 	const {
 		version: currentVersion,
@@ -743,12 +771,33 @@ export class SnapshotCompatibilityChecker {
 		 * How the `snapshotDirectory` is accessed.
 		 */
 		private readonly fileSystemMethods: SnapshotFileSystem,
-	) {}
+		/**
+		 * Text surrounding the version in snapshot file names.
+		 */
+		private readonly snapshotFileNameFormat: {
+			readonly prefix?: string;
+			readonly suffix?: string;
+		} = {},
+	) {
+		const { prefix = "", suffix = "" } = snapshotFileNameFormat;
+		// eslint-disable-next-line no-control-regex -- The control character range is intentionally invalid for cross-platform file names.
+		const invalidFileNameCharacters = /[\u0000-\u001F<>:"/\\|?*]/u;
+		for (const [property, value] of [
+			["prefix", prefix],
+			["suffix", suffix],
+		] as const) {
+			if (invalidFileNameCharacters.test(value)) {
+				throw new UsageError(
+					`Invalid snapshotFileNameFormat.${property}: ${JSON.stringify(value)}. Must not contain ASCII control characters or any of <>:"/\\|?*.`,
+				);
+			}
+		}
+	}
 
 	public writeSchemaSnapshot(snapshotName: string, snapshot: JsonCompatibleReadOnly): void {
 		const fullPath = this.fileSystemMethods.join(
 			this.snapshotDirectory,
-			`${snapshotName}.json`,
+			this.getSnapshotFileName(snapshotName),
 		);
 		this.ensureSnapshotDirectoryExists();
 		this.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, "\t"), {
@@ -764,7 +813,7 @@ export class SnapshotCompatibilityChecker {
 	public readSchemaSnapshotRaw(snapshotName: string): JsonCompatibleReadOnly {
 		const fullPath = this.fileSystemMethods.join(
 			this.snapshotDirectory,
-			`${snapshotName}.json`,
+			this.getSnapshotFileName(snapshotName),
 		);
 		const snapshot = JSON.parse(
 			this.fileSystemMethods.readFileSync(fullPath, "utf8"),
@@ -782,8 +831,8 @@ export class SnapshotCompatibilityChecker {
 		const files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);
 		const versions: string[] = [];
 		for (const file of files) {
-			if (file.endsWith(".json")) {
-				const snapshotName = file.slice(0, ".json".length * -1);
+			const snapshotName = this.getSnapshotName(file);
+			if (snapshotName !== undefined) {
 				versions.push(snapshotName);
 			}
 		}
@@ -800,6 +849,38 @@ export class SnapshotCompatibilityChecker {
 	public ensureSnapshotDirectoryExists(): void {
 		this.fileSystemMethods.mkdirSync(this.snapshotDirectory, { recursive: true });
 	}
+
+	/**
+	 * Builds the file name used to read or write a snapshot with a known snapshot name.
+	 */
+	private getSnapshotFileName(snapshotName: string): string {
+		const { prefix = "", suffix = "" } = this.snapshotFileNameFormat;
+		return `${prefix}${snapshotName}${suffix}.json`;
+	}
+
+	/**
+	 * Extracts the snapshot name from a matching file found while scanning the snapshot directory.
+	 */
+	private getSnapshotName(fileName: string): string | undefined {
+		const extension = ".json";
+		if (!fileName.endsWith(extension)) {
+			return undefined;
+		}
+
+		const { prefix = "", suffix = "" } = this.snapshotFileNameFormat;
+		const fileNameWithoutExtension = fileName.slice(0, -extension.length);
+		if (
+			!fileNameWithoutExtension.startsWith(prefix) ||
+			!fileNameWithoutExtension.endsWith(suffix)
+		) {
+			return undefined;
+		}
+
+		return fileNameWithoutExtension.slice(
+			prefix.length,
+			fileNameWithoutExtension.length - suffix.length,
+		);
+	}
 }
 
 /**

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

@@ -62,7 +62,7 @@ export interface WithValue<TValue> {
 }
 
 /**
- * Contains a value and status returned from a user-supplied {@link TreeViewBeta.runTransaction | transaction callback}.
+ * Contains a value and status returned from a user-supplied {@link UntypedTreeView.(runTransaction:3) | transaction callback}.
  * @input
  * @beta
  */
@@ -77,7 +77,7 @@ export type TransactionCallbackStatusBeta<TSuccessValue, TFailureValue> =
 	  });
 
 /**
- * The result of a {@link TreeViewBeta.runTransaction | transaction} that doesn't return a value.
+ * The result of a {@link UntypedTreeView.(runTransaction:2) | transaction} that doesn't return a value.
  * @input
  * @beta
  */
@@ -114,7 +114,7 @@ export type VoidTransactionCallbackStatusAlpha = Omit<
 >;
 
 /**
- * The result of a {@link TreeViewBeta.(runTransaction:1) | transaction} that completed successfully.
+ * The result of a {@link UntypedTreeView.(runTransaction:1) | transaction} that completed successfully.
  * @sealed
  * @beta
  */
@@ -124,7 +124,7 @@ export interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSucc
 }
 
 /**
- * The result of a {@link TreeViewBeta.runTransaction | transaction} that was rolled back.
+ * The result of a {@link UntypedTreeView.(runTransaction:2) | transaction} that was rolled back.
  * @sealed
  * @beta
  */