@fluidframework/tree 2.102.0 → 2.110.0

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

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { type ObjectOptions, type Static, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, Static, TSchema } from "@sinclair/typebox";
 
 import { unionOptions } from "../../codec/index.js";
 import { RevisionTagSchema } from "../../core/index.js";

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

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { type ObjectOptions, type Static, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, Static, TSchema } from "@sinclair/typebox";
 
 import { unionOptions } from "../../codec/index.js";
 import { RevisionTagSchema } from "../../core/index.js";

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

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { type ObjectOptions, type Static, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, Static, TSchema } from "@sinclair/typebox";
 
 import { unionOptions } from "../../codec/index.js";
 

package/src/packageVersion.ts

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

package/src/shared-tree/schematizingTreeView.ts

@@ -529,5 +529,9 @@ export class SchematizingSimpleTreeView<
 		this.checkout.rebaseOnto(context);
 	}
 
+	public isMissingEditsFrom(context: TreeBranchAlpha): boolean {
+		return this.checkout.isMissingEditsFrom(context);
+	}
+
 	// #endregion Branching
 }

package/src/shared-tree/sharedTree.ts

@@ -13,10 +13,7 @@ import type {
 	IFluidSerializer,
 	SharedKernel,
 } from "@fluidframework/shared-object-base/internal";
-import {
-	UsageError,
-	type ITelemetryLoggerExt,
-} from "@fluidframework/telemetry-utils/internal";
+import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	type CodecTree,
@@ -201,7 +198,7 @@ export class SharedTreeKernel
 		submitLocalMessage: (content: unknown, localOpMetadata?: unknown) => void,
 		lastSequenceNumber: () => number | undefined,
 		initialSequenceNumber: number,
-		private readonly logger: ITelemetryLoggerExt | undefined,
+		private readonly logger: TelemetryLoggerExt | undefined,
 		idCompressor: IIdCompressor,
 		optionsParam: SharedTreeOptionsInternal,
 	) {
@@ -320,7 +317,6 @@ export class SharedTreeKernel
 			chunkCompressionStrategy: options.treeEncodeType,
 			logger,
 			breaker: this.breaker,
-			disposeForksAfterTransaction: options.disposeForksAfterTransaction,
 		});
 
 		this.registerSharedBranchForEditing("main", this.checkout);
@@ -635,9 +631,7 @@ export interface SharedTreeOptions
 
 export interface SharedTreeOptionsInternal
 	extends SharedTreeOptions,
-		Partial<SharedTreeCoreOptionsInternal> {
-	disposeForksAfterTransaction?: boolean;
-}
+		Partial<SharedTreeCoreOptionsInternal> {}
 
 /**
  * Configuration options for SharedTree's internal tree storage.
@@ -760,7 +754,6 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	minVersionForCollab: FluidClientVersion.v2_0,
 	forest: ForestTypeReference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,
-	disposeForksAfterTransaction: true,
 	shouldEncodeIncrementally: defaultIncrementalEncodingPolicy,
 	enableSharedBranches: false,
 	healUnresolvableIdentifiersOnDecode: false,

package/src/shared-tree/sharedTreeChangeFormat.ts

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { type Static, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { Static, TSchema } from "@sinclair/typebox";
 
 import type { EncodedSchemaChange } from "../feature-libraries/index.js";
 import { JsonCompatibleReadOnlySchema } from "../util/index.js";

package/src/shared-tree/treeCheckout.ts

@@ -8,10 +8,7 @@ import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/i
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
 import { isStableId } from "@fluidframework/id-compressor/internal";
-import {
-	UsageError,
-	type ITelemetryLoggerExt,
-} from "@fluidframework/telemetry-utils/internal";
+import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	FluidClientVersion,
@@ -60,6 +57,7 @@ import {
 	makeAnonChange,
 	type TaggedChange,
 	deltaFieldMapHasVisibleChanges,
+	findCommonAncestor,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -77,7 +75,6 @@ import {
 	SquashingTransactionStack,
 	SharedTreeBranch,
 	TransactionResult as InternalTransactionResult,
-	onForkTransitive,
 	type SharedTreeBranchChange,
 	type Transactor,
 } from "../shared-tree-core/index.js";
@@ -90,7 +87,6 @@ import {
 	type ViewableTree,
 	type TreeBranch,
 	type TreeBranchAlpha,
-	type TreeChangeEvents,
 	type VerboseTree,
 	type VoidTransactionCallbackStatus,
 	type TransactionCallbackStatus,
@@ -309,9 +305,8 @@ export function createTreeCheckout(
 		fieldBatchCodec?: FieldBatchCodec;
 		removedRoots?: DetachedFieldIndex;
 		chunkCompressionStrategy?: TreeCompressionStrategy;
-		logger?: ITelemetryLoggerExt;
+		logger?: TelemetryLoggerExt;
 		breaker?: Breakable;
-		disposeForksAfterTransaction?: boolean;
 		codecOptions?: Partial<CodecWriteOptions>;
 	},
 ): TreeCheckout {
@@ -358,7 +353,6 @@ export function createTreeCheckout(
 		args?.removedRoots,
 		args?.logger,
 		breaker,
-		args?.disposeForksAfterTransaction,
 	);
 }
 
@@ -528,9 +522,8 @@ export class TreeCheckout implements ITreeCheckout {
 			idCompressor,
 		),
 		/** Optional logger for telemetry. */
