@fluidframework/tree 2.113.0-411909 → 2.114.0

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

@@ -17,6 +17,7 @@ import {
 	tagChange,
 	type ChangeFamilyEditor,
 	type GraphCommit,
+	type ProcessChangeFn,
 	type RevisionTag,
 } from "../core/index.js";
 import { getLast, getOrCreate } from "../util/index.js";
@@ -263,7 +264,7 @@ export enum ChangeProcessorApplicability {
  * (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> {
+export interface ChangeProcessor<TChange, TChangeProcessingContext> {
 	/**
 	 * Informs what context it should be invoked for.
 	 */
@@ -271,13 +272,13 @@ export interface ChangeProcessor<TChange> {
 	/**
 	 * Processes the given change, returning a change with the same observable effect.
 	 */
-	readonly processChange: (change: TChange) => TChange;
+	readonly processChange: ProcessChangeFn<TChange, TChangeProcessingContext>;
 }
 
 /**
  * Options for {@link Transactor.start | starting} a transaction.
  */
-export interface SquashingTransactionOptions<TChange> {
+export interface SquashingTransactionOptions<TChange, TChangeProcessingContext> {
 	/**
 	 * An optional {@link ChangeProcessor} applied to the squashed change produced when a transaction that was started
 	 * with this option is committed.
@@ -288,7 +289,7 @@ export interface SquashingTransactionOptions<TChange> {
 	 * How often the processor is invoked across nested transactions is governed by its
 	 * {@link ChangeProcessor.applicability | applicability}.
 	 */
-	readonly postProcessor?: ChangeProcessor<TChange>;
+	readonly postProcessor?: ChangeProcessor<TChange, TChangeProcessingContext>;
 }
 
 /**
@@ -300,8 +301,9 @@ export interface SquashingTransactionOptions<TChange> {
 export class SquashingTransactionStack<
 	TEditor extends ChangeFamilyEditor,
 	TChange,
-> extends TransactionStack<SquashingTransactionOptions<TChange>> {
-	#transactionBranch?: SharedTreeBranch<TEditor, TChange>;
+	TChangeProcessingContext,
+> extends TransactionStack<SquashingTransactionOptions<TChange, TChangeProcessingContext>> {
+	#transactionBranch?: SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>;
 
 	/**
 	 * An editor for whichever branch is currently the {@link SquashingTransactionStack.activeBranch | active branch}.
@@ -317,7 +319,7 @@ export class SquashingTransactionStack<
 	/**
 	 * Get the "active branch" for this transactor - either the transaction branch if a transaction is in progress, or the original branch otherwise.
 	 */
-	public get activeBranch(): SharedTreeBranch<TEditor, TChange> {
+	public get activeBranch(): SharedTreeBranch<TEditor, TChange, TChangeProcessingContext> {
 		return this.#transactionBranch ?? this.branch;
 	}
 
@@ -326,10 +328,16 @@ export class SquashingTransactionStack<
 	 * @remarks When the active branch changes, the listeners for these events will automatically be transferred to the new active branch.
 	 * In contrast, binding an event to the {@link SquashingTransactionStack.activeBranch | active branch} directly will not automatically transfer the listener when the active branch changes.
 	 */
-	public get activeBranchEvents(): Listenable<SharedTreeBranchEvents<TEditor, TChange>> {
+	public get activeBranchEvents(): Listenable<
+		SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>
+	> {
 		const off = (
-			eventName: keyof SharedTreeBranchEvents<TEditor, TChange>,
-			listener: SharedTreeBranchEvents<TEditor, TChange>[typeof eventName],
+			eventName: keyof SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>,
+			listener: SharedTreeBranchEvents<
+				TEditor,
+				TChange,
+				TChangeProcessingContext
+			>[typeof eventName],
 		): void => {
 			this.activeBranch.events.off(eventName, listener);
 			const listeners = this.#activeBranchEvents.get(eventName);
@@ -349,9 +357,13 @@ export class SquashingTransactionStack<
 		};
 	}
 	readonly #activeBranchEvents = new Map<
-		keyof SharedTreeBranchEvents<TEditor, TChange>,
+		keyof SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>,
 		Set<
-			SharedTreeBranchEvents<TEditor, TChange>[keyof SharedTreeBranchEvents<TEditor, TChange>]
+			SharedTreeBranchEvents<
+				TEditor,
+				TChange,
+				TChangeProcessingContext
+			>[keyof SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>]
 		>
 	>();
 
@@ -365,20 +377,23 @@ export class SquashingTransactionStack<
 	 * 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>,
+		public readonly branch: SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>,
 		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)[] = [];
+		const postProcessorStack: (
+			| ChangeProcessor<TChange, TChangeProcessingContext>
+			| 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 => {
+			requested: ChangeProcessor<TChange, TChangeProcessingContext> | undefined,
+		): ChangeProcessor<TChange, TChangeProcessingContext> | undefined => {
 			if (
 				requested?.applicability === ChangeProcessorApplicability.IfOutermost &&
 				postProcessorStack.includes(requested)
@@ -391,12 +406,13 @@ export class SquashingTransactionStack<
 		super(
 			// Invoked when an outer transaction starts
 			(
-				startOptions?: SquashingTransactionOptions<TChange>,
-			): Callbacks<SquashingTransactionOptions<TChange>> => {
+				startOptions?: SquashingTransactionOptions<TChange, TChangeProcessingContext>,
+			): Callbacks<SquashingTransactionOptions<TChange, TChangeProcessingContext>> => {
 				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;
+				const changeFamily = this.branch.changeFamily;
+				const rebaser = changeFamily.rebaser;
 				const outerOnPop = onPush?.();
 				let transactionRevision: RevisionTag | undefined;
 				const transactionBranch = this.branch.fork(
@@ -462,7 +478,9 @@ export class SquashingTransactionStack<
 								// 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);
+									postProcessor === undefined
+										? squash
+										: changeFamily.buildProcessor(postProcessor.processChange)(squash);
 
 								if (change !== squash) {
 									// The post-processor produced a change that differs from the
@@ -524,9 +542,9 @@ export class SquashingTransactionStack<
 					outerOnPop?.(result, viewUpdate);
 				};
 				// Invoked when a nested transaction begins
-				const onNestedTransactionPush: OnPush<SquashingTransactionOptions<TChange>> = (
-					nestedStartOptions,
-				) => {
+				const onNestedTransactionPush: OnPush<
+					SquashingTransactionOptions<TChange, TChangeProcessingContext>
+				> = (nestedStartOptions) => {
 					postProcessorStack.push(resolvePostProcessor(nestedStartOptions?.postProcessor));
 					const nestedStartHead = this.activeBranch.getHead();
 					const nestedOuterOnPop = onPush?.();
@@ -558,7 +576,9 @@ export class SquashingTransactionStack<
 												0xd07 /* Expected transaction revision in the presence of transaction steps */,
 											);
 											const squash = rebaser.compose(nestedSteps);
-											const processedSquash = nestedPostProcessor.processChange(squash);
+											const processedSquash = changeFamily.buildProcessor(
+												nestedPostProcessor.processChange,
+											)(squash);
 											// Roll back the transaction branch to the nested start head and apply the
 											// processed change if it differs from the original change.
 											if (processedSquash !== squash) {
@@ -586,7 +606,9 @@ export class SquashingTransactionStack<
 
 	/** Updates the transaction branch (and therefore the active branch) and rebinds the branch events. */
 	private setTransactionBranch(
-		transactionBranch: SharedTreeBranch<TEditor, TChange> | undefined,
+		transactionBranch:
+			| SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>
+			| undefined,
 	): void {
 		const oldActiveBranch = this.activeBranch;
 		this.#transactionBranch = transactionBranch;

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

@@ -103,6 +103,21 @@ export function eraseSchemaDetails<TNode, ExtraSchemaProperties = unknown>(): <
  * const square = Square.create(10);
  * assert.equal(square.area, 100);
  * ```
+ * @remarks
+ * Care must be taken to avoid subclass members colliding with internal members of the schema.
+ * This is mainly a problem when using the output from {@link eraseSchemaDetailsSubclassable} to type a class returned to third party code which can subclass it.
+ * This pattern mainly occurs when writing generic schema factory functions which generate a schema from some parameters and return it to third party code which can subclass it.
+ *
+ * For example if the schema has a field or method named `size` (from a field, like in the `Square` example, or otherwise),
+ * then a subclass should not define a member named `size` as it will collide with the internal field.
+ *
+ * In practice, this risk can be mitigated by doing one of:
+ * 1. Using JavaScript private properties
+ * 2. Use non exported symbols for the properties
+ * 3. Use a naming convention for internal properties which you document the subclasses must not use.
+ * 4. Documenting the specific internal properties keys as not to be used by subclasses.
+ * 5. Subclass the returned class and declaring uninitialized readonly private properties to protect them (`private readonly size!: unknown;`).
+ * 6. Include the properties in `TNode` or `ExtraSchemaProperties`. This can use readonly erased types (like unknown) if desired.
  * @privateRemarks
  * See "example" test for an executable version of this example.
  * @alpha

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -158,6 +158,11 @@ export interface TreeArrayNode<
 	 * Removes the item at the specified location.
 	 * @param index - The index at which to remove the item.
 	 * @throws Throws if `index` is not in the range [0, `array.length`).
+	 * @remarks
+	 * The item to remove is determined when this method is called, not when the resulting edit is sequenced.
+	 * This means that, once the edit is sequenced, the item being removed may no longer be at `index`,
+	 * and may in fact no longer be in this array at all (for example, if a concurrent edit moved it to another array).
+	 * This operation removes that item from wherever it then resides.
 	 */
 	removeAt(index: number): void;
 
@@ -534,12 +539,22 @@ export interface TreeArrayNodeAlpha<
 	/**
 	 * Removes the last item from the array and returns it.
 	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 * @remarks
+	 * Equivalent to `removeAt(array.length - 1)`, additionally returning the removed item:
+	 * see {@link (TreeArrayNode:interface).removeAt} for details, including merge semantics with concurrent edits.
+	 * In particular, the item removed is the one that is last at the time this method is called,
+	 * not the one that is last at the time the resulting edit is sequenced.
 	 */
 	pop(): T | undefined;
 
 	/**
 	 * Removes the first item from the array and returns it.
 	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 * @remarks
+	 * Equivalent to `removeAt(0)`, additionally returning the removed item:
+	 * see {@link (TreeArrayNode:interface).removeAt} for details, including merge semantics with concurrent edits.
+	 * In particular, the item removed is the one that is first at the time this method is called,
+	 * not the one that is first at the time the resulting edit is sequenced.
 	 */
 	shift(): T | undefined;
 
@@ -550,8 +565,10 @@ export interface TreeArrayNodeAlpha<
 	 * @remarks
 	 * Unlike `Array.prototype.unshift`, this method does not return the new length of the array.
 	 *
-	 * Equivalent to `insertAt(0, ...value)`:
-	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
+	 * All items inserted by a single call to this method are inserted consecutively.
+	 * The order of the inserted items relative to other concurrently inserted items is fully specified:
+	 * Concurrently unshifting `[A, B]` and `[X, Y]` will yield `[A, B, X, Y]` if the edit unshifting `[A, B]`
+	 * is sequenced after the edit unshifting `[X, Y]`.
 	 */
 	unshift(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
 
@@ -563,6 +580,8 @@ export interface TreeArrayNodeAlpha<
 	 * Must be a non-negative integer no greater than the number of items from `start` to the end of the array.
 	 * @param items - The item(s) to insert at `start`.
 	 * @returns An array containing the item(s) that were removed.
+	 * @remarks
+	 * See {@link (TreeArrayNode:interface).insertAt} for the merge semantics of the inserted items.
 	 */
 	splice(
 		start: number,

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -166,7 +166,21 @@ export interface TreeMapNode<T extends ImplicitAllowedTypes = ImplicitAllowedTyp
 export interface TreeMapNodeAlpha<T extends ImplicitAllowedTypes = ImplicitAllowedTypes>
 	extends FluidReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>,
 		TreeNode,
-		Pick<TreeMapNode<T>, "set" | "delete"> {}
+		Pick<TreeMapNode<T>, "set" | "delete"> {
+	/**
+	 * Removes all elements from the map.
+	 * @remarks
+	 * The merge semantics of this operation are loosely specified. Either of the following may occur:
+	 *
+	 * - `clear` may remove all elements that were in the map when the edit was authored,
+	 * even if some of those elements have since been moved elsewhere in the tree
+	 * (in which case they are removed from their new location).
+	 *
+	 * - `clear` may remove all elements that are in the map when the edit is sequenced,
+	 * even if some of those elements were not yet in the map when the edit was authored.
+	 */
+	clear(): void;
+}
 
 // TreeMapNode is invariant over schema type, so for this handler to work with all schema, the only possible type for the schema is `any`.
 // This is not ideal, but no alternatives are possible.
@@ -265,7 +279,15 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 			callbackFn.call(thisArg, node, field.key, this);
 		}
 	}
-	// TODO: add `clear` once we have established merge semantics for it.
+	public clear(): void {
+		const node = this.innerNode;
+		const transaction = node.isHydrated() ? node.context.checkout.transaction : undefined;
+		transaction?.start();
+		for (const key of [...node.keys()]) {
+			this.delete(key);
+		}
+		transaction?.commit();
+	}
 }
 
 /**

package/src/text/textDomain.ts

@@ -34,6 +34,29 @@ import type {
 // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports, import-x/no-duplicates
 import type { NodeKind, TreeNodeSchema } from "../simple-tree/index.js";
 
+/**
+ * Enables expensive debug assertions for formatted text.
+ */
+let enableTextExpensiveDebugAsserts = false;
+
+/**
+ * Enables or disables expensive debug assertions for formatted text.
+ * @remarks
+ * These should remain disabled except when testing implementation details of this code.
+ */
+export function setEnableExpensiveDebugAsserts(value: boolean): void {
+	enableTextExpensiveDebugAsserts = value;
+}
+
+/**
+ * Runs `condition` as a {@link debugAssert} only when {@link enableTextExpensiveDebugAsserts} is enabled.
+ * @remarks
+ * Like all {@link debugAssert}s, this is compiled out of production builds, so `condition` is never evaluated there.
+ */
+export function expensiveInternalValidationAssert(condition: () => true | string): void {
+	debugAssert(() => !enableTextExpensiveDebugAsserts || condition());
+}
+
 const sf = new SchemaFactoryAlpha("com.fluidframework.text");
 
 class TextNode
@@ -120,9 +143,9 @@ class TextNode
 
 	public charactersCopy(): string[] {
 		const result = this.content.charactersCopy();
-		debugAssert(
+		expensiveInternalValidationAssert(
 			() =>
-				compareArrays(result, this.charactersCopy_reference()) ||
+				compareArrays(result, this.#charactersCopy_reference()) ||
 				"invalid charactersCopy optimizations",
 		);
 		return result;
@@ -130,8 +153,8 @@ class TextNode
 
 	public fullString(): string {
 		const result = this.content.fullString();
-		debugAssert(
-			() => result === this.fullString_reference() || "invalid fullString optimizations",
+		expensiveInternalValidationAssert(
+			() => result === this.#fullString_reference() || "invalid fullString optimizations",
 		);
 		return result;
 	}
@@ -139,14 +162,14 @@ class TextNode
 	/**
 	 * Unoptimized trivially correct implementation of fullString.
 	 */
-	public fullString_reference(): string {
+	#fullString_reference(): string {
 		return this.content.join("");
 	}
 
 	/**
 	 * Unoptimized trivially correct implementation of charactersCopy.
 	 */
-	public charactersCopy_reference(): string[] {
+	#charactersCopy_reference(): string[] {
 		return [...this.content];
 	}