@fluidframework/tree 2.110.0 → 2.111.0

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

@@ -13,6 +13,7 @@ import type {
 	SchemaAndPolicy,
 } from "../core/index.js";
 import {
+	type IdentifierHealingConfig,
 	type JsonCompatibleReadOnly,
 	type JsonCompatibleReadOnlyObject,
 	JsonCompatibleReadOnlySchema,
@@ -26,8 +27,8 @@ export interface EditManagerEncodingContext {
 	idCompressor: IIdCompressor;
 	readonly schema?: SchemaAndPolicy;
 	readonly isSummary: boolean;
-	readonly healUnresolvableIdentifiersOnDecode?: boolean;
-	readonly sharedObjectId?: string;
+	/** See {@link IdentifierHealingConfig}. */
+	readonly healing?: IdentifierHealingConfig;
 }
 
 /**

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

@@ -14,6 +14,7 @@ import type {
 	SchemaAndPolicy,
 } from "../core/index.js";
 import {
+	type IdentifierHealingConfig,
 	type JsonCompatibleReadOnly,
 	type JsonCompatibleReadOnlyObject,
 	JsonCompatibleReadOnlySchema,
@@ -30,8 +31,8 @@ export interface EditManagerEncodingContext {
 	idCompressor: IIdCompressor;
 	readonly schema?: SchemaAndPolicy;
 	readonly isSummary: boolean;
-	readonly healUnresolvableIdentifiersOnDecode?: boolean;
-	readonly sharedObjectId?: string;
+	/** See {@link IdentifierHealingConfig}. */
+	readonly healing?: IdentifierHealingConfig;
 }
 
 export function makeSharedBranchesCodecWithVersion<TChangeset>(

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

@@ -16,7 +16,7 @@ import type { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal"
 
 import type { IJsonCodec } from "../codec/index.js";
 import type { ChangeFamily, ChangeFamilyEditor, SchemaAndPolicy } from "../core/index.js";
-import type { JsonCompatibleReadOnly } from "../util/index.js";
+import type { IdentifierHealingConfig, JsonCompatibleReadOnly } from "../util/index.js";
 
 import type { EditManager, SummaryData } from "./editManager.js";
 import type { EditManagerEncodingContext } from "./editManagerCodecs.js";
@@ -85,10 +85,8 @@ export class EditManagerSummarizer<TChangeset>
 		private readonly idCompressor: IIdCompressor,
 		minVersionForCollab: MinimumVersionForCollab,
 		private readonly schemaAndPolicy?: SchemaAndPolicy,
-		/** See {@link EditManagerEncodingContext.healUnresolvableIdentifiersOnDecode}. */
-		private readonly healUnresolvableIdentifiersOnDecode?: boolean,
-		/** See {@link EditManagerEncodingContext.sharedObjectId}. */
-		private readonly sharedObjectId?: string,
+		/** See {@link IdentifierHealingConfig}. */
+		private readonly healing?: IdentifierHealingConfig,
 	) {
 		super(
 			EditManagerSummarizer.key,
@@ -111,8 +109,7 @@ export class EditManagerSummarizer<TChangeset>
 			idCompressor: this.idCompressor,
 			schema: this.schemaAndPolicy,
 			isSummary: true,
-			healUnresolvableIdentifiersOnDecode: this.healUnresolvableIdentifiersOnDecode,
-			sharedObjectId: this.sharedObjectId,
+			healing: this.healing,
 		};
 		const jsonCompatible = this.codec.encode(this.editManager.getSummaryData(), context);
 		const dataString = stringify(jsonCompatible);
@@ -137,8 +134,7 @@ export class EditManagerSummarizer<TChangeset>
 		const data = this.codec.decode(summary, {
 			idCompressor: this.idCompressor,
 			isSummary: true,
-			healUnresolvableIdentifiersOnDecode: this.healUnresolvableIdentifiersOnDecode,
-			sharedObjectId: this.sharedObjectId,
+			healing: this.healing,
 		});
 		this.editManager.loadSummaryData(data);
 	}

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.