-		private readonly logger?: ITelemetryLoggerExt,
+		private readonly logger?: TelemetryLoggerExt,
 		public readonly breaker: Breakable = new Breakable("TreeCheckout"),
-		public readonly disposeForksAfterTransaction = true,
 	) {
 		this.#transaction = this.createTransactionStack(branch);
 		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
@@ -662,9 +655,6 @@ export class TreeCheckout implements ITreeCheckout {
 		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
 	): SquashingTransactionStack<SharedTreeEditBuilder, SharedTreeChange> {
 		return new SquashingTransactionStack(branch, this.mintRevisionTag, () => {
-			const disposeForks = this.disposeForksAfterTransaction
-				? trackForksForDisposal(this)
-				: undefined;
 			// When each transaction is started, make a restorable checkpoint of the current state of removed roots
 			const restoreRemovedRoots = this._removedRoots.createCheckpoint();
 			return (result, viewUpdate: SharedTreeChange | undefined) => {
@@ -691,7 +681,6 @@ export class TreeCheckout implements ITreeCheckout {
 						unreachableCase(result);
 					}
 				}
-				disposeForks?.();
 			};
 		});
 	}
@@ -791,19 +780,48 @@ export class TreeCheckout implements ITreeCheckout {
 					labels: buildLabelsSet(this.labelTreeNode),
 				};
 
-				this.#events.emit("changed", metadata, getRevertible);
+				this.emitChangedLocked(() => {
+					this.#events.emit("changed", metadata, getRevertible);
+				});
 				withinEventContext = false;
 			}
 		} 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,
-				labels: new Set<unknown>(),
+			this.emitChangedLocked(() => {
+				this.#events.emit("changed", {
+					isLocal: false,
+					kind: CommitKind.Default,
+					labels: new Set<unknown>(),
+				});
 			});
 		}
 	};
 
