@fluidframework/tree 2.103.0 → 2.111.0

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

@@ -11,17 +11,14 @@ import type {
 	RevertibleAlphaFactory,
 	RevertibleFactory,
 } from "../../core/index.js";
-// This is referenced by doc comments.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- This is referenced by doc comments.
 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
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports -- This is referenced by doc comments.
 	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
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- This is referenced by doc comments.
 import type { Unhydrated } from "../core/index.js";
 import type {
 	ImplicitFieldSchema,
@@ -36,11 +33,14 @@ import type { UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
 
 import type { TreeViewConfiguration } from "./configuration.js";
 import type {
-	RunTransactionParams,
-	TransactionCallbackStatus,
-	TransactionResult,
-	TransactionResultExt,
-	VoidTransactionCallbackStatus,
+	RunTransactionParamsAlpha,
+	RunTransactionParamsBeta,
+	TransactionCallbackStatusAlpha,
+	TransactionCallbackStatusBeta,
+	TransactionVoidResult,
+	TransactionValueResult,
+	VoidTransactionCallbackStatusAlpha,
+	VoidTransactionCallbackStatusBeta,
 	WithValue,
 } from "./transactionTypes.js";
 import type { VerboseTree } from "./verboseTree.js";
@@ -193,8 +193,8 @@ 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`.
+	 * @param params - Optional {@link RunTransactionParamsAlpha | parameters} for the transaction.
+	 * @returns A {@link TransactionValueResult | 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.
@@ -215,11 +215,20 @@ export interface TreeContextAlpha {
 	 */
 	runTransaction<TValue>(
 		transaction: () => WithValue<TValue>,
-		params?: RunTransactionParams,
-	): TransactionResultExt<TValue, TValue>;
+		params?: RunTransactionParamsAlpha,
+	): TransactionValueResult<TValue, TValue>;
 
-	/** An overload of {@link TreeContextAlpha.(runTransaction:1) | runTransaction } which does not return a value. */
-	runTransaction(transaction: () => void, params?: RunTransactionParams): TransactionResult;
+	/**
+	 * An overload of {@link TreeContextAlpha.(runTransaction:1) | runTransaction } which does not return a value.
+	 *
+	 * @privateRemarks
+	 * TODO: Consider updating these methods to avoid the need for overloads.
+	 * See {@link TreeViewBeta.runTransaction} for an example of how to do this.
+	 */
+	runTransaction(
+		transaction: () => void,
+		params?: RunTransactionParamsAlpha,
+	): TransactionVoidResult;
 
 	/**
 	 * An asynchronous version of {@link TreeContextAlpha.(runTransaction:1) | runTransaction}.
@@ -234,14 +243,20 @@ export interface TreeContextAlpha {
 	 */
 	runTransactionAsync<TValue>(
 		transaction: () => Promise<WithValue<TValue>>,
-		params?: RunTransactionParams,
-	): Promise<TransactionResultExt<TValue, TValue>>;
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionValueResult<TValue, TValue>>;
 
-	/** An overload of {@link TreeContextAlpha.(runTransactionAsync:1) | runTransactionAsync } which does not return a value. */
+	/**
+	 * An overload of {@link TreeContextAlpha.(runTransactionAsync:1) | runTransactionAsync } which does not return a value.
+	 *
+	 * @privateRemarks
+	 * TODO: Consider updating these methods to avoid the need for overloads.
+	 * See {@link TreeViewBeta.runTransactionAsync} for an example of how to do this.
+	 */
 	runTransactionAsync(
 		transaction: () => Promise<void>,
-		params?: RunTransactionParams,
-	): Promise<TransactionResult>;
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionVoidResult>;
 
 	/**
 	 * True if this context is associated with a {@link TreeBranchAlpha | branch} and false if it is associated with an {@link Unhydrated | unhydrated } node.
@@ -295,22 +310,26 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 
 	/**
 	 * {@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}.
+	 * @param transaction - The function to run as the body of the transaction, which may optionally return a {@link TransactionCallbackStatusAlpha | value or rollback signal}.
 	 * @remarks
 	 * 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>;
+		transaction: () => TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>,
+		params?: RunTransactionParamsAlpha,
+	): TransactionValueResult<TSuccessValue, TFailureValue>;
 
 	/**
 	 * An overload of {@link TreeBranchAlpha.(runTransaction:1) | runTransaction } which does not return a value.
+	 *
+	 * @privateRemarks
+	 * TODO: Consider updating these methods to avoid the need for overloads.
+	 * See {@link TreeViewBeta.runTransaction} for an example of how to do this.
 	 */
 	runTransaction(
-		transaction: () => VoidTransactionCallbackStatus | void,
-		params?: RunTransactionParams,
-	): TransactionResult;
+		transaction: () => VoidTransactionCallbackStatusAlpha | void,
+		params?: RunTransactionParamsAlpha,
+	): TransactionVoidResult;
 
 	/**
 	 * An asynchronous version of {@link TreeBranchAlpha.(runTransaction:1) | runTransaction}.
@@ -318,17 +337,21 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 	 */
 
 	runTransactionAsync<TSuccessValue, TFailureValue>(
-		transaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,
-		params?: RunTransactionParams,
-	): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;
+		transaction: () => Promise<TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>>,
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionValueResult<TSuccessValue, TFailureValue>>;
 
 	/**
 	 * An overload of {@link TreeBranchAlpha.(runTransactionAsync:1) | runTransactionAsync } which does not return a value.
+	 *
+	 * @privateRemarks
+	 * TODO: Consider updating these methods to avoid the need for overloads.
+	 * See {@link TreeViewBeta.runTransactionAsync} for an example of how to do this.
 	 */
 	runTransactionAsync(
-		transaction: () => Promise<VoidTransactionCallbackStatus | void>,
-		params?: RunTransactionParams,
-	): Promise<TransactionResult>;
+		transaction: () => Promise<VoidTransactionCallbackStatusAlpha | void>,
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionVoidResult>;
 
 	/**
 	 * Apply a serialized change to this branch.
@@ -342,6 +365,17 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 	 * Update the tests and docs to match when that is done.
 	 */
 	applyChange(change: JsonCompatibleReadOnly): void;
+
+	/**
+	 * Determines if there are changes on the given branch that are not present on this branch.
+	 * @param branch - The branch to compare to.
+	 *
+	 * The new edits, if any, can be applied to this branch by {@link TreeBranch.rebaseOnto | rebasing this branch onto the given branch}
+	 * or by {@link TreeBranch.merge | merging the given branch into this branch}.
+	 *
+	 * @throws UsageError if the branches are unrelated.
+	 */
+	isMissingEditsFrom(branch: TreeBranch): boolean;
 }
 
 /**
@@ -438,13 +472,92 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 	readonly schema: TSchema;
 }
 
+/**
+ * {@link TreeView} with additional beta APIs.
+ * @sealed @beta
+ */
+export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>
+	extends TreeView<TSchema>,
+		TreeBranch {
+	// Override the base branch method to return a typed view rather than merely a branch.
+	fork(): ReturnType<TreeBranch["fork"]> & TreeViewBeta<TSchema>;
+
+	/**
+	 * Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible.
+	 *
+	 * @param transaction - The function to run as the body of the transaction, which may optionally return a {@link TransactionCallbackStatusBeta | value or rollback signal}.
+	 * It may optionally return a {@link WithValue | value }, which will be returned by the `runTransaction` call.
+	 *
+	 * @param params - Optional {@link RunTransactionParamsBeta | parameters} for the transaction.
+	 *
+	 * @returns A {@link TransactionValueResult | 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.
+	 *
+	 * If the transaction is rolled back, a corresponding {@link TreeBranchEvents.changed | `changed`} event will also be emitted for the rollback.
+	 */
+	runTransaction<
+		TOut extends
+			| TransactionCallbackStatusBeta<unknown, unknown>
+			| VoidTransactionCallbackStatusBeta
+			| void,
+	>(
+		transaction: () => TOut,
+		params?: RunTransactionParamsBeta,
+	): TOut extends TransactionCallbackStatusBeta<infer TSuccessValue, infer TFailureValue>
+		? TransactionValueResult<TSuccessValue, TFailureValue>
+		: TransactionVoidResult;
+
+	/**
+	 * An asynchronous version of {@link TreeViewBeta.runTransaction | 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 view.
+	 */
+	runTransactionAsync<
+		TOut extends
+			| TransactionCallbackStatusBeta<unknown, unknown>
+			| VoidTransactionCallbackStatusBeta
+			| void,
+	>(
+		transaction: () => Promise<TOut>,
+		params?: RunTransactionParamsBeta,
+	): Promise<
+		TOut extends TransactionCallbackStatusBeta<infer TSuccessValue, infer TFailureValue>
+			? TransactionValueResult<TSuccessValue, TFailureValue>
+			: TransactionVoidResult
+	>;
+}
+
 /**
  * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.
  * @sealed @alpha
  */
 export interface TreeViewAlpha<
 	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
-> extends Omit<TreeViewBeta<ReadSchema<TSchema>>, "root" | "initialize" | "fork">,
+> extends Omit<
+			TreeViewBeta<ReadSchema<TSchema>>,
+			"root" | "initialize" | "fork" | "runTransaction" | "runTransactionAsync"
+		>,
 		TreeBranchAlpha {
 	get root(): ReadableField<TSchema>;
 
@@ -458,23 +571,15 @@ export interface TreeViewAlpha<
 	fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
 }
 
-/**
- * {@link TreeView} with additional beta APIs.
- * @sealed @beta
- */
-export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>
-	extends TreeView<TSchema>,
-		TreeBranch {
-	// Override the base branch method to return a typed view rather than merely a branch.
-	fork(): ReturnType<TreeBranch["fork"]> & TreeViewBeta<TSchema>;
-}
-
 /**
  * Information about a view schema's compatibility with the document's stored schema.
  *
+ * @see
  * See SharedTree's README for more information about choosing a compatibility policy.
+ *
  * @privateRemarks
  * See {@link SchemaCompatibilityTester} for the implementation of this compatibility checking.
+ *
  * @sealed @public
  */
 export interface SchemaCompatibilityStatus {

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

@@ -37,6 +37,8 @@ import type { InsertableField, UnsafeUnknownSchema } from "../unsafeUnknownSchem
 import { conciseFromCursor, type ConciseTree } from "./conciseTree.js";
 import { createFromCursor } from "./create.js";
 import type { TreeEncodingOptions } from "./customTree.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used by docs
+import type { ObjectSchemaOptions } from "./schemaFactory.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 import { treeNodeApi } from "./treeNodeApi.js";
 import { cursorFromVerbose } from "./verboseTree.js";

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

@@ -290,18 +290,18 @@ export interface TreeNodeSchemaCore<
 	readonly implicitlyConstructable: ImplicitlyConstructable;
 
 	/**
-	 * All possible schema that a direct child of a node with this schema could have.
+	 * All possible schemas that a direct child of a node with this schema could have.
 	 *
-	 * Equivalently, this is also all schema directly referenced when defining this schema's allowed child types,
-	 * which is also the same as the set of schema referenced directly by the `Info` type parameter and the `info` property.
+	 * Equivalently, this is also all schemas directly referenced when defining this schema's allowed child types,
+	 * which is also the same as the set of schemas referenced directly by the `Info` type parameter and the `info` property.
 	 * This property is simply re-exposing that information in an easier to traverse format consistent across all node kinds.
 	 * @remarks
 	 * Some kinds of nodes may have additional restrictions on children:
-	 * this set simply enumerates all directly referenced schema, and can be use to walk over all referenced schema types.
+	 * this set simply enumerates all directly referenced schemas, and can be use to walk over all referenced schema types.
 	 *
-	 * This set cannot be used before the schema in it have been defined:
-	 * more specifically, when using lazy schema references (for example to make foreword references to schema which have not yet been defined),
-	 * users must wait until after the schema are defined to access this set.
+	 * This set cannot be used before the schemas in it have been defined:
+	 * more specifically, when using lazy schema references (for example to make foreword references to schemas which have not yet been defined),
+	 * users must wait until after the schemas are defined to access this set.
 	 * @privateRemarks
 	 * Currently there isn't much use for this in the public API,
 	 * and it's possible this will want to be tweaked or renamed as part of a larger schema reflection API surface that might be added later.

package/src/simple-tree/index.ts

@@ -175,17 +175,21 @@ export {
 	tryStoredSchemaAsArray,
 	type SchemaStatics,
 	type ITreeAlpha,
+	type NoChangeConstraint,
+	type NodeInDocumentConstraint,
+	type RunTransactionParamsAlpha,
+	type RunTransactionParamsBeta,
+	type TransactionCallbackStatusAlpha,
+	type TransactionCallbackStatusBeta,
 	type TransactionConstraint,
 	type TransactionConstraintAlpha,
-	type NodeInDocumentConstraint,
-	type NoChangeConstraint,
-	type RunTransactionParams,
-	type VoidTransactionCallbackStatus,
-	type TransactionCallbackStatus,
-	type TransactionResult,
-	type TransactionResultExt,
-	type TransactionResultSuccess,
+	type TransactionPostProcessor,
 	type TransactionResultFailed,
+	type TransactionResultSuccess,
+	type TransactionValueResult,
+	type TransactionVoidResult,
+	type VoidTransactionCallbackStatusAlpha,
+	type VoidTransactionCallbackStatusBeta,
 	rollback,
 	generateSchemaFromSimpleSchema,
 	replaceConciseTreeHandles,