@fluidframework/tree 2.83.0 → 2.90.0

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

@@ -17,7 +17,6 @@ import {
 	type TreeIndexNodes,
 	hasElement,
 	type TreeIndex,
-	type TreeIndexKey,
 	type KeyFinder,
 } from "../../feature-libraries/index.js";
 import type { SchematizingSimpleTreeView } from "../../shared-tree/index.js";
@@ -27,6 +26,7 @@ import {
 	type TreeNode,
 	type TreeNodeSchema,
 	type NodeFromSchema,
+	type TreeLeafValue,
 } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../fieldSchema.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -35,14 +35,16 @@ import type { TreeView } from "./tree.js";
 import { treeNodeApi } from "./treeNodeApi.js";
 
 /**
- * A {@link TreeIndex} that returns tree nodes given their associated keys.
- *
+ * Value that may be used as keys in a {@link TreeIndex}.
+ * @remarks
+ * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.
+ * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).
  * @alpha
  */
-export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;
+export type TreeIndexKey = TreeLeafValue;
 
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
@@ -52,7 +54,7 @@ export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey,
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -61,9 +63,10 @@ export function createSimpleTreeIndex<
 	indexer: (schema: TreeNodeSchema) => string | undefined,
 	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
@@ -74,7 +77,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -85,9 +88,10 @@ export function createSimpleTreeIndex<
 	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema: readonly TSchema[],
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
@@ -97,7 +101,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -106,9 +110,10 @@ export function createSimpleTreeIndex<
 	indexer: Map<TreeNodeSchema, string>,
 	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
@@ -119,7 +124,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -130,13 +135,14 @@ export function createSimpleTreeIndex<
 	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema: readonly TSchema[],
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -148,7 +154,7 @@ export function createSimpleTreeIndex<
 		| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema?: readonly TreeNodeSchema[],
-): SimpleTreeIndex<TKey, TValue> {
+): TreeIndex<TKey, TValue> {
 	const indexableSchemaMap = new Map<string, TreeNodeSchema>();
 	if (indexableSchema === undefined) {
 		walkFieldSchema(view.schema, {
@@ -214,7 +220,7 @@ export function createSimpleTreeIndex<
 
 	// all the type checking guarantees that we put nodes of the correct type in the index
 	// but it's not captured in the type system
-	return index as SimpleTreeIndex<TKey, TValue>;
+	return index as TreeIndex<TKey, TValue>;
 }
 
 function makeGenericKeyFinder<TKey extends TreeIndexKey>(

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

@@ -167,7 +167,7 @@ export function importCompatibilitySchemaSnapshot(
  * allowing for greater portability and easier testing.
  *
  * @input
- * @alpha
+ * @beta
  */
 export interface SnapshotFileSystem {
 	/**
@@ -245,7 +245,7 @@ export interface CombinedSchemaCompatibilityStatus {
 /**
  * The options for {@link snapshotSchemaCompatibility}.
  * @input
- * @alpha
+ * @beta
  */
 export interface SnapshotSchemaCompatibilityOptions {
 	/**
@@ -447,7 +447,7 @@ export interface SnapshotSchemaCompatibilityOptions {
  * import fs from "node:fs";
  * import path from "node:path";
  *
- * import { snapshotSchemaCompatibility } from "@fluidframework/tree/alpha";
+ * import { snapshotSchemaCompatibility } from "@fluidframework/tree/beta";
  *
  * // The TreeViewConfiguration the application uses, which contains the application's schema.
  * import { treeViewConfiguration } from "./schema.js";
@@ -485,7 +485,7 @@ export interface SnapshotSchemaCompatibilityOptions {
  * but it would be nice to better unify how we do that versioning and format validation with our codecs.
  *
  * See snapshotCompatibilityChecker.example.mts for the large example included above.
- * @alpha
+ * @beta
  */
 export function snapshotSchemaCompatibility(
 	options: SnapshotSchemaCompatibilityOptions,

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

@@ -49,22 +49,27 @@ export interface NoChangeConstraint {
 }
 
 /**
- * The status of the transaction callback in the {@link RunTransaction | RunTransaction} API.
+ * Contains a value returned from a transaction.
+ * @alpha
+ */
+export interface WithValue<TValue> {
+	/** The user-supplied value. */
+	value: TValue;
+}
+
+/**
+ * Contains a value and status returned from a user-supplied {@link TreeBranchAlpha.(runTransaction:1) | transaction callback}.
  * @alpha
  */
 export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = (
-	| {
+	| (WithValue<TSuccessValue> & {
 			/** Indicates that the transaction callback ran successfully. */
 			rollback?: false;
-			/** The user defined value when the transaction ran successfully. */
-			value: TSuccessValue;
-	  }
-	| {
+	  })
+	| (WithValue<TFailureValue> & {
 			/** 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 TransactionConstraintAlpha | constraints} that will be checked when the commit corresponding
@@ -77,8 +82,7 @@ export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = (
 };
 
 /**
- * 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
+ * The result of a {@link TreeBranchAlpha.(runTransaction:2) | transaction} that doesn't return a value.
  * @alpha
  */
 export type VoidTransactionCallbackStatus = Omit<
@@ -87,25 +91,21 @@ export type VoidTransactionCallbackStatus = Omit<
 >;
 
 /**
- * The result of the {@link RunTransaction | RunTransaction} API when it was successful.
+ * The result of a {@link TreeBranchAlpha.(runTransaction:1) | transaction} that completed successfully.
  * @alpha
  */
-export interface TransactionResultSuccess<TSuccessValue> {
-	/** Indicates that the transaction was successful. */
+export interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSuccessValue> {
+	/** The success flag for a transaction that completed without being {@link TransactionCallbackStatus | rolled back}. */
 	success: true;
-	/** The user defined value when the transaction was successful. */
-	value: TSuccessValue;
 }
 
 /**
- * The result of the {@link RunTransaction | RunTransaction} API when it failed.
+ * The result of a {@link TreeBranchAlpha.(runTransaction:1) | transaction} that was rolled back.
  * @alpha
  */
-export interface TransactionResultFailed<TFailureValue> {
-	/** Indicates that the transaction failed. */
+export interface TransactionResultFailed<TFailureValue> extends WithValue<TFailureValue> {
+	/** The failure flag for a transaction that was {@link TransactionCallbackStatus | rolled back}. */
 	success: false;
-	/** The user defined value when the transaction failed. */
-	value: TFailureValue;
 }
 
 /**
@@ -133,17 +133,15 @@ export type TransactionResult =
 export interface RunTransactionParams {
 	/**
 	 * An optional list of {@link TransactionConstraintAlpha | constraints} that are checked just before the transaction begins.
+	 * @remarks
 	 * 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.
+	 * 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 TransactionConstraintAlpha[];
 	/**
 	 * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).
-	 *
 	 * @remarks
-	 * This label is associated with the commit produced by this transaction, and is surfaced through the
-	 * `label` property of {@link ChangeMetadata} in the `commitApplied` or `changed` event.
+	 * If this transaction is applied to a {@link TreeBranchAlpha | branch}, the label will be available in the {@link LocalChangeMetadata.label | metadata} of the {@link TreeBranchEvents.changed | `changed`} event.
 	 *
 	 * If there is a nested transaction, only the outermost transaction label will be used.
 	 */

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

@@ -11,12 +11,18 @@ import type {
 	RevertibleAlphaFactory,
 	RevertibleFactory,
 } from "../../core/index.js";
+// This is referenced by doc comments.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { TreeStatus } from "../../feature-libraries/index.js";
 import type {
 	// This is referenced by doc comments.
 	// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
 	TreeAlpha,
 } from "../../shared-tree/index.js";
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
+// This is referenced by doc comments.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Unhydrated } from "../core/index.js";
 import type {
 	ImplicitFieldSchema,
 	InsertableField,
@@ -35,6 +41,7 @@ import type {
 	TransactionResult,
 	TransactionResultExt,
 	VoidTransactionCallbackStatus,
+	WithValue,
 } from "./transactionTypes.js";
 import type { VerboseTree } from "./verboseTree.js";
 
@@ -175,6 +182,80 @@ export interface TreeBranch extends IDisposable {
 	dispose(error?: Error): void;
 }
 
+/**
+ * Provides additional APIs that may be used to interact with a tree node or a tree node's SharedTree.
+ * @alpha
+ */
+export interface TreeContextAlpha {
+	/**
+	 * Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible.
+	 * @param transaction - A callback run during the transaction to perform user-supplied operations.
+	 * It may optionally return a {@link WithValue | value }, which will be returned by the `runTransaction` call.
+	 * @param params - Optional {@link RunTransactionParams | parameters} for the transaction.
+	 * @returns A {@link TransactionResultExt | value } indicating whether or not the transaction succeeded, and containing the value returned by `transaction`.
+	 * @remarks
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes from a remote client can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 *
+	 * {@link (TreeBeta:interface).on | Change events } will be emitted for changed nodes on this client _as each edit happens_, just as they would be if the changes were made outside of a transaction.
+	 * Any other/future clients or contexts will process the transaction "squashed", i.e. they will apply its changes all at once, emitting only a single event per node (even if that node was edited multiple times in the transaction).
+	 * Edits to the tree are not permitted within these event callbacks, therefore no other local changes from this client will be interleaved with the changes in this transaction.
+	 *
+	 * Using a transaction has the following additional consequences:
+	 *
+	 * - If {@link Revertible | reverted } (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * Only the "outermost" transaction commits a change to the synchronized tree state and therefore only the outermost transaction can be reverted.
+	 * If a transaction is started and completed while another transaction is already in progress, then the inner transaction will be reverted together with the outer transaction.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * `runTransaction` may be invoked on the context of a {@link TreeStatus.InDocument | hydrated } or {@link Unhydrated | unhydrated } node.
+	 * Use {@link TreeContextAlpha.isBranch | isBranch() } to check whether this context is associated with a branch and gain {@link TreeBranchAlpha.(runTransaction:1) | access to more transaction capabilities} if so.
+	 */
+	runTransaction<TValue>(
+		transaction: () => WithValue<TValue>,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TValue, TValue>;
+
+	/** An overload of {@link TreeContextAlpha.(runTransaction:1) | runTransaction } which does not return a value. */
+	runTransaction(transaction: () => void, params?: RunTransactionParams): TransactionResult;
+
+	/**
+	 * An asynchronous version of {@link TreeContextAlpha.(runTransaction:1) | runTransaction}.
+	 * @remarks
+	 * As with synchronous transactions, all of the changes in an asynchronous transaction are treated as a unit.
+	 * Therefore, no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
+	 *
+	 * Unlike with synchronous transactions, it is possible that other changes (e.g. from a remote client) may be applied to the branch while this transaction is in progress.
+	 * Those other changes will be not be reflected on the branch until after this transaction completes, at which point the transaction changes will be applied after those other changes.
+	 *
+	 * An asynchronous transaction may not be started while any other transaction is in progress in this context.
+	 */
+	runTransactionAsync<TValue>(
+		transaction: () => Promise<WithValue<TValue>>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResultExt<TValue, TValue>>;
+
+	/** An overload of {@link TreeContextAlpha.(runTransactionAsync:1) | runTransactionAsync } which does not return a value. */
+	runTransactionAsync(
+		transaction: () => Promise<void>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResult>;
+
+	/**
+	 * True if this context is associated with a {@link TreeBranchAlpha | branch} and false if it is associated with an {@link Unhydrated | unhydrated } node.
+	 * @remarks If this returns true, the context can be safely inferred or cast to {@link TreeBranchAlpha} to access additional branch-specific APIs.
+	 * @example
+	 * ```typescript
+	 * const context = tree.context(someNode);
+	 * if (context.isBranch()) {
+	 *   assert(context.hasRootSchema(MySchema)) // `hasRootSchema` is a method on TreeBranchAlpha, so this is only accessible if `context` is a branch context.
+	 *   context.root.foo = "bar"; // Edit the root of the SharedTree that `someNode` belongs to.
+	 * }
+	 * ```
+	 */
+	isBranch(): this is TreeBranchAlpha;
+}
+
 /**
  * {@link TreeBranch} with alpha-level APIs.
  * @remarks
@@ -183,7 +264,7 @@ export interface TreeBranch extends IDisposable {
  * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranchAlpha.hasRootSchema | hasRootSchema()}.
  * @sealed @alpha
  */
-export interface TreeBranchAlpha extends TreeBranch {
+export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 	/**
 	 * Events for the branch
 	 */
@@ -211,75 +292,18 @@ export interface TreeBranchAlpha extends TreeBranch {
 	fork(): TreeBranchAlpha;
 
 	/**
-	 * Run a synchronous transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction.
-	 * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.
-	 * It includes a "rollback" property which may be returned as true at any point during the transaction. This will
-	 * abort the transaction and discard any changes it made so far.
-	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
-	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
-	 *
-	 * - A "success" flag indicating whether the transaction was successful or not.
-	 * - The success or failure value as returned by the transaction function.
-	 *
+	 * {@link TreeContextAlpha.(runTransaction:1) | Run a transaction} on a branch of the SharedTree.
+	 * @param transaction - The function to run as the body of the transaction, which may optionally return a {@link TransactionCallbackStatus | value or rollback signal}.
 	 * @remarks
-	 * This API will throw an error if the constraints are not met or something unexpected happens.
-	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
-	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
-	 * However, using a transaction has the following additional consequences:
-	 *
-	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * Local change events will be emitted for each change as the transaction is being applied.
-	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
-	 *
-	 * Nested transactions:
-	 * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` call. That will have slightly different behavior:
-	 *
-	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
-	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
-	 * for the outermost transaction which includes all inner transactions.
-	 * - Undo will undo the outermost transaction and all inner transactions.
-	 * - If a label is provided in the params, only the label for the outermost transaction will be used. All other labels will be ignored.
+	 * If the transaction is rolled back, a corresponding {@link TreeBranchEvents.changed | `changed`} event will also be emitted for the rollback.
 	 */
 	runTransaction<TSuccessValue, TFailureValue>(
 		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
 		params?: RunTransactionParams,
 	): TransactionResultExt<TSuccessValue, TFailureValue>;
+
 	/**
-	 * Run a synchronous transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction. It may return the following:
-	 *
-	 * - Nothing to indicate that the body of the transaction has successfully run.
-	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
-	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
-	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
-	 *
-	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
-	 * transaction was successful or not.
-	 *
-	 * @remarks
-	 * This API will throw an error if the constraints are not met or something unexpected happens.
-	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
-	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
-	 * However, using a transaction has the following additional consequences:
-	 *
-	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * Local change events will be emitted for each change as the transaction is being applied.
-	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
-	 *
-	 * Nested transactions:
-	 * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` call. That will have slightly different behavior:
-	 *
-	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
-	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
-	 * for the outermost transaction which includes all inner transactions.
-	 * - Undo will undo the outermost transaction and all inner transactions.
+	 * An overload of {@link TreeBranchAlpha.(runTransaction:1) | runTransaction } which does not return a value.
 	 */
 	runTransaction(
 		transaction: () => VoidTransactionCallbackStatus | void,
@@ -287,80 +311,17 @@ export interface TreeBranchAlpha extends TreeBranch {
 	): TransactionResult;
 
 	/**
-	 * Run an asynchronous transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction.
-	 * It should return a promise that resolves to a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.
-	 * It includes a "rollback" property which may be returned as true at any point during the transaction. This will
-	 * abort the transaction and discard any changes it made so far.
-	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
-	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A promise that resolves to a result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
-	 *
-	 * - A "success" flag indicating whether the transaction was successful or not.
-	 * - The success or failure value as returned by the transaction function.
-	 *
-	 * The promise will reject if the constraints are not met or something unexpected happens.
-	 *
-	 * @remarks
-	 * As with synchronous transactions, using an asynchronous transaction has the following consequences:
-	 * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
-	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:
-	 * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.
-	 * These other changes will be not be reflected on the branch until after this transaction completes,
-	 * at which point the transaction changes will be applied after these other changes.
-	 *
-	 * Local change events will be emitted for each change as the transaction is being applied.
-	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
-	 *
-	 * Nested transactions:
-	 * This API can be called from within the transaction callback of another `runTransactionAsync` call. That will have slightly different behavior:
-	 *
-	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
-	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
-	 * for the outermost transaction which includes all inner transactions.
-	 * - Undo will undo the outermost transaction and all inner transactions.
+	 * An asynchronous version of {@link TreeBranchAlpha.(runTransaction:1) | runTransaction}.
+	 * @remarks See {@link TreeContextAlpha.(runTransactionAsync:1) | runTransactionAsync} for additional information about asynchronous transactions.
 	 */
+
 	runTransactionAsync<TSuccessValue, TFailureValue>(
 		transaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,
 		params?: RunTransactionParams,
 	): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;
+
 	/**
-	 * Run an asynchronous transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction. It must return a promise that can resolve to any of the following:
-	 *
-	 * - Nothing to indicate that the body of the transaction has successfully run.
-	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
-	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
-	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
-	 *
-	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A promise that resolves to a result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
-	 * transaction was successful or not. The promise will reject if the constraints are not met or something unexpected happens.
-	 *
-	 * @remarks
-	 * As with synchronous transactions, using an asynchronous transaction has the following consequences:
-	 * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
-	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:
-	 * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.
-	 * These other changes will be not be reflected on the branch until after this transaction completes,
-	 * at which point the transaction changes will be applied after these other changes.
-	 *
-	 * Local change events will be emitted for each change as the transaction is being applied.
-	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
-	 *
-	 * Nested transactions:
-	 * This API can be called from within the transaction callback of another `runTransactionAsync` call. That will have slightly different behavior:
-	 *
-	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
-	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
-	 * for the outermost transaction which includes all inner transactions.
-	 * - Undo will undo the outermost transaction and all inner transactions.
+	 * An overload of {@link TreeBranchAlpha.(runTransactionAsync:1) | runTransactionAsync } which does not return a value.
 	 */
 	runTransactionAsync(
 		transaction: () => Promise<VoidTransactionCallbackStatus | void>,

package/src/simple-tree/index.ts

@@ -95,10 +95,10 @@ export {
 	importConcise,
 	TreeBeta,
 	type TreeChangeEventsBeta,
-	type SimpleTreeIndex,
 	type IdentifierIndex,
-	createSimpleTreeIndex,
+	createTreeIndex,
 	createIdentifierIndex,
+	type TreeIndexKey,
 	type DirtyTreeStatus,
 	trackDirtyNodes,
 	type DirtyTreeMap,
@@ -201,6 +201,8 @@ export {
 	type SnapshotFileSystem,
 	type SnapshotSchemaCompatibilityOptions,
 	createCustomizedFluidFrameworkScopedFactory,
+	type TreeContextAlpha,
+	type WithValue,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,