@fluidframework/tree 2.12.0 → 2.13.0

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

@@ -19,6 +19,7 @@ import {
 	CrossFieldTarget,
 	type NodeId,
 	type CrossFieldKeyRange,
+	type NestedChangesIndices,
 } from "../modular-schema/index.js";
 
 import type {
@@ -61,15 +62,25 @@ export function createEmpty(): Changeset {
 	return [];
 }
 
-export function getNestedChanges(change: Changeset): [NodeId, number | undefined][] {
-	const output: [NodeId, number | undefined][] = [];
-	let index = 0;
-	for (const { changes, cellId, count } of change) {
+export function getNestedChanges(change: Changeset): NestedChangesIndices {
+	const output: NestedChangesIndices = [];
+	let inputIndex = 0;
+	let outputIndex = 0;
+	for (const mark of change) {
+		const { changes, count } = mark;
 		if (changes !== undefined) {
-			output.push([changes, cellId === undefined ? index : undefined]);
+			output.push([
+				changes,
+				!areInputCellsEmpty(mark) ? inputIndex : undefined /* inputIndex */,
+				!areOutputCellsEmpty(mark) ? outputIndex : undefined /* outputIndex */,
+			]);
+		}
+		if (!areInputCellsEmpty(mark)) {
+			inputIndex += count;
 		}
-		if (cellId === undefined) {
-			index += count;
+
+		if (!areOutputCellsEmpty(mark)) {
+			outputIndex += count;
 		}
 	}
 	return output;

package/src/index.ts

@@ -48,6 +48,13 @@ export {
 	type ViewContent,
 	TreeAlpha,
 	independentView,
+	type RunTransactionParams,
+	type VoidTransactionCallbackStatus,
+	type TransactionCallbackStatus,
+	type TransactionResult,
+	type TransactionResultExt,
+	type TransactionResultSuccess,
+	type TransactionResultFailed,
 } from "./shared-tree/index.js";
 
 export {
@@ -64,6 +71,8 @@ export {
 	type TreeView,
 	type TreeViewEvents,
 	SchemaFactory,
+	SchemaFactoryAlpha,
+	type SchemaFactoryObjectOptions,
 	type ImplicitFieldSchema,
 	type TreeFieldFromImplicitField,
 	type TreeChangeEvents,
@@ -175,6 +184,8 @@ export {
 	type TreeBranch,
 	type TreeBranchEvents,
 	asTreeViewAlpha,
+	type NodeSchemaOptions,
+	type NodeSchemaMetadata,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

package/src/packageVersion.ts

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

package/src/shared-tree/index.ts

@@ -40,11 +40,21 @@ export type { ISharedTreeEditor, ISchemaEditor } from "./sharedTreeEditBuilder.j
 export {
 	treeApi as Tree,
 	type TreeApi,
+	type RunTransaction,
+} from "./treeApi.js";
+
+export {
 	type TransactionConstraint,
 	type NodeInDocumentConstraint,
-	type RunTransaction,
+	type RunTransactionParams,
+	type VoidTransactionCallbackStatus,
+	type TransactionCallbackStatus,
+	type TransactionResult,
+	type TransactionResultExt,
+	type TransactionResultSuccess,
+	type TransactionResultFailed,
 	rollback,
-} from "./treeApi.js";
+} from "./transactionTypes.js";
 
 export { TreeAlpha } from "./treeApiAlpha.js";
 

package/src/shared-tree/schematizingTreeView.ts

@@ -9,7 +9,7 @@ import type {
 	Listenable,
 } from "@fluidframework/core-interfaces/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { AllowedUpdateType, anchorSlot, type SchemaPolicy } from "../core/index.js";
@@ -19,6 +19,7 @@ import {
 	ContextSlot,
 	cursorForMapTreeNode,
 	type FullSchemaPolicy,
+	TreeStatus,
 } from "../feature-libraries/index.js";
 import {
 	type FieldSchema,
@@ -43,6 +44,8 @@ import {
 	type UnsafeUnknownSchema,
 	type TreeBranch,
 	type TreeBranchEvents,
+	getOrCreateInnerNode,
+	getKernel,
 } from "../simple-tree/index.js";
 import { Breakable, breakingClass, disposeSymbol, type WithBreakable } from "../util/index.js";
 
@@ -55,6 +58,14 @@ import {
 	areImplicitFieldSchemaEqual,
 	createUnknownOptionalFieldPolicy,
 } from "../simple-tree/index.js";
+import type {
+	VoidTransactionCallbackStatus,
+	TransactionCallbackStatus,
+	TransactionResult,
+	TransactionResultExt,
+	RunTransactionParams,
+	TransactionConstraint,
+} from "./transactionTypes.js";
 
 /**
  * Creating multiple tree views from the same checkout is not supported. This slot is used to detect if one already
@@ -213,6 +224,84 @@ export class SchematizingSimpleTreeView<
 		return this.view;
 	}
 
+	/**
+	 * {@inheritDoc @fluidframework/shared-tree#TreeViewAlpha.runTransaction}
+	 */
+	public runTransaction<TSuccessValue, TFailureValue>(
+		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TSuccessValue, TFailureValue>;
+	/**
+	 * {@inheritDoc @fluidframework/shared-tree#TreeViewAlpha.runTransaction}
+	 */
+	public runTransaction(
+		transaction: () => VoidTransactionCallbackStatus | void,
+		params?: RunTransactionParams,
+	): TransactionResult;
+	public runTransaction<TSuccessValue, TFailureValue>(
+		transaction: () =>
+			| TransactionCallbackStatus<TSuccessValue, TFailureValue>
+			| VoidTransactionCallbackStatus
+			| void,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
+		const addConstraints = (
+			constraintsOnRevert: boolean,
+			constraints: readonly TransactionConstraint[] = [],
+		): void => {
+			for (const constraint of constraints) {
+				switch (constraint.type) {
+					case "nodeInDocument": {
+						const node = getOrCreateInnerNode(constraint.node);
+						const nodeStatus = getKernel(constraint.node).getStatus();
+						if (nodeStatus !== TreeStatus.InDocument) {
+							const revertText = constraintsOnRevert ? " on revert" : "";
+							throw new UsageError(
+								`Attempted to add a "nodeInDocument" constraint${revertText}, but the node is not currently in the document. Node status: ${nodeStatus}`,
+							);
+						}
+						if (constraintsOnRevert) {
+							this.checkout.editor.addNodeExistsConstraintOnRevert(node.anchorNode);
+						} else {
+							this.checkout.editor.addNodeExistsConstraint(node.anchorNode);
+						}
+						break;
+					}
+					default:
+						unreachableCase(constraint.type);
+				}
+			}
+		};
+
+		this.checkout.transaction.start();
+
+		// Validate preconditions before running the transaction callback.
+		addConstraints(false /* constraintsOnRevert */, params?.preconditions);
+		const transactionCallbackStatus = transaction();
+		const rollback = transactionCallbackStatus?.rollback;
+		const value = (
+			transactionCallbackStatus as TransactionCallbackStatus<TSuccessValue, TFailureValue>
+		)?.value;
+
+		if (rollback === true) {
+			this.checkout.transaction.abort();
+			return value !== undefined
+				? { success: false, value: value as TFailureValue }
+				: { success: false };
+		}
+
+		// Validate preconditions on revert after running the transaction callback and was successful.
+		addConstraints(
+			true /* constraintsOnRevert */,
+			transactionCallbackStatus?.preconditionsOnRevert,
+		);
+
+		this.checkout.transaction.commit();
+		return value !== undefined
+			? { success: true, value: value as TSuccessValue }
+			: { success: true };
+	}
+
 	private ensureUndisposed(): void {
 		if (this.disposed) {
 			this.failDisposed();
@@ -383,7 +472,7 @@ export class SchematizingSimpleTreeView<
 
 	// #region Branching
 
-	public fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TRootSchema> {
+	public fork(): ReturnType<TreeBranch["fork"]> & SchematizingSimpleTreeView<TRootSchema> {
 		return this.checkout.branch().viewWith(this.config);
 	}
 

package/src/shared-tree/sharedTree.ts

@@ -229,7 +229,7 @@ export class SharedTree
 		id: string,
 		runtime: IFluidDataStoreRuntime,
 		attributes: IChannelAttributes,
-		optionsParam: SharedTreeOptions,
+		optionsParam: SharedTreeOptionsInternal,
 		telemetryContextPrefix: string = "fluid_sharedTree_",
 	) {
 		if (runtime.idCompressor === undefined) {
@@ -333,6 +333,7 @@ export class SharedTree
 				chunkCompressionStrategy: options.treeEncodeType,
 				logger: this.logger,
 				breaker: this.breaker,
+				disposeForksAfterTransaction: options.disposeForksAfterTransaction,
 			},
 		);
 
@@ -459,7 +460,7 @@ export class SharedTree
 	): void {
 		assert(
 			!this.checkout.transaction.isInProgress(),
-			"Cannot submit a commit while a transaction is in progress",
+			0xaa6 /* Cannot submit a commit while a transaction is in progress */,
 		);
 		if (isResubmit) {
 			return super.submitCommit(commit, schemaAndPolicy, isResubmit);
@@ -555,6 +556,9 @@ export type SharedTreeOptions = Partial<ICodecOptions> &
 	Partial<SharedTreeFormatOptions> &
 	ForestOptions;
 
+export interface SharedTreeOptionsInternal extends SharedTreeOptions {
+	disposeForksAfterTransaction?: boolean;
+}
 /**
  * Configuration options for SharedTree's internal tree storage.
  * @alpha
@@ -609,11 +613,12 @@ export enum ForestType {
 	Expensive = 2,
 }
 
-export const defaultSharedTreeOptions: Required<SharedTreeOptions> = {
+export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	jsonValidator: noopValidator,
 	forest: ForestType.Reference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
+	disposeForksAfterTransaction: true,
 };
 
 /**
@@ -628,7 +633,7 @@ export class SharedTreeFactory implements IChannelFactory<ISharedTree> {
 		packageVersion: "0.0.0",
 	};
 
-	public constructor(private readonly options: SharedTreeOptions = {}) {}
+	public constructor(private readonly options: SharedTreeOptionsInternal = {}) {}
 
 	public async load(
 		runtime: IFluidDataStoreRuntime,

package/src/shared-tree/transactionTypes.ts

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TreeNode } from "../simple-tree/index.js";
+
+/**
+ * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should "roll back".
+ * @public
+ */
+export const rollback = Symbol("SharedTree Transaction Rollback");
+
+/**
+ * A requirement for a SharedTree transaction to succeed.
+ * @remarks Transaction constraints are useful for validating that the state of the tree meets some requirement when a transaction runs.
+ * In general, when running a transaction a client can validate their tree state in whatever way they wish and decide to either proceed with the transaction or not.
+ * However, they cannot know what the tree state will be when the transaction is _sequenced_.
+ * There may have been any number of edits from other clients that get sequenced before the transaction is eventually sequenced.
+ * Constraints provide a way to validate the tree state after the transaction has been sequenced and abort the transaction if the constraints are not met.
+ * All clients will validate the constraints of a transaction when it is sequenced, so all clients will agree on whether the transaction succeeds or not.
+ * @public
+ */
+export type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here
+
+/**
+ * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.
+ * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as "existing".
+ * @public
+ */
+export interface NodeInDocumentConstraint {
+	readonly type: "nodeInDocument";
+	readonly node: TreeNode;
+}
+
+/**
+ * The status of the transaction callback in the {@link RunTransaction | RunTransaction} API.
+ * @alpha
+ */
+export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = (
+	| {
+			/** Indicates that the transaction callback ran successfully. */
+			rollback?: false;
+			/** The user defined value when the transaction ran successfully. */
+			value: TSuccessValue;
+	  }
+	| {
+			/** Indicates that the transaction callback failed and the transaction should be rolled back. */
+			rollback: true;
+			/** The user defined value when the transaction failed. */
+			value: TFailureValue;
+	  }
+) & {
+	/**
+	 * An optional list of {@link TransactionConstraint | constraints} that will be checked when the commit corresponding
+	 * to this transaction is reverted. If any of these constraints are not met when the revert is being applied either
+	 * locally or on remote clients, the revert will be ignored.
+	 * These constraints must also be met at the time they are first introduced. If they are not met after the transaction
+	 * callback returns, then `runTransaction` (which invokes the transaction callback) will throw a `UsageError`.
+	 */
+	preconditionsOnRevert?: readonly TransactionConstraint[];
+};
+
+/**
+ * The status of a the transaction callback in the {@link RunTransaction | RunTransaction} API where the transaction doesn't
+ * need to return a value. This is the same as {@link TransactionCallbackStatus} but with the `value` field omitted. This
+ * @alpha
+ */
+export type VoidTransactionCallbackStatus = Omit<
+	TransactionCallbackStatus<unknown, unknown>,
+	"value"
+>;
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API when it was successful.
+ * @alpha
+ */
+export interface TransactionResultSuccess<TSuccessValue> {
+	/** Indicates that the transaction was successful. */
+	success: true;
+	/** The user defined value when the transaction was successful. */
+	value: TSuccessValue;
+}
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API when it failed.
+ * @alpha
+ */
+export interface TransactionResultFailed<TFailureValue> {
+	/** Indicates that the transaction failed. */
+	success: false;
+	/** The user defined value when the transaction failed. */
+	value: TFailureValue;
+}
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API.
+ * @alpha
+ */
+export type TransactionResultExt<TSuccessValue, TFailureValue> =
+	| TransactionResultSuccess<TSuccessValue>
+	| TransactionResultFailed<TFailureValue>;
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API. This is the same as {@link TransactionResultExt}
+ * but with the `value` field omitted. This is useful when the transaction callback doesn't need to return a value.
+ * @alpha
+ */
+export type TransactionResult =
+	| Omit<TransactionResultSuccess<unknown>, "value">
+	| Omit<TransactionResultFailed<unknown>, "value">;
+
+/**
+ * The parameters for the {@link RunTransaction | RunTransaction} API.
+ * @alpha
+ */
+export interface RunTransactionParams {
+	/**
+	 * An optional list of {@link TransactionConstraint | constraints} that are checked just before the transaction begins.
+	 * If any of the constraints are not met when `runTransaction` is called, an error will be thrown.
+	 * If any of the constraints are not met after the transaction has been ordered by the service, it will be rolled back on
+	 * this client and ignored by all other clients.
+	 */
+	readonly preconditions?: readonly TransactionConstraint[];
+}

package/src/shared-tree/treeApi.ts

@@ -19,12 +19,7 @@ import {
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
 import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
-
-/**
- * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should "roll back".
- * @public
- */
-export const rollback = Symbol("SharedTree Transaction Rollback");
+import { rollback, type TransactionConstraint } from "./transactionTypes.js";
 
 /**
  * A function which runs a transaction in a SharedTree.
@@ -380,28 +375,6 @@ export const treeApi: TreeApi = {
 	},
 };
 
-/**
- * A requirement for a SharedTree transaction to succeed.
- * @remarks Transaction constraints are useful for validating that the state of the tree meets some requirement when a transaction runs.
- * In general, when running a transaction a client can validate their tree state in whatever way they wish and decide to either proceed with the transaction or not.
- * However, they cannot know what the tree state will be when the transaction is _sequenced_.
- * There may have been any number of edits from other clients that get sequenced before the transaction is eventually sequenced.
- * Constraints provide a way to validate the tree state after the transaction has been sequenced and abort the transaction if the constraints are not met.
- * All clients will validate the constraints of a transaction when it is sequenced, so all clients will agree on whether the transaction succeeds or not.
- * @public
- */
-export type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here
-
-/**
- * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.
- * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as "existing".
- * @public
- */
-export interface NodeInDocumentConstraint {
-	readonly type: "nodeInDocument";
-	readonly node: TreeNode;
-}
-
 // TODO: Add more constraint types here
 
 /** Creates a copy of `runTransaction` with the `rollback` property added so as to satisfy the `RunTransaction` interface. */