@fluidframework/tree 2.103.0 → 2.111.0

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

@@ -12,13 +12,16 @@ export {
 } from "./branch.js";
 
 export {
-	TransactionResult,
-	type Transactor,
+	type ChangeProcessor,
+	type OnPop,
+	type OnPush,
+	type SquashingTransactionOptions,
 	type TransactionEvents,
-	TransactionStack,
+	type Transactor,
+	ChangeProcessorApplicability,
 	SquashingTransactionStack,
-	type OnPush,
-	type OnPop,
+	TransactionResult,
+	TransactionStack,
 } from "./transaction.js";
 
 export {

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

@@ -197,8 +197,9 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.idCompressor,
 				options.minVersionForCollab,
 				this.schemaAndPolicy,
-				options.healUnresolvableIdentifiersOnDecode,
-				sharedObject.id,
+				options.healUnresolvableIdentifiersOnDecode === true
+					? { sharedObjectId: sharedObject.id }
+					: undefined,
 			),
 			...summarizables,
 		];

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

@@ -40,15 +40,17 @@ export enum TransactionResult {
 
 /**
  * A simple API for managing transactions.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-export interface Transactor {
+export interface Transactor<TOptions> {
 	/**
 	 * Start a new transaction.
+	 * @param options - Options controlling how the transaction is committed.
 	 * @remarks
 	 * 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.
 	 */
-	start(): void;
+	start(options?: TOptions): void;
 	/**
 	 * Close this transaction by squashing its edits and committing them as a single edit.
 	 * @remarks If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
@@ -89,8 +91,9 @@ export interface TransactionEvents {
 
 /**
  * Callbacks for transaction lifecycle events.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-export interface Callbacks {
+export interface Callbacks<TOptions> {
 	/**
 	 * Called when the current transaction is popped from the {@link TransactionStack | stack}.
 	 */
@@ -104,37 +107,42 @@ export interface Callbacks {
 	 * 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;
+	readonly onPush?: OnPush<TOptions>;
 }
 
 /**
  * A function that will be called when a transaction is pushed to the {@link TransactionStack | 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.size} will be 0 during its execution.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
+ * @param options - The options passed to {@link Transactor.start | start}.
  */
-export type OnPush = () => Callbacks | void;
+export type OnPush<TOptions> = (options?: TOptions) => Callbacks<TOptions> | 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.size} will be 0 during its execution.
+ * @param result - The result of the transaction.
  */
 export type OnPop = (result: TransactionResult) => void;
 
 /**
  * A frame in the transaction stack.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-interface TransactionStackFrame {
+interface TransactionStackFrame<TOptions> {
 	/** The callbacks provided when this transaction frame was pushed onto the stack. */
