@fluidframework/tree 2.81.1 → 2.83.0

package/src/feature-libraries/sequence-field/replaceRevisions.ts

@@ -40,9 +40,9 @@ export function replaceRevisions(changeset: Changeset, replacer: RevisionReplace
 }
 
 function updateMark(mark: Mark, replacer: RevisionReplacer): Mark {
-	const updatedMark = { ...updateEffect(mark, replacer) };
+	const updatedMark = { ...updateEffect(mark, mark.count, replacer) };
 	if (mark.cellId !== undefined) {
-		updatedMark.cellId = replacer.getUpdatedAtomId(mark.cellId);
+		updatedMark.cellId = replacer.getUpdatedAtomId(mark.cellId, mark.count);
 	}
 
 	if (mark.changes !== undefined) {
@@ -54,9 +54,11 @@ function updateMark(mark: Mark, replacer: RevisionReplacer): Mark {
 
 function updateEffect<TMark extends MarkEffect>(
 	input: TMark,
+	count: number,
 	replacer: RevisionReplacer,
 ): TMark {
-	const mark = isDetach(input) || isRename(input) ? updateIdOverride(input, replacer) : input;
+	const mark =
+		isDetach(input) || isRename(input) ? updateIdOverride(input, count, replacer) : input;
 	const type = mark.type;
 	switch (type) {
 		case "Rename":
@@ -66,8 +68,8 @@ function updateEffect<TMark extends MarkEffect>(
 		case "AttachAndDetach": {
 			return {
 				...mark,
-				attach: updateEffect(mark.attach, replacer),
-				detach: updateEffect(mark.detach, replacer),
+				attach: updateEffect(mark.attach, count, replacer),
+				detach: updateEffect(mark.detach, count, replacer),
 			};
 		}
 		case "MoveIn":
@@ -75,12 +77,13 @@ function updateEffect<TMark extends MarkEffect>(
 			return updateMoveEffect<TMark & MoveMarkEffect>(
 				// For some reason, TypeScript is not able to infer that `mark` cannot be a `NoopMark` here.
 				mark as MoveMarkEffect,
+				count,
 				replacer,
 			);
 		}
 		case "Insert":
 		case "Remove": {
-			return updateRevisionAndId(mark as (TMark & Insert) | (TMark & Remove), replacer);
+			return updateRevisionAndId(mark as (TMark & Insert) | (TMark & Remove), count, replacer);
 		}
 		default: {
 			unreachableCase(type);
@@ -90,38 +93,42 @@ function updateEffect<TMark extends MarkEffect>(
 
 function updateIdOverride<TEffect extends Detach | Rename>(
 	effect: TEffect,
+	count: number,
 	replacer: RevisionReplacer,
 ): TEffect {
 	if (effect.idOverride === undefined) {
 		return effect;
 	}
-	const idOverride = replacer.getUpdatedAtomId(effect.idOverride);
+	const idOverride = replacer.getUpdatedAtomId(effect.idOverride, count);
 	return { ...effect, idOverride };
 }
 
 function updateMoveEffect<TEffect extends HasMoveFields>(
 	effect: TEffect,
+	count: number,
 	replacer: RevisionReplacer,
 ): TEffect {
 	return effect.finalEndpoint === undefined
-		? updateRevisionAndId(effect, replacer)
+		? updateRevisionAndId(effect, count, replacer)
 		: updateRevisionAndId(
 				{
 					...effect,
-					finalEndpoint: replacer.getUpdatedAtomId(effect.finalEndpoint),
+					finalEndpoint: replacer.getUpdatedAtomId(effect.finalEndpoint, count),
 				},
+				count,
 				replacer,
 			);
 }
 
 function updateRevisionAndId<T extends HasRevisionTag & HasMoveId>(
 	input: T,
+	count: number,
 	replacer: RevisionReplacer,
 ): T {
 	if (!replacer.isObsolete(input.revision)) {
 		return input;
 	}
-	const newAtom = replacer.getUpdatedAtomId(makeChangeAtomId(input.id, input.revision));
+	const newAtom = replacer.getUpdatedAtomId(makeChangeAtomId(input.id, input.revision), count);
 	return withRevisionAndId(input, newAtom.revision, newAtom.localId);
 }
 

package/src/feature-libraries/sequence-field/sequenceFieldToDelta.ts

@@ -191,7 +191,7 @@ export function sequenceFieldToDelta(
 	}
 	const delta: Mutable<FieldChangeDelta> = {};
 	if (local.length > 0) {
-		delta.local = local;
+		delta.local = { marks: local };
 	}
 	if (global.length > 0) {
 		delta.global = global;

package/src/index.ts

@@ -76,8 +76,10 @@ export {
 	type ObservationResults,
 	type TreeIdentifierUtils,
 	independentView,
+	type IndependentViewOptions,
 	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
+	type CreateIndependentTreeAlphaOptions,
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
 	ForestTypeReference,
@@ -294,13 +296,15 @@ export {
 	exportCompatibilitySchemaSnapshot,
 	importCompatibilitySchemaSnapshot,
 	checkCompatibility,
-	checkSchemaCompatibilitySnapshots,
+	snapshotSchemaCompatibility,
 	type SnapshotFileSystem,
 	incrementalSummaryHint,
 	incrementalEncodingPolicyForAllowedTypes,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
-	type SchemaCompatibilitySnapshotsOptions,
+	type SnapshotSchemaCompatibilityOptions,
+	type ArrayPlaceAnchor,
+	createArrayInsertionAnchor,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,
@@ -315,6 +319,7 @@ export { persistedToSimpleSchema } from "./shared-tree/index.js";
 export {
 	type ICodecOptions,
 	type CodecWriteOptions,
+	type CodecWriteOptionsBeta,
 	FluidClientVersion,
 	type FormatValidator,
 	FormatValidatorNoOp,
@@ -348,13 +353,12 @@ export type {
 export { cloneWithReplacements } from "./util/index.js";
 
 import * as InternalTypes from "./internalTypes.js";
-export {
-	/**
-	 * Contains types used by the API, but which serve mechanical purposes and do not represent semantic concepts.
-	 * They are used internally to implement API aspects, but are not intended for use by external consumers.
-	 */
-	InternalTypes,
-};
+/**
+ * Contains types used by the API, but which serve mechanical purposes and do not represent semantic concepts.
+ * They are used internally to implement API aspects, but are not intended for use by external consumers.
+ */
+// eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor)
+export { InternalTypes };
 
 // Internal/System types:
 // These would be put in `internalTypes` except doing so tents to cause errors like:
@@ -367,3 +371,4 @@ export { TableSchema, type System_TableSchema } from "./tableSchema.js";
 export { asAlpha, asBeta } from "./api.js";
 
 export { TextAsTree, FormattedTextAsTree } from "./text/index.js";
+export { ExtensibleUnionNode } from "./extensibleUnionNode.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.81.1";
+export const pkgVersion = "2.83.0";

package/src/shared-tree/independentView.ts

@@ -61,6 +61,45 @@ import {
 } from "./sharedTree.js";
 import { createTreeCheckout } from "./treeCheckout.js";
 
+/**
+ * {@link independentView} options.
+ * @alpha @input
+ */
+export interface IndependentViewOptions extends ForestOptions, Partial<CodecWriteOptions> {
+	/**
+	 * Optional ID compressor for generating and compressing identifiers.
+	 * If not provided, a new one will be created.
+	 */
+	idCompressor?: IIdCompressor | undefined;
+}
+
+/**
+ * {@link createIndependentTreeAlpha} options.
+ * @alpha
+ */
+export type CreateIndependentTreeAlphaOptions = ForestOptions &
+	(
+		| (IndependentViewOptions & {
+				/**
+				 * Optional content for initializing the tree.
+				 * If not provided, the tree will be uninitialized.
+				 */
+				content?: never;
+		  })
+		| (ICodecOptions & {
+				/**
+				 * Content for initializing the tree.
+				 * The content includes the idCompressor, so idCompressor should not be provided at the top level.
+				 */
+				content: ViewContent;
+				/**
+				 * Should not be provided when content is specified.
+				 * The idCompressor will be obtained from the content.
+				 */
+				idCompressor?: never;
+		  })
+	);
+
 /**
  * Create an uninitialized {@link TreeView} that is not tied to any {@link ITree} instance.
  *
@@ -72,7 +111,7 @@ import { createTreeCheckout } from "./treeCheckout.js";
  */
 export function independentView<const TSchema extends ImplicitFieldSchema>(
 	config: TreeViewConfiguration<TSchema>,
-	options?: ForestOptions & { idCompressor?: IIdCompressor | undefined },
+	options?: IndependentViewOptions,
 ): TreeViewAlpha<TSchema> {
 	return createIndependentTreeAlpha(options).viewWith(config) as TreeViewAlpha<TSchema>;
 }
@@ -170,11 +209,7 @@ export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSch
  * @alpha
  */
 export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSchema>(
-	options?: ForestOptions &
-		(
-			| ({ idCompressor?: IIdCompressor | undefined } & { content?: undefined })
-			| (ICodecOptions & { content: ViewContent } & { idCompressor?: undefined })
-		),
+	options?: CreateIndependentTreeAlphaOptions,
 ): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema"> {
 	const breaker = new Breakable("independentView");
 	const idCompressor: IIdCompressor =
@@ -197,6 +232,7 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 		forest,
 		schema: schemaRepository,
 		breaker,
+		codecOptions: options,
 	});
 
 	if (options?.content !== undefined) {

package/src/shared-tree/index.ts

@@ -59,8 +59,10 @@ export {
 	independentInitializedView,
 	type ViewContent,
 	independentView,
+	type IndependentViewOptions,
 	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
+	type CreateIndependentTreeAlphaOptions,
 } from "./independentView.js";
 
 export type { SharedTreeChange } from "./sharedTreeChangeTypes.js";

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 {
@@ -61,8 +61,8 @@ export function makeSharedTreeChangeCodecFamily(
 		([format, { modularChange, schemaChange }]) => [
 			format,
 			makeSharedTreeChangeCodec(
-				modularChangeCodecFamily.resolve(modularChange).json,
-				schemaChangeCodecs.resolve(schemaChange).json,
+				modularChangeCodecFamily.resolve(modularChange),
+				schemaChangeCodecs.resolve(schemaChange),
 				options,
 			),
 		],
@@ -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

@@ -28,7 +28,7 @@ import type { ITreeCheckout } from "./treeCheckout.js";
  * Provides various functions for interacting with {@link TreeNode}s.
  * @remarks
  * This type should only be used via the {@link (Tree:variable)} export.
- * @system @sealed @public
+ * @sealed @public
  */
 export interface Tree extends TreeNodeApi {
 	/**
@@ -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/treeAlpha.ts

@@ -226,7 +226,7 @@ export interface TreeIdentifierUtils {
  * There should be a way to provide a source for defaulted identifiers for unhydrated node creation, either via these APIs or some way to add them to its output later.
  * If an option were added to these APIs, it could also be used to enable unknown optional fields.
  *
- * @system @sealed @alpha
+ * @sealed @alpha
  */
 export interface TreeAlpha {
 	/**