@fluidframework/tree 2.10.0 → 2.11.0

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import type {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
@@ -45,7 +45,7 @@ import {
 	breakingClass,
 } from "../util/index.js";
 
-import { type SharedTreeBranch, getChangeReplaceType } from "./branch.js";
+import { getChangeReplaceType, type SharedTreeBranch } from "./branch.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
 import { makeEditManagerCodec } from "./editManagerCodecs.js";
 import type { SeqNumber } from "./editManagerFormat.js";
@@ -183,60 +183,20 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			rebaseLogger,
 		);
-		this.editManager.localBranch.events.on("transactionStarted", () => {
-			this.commitEnricher.startNewTransaction();
-		});
-		this.editManager.localBranch.events.on("transactionAborted", () => {
-			this.commitEnricher.abortCurrentTransaction();
-		});
-		this.editManager.localBranch.events.on("transactionCommitted", () => {
-			this.commitEnricher.commitCurrentTransaction();
-		});
+
 		this.editManager.localBranch.events.on("beforeChange", (change) => {
-			// Ensure that any previously prepared commits that have not been sent are purged.
-			this.commitEnricher.purgePreparedCommits();
-			if (this.detachedRevision !== undefined) {
-				// Edits submitted before the first attach do not need enrichment because they will not be applied by peers.
-			} else if (change.type === "append") {
-				if (this.getLocalBranch().isTransacting()) {
-					for (const newCommit of change.newCommits) {
-						this.commitEnricher.ingestTransactionCommit(newCommit);
-					}
-				} else {
-					for (const newCommit of change.newCommits) {
-						this.commitEnricher.prepareCommit(newCommit, false);
-					}
-				}
-			} else if (
-				change.type === "replace" &&
-				getChangeReplaceType(change) === "transactionCommit" &&
-				!this.getLocalBranch().isTransacting()
-			) {
-				assert(
-					change.newCommits.length === 1,
-					0x983 /* Unexpected number of commits when committing transaction */,
-				);
-				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
+			if (this.detachedRevision === undefined) {
+				// Commit enrichment is only necessary for changes that will be submitted as ops, and changes issued while detached are not submitted.
+				this.commitEnricher.processChange(change);
 			}
 		});
 		this.editManager.localBranch.events.on("afterChange", (change) => {
-			if (this.getLocalBranch().isTransacting()) {
-				// We do not submit ops for changes that are part of a transaction.
-				return;
-			}
 			if (
 				change.type === "append" ||
 				(change.type === "replace" && getChangeReplaceType(change) === "transactionCommit")
 			) {
-				if (this.detachedRevision !== undefined) {
-					for (const newCommit of change.newCommits) {
-						this.submitCommit(newCommit, this.schemaAndPolicy);
-					}
-				} else {
-					for (const newCommit of change.newCommits) {
-						const prepared = this.commitEnricher.getPreparedCommit(newCommit);
-						this.submitCommit(prepared, this.schemaAndPolicy);
-					}
+				for (const commit of change.newCommits) {
+					this.submitCommit(commit, this.schemaAndPolicy);
 				}
 			}
 		});
@@ -353,22 +313,21 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	 * @returns the submitted commit. This is undefined if the underlying `SharedObject` is not attached,
 	 * and may differ from `commit` due to enrichments like detached tree refreshers.
 	 */
-
-	private submitCommit(
+	protected submitCommit(
 		commit: GraphCommit<TChange>,
 		schemaAndPolicy: ClonableSchemaAndPolicy,
 		isResubmit = false,
 	): void {
-		assert(
-			// Edits should not be submitted until all transactions finish
-			!this.getLocalBranch().isTransacting() || isResubmit,
-			0x68b /* Unexpected edit submitted during transaction */,
-		);
 		assert(
 			this.isAttached() === (this.detachedRevision === undefined),
 			0x95a /* Detached revision should only be set when not attached */,
 		);
 
+		const enrichedCommit =
+			this.detachedRevision === undefined && !isResubmit
+				? this.commitEnricher.enrich(commit)
+				: commit;
+
 		// Edits submitted before the first attach are treated as sequenced because they will be included
 		// in the attach summary that is uploaded to the service.
 		// Until this attach workflow happens, this instance essentially behaves as a centralized data structure.
@@ -376,7 +335,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			const newRevision: SeqNumber = brand((this.detachedRevision as number) + 1);
 			this.detachedRevision = newRevision;
 			this.editManager.addSequencedChange(
-				{ ...commit, sessionId: this.editManager.localSessionId },
+				{ ...enrichedCommit, sessionId: this.editManager.localSessionId },
 				newRevision,
 				this.detachedRevision,
 			);
@@ -385,7 +344,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		}
 		const message = this.messageCodec.encode(
 			{
-				commit,
+				commit: enrichedCommit,
 				sessionId: this.editManager.localSessionId,
 			},
 			{
@@ -398,7 +357,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			schema: schemaAndPolicy.schema.clone(),
 			policy: schemaAndPolicy.policy,
 		});
-		this.resubmitMachine.onCommitSubmitted(commit);
+		this.resubmitMachine.onCommitSubmitted(enrichedCommit);
 	}
 
 	protected processCore(
@@ -469,10 +428,6 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	}
 
 	protected applyStashedOp(content: JsonCompatibleReadOnly): void {
-		assert(
-			!this.getLocalBranch().isTransacting(),
-			0x674 /* Unexpected transaction is open while applying stashed ops */,
-		);
 		// Empty context object is passed in, as our decode function is schema-agnostic.
 		const {
 			commit: { revision, change },

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

@@ -0,0 +1,165 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { IDisposable, Listenable } from "@fluidframework/core-interfaces";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+/**
+ * Describes the result of a transaction.
+ * Transactions may either succeed and commit, or fail and abort.
+ */
+export enum TransactionResult {
+	/**
+	 * Indicates the transaction failed.
+	 */
+	Abort,
+	/**
+	 * Indicates the transaction succeeded.
+	 */
+	Commit,
+}
+
+/**
+ * A simple API for managing transactions.
+ */
+export interface Transactor {
+	/**
+	 * Start a new transaction.
+	 * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
+	 * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
+	 *
+	 * @remarks - Asynchronous transactions are not supported on the root checkout,
+	 * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate
+	 * the transaction) is not visible to the application author.
+	 * Instead,
+	 *
+	 * 1. fork the root checkout
+	 * 2. run the transaction on the fork
+	 * 3. merge the fork back into the root checkout
+	 *
+	 * @privateRemarks - There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
+	 * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.
+	 */
+	start(): void;
+	/**
+	 * Close this transaction by squashing its edits and committing them as a single edit.
+	 * If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
+	 */
+	commit(): void;
+	/**
+	 * Close this transaction and revert the state of the tree to what it was before this transaction began.
+	 */
+	abort(): void;
+	/**
+	 * True if there is at least one transaction currently in progress on this view, otherwise false.
+	 */
+	isInProgress(): boolean;
+	/**
+	 * Provides events for changes in transaction progress.
+	 */
+	events: Listenable<TransactionEvents>;
+}
+
+export interface TransactionEvents {
+	/**
+	 * Raised just after a transaction has begun.
+	 * @remarks When this event fires, {@link Transactor.isInProgress} will be true because the transaction has already begun.
+	 */
+	started(): void;
+	/**
+	 * Raised just before a transaction is aborted.
+	 * @remarks When this event fires, {@link Transactor.isInProgress} will still be true because the transaction has not yet ended.
+	 */
+	aborting(): void;
+	/**
+	 * Raised just before a transaction is committed.
+	 * @remarks When this event fires, {@link Transactor.isInProgress} will still be true because the transaction has not yet ended.
+	 */
+	committing(): void;
+}
+
+/**
+ * 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.
+ * 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;
+
+/**
+ * A function that will be called when a transaction is popped from the {@link TransactionStack | stack}.
+ * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ */
+export type OnPop = (result: TransactionResult) => void;
+
+/**
+ * An implementation of {@link Transactor} that uses a stack to manage transactions.
+ * @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 #events = createEmitter<TransactionEvents>();
+	public get events(): Listenable<TransactionEvents> {
+		return this.#events;
+	}
+
+	#disposed = false;
+	public get disposed(): boolean {
+		return this.#disposed;
+	}
+
+	/**
+	 * Construct a new {@link TransactionStack}.
+	 * @param onPush - A {@link OnPush | function} that will be called when a transaction begins.
+	 */
+	public constructor(onPush?: () => OnPop | void) {
+		this.#onPush = onPush;
+	}
+
+	public isInProgress(): boolean {
+		this.ensureNotDisposed();
+		return this.#stack.length > 0;
+	}
+
+	public start(): void {
+		this.ensureNotDisposed();
+		this.#stack.push(this.#onPush?.());
+		this.#events.emit("started");
+	}
+
+	public commit(): void {
+		this.ensureNotDisposed();
+		if (!this.isInProgress()) {
+			throw new UsageError("No transaction to commit");
+		}
+		this.#events.emit("committing");
+		this.#stack.pop()?.(TransactionResult.Commit);
+	}
+
+	public abort(): void {
+		this.ensureNotDisposed();
+		if (!this.isInProgress()) {
+			throw new UsageError("No transaction to abort");
+		}
+		this.#events.emit("aborting");
+		this.#stack.pop()?.(TransactionResult.Abort);
+	}
+
+	public dispose(): void {
+		this.ensureNotDisposed();
+		while (this.isInProgress()) {
+			this.abort();
+		}
+		this.#disposed = true;
+	}
+
+	private ensureNotDisposed(): void {
+		if (this.disposed) {
+			throw new UsageError("Transactor is disposed");
+		}
+	}
+}

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

@@ -11,54 +11,60 @@ import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
  * Utility for producing an enriched commit out of multiple transaction steps
  */
 export class TransactionEnricher<TChange> {
-	private readonly rebaser: ChangeRebaser<TChange>;
-	private readonly enricher: ChangeEnricherReadonlyCheckout<TChange>;
-	private readonly transactionCommits: GraphCommit<TChange>[] = [];
+	readonly #rebaser: ChangeRebaser<TChange>;
+	readonly #enricher: ChangeEnricherReadonlyCheckout<TChange>;
+	#transactionCommits: GraphCommit<TChange>[] = [];
 	/**
 	 * The number of commits before the start of each active transaction scope.
 	 * For a stack of `n` transaction scopes, the array will contain `n` integers,
 	 * where the integer at index `i` is the number of commits made before the start of the `i`th transaction scope
 	 * (therefore, the first element in the array, if present, is always 0)
 	 */
-	private readonly transactionScopesStart: number[] = [];
+	readonly #transactionScopesStart: number[] = [];
 
 	public constructor(
 		rebaser: ChangeRebaser<TChange>,
 		enricher: ChangeEnricherReadonlyCheckout<TChange>,
 	) {
-		this.rebaser = rebaser;
-		this.enricher = enricher;
+		this.#rebaser = rebaser;
+		this.#enricher = enricher;
 	}
 
-	public startNewTransaction(): void {
-		this.transactionScopesStart.push(this.transactionCommits.length);
+	public isTransacting(): boolean {
+		return this.#transactionScopesStart.length !== 0;
 	}
 
-	public commitCurrentTransaction(): void {
-		const commitsCommitted = this.transactionScopesStart.pop();
+	public startTransaction(): void {
+		this.#transactionScopesStart.push(this.#transactionCommits.length);
+	}
+
+	/**
+	 * Commits the current transaction.
+	 * @returns If and only if the closed transaction was the outermost transaction, returns a function which can be used to compute the composed change for that transaction's commits.
+	 */
+	public commitTransaction(): ((revision: RevisionTag) => TChange) | undefined {
+		const commitsCommitted = this.#transactionScopesStart.pop();
 		assert(commitsCommitted !== undefined, 0x985 /* No transaction to commit */);
+		if (this.#transactionScopesStart.length === 0) {
+			const transactionCommits = this.#transactionCommits;
+			this.#transactionCommits = [];
+			return (revision: RevisionTag) =>
+				this.#rebaser.changeRevision(this.#rebaser.compose(transactionCommits), revision);
+		}
 	}
 
-	public abortCurrentTransaction(): void {
-		const scopeStart = this.transactionScopesStart.pop();
+	public abortTransaction(): void {
+		const scopeStart = this.#transactionScopesStart.pop();
 		assert(scopeStart !== undefined, 0x986 /* No transaction to abort */);
-		this.transactionCommits.length = scopeStart;
+		this.#transactionCommits.length = scopeStart;
 	}
 
 	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);
-		this.transactionCommits.push({ ...commit, change });
-	}
-
-	public getComposedChange(revision: RevisionTag): TChange {
-		assert(this.transactionScopesStart.length === 0, 0x988 /* Transaction not committed */);
-		const squashed = this.rebaser.compose(this.transactionCommits);
-		const tagged = this.rebaser.changeRevision(squashed, revision);
-		this.transactionCommits.length = 0;
-		return tagged;
+		const change = this.#enricher.updateChangeEnrichments(commit.change, commit.revision);
+		this.#transactionCommits.push({ ...commit, change });
 	}
 }

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

@@ -0,0 +1,64 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { TreeIndexKey } from "../../feature-libraries/index.js";
+import { FieldKind, type ImplicitFieldSchema } from "../schemaTypes.js";
+import type { TreeNode } from "../core/index.js";
+import { ObjectNodeSchema } from "../objectNodeTypes.js";
+import type { TreeView } from "./tree.js";
+import { walkFieldSchema } from "../walkFieldSchema.js";
+import { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
+
+/**
+ * An index that returns tree nodes given their associated identifiers.
+ *
+ * @alpha
+ */
+export type IdentifierIndex = SimpleTreeIndex<string, TreeNode>;
+
+function isStringKey(key: TreeIndexKey): key is string {
+	return typeof key === "string";
+}
+
+/**
+ * Creates an {@link IdentifierIndex} for a given {@link TreeView}.
+ *
+ * @alpha
+ */
+export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(
+	view: TreeView<TSchema>,
+): IdentifierIndex {
+	// For each node schema, find which field key the identifier field is under.
+	// This can be done easily because identifiers are their own field kinds.
+	const identifierFields = new Map<string, string>();
+	walkFieldSchema(view.schema, {
+		node: (schemus) => {
+			if (schemus instanceof ObjectNodeSchema) {
+				for (const [fieldKey, fieldSchema] of schemus.fields.entries()) {
+					if (fieldSchema.kind === FieldKind.Identifier) {
+						identifierFields.set(schemus.identifier, fieldKey);
+						break;
+					}
+				}
+			}
+		},
+	});
+
+	return createSimpleTreeIndex(
+		view,
+		(schemus) => identifierFields.get(schemus.identifier),
+		(nodes) => {
+			if (nodes.length > 1) {
+				throw new UsageError(
+					"cannot retrieve node from index: there are multiple nodes with the same identifier",
+				);
+			}
+
+			return nodes[0];
+		},
+		isStringKey,
+	);
+}

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

@@ -95,6 +95,11 @@ export type { EncodeOptions } from "./customTree.js";
 export { type ConciseTree, conciseFromCursor } from "./conciseTree.js";
 
 export { TreeBeta, type NodeChangedData, type TreeChangeEventsBeta } from "./treeApiBeta.js";
+export { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
+export {
+	createIdentifierIndex,
+	type IdentifierIndex,
+} from "./identifierIndex.js";
 
 export {
 	extractPersistedSchema,

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

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { oob, unreachableCase } from "@fluidframework/core-utils/internal";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { ValueSchema } from "../../core/index.js";
-import { getOrCreate, type Mutable } from "../../util/index.js";
+import { getOrCreate, hasSingle, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -42,9 +42,9 @@ export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
-	return allowedTypes.length === 1
+	return hasSingle(allowedTypes)
 		? {
-				...(allowedTypes[0] ?? oob()),
+				...allowedTypes[0],
 				$defs: definitions,
 			}
 		: {
@@ -96,8 +96,9 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 		allowedTypes.push(createSchemaRef(type));
 	});
 
-	const items: JsonFieldSchema =
-		allowedTypes.length === 1 ? (allowedTypes[0] ?? oob()) : { anyOf: allowedTypes };
+	const items: JsonFieldSchema = hasSingle(allowedTypes)
+		? allowedTypes[0]
+		: { anyOf: allowedTypes };
 
 	return {
 		type: "array",
@@ -142,12 +143,11 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 			allowedTypes.push(createSchemaRef(allowedType));
 		}
 
-		const output: Mutable<JsonFieldSchema> =
-			allowedTypes.length === 1
-				? (allowedTypes[0] ?? oob())
-				: {
-						anyOf: allowedTypes,
-					};
+		const output: Mutable<JsonFieldSchema> = hasSingle(allowedTypes)
+			? allowedTypes[0]
+			: {
+					anyOf: allowedTypes,
+				};
 
 		// Don't include "description" property at all if it's not present in the input.
 		if (value.metadata?.description !== undefined) {
@@ -178,12 +178,11 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 		type: "object",
 		_treeNodeSchemaKind: NodeKind.Map,
 		patternProperties: {
-			"^.*$":
-				allowedTypes.length === 1
-					? (allowedTypes[0] ?? oob())
-					: {
-							anyOf: allowedTypes,
-						},
+			"^.*$": hasSingle(allowedTypes)
+				? allowedTypes[0]
+				: {
+						anyOf: allowedTypes,
+					},
 		},
 	};
 }