-	readonly callbacks: Callbacks;
+	readonly callbacks: Callbacks<TOptions>;
 }
 
 /**
  * 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.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-export class TransactionStack implements Transactor, IDisposable {
-	readonly #stack: TransactionStackFrame[] = [];
-	readonly #onPush?: OnPush;
+export class TransactionStack<TOptions> implements Transactor<TOptions>, IDisposable {
+	readonly #stack: TransactionStackFrame<TOptions>[] = [];
+	readonly #onPush?: OnPush<TOptions>;
 
 	readonly #events = createEmitter<TransactionEvents>();
 	public get events(): Listenable<TransactionEvents> {
@@ -150,7 +158,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?: OnPush) {
+	public constructor(onPush?: OnPush<TOptions>) {
 		this.#onPush = onPush;
 	}
 
@@ -159,11 +167,11 @@ export class TransactionStack implements Transactor, IDisposable {
 		return this.#stack.length;
 	}
 
-	public start(): void {
+	public start(options?: TOptions): void {
 		this.ensureNotDisposed();
 		const last = getLast(this.#stack);
 		const onPushCurrent = last === undefined ? this.#onPush : last.callbacks.onPush;
-		const { onPush, onPop } = onPushCurrent?.() ?? {};
+		const { onPush, onPop } = onPushCurrent?.(options) ?? {};
 		this.#stack.push({
 			callbacks: { onPop, onPush: onPush ?? onPushCurrent },
 		});
@@ -216,6 +224,73 @@ export type OnPopWithViewUpdate<TChange> = (
 	viewUpdate: TChange | undefined,
 ) => void;
 
+/**
+ * Informs the caller of {@link ChangeProcessor} what context it should be invoked for.
+ * @remarks This is purely a recommendation to the caller of the processor and
+ * not a strict rule.
+ */
+export enum ChangeProcessorApplicability {
+	/**
+	 * Invoke the processor if no later (outer) instance of this change processor
+	 * may be applied to related changes before changes are "visible".
+	 *
+	 * @remarks
+	 * This designation is meant for processors that only need to be applied
+	 * once to a set of related changes independent of scope or nesting,
+	 * with the understanding that the processor should still be applied no
+	 * later than when the changes are "visible" (e.g. committed to a branch).
+	 * For example, a processor that removes extraneous information from a
+	 * change (e.g. data for nodes that were both created and removed within a
+	 * transaction) only needs to be applied once to the squashed change
+	 * produced by the outermost transaction.
+	 */
+	IfOutermost,
+	/**
+	 * Invoke the processor in all contexts.
+	 */
+	Always,
+}
+
+/**
+ * Processes a change altering its representation.
+ *
+ * @remarks
+ * A change processor receives a change and returns a change with the
+ * same observable effect but otherwise transformed.
+ *
+ * Currently this is the internal counterpart of the type-erased post-processor
+ * exposed on the public transaction API. The public boundary type-erases this
+ * (see the conversion helpers in the `shared-tree` layer) so that its internal
+ * change representation does not leak into the public API.
+ */
+export interface ChangeProcessor<TChange> {
+	/**
+	 * Informs what context it should be invoked for.
+	 */
+	readonly applicability: ChangeProcessorApplicability;
+	/**
+	 * Processes the given change, returning a change with the same observable effect.
+	 */
+	readonly processChange: (change: TChange) => TChange;
+}
+
+/**
+ * Options for {@link Transactor.start | starting} a transaction.
+ */
+export interface SquashingTransactionOptions<TChange> {
+	/**
+	 * An optional {@link ChangeProcessor} applied to the squashed change produced when a transaction that was started
+	 * with this option is committed.
+	 *
+	 * @remarks
+	 * When omitted, the transaction's edits are squashed without any post-processing.
+	 *
+	 * How often the processor is invoked across nested transactions is governed by its
+	 * {@link ChangeProcessor.applicability | applicability}.
+	 */
+	readonly postProcessor?: ChangeProcessor<TChange>;
+}
+
 /**
  * An implementation of {@link Transactor} that {@link TransactionStack | uses a stack} and a {@link SharedTreeBranch | branch} to manage transactions.
  * @remarks Given a branch, this class will fork the branch when a transaction begins and squash the forked branch back into the original branch when the transaction ends.
@@ -225,7 +300,7 @@ export type OnPopWithViewUpdate<TChange> = (
 export class SquashingTransactionStack<
 	TEditor extends ChangeFamilyEditor,
 	TChange,
-> extends TransactionStack {
+> extends TransactionStack<SquashingTransactionOptions<TChange>> {
 	#transactionBranch?: SharedTreeBranch<TEditor, TChange>;
 
 	/**
@@ -284,15 +359,41 @@ 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 onPush - A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
+	 * @remarks To post-process the squashed change produced when a transaction is committed (for example, to "minimize"
+	 * it so that it contains no extraneous information), start the transaction with a
+	 * {@link SquashingTransactionOptions.postProcessor | post-processor}. The post-processor is injected via the transaction
+	 * options rather than baked into this stack, so different transactions may supply different post-processors (or none).
 	 */
 	public constructor(
 		public readonly branch: SharedTreeBranch<TEditor, TChange>,
 		mintRevisionTag: () => RevisionTag,
 		onPush?: () => OnPopWithViewUpdate<TChange> | void,
 	) {
+		// A stack of the post-processors to apply when each in-progress transaction commits, ordered from outermost to
+		// innermost. Each in-progress transaction contributes exactly one entry: either the processor to apply when it
+		// commits, or `undefined` when none should be applied.
+		const postProcessorStack: (ChangeProcessor<TChange> | undefined)[] = [];
+		// Determines the entry to push for a transaction that was started with the given `requested` processor (if any).
+		// A processor with "outermost" applicability that is already active in an enclosing transaction resolves to
+		// `undefined` so that it is only applied once (at the outermost transaction that supplied it).
+		const resolvePostProcessor = (
+			requested: ChangeProcessor<TChange> | undefined,
+		): ChangeProcessor<TChange> | undefined => {
+			if (
+				requested?.applicability === ChangeProcessorApplicability.IfOutermost &&
+				postProcessorStack.includes(requested)
+			) {
+				return undefined;
+			}
+			return requested;
+		};
+
 		super(
 			// Invoked when an outer transaction starts
-			(): Callbacks => {
+			(
+				startOptions?: SquashingTransactionOptions<TChange>,
+			): Callbacks<SquashingTransactionOptions<TChange>> => {
+				postProcessorStack.push(resolvePostProcessor(startOptions?.postProcessor));
 				// Keep track of the commit that each transaction was on when it started
 				const startHead = this.activeBranch.getHead();
 				const rebaser = this.branch.changeFamily.rebaser;
@@ -309,6 +410,7 @@ export class SquashingTransactionStack<
 				// Invoked when an outer transaction ends
 				const onOuterTransactionPop: OnPop = (result) => {
 					assert(this.size === 0, 0xcae /* The outer transaction should be ending */);
+					const postProcessor = postProcessorStack.pop();
 					transactionBranch.editor.exitTransaction();
 
 					const sourcePath: GraphCommit<TChange>[] = [];
@@ -357,16 +459,20 @@ export class SquashingTransactionStack<
 								}
 								// Squash all the new commits on the transaction branch into a new commit on the original branch
 								const squash = rebaser.compose(transactionSteps);
+								// Apply this transaction's post-processor (if any) to the squashed change (for example, to
+								// "minimize" it so that it contains no extraneous information).
+								const change =
+									postProcessor === undefined ? squash : postProcessor.processChange(squash);
 
 								if (targetPath.length === 0) {
 									// No changes were made on the original branch since the transaction began
 									// The transaction commit can be applied directly
-									this.branch.apply(tagChange(squash, transactionRevision));
+									this.branch.apply(tagChange(change, transactionRevision));
 									// The view is already up-to-date so there's nothing more to do
 								} else {
 									// Some changes were made on `branch` since the transaction began
 									const unrebasedHead = mintCommit(startHead, {
-										change: squash,
+										change,
 										revision: transactionRevision,
 									});
 									// We need to rebase the transaction commit on top of the new changes
@@ -407,13 +513,17 @@ export class SquashingTransactionStack<
 					outerOnPop?.(result, viewUpdate);
 				};
 				// Invoked when a nested transaction begins
-				const onNestedTransactionPush: OnPush = () => {
+				const onNestedTransactionPush: OnPush<SquashingTransactionOptions<TChange>> = (
+					nestedStartOptions,
+				) => {
+					postProcessorStack.push(resolvePostProcessor(nestedStartOptions?.postProcessor));
 					const nestedStartHead = this.activeBranch.getHead();
 					const nestedOuterOnPop = onPush?.();
 					transactionBranch.editor.enterTransaction();
 					return {
 						// Invoked when a nested transaction ends
 						onPop: (result) => {
+							const nestedPostProcessor = postProcessorStack.pop();
 							transactionBranch.editor.exitTransaction();
 							switch (result) {
 								case TransactionResult.Abort: {
@@ -422,6 +532,26 @@ export class SquashingTransactionStack<
 									break;
 								}
 								case TransactionResult.Commit: {
+									// When this nested transaction supplied a post-processor that should be applied here, squash its
+									// edits into a single (post-processed) commit on the transaction branch rather than leaving them to
+									// be squashed only when the outermost transaction is committed.
+									if (nestedPostProcessor !== undefined) {
+										const nestedSteps: GraphCommit<TChange>[] = [];
+										findAncestor(
+											[transactionBranch.getHead(), nestedSteps],
+											(c) => c === nestedStartHead,
+										);
+										if (nestedSteps.length > 0) {
+											assert(
+												transactionRevision !== undefined,
+												0xd07 /* Expected transaction revision in the presence of transaction steps */,
+											);
+											const squash = rebaser.compose(nestedSteps);
+											const processedSquash = nestedPostProcessor.processChange(squash);
+											transactionBranch.removeAfter(nestedStartHead);
+											transactionBranch.apply(tagChange(processedSquash, transactionRevision));
+										}
+									}
 									break;
 								}
 								default: {

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

@@ -179,19 +179,23 @@ export {
 } from "./storedSchema.js";
 
 export {
+	type NoChangeConstraint,
+	type NodeInDocumentConstraint,
+	rollback,
+	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,
 	type WithValue,
-	rollback,
 } from "./transactionTypes.js";
 
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";

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

@@ -78,7 +78,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 }
 
 /**
- * Converts an enum into a collection of schema which can be used in a union.
+ * Converts an enum into a collection of schemas which can be used in a union.
  *
  * @typeParam TScope - The scope of the provided factory.
  * There is a known issue where if a factory is provided that is typed as a {@link SchemaFactoryAlpha}, and its scope contains a "." character,
@@ -88,7 +88,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * @remarks
  * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
  * Numeric enums values have the value implicitly converted into a string.
- * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryBeta.scopedFactory}) to avoid the enum members colliding with other schema.
+ * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryBeta.scopedFactory}) to avoid the enum members colliding with other schemas.
  * @example
  * ```typescript
  * const schemaFactory = new SchemaFactory("com.myApp");
@@ -213,7 +213,7 @@ export function enumEntries(
 }
 
 /**
- * Converts an array of distinct strings into a collection of schema which can be used like an enum style union.
+ * Converts an array of distinct strings into a collection of schemas which can be used like an enum style union.
  * @remarks
  * The returned collection is also a function which can be used to convert strings into {@link Unhydrated} nodes in the union.
  * Each node type has a `.value` getter which returns the associated string.

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

@@ -339,7 +339,7 @@ export class SchemaFactory<
 	/**
 	 * Construct a SchemaFactory with a given {@link SchemaFactory.scope|scope}.
 	 * @remarks
-	 * There are no restrictions on mixing schema from different schema factories.
+	 * There are no restrictions on mixing schemas from different schema factories.
 	 * Typically each library will create one or more SchemaFactories and use them to define its schema.
 	 */
 	public constructor(
@@ -698,7 +698,7 @@ export class SchemaFactory<
 		const same = compareSets({ a: inputTypes, b: outputTypes });
 		if (!same) {
 			throw new UsageError(
-				`Structurally named schema collision: two schema named "${fullName}" were defined with different input schema.`,
+				`Structurally named schema collision: two schemas named "${fullName}" were defined with different input schemas.`,
 			);
 		}
 		return structural;

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

@@ -422,11 +422,11 @@ export interface SnapshotSchemaCompatibilityOptions {
  * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.
  *
  * This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.
- * Generally any historical schema should have been tested against the ones before them at the time they were current.
+ * Generally any historical schemas should have been tested against the ones before them at the time they were current.
  * If for some reason a version of a schema made it into production that was not compatible with a previous version,
  * that can still be represented here (but may require manually generating a snapshot for that version)
  * and this will still allow testing that all historical version can be upgraded to the current one.
- * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:
+ * If a sufficiently incompatible historical schemas were used in production, it may be impossible to make a single schema which can accommodate all of them:
  * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.
  *
  * @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.

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

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import type { ErasedType } from "@fluidframework/core-interfaces";
+
 import type { TreeNode } from "../core/index.js";
 
 /**
@@ -50,87 +52,148 @@ export interface NoChangeConstraint {
 
 /**
  * Contains a value returned from a transaction.
- * @alpha
+ * @input
+ * @beta
  */
 export interface WithValue<TValue> {
 	/** The user-supplied value. */
-	value: TValue;
+	readonly value: TValue;
 }
 
 /**
- * Contains a value and status returned from a user-supplied {@link TreeBranchAlpha.(runTransaction:1) | transaction callback}.
- * @alpha
+ * Contains a value and status returned from a user-supplied {@link TreeViewBeta.runTransaction | transaction callback}.
+ * @input
+ * @beta
  */
-export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = (
+export type TransactionCallbackStatusBeta<TSuccessValue, TFailureValue> =
 	| (WithValue<TSuccessValue> & {
 			/** Indicates that the transaction callback ran successfully. */
-			rollback?: false;
+			readonly rollback?: false;
 	  })
 	| (WithValue<TFailureValue> & {
 			/** Indicates that the transaction callback failed and the transaction should be rolled back. */
-			rollback: true;
-	  })
-) & {
-	/**
-	 * An optional list of {@link TransactionConstraintAlpha | 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 TransactionConstraintAlpha[];
-};
+			readonly rollback: true;
+	  });
+
+/**
+ * The result of a {@link TreeViewBeta.runTransaction | transaction} that doesn't return a value.
+ * @input
+ * @beta
+ */
+export type VoidTransactionCallbackStatusBeta = Omit<
+	TransactionCallbackStatusBeta<unknown, unknown>,
+	"value"
+>;
+
+/**
+ * {@link TransactionCallbackStatusBeta} extended with alpha-only {@link TransactionConstraintAlpha | constraint} options.
+ * @input
+ * @alpha
+ */
+export type TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue> =
+	TransactionCallbackStatusBeta<TSuccessValue, TFailureValue> & {
+		/**
+		 * An optional list of {@link TransactionConstraintAlpha | 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`.
+		 */
+		readonly preconditionsOnRevert?: readonly TransactionConstraintAlpha[];
+	};
 
 /**
  * The result of a {@link TreeBranchAlpha.(runTransaction:2) | transaction} that doesn't return a value.
+ * @input
  * @alpha
  */
-export type VoidTransactionCallbackStatus = Omit<
-	TransactionCallbackStatus<unknown, unknown>,
+export type VoidTransactionCallbackStatusAlpha = Omit<
+	TransactionCallbackStatusAlpha<unknown, unknown>,
 	"value"
 >;
 
 /**
- * The result of a {@link TreeBranchAlpha.(runTransaction:1) | transaction} that completed successfully.
- * @alpha
+ * The result of a {@link TreeViewBeta.(runTransaction:1) | transaction} that completed successfully.
+ * @sealed
+ * @beta
  */
 export interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSuccessValue> {
-	/** The success flag for a transaction that completed without being {@link TransactionCallbackStatus | rolled back}. */
-	success: true;
+	/** The success flag for a transaction that completed without being {@link TransactionCallbackStatusBeta | rolled back}. */
+	readonly success: true;
 }
 
 /**
- * The result of a {@link TreeBranchAlpha.(runTransaction:1) | transaction} that was rolled back.
- * @alpha
+ * The result of a {@link TreeViewBeta.runTransaction | transaction} that was rolled back.
+ * @sealed
+ * @beta
  */
 export interface TransactionResultFailed<TFailureValue> extends WithValue<TFailureValue> {
-	/** The failure flag for a transaction that was {@link TransactionCallbackStatus | rolled back}. */
-	success: false;
+	/** The failure flag for a transaction that was {@link TransactionCallbackStatusBeta | rolled back}. */
+	readonly success: false;
 }
 
 /**
  * The result of the {@link RunTransaction | RunTransaction} API.
- * @alpha
+ * @sealed
+ * @beta
  */
-export type TransactionResultExt<TSuccessValue, TFailureValue> =
+export type TransactionValueResult<TSuccessValue, TFailureValue> =
 	| TransactionResultSuccess<TSuccessValue>
 	| TransactionResultFailed<TFailureValue>;
 
 /**
- * The result of the {@link RunTransaction | RunTransaction} API. This is the same as {@link TransactionResultExt}
+ * The result of the {@link RunTransaction | RunTransaction} API. This is the same as {@link TransactionValueResult}
  * but with the `value` field omitted. This is useful when the transaction callback doesn't need to return a value.
- * @alpha
+ * @sealed
+ * @beta
  */
-export type TransactionResult =
+export type TransactionVoidResult =
 	| Omit<TransactionResultSuccess<unknown>, "value">
 	| Omit<TransactionResultFailed<unknown>, "value">;
 
 /**
- * The parameters for the {@link RunTransaction | RunTransaction} API.
+ * A type-erased function that post-processes the change produced when a transaction is committed.
+ *
+ * @remarks
+ * Supply one via {@link RunTransactionParamsAlpha.postProcessor} to process/alter
+ * the change that a transaction produces. For example a post-processor could
+ * remove extraneous information, so that the resulting squashed change contains
+ * no extraneous information.
+ *
+ * This type intentionally hides its internal representation: its concrete shape
+ * is an implementation detail of `@fluidframework/tree`. Obtain a value of this
+ * type from a `@fluidframework/tree` helper or constant rather than constructing
+ * one directly.
+ *
  * @alpha
+ * @sealed
+ * @system
+ */
+export interface TransactionPostProcessor
+	extends ErasedType<"@fluidframework/tree.TransactionPostProcessor"> {}
+
+/**
+ * The parameters for the {@link RunTransaction | RunTransaction} API.
+ * @input
+ * @beta
+ */
+export interface RunTransactionParamsBeta {
+	/**
+	 * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).
+	 * @remarks
+	 * 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.
+	 */
+	readonly label?: unknown;
+}
+
+/**
+ * The parameters for the {@link RunTransaction | RunTransaction} API, extended with alpha-only {@link TransactionConstraintAlpha | constraint} options.
  * @input
+ * @alpha
  */
-export interface RunTransactionParams {
+export interface RunTransactionParamsAlpha extends RunTransactionParamsBeta {
 	/**
 	 * An optional list of {@link TransactionConstraintAlpha | constraints} that are checked just before the transaction begins.
 	 * @remarks
@@ -138,12 +201,21 @@ export interface RunTransactionParams {
 	 * 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).
+	 * An optional {@link TransactionPostProcessor | post-processor} applied to
+	 * the change produced when this transaction is committed.
 	 * @remarks
-	 * 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.
+	 * When omitted, the transaction's edits are squashed without any such processing.
 	 *
-	 * If there is a nested transaction, only the outermost transaction label will be used.
+	 * Specific post-processors are applied according to their own rules for
+	 * optimization and other post-processing tasks in a transaction stack. For
+	 * example a "minimization" post-processor may be applied once for the
+	 * outermost transaction in a stack as it will process all nested edits and
+	 * there is no benefit from multiple applications.
+	 *
+	 * Note: minimization is not yet implemented. Supplying a post-processor currently has no observable effect beyond
+	 * reserving the behavior; a real post-processor will be provided in a future change.
 	 */
-	readonly label?: unknown;
+	readonly postProcessor?: TransactionPostProcessor;
 }