@fluidframework/tree 2.74.0 → 2.81.0-374083

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

@@ -10,11 +10,12 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	findAncestor,
+	tagChange,
 	type ChangeFamilyEditor,
 	type GraphCommit,
-	type TaggedChange,
+	type RevisionTag,
 } from "../core/index.js";
-import { getOrCreate } from "../util/index.js";
+import { getLast, getOrCreate, hasSome } from "../util/index.js";
 
 import type { SharedTreeBranch, SharedTreeBranchEvents } from "./branch.js";
 
@@ -92,12 +93,32 @@ export interface TransactionEvents {
 	committing(): void;
 }
 
+/**
+ * Callbacks for transaction lifecycle events.
+ */
+export interface Callbacks {
+	/**
+	 * Called when the current transaction is popped from the {@link TransactionStack | stack}.
+	 */
+	readonly onPop?: OnPop;
+	/**
+	 * Called when a nested transaction is pushed onto the {@link TransactionStack | stack}.
+	 * @remarks
+	 * Transactions may be arbitrarily nested (by {@link TransactionStack.start | start}ing a transaction within a transaction that is already in progress).
+	 * The `OnPush` callback for an (outer) transaction may optionally return another `OnPush` callback that is associated with any nested (inner) transaction(s).
+	 * In that case, the inner `OnPush` will be called when those inner transactions are pushed and the outer `OnPush` will not be called.
+	 * Put another way, a transaction always results in a call to exactly one `OnPush` callback - whichever is closest to the transaction.
+	 * The event "bubbles up" to (and no further past) its first registered callback.
+	 */
+	readonly onPush?: OnPush;
+}
+
 /**
  * A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
- * @remarks This function may return {@link OnPop | its complement} - another function that will be called when the transaction is popped from the stack.
+ * @remarks This function may return other functions that will be called when the transaction is popped from the stack or a nested transaction is pushed onto the stack.
  * This function runs just before the transaction begins, so if this is the beginning of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
  */