+	/**
+	 * Hold the `editLock` for the duration of `emit`, so that re-entrant edits, transactions,
+	 * branch operations, etc. attempted from inside a `changed` listener throw the canonical
+	 * "forbidden during a change event" {@link UsageError} via {@link EditLock.checkUnlocked}.
+	 *
+	 * @remarks
+	 * Shared by both the local and remote `changed` emission paths in {@link TreeCheckout.onAfterBranchChange}.
+	 * The `try`/`finally` ensures the lock is released even if a listener throws.
+	 */
+	private emitChangedLocked(emit: () => void): void {
+		this.editLock.lock();
+		try {
+			emit();
+		} finally {
+			// TODO: any event that throws potentially leaves the code which triggered that event,
+			// and thus this checkout (and likely more) in a broken state.
+			// Unlocking this editLock prevents future use of this broken state from giving a confusing error in this case,
+			// however, a better approach would probably be to put something (this checkout and/or the editLock)
+			// into a broken state (using a properly scoped `Breakable`),
+			// likely by moving emitChangedLocked into EditLock, and having EditLock get a Breakable,
+			// and having the new emitChangedLocked use `Breakable.use`.
+			this.editLock.unlock();
+		}
+	}
+
 	private readonly onAfterChange = (event: SharedTreeBranchChange<SharedTreeChange>): void => {
 		this.editLock.lock();
 		this.#events.emit("beforeBatch", event);
@@ -911,6 +929,15 @@ export class TreeCheckout implements ITreeCheckout {
 
 	private mountTransaction(params: RunTransactionParams | undefined, isAsync: boolean): void {
 		this.checkNotDisposed();
+		// Starting a transaction is an edit, so it is forbidden from within a change-event
+		// callback (where the edit lock is held), the same as direct edits. For the async
+		// entry point this throw is captured as a rejected promise by the `async` wrapper.
+		//
+		// Note: because runTransaction/runTransactionAsync are `@breakingMethod`, this throw also
+		// puts the checkout into a broken state (unlike a direct edit, which throws recoverably).
+		// That is the same pre-existing broken-state limitation tracked by the TODO in
+		// `emitChangedLocked`, not something specific to transactions.
+		this.editLock.checkUnlocked("Running a transaction");
 		if (isAsync && this.transaction.size > 0) {
 			throw new UsageError(
 				"An asynchronous transaction cannot be started while another transaction is already in progress.",
@@ -1173,7 +1200,6 @@ export class TreeCheckout implements ITreeCheckout {
 			throw new UsageError("A view cannot be forked while it has a pending transaction.");
 		}
 
-		this.editLock.checkUnlocked("Branching");
 		const branch = this.#transaction.activeBranch.fork();
 		const storedSchema = this.storedSchema.clone();
 		const forkBreaker = new Breakable("TreeCheckout");
@@ -1190,7 +1216,6 @@ export class TreeCheckout implements ITreeCheckout {
 			this._removedRoots.clone(),
 			this.logger,
 			forkBreaker,
-			this.disposeForksAfterTransaction,
 		);
 		this.#events.emit("fork", checkout);
 		return checkout;
@@ -1253,6 +1278,19 @@ export class TreeCheckout implements ITreeCheckout {
 		getCheckout(branch).rebase(this);
 	}
 
+	public isMissingEditsFrom(branch: TreeBranch): boolean {
+		const branchCheckout = getCheckout(branch);
+		const targetPath: GraphCommit<unknown>[] = [];
+		const ancestor = findCommonAncestor(this.mainBranch.getHead(), [
+			branchCheckout.mainBranch.getHead(),
+			targetPath,
+		]);
+		if (ancestor === undefined) {
+			throw new UsageError("Branches do not share a common ancestor.");
+		}
+		return targetPath.length > 0;
+	}
+
 	public merge(branch: TreeBranch): void;
 	public merge(branch: TreeBranch, disposeMerged: boolean): void;
 	public merge(branch: TreeBranch, disposeMerged = true): void {
@@ -1684,12 +1722,7 @@ class EditLock {
 	 */
 	public checkUnlocked<T extends string>(action: T extends Capitalize<T> ? T : never): void {
 		if (this.locked) {
-			// These type assertions ensure that the event name strings used here match the actual event names
-			const nodeChanged: keyof TreeChangeEvents = "nodeChanged";
-			const treeChanged: keyof TreeChangeEvents = "treeChanged";
-			throw new UsageError(
-				`${action} is forbidden during a ${nodeChanged} or ${treeChanged} event`,
-			);
+			throw new UsageError(`${action} is forbidden during a change event callback`);
 		}
 	}
 
@@ -1703,34 +1736,6 @@ class EditLock {
 	}
 }
 
-/**
- * Keeps track of all new forks created until the returned function is invoked, which will dispose all of those for.
- * The returned function may only be called once.
- *
- * @param checkout - The tree checkout for which you want to monitor forks for disposal.
- * @returns a function which can be called to dispose all of the tracked forks.
- */
-function trackForksForDisposal(checkout: TreeCheckout): () => void {
-	const forks = new Set<TreeCheckout>();
-	const onDisposeUnSubscribes: (() => void)[] = [];
-	const onForkUnSubscribe = onForkTransitive(checkout, (fork) => {
-		forks.add(fork);
-		onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
-	});
-	let disposed = false;
-	return () => {
-		assert(!disposed, 0xaa9 /* Forks may only be disposed once */);
-		for (const fork of forks) {
-			fork.dispose();
-		}
-		for (const unsubscribe of onDisposeUnSubscribes) {
-			unsubscribe();
-		}
-		onForkUnSubscribe();
-		disposed = true;
-	};
-}
-
 function verboseFromCursor(
 	reader: ITreeCursor,
 	schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,

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

@@ -9,7 +9,7 @@ import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { SessionId } from "@fluidframework/id-compressor";
 import {
 	TelemetryEventBatcher,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
 
@@ -123,7 +123,7 @@ export class EditManager<
 		public readonly localSessionId: SessionId,
 		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly onSharedBranchCreated?: (branchId: BranchId) => void,
-		logger?: ITelemetryLoggerExt,
+		logger?: TelemetryLoggerExt,
 	) {
 		this.trunkBase = {
 			revision: rootRevision,

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

@@ -4,7 +4,8 @@
  */
 
 import type { SessionId } from "@fluidframework/id-compressor";
-import { type ObjectOptions, type Static, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, Static, TSchema } from "@sinclair/typebox";
 
 import {
 	type EncodedRevisionTag,

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

@@ -4,7 +4,8 @@
  */
 
 import type { SessionId } from "@fluidframework/id-compressor";
-import { type ObjectOptions, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, TSchema } from "@sinclair/typebox";
 
 import { SessionIdSchema } from "../core/index.js";
 

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

@@ -4,7 +4,8 @@
  */
 
 import type { SessionId } from "@fluidframework/id-compressor";
-import { type ObjectOptions, type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, TSchema } from "@sinclair/typebox";
 
 import { SessionIdSchema } from "../core/index.js";
 

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

@@ -4,7 +4,8 @@
  */
 
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
-import { type TAnySchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { TAnySchema } from "@sinclair/typebox";
 
 import type { CodecAndSchema, IJsonCodec, Versioned } from "../codec/index.js";
 import type {

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

@@ -4,7 +4,8 @@
  */
 
 import type { SessionId } from "@fluidframework/id-compressor";
-import { type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
 
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";

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

@@ -4,7 +4,8 @@
  */
 
 import type { SessionId } from "@fluidframework/id-compressor";
-import { type TSchema, Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
 
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";

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

@@ -342,6 +342,17 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 	 * Update the tests and docs to match when that is done.
 	 */
 	applyChange(change: JsonCompatibleReadOnly): void;
+
+	/**
+	 * Determines if there are changes on the given branch that are not present on this branch.
+	 * @param branch - The branch to compare to.
+	 *
+	 * The new edits, if any, can be applied to this branch by {@link TreeBranch.rebaseOnto | rebasing this branch onto the given branch}
+	 * or by {@link TreeBranch.merge | merging the given branch into this branch}.
+	 *
+	 * @throws UsageError if the branches are unrelated.
+	 */
+	isMissingEditsFrom(branch: TreeBranch): boolean;
 }
 
 /**

package/src/simple-tree/core/treeNodeKernel.ts

@@ -332,34 +332,53 @@ export function withBufferedTreeEvents(callback: () => void): void {
 		callback();
 	} else {
 		bufferTreeEvents = true;
+		const toFlush: KernelEventBuffer[] = [];
 		try {
 			callback();
 		} finally {
 			bufferTreeEvents = false;
-			flushEventsEmitter.emit("flush");
+			// Snapshot-and-clear before flushing to safely handle reentrant `withBufferedTreeEvents`
+			// calls made by listeners that fire during `buffer.flush()` below:
+			// - Iterating an array means a reentrant call's `clear()` cannot truncate our loop
+			//   and cause buffers later in `activeBuffers` to be skipped (and their events dropped).
+			// - Clearing up front means the reentrant call starts from an empty set, so its own
+			//   finally block only flushes what it buffered - not a re-flush of our remaining buffers.
+			toFlush.push(...activeBuffers);
+			activeBuffers.clear();
+		}
+
+		// Don't flush/emit events in the case of an error
+		for (const buffer of toFlush) {
+			buffer.flush();
 		}
 	}
 }
 
 /**
- * Event emitter to notify subscribers when tree events buffered due to {@link withBufferedTreeEvents} should be flushed.
+ * Set of {@link KernelEventBuffer}s that have accumulated buffered events during the current
+ * {@link withBufferedTreeEvents} window and therefore need to be flushed when it ends.
+ *
+ * @remarks
+ * The set should be empty whenever no buffering window is in progress.
  */
-const flushEventsEmitter = createEmitter<{
-	flush: () => void;
-}>();
+const activeBuffers: Set<KernelEventBuffer> = new Set();
+
+/**
+ * Test-only accessor for the current size of {@link activeBuffers}.
+ * @remarks Only exported for testing purposes. Not intended for any other use.
+ */
+export function TEST_activeBufferCount(): number {
+	return activeBuffers.size;
+}
 
 /**
  * Event emitter for {@link TreeNodeKernel}, which optionally buffers events based on {@link bufferTreeEvents}.
- * @remarks Listens to {@link flushEventsEmitter} to know when to flush any buffered events.
+ * @remarks When buffering is active, this adds itself to {@link activeBuffers} so that
+ * {@link withBufferedTreeEvents} can flush it at the end of the buffering window.
  */
 class KernelEventBuffer implements Listenable<KernelEvents> {
 	#disposed: boolean = false;
 
-	/**
-	 * Listen to {@link flushEventsEmitter} to know when to flush buffered events.
-	 */
-	readonly #disposeOnFlushListener = flushEventsEmitter.on("flush", this.flush.bind(this));
-
 	readonly #events = createEmitter<KernelEvents>();
 
 	#eventSource: Listenable<KernelEvents> & HasListeners<KernelEvents>;
@@ -501,6 +520,7 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>,
 	): void {
 		if (bufferTreeEvents) {
+			activeBuffers.add(this);
 			for (const fieldKey of changedFields) {
 				this.#childrenChangedBuffer.add(fieldKey);
 			}
@@ -528,6 +548,7 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 
 	#handleSubtreeChangedAfterBatch(): void {
 		if (bufferTreeEvents) {
+			activeBuffers.add(this);
 			this.#subTreeChangedBuffer = true;
 		} else {
 			this.#events.emit("subtreeChangedAfterBatch");
@@ -565,12 +586,15 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 			return;
 		}
 
-		assert(
-			this.#childrenChangedBuffer.size === 0 && !this.#subTreeChangedBuffer,
-			0xc52 /* Buffered kernel events should have been flushed before disposing. */,
+		debugAssert(
+			() =>
+				(this.#childrenChangedBuffer.size === 0 && !this.#subTreeChangedBuffer) ||
+				"Buffered kernel events should have been flushed before disposing.",
+		);
+		debugAssert(
+			() => !activeBuffers.has(this) || "Disposed buffer should not be in activeBuffers.",
 		);
 
-		this.#disposeOnFlushListener();
 		for (const off of this.#disposeSourceListeners.values()) {
 			off();
 		}

package/src/simple-tree/simpleSchemaFormatV1.ts

@@ -11,7 +11,8 @@
  * It may not include some details which impact maintenance of application enforced invariants (like persisted metadata or logic in view schema).
  */
 
-import { Type, type ObjectOptions, type Static } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, Static } from "@sinclair/typebox";
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };