@fluidframework/tree 2.101.1 → 2.102.0

package/src/text/textDomain.ts

@@ -14,6 +14,7 @@ import {
 import { typeFactory as tf } from "@fluidframework/type-factory/internal";
 
 import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
+import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	eraseSchemaDetails,
 	getInnerNode,
@@ -21,8 +22,13 @@ import {
 	SchemaFactoryAlpha,
 	TreeArrayNode,
 } from "../simple-tree/index.js";
-// eslint-disable-next-line import-x/no-duplicates
-import type { TreeNode, WithType } from "../simple-tree/index.js";
+import type {
+	ArrayNodeDeltaOp,
+	ArrayNodeTreeChangedDeltaOp,
+	TreeNode,
+	WithType,
+	// eslint-disable-next-line import-x/no-duplicates
+} from "../simple-tree/index.js";
 // Add some unused imports which show up in the generated d.ts file.
 // This prevents them from getting inline imports generated, cleaning up the d.ts file and API reports.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports, import-x/no-duplicates
@@ -144,6 +150,14 @@ class TextNode
 		return [...this.content];
 	}
 
+	public onCharactersChanged(
+		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	): () => void {
+		return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
+			processCharactersChangedDelta(delta, (i) => this.content[i], callback),
+		);
+	}
+
 	public static fromString(value: string): TextNode {
 		// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its not necessary here,
 		// but to reduce the risk of incorrect data interpretation, we actually ban this in the special case where the iterable is a string directly, which is the case here.
@@ -186,6 +200,63 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {
 	}
 }
 
+/**
+ * Processes an array-node delta into a {@link TextAsTree.TextOp}[] and calls `callback`.
+ * @remarks
+ * Shared by both the plain `onCharactersChanged` (from `nodeChanged`) and formatted `onContentChanged`
+ * (from `treeChanged`) implementations.
+ * @param delta - The raw array-node delta, or `undefined` when no delta is available.
+ * When retain ops carry `subtreeChanged` (i.e. delta comes from a `treeChanged` event), the emitted
+ * retain ops include an explicit `formattingChanged: boolean`. Otherwise `formattingChanged` is omitted.
+ * @param getCharacter - Returns the character string at the given array index in the **post-edit** tree.
+ * Only invoked for insert ops, where it must read the inserted character at the given index of the tree
+ * after the edit has been applied. Passing an accessor that reads pre-edit content will silently produce wrong text.
+ * Return `undefined` if the tree is out of sync with the delta; this triggers a full-reread fallback.
+ * @param callback - The user-supplied callback to invoke with the translated ops.
+ */
+export function processCharactersChangedDelta(
+	delta: readonly (ArrayNodeDeltaOp | ArrayNodeTreeChangedDeltaOp)[] | undefined,
+	getCharacter: (index: number) => string | undefined,
+	callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+): void {
+	if (delta === undefined) {
+		callback(undefined);
+		return;
+	}
+	let readPosition = 0;
+	const ops: TextAsTree.TextOp[] = [];
+	for (const op of delta) {
+		if (op.type === "retain") {
+			// `subtreeChanged` is only present on retain ops from `treeChanged` deltas.
+			ops.push(
+				"subtreeChanged" in op
+					? { type: "retain", count: op.count, formattingChanged: op.subtreeChanged === true }
+					: { type: "retain", count: op.count },
+			);
+			readPosition += op.count;
+		} else if (op.type === "insert") {
+			// Accumulate into an array and join at the end to keep this O(n) for large inserts
+			// (paste of long text) instead of O(n^2) from repeated string concatenation.
+			const characters: string[] = [];
+			for (let i = 0; i < op.count; i++) {
+				const character = getCharacter(readPosition);
+				if (character === undefined) {
+					// Tree is out of sync with the delta — fall back to full re-read.
+					callback(undefined);
+					return;
+				}
+				characters.push(character);
+				readPosition++;
+			}
+			ops.push({ type: "insert", text: characters.join("") });
+		} else {
+			// Construct explicit remove op so internal fields on the source op don't leak.
+			ops.push({ type: "remove", count: op.count });
+		}
+	}
+	callback(ops);
+}
+
 /**
  * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
  * @privateRemarks
@@ -249,6 +320,71 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {
  * @alpha
  */
 export namespace TextAsTree {
+	/**
+	 * A retain op in a character-level delta — a span of unchanged characters that the consumer should skip over.
+	 * @sealed
+	 * @alpha
+	 */
+	export interface TextRetainOp {
+		/**
+		 * Discriminator identifying this op as a retain.
+		 */
+		readonly type: "retain";
+		/**
+		 * The number of Unicode code points to retain.
+		 */
+		readonly count: number;
+		/**
+		 * Whether at least one character in the retained range had a deep change.
+		 * @remarks
+		 * Present only on retain ops delivered by {@link @fluidframework/tree#FormattedTextAsTree.Members.onContentChanged};
+		 * always absent on retain ops delivered by {@link TextAsTree.Members.onCharactersChanged}.
+		 * When present, `true` indicates the retained range contained a formatting property update
+		 * or an atom content edit; `false` indicates no deep change.
+		 */
+		readonly formattingChanged?: boolean;
+	}
+
+	/**
+	 * An insert op in a character-level delta — characters newly added to the text.
+	 * @remarks
+	 * Carries the inserted text as a single string, which is more convenient for consumers than individual characters.
+	 * @sealed
+	 * @alpha
+	 */
+	export interface TextInsertOp {
+		/**
+		 * Discriminator identifying this op as an insert.
+		 */
+		readonly type: "insert";
+		/**
+		 * The newly inserted characters, concatenated into a single string.
+		 */
+		readonly text: string;
+	}
+
+	/**
+	 * A remove op in a character-level delta — a span of characters that has been deleted from the text.
+	 * @sealed
+	 * @alpha
+	 */
+	export interface TextRemoveOp {
+		/**
+		 * Discriminator identifying this op as a remove.
+		 */
+		readonly type: "remove";
+		/**
+		 * The number of Unicode code points removed.
+		 */
+		readonly count: number;
+	}
+
+	/**
+	 * A single operation in a character-level delta describing an insert, remove, or retain of text.
+	 * @alpha
+	 */
+	export type TextOp = TextRetainOp | TextInsertOp | TextRemoveOp;
+
 	/**
 	 * Statics for text nodes.
 	 * @alpha
@@ -276,6 +412,7 @@ export namespace TextAsTree {
 	 *
 	 * @see {@link TextAsTree.Statics.fromString} for construction.
 	 * @see {@link TextAsTree.(Tree:type)} for schema.
+	 * @sealed
 	 * @alpha
 	 */
 	export interface Members {
@@ -325,6 +462,22 @@ export namespace TextAsTree {
 		 * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.
 		 */
 		removeRange(startIndex: number | undefined, endIndex: number | undefined): void;
+
+		/**
+		 * Subscribe to shallow character-level changes on this text node — inserts and removes only.
+		 * @param callback - Called after each change with a sequence of {@link TextAsTree.TextOp}s describing what changed,
+		 * or `undefined` when a delta could not be computed (e.g. during a schema upgrade).
+		 * @returns A cleanup function that unsubscribes the callback when called.
+		 * @remarks
+		 * Only fires on shallow changes — inserts and removes.
+		 * It does not fire on deep changes such as formatting property updates on existing characters.
+		 * For formatted text, use {@link @fluidframework/tree#FormattedTextAsTree.Members.onContentChanged} to also receive deep changes.
+		 *
+		 * All counts in the delivered ops are in Unicode code points, not UTF-16 code units.
+		 * For characters outside the Basic Multilingual Plane (e.g. emoji), one code point
+		 * corresponds to two UTF-16 code units — convert before using the counts as string indices.
+		 */
+		onCharactersChanged(callback: (ops: readonly TextOp[] | undefined) => void): () => void;
 	}
 
 	/**

package/src/text/textDomainFormatted.ts

@@ -31,7 +31,11 @@ import type {
 } from "../simple-tree/index.js";
 import { brand, mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
 
-import { charactersFromString, type TextAsTree } from "./textDomain.js";
+import {
+	charactersFromString,
+	processCharactersChangedDelta,
+	type TextAsTree,
+} from "./textDomain.js";
 
 const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted");
 
@@ -169,6 +173,15 @@ class TextNode
 			// If this node does not have a corresponding branch, then it is unhydrated.
 			// I.e., it is not part of a collaborative session yet.
 			// Therefore, we don't need to run the edits as a transaction.
+			// Note: for unhydrated nodes each atom edit fires a separate `treeChanged` event,
+			// so formatting N atoms will produce N callbacks on `onContentChanged` subscribers
+			// instead of the single callback that hydrated (transacted) edits produce.
+			// `withBufferedTreeEvents` is not a viable mitigation here: when more than one atom's
+			// `format` field changes within the same buffered scope, the kernel's per-field
+			// dedup logic discards the delta (see `treeNodeKernel.ts` `#fieldMarksBuffer`),
+			// which is worse for incremental consumers than N well-formed callbacks.
+			// Use `runTransaction` on a hydrated node (i.e. after inserting into the document)
+			// if batched events matter.
 			applyFormatting();
 		} else {
 			// Wrap all formatting operations in a single transaction for atomicity.
@@ -177,6 +190,43 @@ class TextNode
 			});
 		}
 	}
+	/**
+	 * Returns the character string at the given atom index, or `undefined` if out of bounds.
+	 * @remarks
+	 * Line atoms expand to `"\n"`; text atoms return their underlying code point(s).
+	 */
+	private getAtomCharacterAt(index: number): string | undefined {
+		const atom = this.content[index];
+		if (atom === undefined) return undefined;
+		return atom.content instanceof FormattedTextAsTree.StringLineAtom
+			? "\n"
+			: atom.content.content;
+	}
+
+	public onCharactersChanged(
+		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	): () => void {
+		return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
+			processCharactersChangedDelta(
+				delta,
+				(index) => this.getAtomCharacterAt(index),
+				callback,
+			),
+		);
+	}
+
+	public onContentChanged(
+		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	): () => void {
+		return TreeAlpha.on(this.content, "treeChanged", ({ delta }) =>
+			processCharactersChangedDelta(
+				delta,
+				(index) => this.getAtomCharacterAt(index),
+				callback,
+			),
+		);
+	}
+
 	public getUniformRun(startIndex: number, endIndex?: number): number {
 		return this.content.getUniformRun(startIndex, endIndex);
 	}
@@ -363,7 +413,7 @@ export namespace FormattedTextAsTree {
 		/**
 		 * The underlying text content of this atom.
 		 * @remarks
-		 * This is typically a single unicode codepoint, and thus may contain multiple utf-16 surrogate pair code units.
+		 * This is typically a single Unicode code point, and thus may contain multiple UTF-16 surrogate pair code units.
 		 * Using longer strings is still valid. For example, so users might store whole grapheme clusters here, or even longer sections of text.
 		 * Anything combined into a single atom will be treated atomically, and can not be partially selected or formatted.
 		 * Using larger atoms and splitting them as needed is NOT a recommended approach, since this will result in poor merge behavior for concurrent edits.
@@ -529,6 +579,27 @@ export namespace FormattedTextAsTree {
 		 * @param endIndex - Optional ending index (exclusive). Defaults to the end of the text.
 		 */
 		getString(startIndex: number, endIndex?: number): string;
+
+		/**
+		 * Subscribe to all content changes on this text node, including both shallow
+		 * changes (inserts/removes) and deep changes (formatting updates on existing characters).
+		 * @param callback - Called after each change with a sequence of {@link TextAsTree.TextOp}s describing what changed,
+		 * or `undefined` when a delta could not be computed (e.g. during a schema upgrade).
+		 * @returns A cleanup function that unsubscribes the callback when called.
+		 * @remarks
+		 * Unlike {@link TextAsTree.Members.onCharactersChanged} which only fires on
+		 * shallow changes (inserts and removes), this method also fires on deep changes —
+		 * formatting property updates on existing characters.
+		 * The {@link TextAsTree.TextRetainOp.formattingChanged} flag on retain ops
+		 * indicates which character ranges had formatting updates.
+		 *
+		 * All counts in the delivered ops are in Unicode code points, not UTF-16 code units.
+		 * For characters outside the Basic Multilingual Plane (e.g. emoji), one code point
+		 * corresponds to two UTF-16 code units — convert before using the counts as string indices.
+		 */
+		onContentChanged(
+			callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+		): () => void;
 	}
 
 	/**

package/src/treeFactory.ts

@@ -17,6 +17,10 @@ import {
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { FluidClientVersion, type FormatVersion } from "./codec/index.js";
+import {
+	detachedFieldIndexCodecBuilder,
+	DetachedFieldIndexFormatVersion,
+} from "./core/index.js";
 import {
 	SharedTreeKernel,
 	type ITreePrivate,
@@ -227,6 +231,7 @@ const sharedBranchesOptions: SharedTreeOptionsInternal = {
 	writeVersionOverrides: new Map<string, FormatVersion>([
 		[editManagerCodecName, EditManagerFormatVersion.vSharedBranches],
 		[messageCodecName, MessageFormatVersion.vSharedBranches],
+		[detachedFieldIndexCodecBuilder.name, DetachedFieldIndexFormatVersion.v2],
 	]),
 	allowPossiblyIncompatibleWriteVersionOverrides: true,
 };

package/src/util/breakable.ts

@@ -29,13 +29,14 @@ export class Breakable {
 	 * @remarks
 	 * Can use {@link throwIfBroken} to apply this to a method.
 	 */
-	public use(): void {
+	public use(
+		message: (brokenBy: Error) => string = (brokenBy) =>
+			`Invalid use of ${this.name} after it was put into an invalid state by another error.\nOriginal Error:\n${brokenBy}`,
+	): void {
 		if (this.brokenBy !== undefined) {
-			const error = new UsageError(
-				`Invalid use of ${this.name} after it was put into an invalid state by another error.\nOriginal Error:\n${this.brokenBy}`,
-			);
+			const error = new UsageError(message(this.brokenBy));
 
-			// This "cause" field is added in ES2022, but using if even without that built in support, it is still helpful.
+			// This "cause" field is added in ES2022, but using it even without that built in support, it is still helpful.
 			// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
 			// TODO: remove this cast when targeting ES2022 lib or later.
 			(error as { cause?: unknown }).cause =
@@ -80,11 +81,31 @@ export class Breakable {
 	 * Like {@link Breakable.use}, this also throws if already broken.
 	 * Any exceptions this catches are re-thrown.
 	 * Can use {@link breakingMethod} to apply this to a method.
+	 *
+	 * If `breaker` returns a Promise, the breakable is also broken if that Promise rejects, and the broken state is rechecked when it resolves:
+	 * if the breakable was put into a broken state during the async operation (by some other code path), the resolved value is discarded and the returned Promise rejects with a {@link UsageError}.
+	 *
+	 * This does not serialize concurrent runs: a synchronous run invoked while an async run is in flight will execute immediately, and is only blocked if the breakable is already broken.
+	 * Detection of an async result uses `instanceof Promise`, so custom Promise-like objects and Promises from other realms will be treated as synchronous results.
 	 */
 	public run<TResult>(breaker: () => TResult): TResult {
 		this.use();
 		try {
-			return breaker();
+			const result = breaker();
+			if (result instanceof Promise) {
+				return result.then(
+					(value: Awaited<TResult>) => {
+						// If broken while process was running: this will throw instead of returning the value.
+						this.use(
+							(brokenBy) =>
+								`${this.name} was put into a broken state during an async operation.\nOriginal Error:\n${brokenBy}`,
+						);
+						return value;
+					},
+					(error: unknown) => this.rethrowCaught(error),
+				) as TResult;
+			}
+			return result;
 		} catch (error: unknown) {
 			this.rethrowCaught(error);
 		}