-export type OnPush = () => OnPop | void;
+export type OnPush = () => Callbacks | void;
 
 /**
  * A function that will be called when a transaction is popped from the {@link TransactionStack | stack}.
@@ -110,8 +131,8 @@ export type OnPop = (result: TransactionResult) => void;
  * @remarks Using a stack allows transactions to nest - i.e. an inner transaction may be started while an outer transaction is already in progress.
  */
 export class TransactionStack implements Transactor, IDisposable {
-	readonly #stack: (OnPop | void)[] = [];
-	readonly #onPush?: () => OnPop | void;
+	readonly #stack: Callbacks[] = [];
+	readonly #onPush?: OnPush;
 
 	readonly #events = createEmitter<TransactionEvents>();
 	public get events(): Listenable<TransactionEvents> {
@@ -127,7 +148,7 @@ export class TransactionStack implements Transactor, IDisposable {
 	 * Construct a new {@link TransactionStack}.
 	 * @param onPush - A {@link OnPush | function} that will be called when a transaction begins.
 	 */
-	public constructor(onPush?: () => OnPop | void) {
+	public constructor(onPush?: OnPush) {
 		this.#onPush = onPush;
 	}
 
@@ -138,7 +159,9 @@ export class TransactionStack implements Transactor, IDisposable {
 
 	public start(): void {
 		this.ensureNotDisposed();
-		this.#stack.push(this.#onPush?.());
+		const onPushCurrent = hasSome(this.#stack) ? getLast(this.#stack).onPush : this.#onPush;
+		const { onPush, onPop } = onPushCurrent?.() ?? {};
+		this.#stack.push({ onPop, onPush: onPush ?? onPushCurrent });
 		this.#events.emit("started");
 	}
 
@@ -148,7 +171,7 @@ export class TransactionStack implements Transactor, IDisposable {
 			throw new UsageError("No transaction to commit");
 		}
 		this.#events.emit("committing");
-		this.#stack.pop()?.(TransactionResult.Commit);
+		this.#stack.pop()?.onPop?.(TransactionResult.Commit);
 	}
 
 	public abort(): void {
@@ -157,7 +180,7 @@ export class TransactionStack implements Transactor, IDisposable {
 			throw new UsageError("No transaction to abort");
 		}
 		this.#events.emit("aborting");
-		this.#stack.pop()?.(TransactionResult.Abort);
+		this.#stack.pop()?.onPop?.(TransactionResult.Abort);
 	}
 
 	public dispose(): void {
@@ -185,7 +208,6 @@ export class SquashingTransactionStack<
 	TEditor extends ChangeFamilyEditor,
 	TChange,
 > extends TransactionStack {
-	public readonly branch: SharedTreeBranch<TEditor, TChange>;
 	#transactionBranch?: SharedTreeBranch<TEditor, TChange>;
 
 	/**
@@ -243,57 +265,94 @@ export class SquashingTransactionStack<
 	/**
 	 * Construct a new {@link SquashingTransactionStack}.
 	 * @param branch - The {@link SquashingTransactionStack.branch | branch} that will be forked off of when a transaction begins.
-	 * @param squash - Called once when the outer-most transaction is committed to produce a single squashed change from the transaction's commits.
-	 * The change will be applied to the original {@link SquashingTransactionStack.branch | branch}.
-	 * @param onPush - {@link OnPush | A function} that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
+	 * @param onPush - A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
 	 */
 	public constructor(
-		branch: SharedTreeBranch<TEditor, TChange>,
-		squash: (commits: GraphCommit<TChange>[]) => TaggedChange<TChange>,
-		onPush?: OnPush,
+		public readonly branch: SharedTreeBranch<TEditor, TChange>,
+		mintRevisionTag: () => RevisionTag,
+		onPush?: () => OnPop | void,
 	) {
-		super(() => {
-			// Keep track of the commit that each transaction was on when it started
-			// TODO:#8603: This may need to be computed differently if we allow rebasing during a transaction.
-			const startHead = this.activeBranch.getHead();
-			const onPop = onPush?.();
-			const transactionBranch = this.#transactionBranch ?? this.branch.fork();
-			this.setTransactionBranch(transactionBranch);
-			transactionBranch.editor.enterTransaction();
-			return (result) => {
-				assert(this.#transactionBranch !== undefined, 0xa98 /* Expected transaction branch */);
-				this.#transactionBranch.editor.exitTransaction();
-				switch (result) {
-					case TransactionResult.Abort:
-						// When a transaction is aborted, roll back all the transaction's changes on the current branch
-						this.#transactionBranch.removeAfter(startHead);
-						break;
-					case TransactionResult.Commit:
-						// If this was the outermost transaction closing...
-						if (!this.isInProgress()) {
-							if (this.#transactionBranch.getHead() !== startHead) {
-								// ...squash all the new commits on the transaction branch into a new commit on the original branch
-								const removedCommits: GraphCommit<TChange>[] = [];
-								findAncestor(
-									[this.#transactionBranch.getHead(), removedCommits],
-									(c) => c === startHead,
-								);
-								branch.apply(squash(removedCommits));
+		super(
+			// Invoked when an outer transaction starts
+			(): Callbacks => {
+				// Keep track of the commit that each transaction was on when it started
+				// TODO:#8603: This may need to be computed differently if we allow rebasing during a transaction.
+				const startHead = this.activeBranch.getHead();
+				const outerOnPop = onPush?.();
+				let transactionRevision: RevisionTag | undefined;
+				const transactionBranch = this.branch.fork(
+					startHead,
+					// Lazily mint the revision tag for the transaction when it is first needed
+					() => (transactionRevision ??= mintRevisionTag()),
+				);
+				this.setTransactionBranch(transactionBranch);
+				transactionBranch.editor.enterTransaction();
+				// Invoked when an outer transaction ends
+				const onOuterTransactionPop: OnPop = (result) => {
+					assert(!this.isInProgress(), 0xcae /* The outer transaction should be ending */);
+					transactionBranch.editor.exitTransaction();
+					switch (result) {
+						case TransactionResult.Abort: {
+							// When a transaction is aborted, roll back all the transaction's changes on the current branch
+							transactionBranch.removeAfter(startHead);
+							break;
+						}
+						case TransactionResult.Commit: {
+							// ...squash all the new commits on the transaction branch into a new commit on the original branch
+							const removedCommits: GraphCommit<TChange>[] = [];
+							findAncestor(
+								[transactionBranch.getHead(), removedCommits],
+								(c) => c === startHead,
+							);
+							if (removedCommits.length > 0) {
+								for (const commit of removedCommits) {
+									assert(
+										commit.revision === transactionRevision,
+										0xcaf /* Unexpected commit in transaction */,
+									);
+								}
+								const squash = this.branch.changeFamily.rebaser.compose(removedCommits);
+								this.branch.apply(tagChange(squash, transactionRevision));
 							}
+							break;
+						}
+						default: {
+							unreachableCase(result);
 						}
-						break;
-					default:
-						unreachableCase(result);
-				}
-				if (!this.isInProgress()) {
-					this.#transactionBranch.dispose();
+					}
+					transactionBranch.dispose();
 					this.setTransactionBranch(undefined);
-				}
-				onPop?.(result);
-			};
-		});
-
-		this.branch = branch;
+					outerOnPop?.(result);
+				};
+				// Invoked when a nested transaction begins
+				const onNestedTransactionPush: OnPush = () => {
+					const nestedStartHead = this.activeBranch.getHead();
+					const nestedOuterOnPop = onPush?.();
+					transactionBranch.editor.enterTransaction();
+					return {
+						// Invoked when a nested transaction ends
+						onPop: (result) => {
+							transactionBranch.editor.exitTransaction();
+							switch (result) {
+								case TransactionResult.Abort: {
+									// When a transaction is aborted, roll back all the transaction's changes on the current branch
+									transactionBranch.removeAfter(nestedStartHead);
+									break;
+								}
+								case TransactionResult.Commit: {
+									break;
+								}
+								default: {
+									unreachableCase(result);
+								}
+							}
+							nestedOuterOnPop?.(result);
+						},
+					};
+				};
+				return { onPop: onOuterTransactionPop, onPush: onNestedTransactionPush };
+			},
+		);
 	}
 
 	/** Updates the transaction branch (and therefore the active branch) and rebinds the branch events. */

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

@@ -5,7 +5,7 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import type { ChangeRebaser, GraphCommit, RevisionTag } from "../core/index.js";
+import type { ChangeRebaser, GraphCommit } from "../core/index.js";
 
 import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
 
@@ -33,7 +33,7 @@ export class TransactionEnricher<TChange> {
 	}
 
 	public isTransacting(): boolean {
-		return this.#transactionScopesStart.length !== 0;
+		return this.#transactionScopesStart.length > 0;
 	}
 
 	public startTransaction(): void {
@@ -44,7 +44,7 @@ export class TransactionEnricher<TChange> {
 	 * Commits the current transaction.
 	 * @returns A function which can be used to compute the composed change for that transaction's commits. Undefined if the transaction is still ongoing or contained no committed changes.
 	 */
-	public commitTransaction(): ((revision: RevisionTag) => TChange) | undefined {
+	public commitTransaction(): (() => TChange) | undefined {
 		const commitsCommitted = this.#transactionScopesStart.pop();
 		assert(commitsCommitted !== undefined, 0x985 /* No transaction to commit */);
 		if (this.#transactionScopesStart.length === 0) {
@@ -53,8 +53,7 @@ export class TransactionEnricher<TChange> {
 			}
 			const transactionCommits = this.#transactionCommits;
 			this.#transactionCommits = [];
-			return (revision: RevisionTag) =>
-				this.#rebaser.changeRevision(this.#rebaser.compose(transactionCommits), revision);
+			return () => this.#rebaser.compose(transactionCommits);
 		}
 	}
 
@@ -66,7 +65,7 @@ export class TransactionEnricher<TChange> {
 
 	public addTransactionStep(commit: GraphCommit<TChange>): void {
 		assert(
-			this.#transactionScopesStart.length !== 0,
+			this.#transactionScopesStart.length > 0,
 			0x987 /* No transaction to add a step to */,
 		);
 		const change = this.#enricher.updateChangeEnrichments(commit.change, commit.revision);

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

@@ -222,7 +222,7 @@ export class TreeViewConfiguration<
 			},
 		});
 
-		if (ambiguityErrors.length !== 0) {
+		if (ambiguityErrors.length > 0) {
 			// Duplicate errors are common since when two types conflict, both orders error:
 			const deduplicated = new Set(ambiguityErrors);
 			throw new UsageError(`Ambiguous schema found:\n${[...deduplicated].join("\n")}`);

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

@@ -148,26 +148,23 @@ export function customFromCursor<TChild>(
 		case numberSchema.identifier:
 		case booleanSchema.identifier:
 		case nullSchema.identifier:
-		case stringSchema.identifier:
+		case stringSchema.identifier: {
 			assert(reader.value !== undefined, 0xa50 /* out of schema: missing value */);
 			assert(!isFluidHandle(reader.value), 0xa51 /* out of schema: unexpected FluidHandle */);
 			return reader.value;
-		case handleSchema.identifier:
+		}
+		case handleSchema.identifier: {
 			assert(reader.value !== undefined, 0xa52 /* out of schema: missing value */);
 			assert(isFluidHandle(reader.value), 0xa53 /* out of schema: expected FluidHandle */);
 			return reader.value;
+		}
 		default: {
 			assert(reader.value === undefined, 0xa54 /* out of schema: unexpected value */);
 			const nodeSchema =
 				storedSchema.get(type) ?? fail(0xb2e /* missing schema for type in cursor */);
 			const arrayTypes = tryStoredSchemaAsArray(nodeSchema);
 
-			if (arrayTypes !== undefined) {
-				const fields = inCursorField(reader, EmptyKey, () =>
-					mapCursorField(reader, () => childHandler(reader, options, storedSchema, schema)),
-				);
-				return fields;
-			} else {
+			if (arrayTypes === undefined) {
 				const fields: Record<string, TChild> = {};
 				forEachField(reader, () => {
 					assert(reader.getFieldLength() === 1, 0xa19 /* invalid children number */);
@@ -183,6 +180,11 @@ export function customFromCursor<TChild>(
 					reader.exitNode();
 				});
 				return fields;
+			} else {
+				const fields = inCursorField(reader, EmptyKey, () =>
+					mapCursorField(reader, () => childHandler(reader, options, storedSchema, schema)),
+				);
+				return fields;
 			}
 		}
 	}
@@ -209,11 +211,12 @@ function getKeyFromOptions(
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): string | undefined {
 	switch (options) {
-		case KeyEncodingOptions.allStoredKeys:
+		case KeyEncodingOptions.allStoredKeys: {
 			// Since this case might be inside of an unknown optional field,
 			// it must not depend on there being a view schema.
 			// Fortunately, its possible to implement this case without one.
 			return storedKey;
+		}
 		case KeyEncodingOptions.usePropertyKeys:
 		case KeyEncodingOptions.knownStoredKeys: {
 			// Both these cases avoid traversing into unknown optional fields,
@@ -236,8 +239,9 @@ function getKeyFromOptions(
 				return storedKey;
 			}
 		}
-		default:
+		default: {
 			unreachableCase(options);
+		}
 	}
 }
 

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

@@ -154,16 +154,20 @@ function doesNodeKindMatchStoredNodeKind(
 	storedType: SchemaFactoryNodeKind,
 ): boolean {
 	switch (viewKind) {
-		case NodeKind.Leaf:
+		case NodeKind.Leaf: {
 			return storedType === LeafNodeStoredSchema;
+		}
 		case NodeKind.Array:
-		case NodeKind.Object:
+		case NodeKind.Object: {
 			return storedType === ObjectNodeStoredSchema;
+		}
 		case NodeKind.Map:
-		case NodeKind.Record:
+		case NodeKind.Record: {
 			return storedType === MapNodeStoredSchema;
-		default:
+		}
+		default: {
 			unreachableCase(viewKind);
+		}
 	}
 }
 
@@ -291,8 +295,9 @@ function* getNodeDiscrepancies(
 			}
 			break;
 		}
-		default:
+		default: {
 			break;
+		}
 	}
 }
 
@@ -457,18 +462,19 @@ function* computeObjectNodeDiscrepancies(
 		}
 
 		// If the stored schema has a field that's not in the view schema
-		if (!viewKeys.has(fieldKey)) {
-			// When the application has opted into it, we allow viewing documents which have additional
-			// optional fields in the stored schema that are not present in the view schema.
-			if (!view.allowUnknownOptionalFields || schema.kind !== FieldKinds.optional.identifier) {
-				yield {
-					identifier,
-					fieldKey,
-					mismatch: "fieldKind",
-					view: storedEmptyFieldSchema.kind,
-					stored: schema.kind,
-				} satisfies FieldKindDiscrepancy;
-			}
+		// When the application has opted into it, we allow viewing documents which have additional
+		// optional fields in the stored schema that are not present in the view schema.
+		if (
+			!viewKeys.has(fieldKey) &&
+			(!view.allowUnknownOptionalFields || schema.kind !== FieldKinds.optional.identifier)
+		) {
+			yield {
+				identifier,
+				fieldKey,
+				mismatch: "fieldKind",
+				view: storedEmptyFieldSchema.kind,
+				stored: schema.kind,
+			} satisfies FieldKindDiscrepancy;
 		}
 	}
 }

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

@@ -153,7 +153,9 @@ export {
 
 export {
 	type TransactionConstraint,
+	type TransactionConstraintAlpha,
 	type NodeInDocumentConstraint,
+	type NoChangeConstraint,
 	type RunTransactionParams,
 	type VoidTransactionCallbackStatus,
 	type TransactionCallbackStatus,
@@ -178,4 +180,7 @@ export {
 	exportCompatibilitySchemaSnapshot,
 	importCompatibilitySchemaSnapshot,
 	checkCompatibility,
+	checkSchemaCompatibilitySnapshots,
+	type SnapshotFileSystem,
+	type SchemaCompatibilitySnapshotsOptions,
 } from "./snapshotCompatibilityChecker.js";

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

@@ -75,12 +75,15 @@ import { type SchemaStatics, schemaStatics } from "./schemaStatics.js";
  */
 export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 	switch (typeof value) {
-		case "boolean":
+		case "boolean": {
 			return booleanSchema;
-		case "number":
+		}
+		case "number": {
 			return numberSchema;
-		case "string":
+		}
+		case "string": {
 			return stringSchema;
+		}
 		case "object": {
 			if (value === null) {
 				return nullSchema;
@@ -88,8 +91,9 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 			assert(isFluidHandle(value), 0x87e /* invalid TreeValue */);
 			return handleSchema;
 		}
-		default:
+		default: {
 			unreachableCase(value);
+		}
 	}
 }
 
@@ -928,9 +932,7 @@ export function structuralName<const T extends string>(
 	allowedTypes: TreeNodeSchema | readonly TreeNodeSchema[],
 ): `${T}<${string}>` {
 	let inner: string;
-	if (!isReadonlyArray(allowedTypes)) {
-		return structuralName(collectionName, [allowedTypes]);
-	} else {
+	if (isReadonlyArray(allowedTypes)) {
 		const names = allowedTypes.map((t): string => {
 			// Ensure that lazy types (functions) don't slip through here.
 			assert(!isLazy(t), 0x83d /* invalid type provided */);
@@ -943,6 +945,8 @@ export function structuralName<const T extends string>(
 		// Using JSON is a simple way to accomplish this.
 		// The outer `[]` around the result were needed so that a single type name "Any" would not collide with the "any" case which used to exist.
 		inner = JSON.stringify(names);
+	} else {
+		return structuralName(collectionName, [allowedTypes]);
 	}
 	return `${collectionName}<${inner}>`;
 }

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

@@ -94,7 +94,7 @@ export class SchemaFactoryAlpha<
 	} {
 		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
 			...defaultSchemaFactoryObjectOptions,
-			...(options ?? {}),
+			...options,
 		});
 	}
 

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

@@ -260,7 +260,7 @@ export class SchemaFactoryBeta<
 	> {
 		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
 			...defaultSchemaFactoryObjectOptions,
-			...(options ?? {}),
+			...options,
 		});
 	}
 

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

@@ -85,14 +85,18 @@ function generateFieldSchema(
 
 	// Using createFieldSchema could work, but would require setting up the default providers.
 	switch (simple.kind) {
-		case FieldKind.Identifier:
+		case FieldKind.Identifier: {
 			return SchemaFactoryAlpha.identifier(props);
-		case FieldKind.Optional:
+		}
+		case FieldKind.Optional: {
 			return SchemaFactoryAlpha.optional(allowed, props);
-		case FieldKind.Required:
+		}
+		case FieldKind.Required: {
 			return SchemaFactoryAlpha.required(allowed, props);
-		default:
+		}
+		default: {
 			return unreachableCase(simple.kind);
+		}
 	}
 }
 
@@ -127,26 +131,31 @@ function generateNode(
 				allowUnknownOptionalFields: schema.allowUnknownOptionalFields ?? false,
 			});
 		}
-		case NodeKind.Array:
+		case NodeKind.Array: {
 			return factory.arrayAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {
 				metadata: schema.metadata,
 			});
-		case NodeKind.Map:
+		}
+		case NodeKind.Map: {
 			return factory.mapAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {
 				metadata: schema.metadata,
 			});
-		case NodeKind.Record:
+		}
+		case NodeKind.Record: {
 			return factory.recordAlpha(
 				id,
 				generateAllowedTypes(schema.simpleAllowedTypes, context),
 				{ metadata: schema.metadata },
 			);
-		case NodeKind.Leaf:
+		}
+		case NodeKind.Leaf: {
 			return (
 				SchemaFactoryAlpha.leaves.find((leaf) => leaf.identifier === id) ??
 				fail(0xb5b /* Missing schema */)
 			);
-		default:
+		}
+		default: {
 			return unreachableCase(schema);
+		}
 	}
 }

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

@@ -111,16 +111,21 @@ export function decodeSchemaCompatibilitySnapshot(
 function encodeNodeSchema(schema: SimpleNodeSchema): Format.SimpleNodeSchemaUnionFormat {
 	const kind = schema.kind;
 	switch (kind) {
-		case NodeKind.Leaf:
+		case NodeKind.Leaf: {
 			return { leaf: encodeLeafNode(schema) };
-		case NodeKind.Array:
+		}
+		case NodeKind.Array: {
 			return { array: encodeContainerNode(schema) };
-		case NodeKind.Map:
+		}
+		case NodeKind.Map: {
 			return { map: encodeContainerNode(schema) };
-		case NodeKind.Record:
+		}
+		case NodeKind.Record: {
 			return { record: encodeContainerNode(schema) };
-		case NodeKind.Object:
+		}
+		case NodeKind.Object: {
 			return { object: encodeObjectNode(schema) };
+		}
 		default: {
 			unreachableCase(kind);
 		}