@fluidframework/tree 2.90.0-378676 → 2.91.0

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -7,7 +7,6 @@ import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { assert, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { FlexTreeNode } from "../feature-libraries/index.js";
 import { filterIterable, hasSingle, oneFromIterable } from "../util/index.js";
 
 import {
@@ -25,7 +24,7 @@ import { getUnhydratedContext } from "./createContext.js";
 import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fieldSchema.js";
 
 /**
- * Transforms an input {@link TypedNode} tree to a {@link FlexTreeNode}.
+ * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.
  * @param data - The input tree to be converted.
  * If the data is an unsupported value (e.g. NaN), a fallback value will be used when supported,
  * otherwise an error will be thrown.
@@ -50,10 +49,10 @@ import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fie
  * Output should comply with the provided view schema, but this is not explicitly validated:
  * validation against stored schema (to guard against document corruption) is done elsewhere.
  */
-export function flexTreeFromInsertable<TIn extends InsertableContent | undefined>(
+export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(
 	data: TIn,
 	allowedTypes: ImplicitFieldSchema,
-): TIn extends undefined ? undefined : FlexTreeNode {
+): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {
 	const normalizedFieldSchema = normalizeFieldSchema(allowedTypes);
 
 	if (data === undefined) {
@@ -63,15 +62,15 @@ export function flexTreeFromInsertable<TIn extends InsertableContent | undefined
 				`Got undefined for non-optional field expecting one of ${quotedAllowedTypesWithNames(normalizedFieldSchema.allowedTypeSet)}`,
 			);
 		}
-		return undefined as TIn extends undefined ? undefined : FlexTreeNode;
+		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 	}
 
-	const flexTree: FlexTreeNode = flexTreeFromInsertableNode(
+	const flexTree: UnhydratedFlexTreeNode = unhydratedFlexTreeFromInsertableNode(
 		data,
 		normalizedFieldSchema.allowedTypeSet,
 	);
 
-	return flexTree as TIn extends undefined ? undefined : FlexTreeNode;
+	return flexTree as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 }
 
 /**
@@ -118,42 +117,23 @@ function quotedAllowedTypesWithNames(allowedTypes: Iterable<TreeNodeSchema>): st
 /**
  * Copy content from `data` into a UnhydratedFlexTreeNode.
  */
-export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(
-	data: TIn,
-	allowedTypes: ImplicitFieldSchema,
-): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {
-	const result = flexTreeFromInsertable(data, allowedTypes);
-	if (result === undefined) {
-		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
-	}
-	assert(result instanceof UnhydratedFlexTreeNode, "expected unhydrated node");
-	return result as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
-}
-
-/**
- * Copy content from `data` into a UnhydratedFlexTreeNode or return an existing node if `data` is a TreeNode.
- */
-export function flexTreeFromInsertableNode(
+export function unhydratedFlexTreeFromInsertableNode(
 	data: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-): FlexTreeNode {
+): UnhydratedFlexTreeNode {
 	if (isTreeNode(data)) {
 		const kernel = getKernel(data);
-		const inner = kernel.getInnerNode();
-		if (inner.parentField.parent.parent === undefined) {
+		const inner = kernel.getInnerNodeIfUnhydrated();
+		if (inner === undefined) {
+			// The node is already hydrated, meaning that it already got inserted into the tree previously
+			throw new UsageError(
+				`A node with schema ${quotedSchemaIdentifierWithName(kernel.schema)} was inserted into the tree more than once. This is not supported.`,
+			);
+		} else {
 			if (!allowedTypes.has(kernel.schema)) {
 				allowedTypesInsertableSchemaError(allowedTypes, kernel.schema);
 			}
-
-			if (inner.isHydrated()) {
-				// TODO: hook up event bubbling from hydrated to unhydrated tree.
-			}
-
 			return inner;
-		} else {
-			throw new UsageError(
-				"A node which already has a parent may not be used as part of a new tree.",
-			);
 		}
 	}
 

package/src/text/textDomain.ts

@@ -3,14 +3,22 @@
  * Licensed under the MIT License.
  */
 
-import { EmptyKey } from "../core/index.js";
+import { compareArrays, debugAssert } from "@fluidframework/core-utils/internal";
+
+import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
 import {
 	eraseSchemaDetails,
+	getInnerNode,
 	SchemaFactory,
 	SchemaFactoryAlpha,
 	TreeArrayNode,
 } from "../simple-tree/index.js";
+// eslint-disable-next-line import-x/no-duplicates
 import type { TreeNode, WithType } 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
+import type { NodeKind, TreeNodeSchema } from "../simple-tree/index.js";
 
 const sf = new SchemaFactoryAlpha("com.fluidframework.text");
 
@@ -26,16 +34,49 @@ class TextNode
 			TreeArrayNode.spread(charactersFromString(additionalCharacters)),
 		);
 	}
-	public removeRange(index: number, length: number): void {
-		this.content.removeRange(index, length);
+	public removeRange(index: number | undefined, end: number | undefined): void {
+		this.content.removeRange(index, end);
 	}
 	public characters(): Iterable<string> {
 		return this.content[Symbol.iterator]();
 	}
+
+	public characterCount(): number {
+		return this.content.length;
+	}
+
+	public charactersCopy(): string[] {
+		const result = this.content.charactersCopy();
+		debugAssert(
+			() =>
+				compareArrays(result, this.charactersCopy_reference()) ||
+				"invalid charactersCopy optimizations",
+		);
+		return result;
+	}
+
 	public fullString(): string {
+		const result = this.content.fullString();
+		debugAssert(
+			() => result === this.fullString_reference() || "invalid fullString optimizations",
+		);
+		return result;
+	}
+
+	/**
+	 * Unoptimized trivially correct implementation of fullString.
+	 */
+	public fullString_reference(): string {
 		return this.content.join("");
 	}
 
+	/**
+	 * Unoptimized trivially correct implementation of charactersCopy.
+	 */
+	public charactersCopy_reference(): string[] {
+		return [...this.content];
+	}
+
 	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.
@@ -58,7 +99,25 @@ export function charactersFromString(value: string): Iterable<string> {
 	return value;
 }
 
-class StringArray extends sf.array("StringArray", SchemaFactory.string) {}
+class StringArray extends sf.array("StringArray", SchemaFactory.string) {
+	public withBorrowedSequenceCursor<T>(f: (cursor: ITreeCursorSynchronous) => T): T {
+		const cursor = getInnerNode(this).borrowCursor();
+		cursor.enterField(EmptyKey);
+		const result = f(cursor);
+		cursor.exitField();
+		return result;
+	}
+
+	public charactersCopy(): string[] {
+		return this.withBorrowedSequenceCursor((cursor) =>
+			mapCursorField(cursor, () => cursor.value as string),
+		);
+	}
+
+	public fullString(): string {
+		return this.charactersCopy().join("");
+	}
+}
 
 /**
  * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
@@ -120,12 +179,12 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {}
  *
  * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,
  * in addition to implementing them for text.
- * @internal
+ * @alpha
  */
 export namespace TextAsTree {
 	/**
 	 * Statics for text nodes.
-	 * @internal
+	 * @alpha
 	 */
 	export interface Statics {
 		/**
@@ -150,7 +209,7 @@ export namespace TextAsTree {
 	 *
 	 * @see {@link TextAsTree.Statics.fromString} for construction.
 	 * @see {@link TextAsTree.(Tree:type)} for schema.
-	 * @internal
+	 * @alpha
 	 */
 	export interface Members {
 		/**
@@ -160,6 +219,20 @@ export namespace TextAsTree {
 		 */
 		characters(): Iterable<string>;
 
+		/**
+		 * Optimized way to get a copy of the {@link TextAsTree.Members.characters} in an array.
+		 */
+		charactersCopy(): string[];
+
+		/**
+		 * Gets the number of characters currently in the text.
+		 * @remarks
+		 * The length of {@link TextAsTree.Members.characters}.
+		 * This is not the length of the string returned by {@link TextAsTree.Members.fullString},
+		 * as that string may contain characters which are made up of multiple UTF-16 code units.
+		 */
+		characterCount(): number;
+
 		/**
 		 * Copy the content of this node into a string.
 		 */
@@ -184,16 +257,22 @@ export namespace TextAsTree {
 		 * Remove a range from a string based on character index.
 		 * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.
 		 */
-		removeRange(index: number, length: number): void;
+		removeRange(startIndex: number | undefined, endIndex: number | undefined): void;
 	}
 
 	/**
-	 * Schema for a text node.
+	 * Schema for a {@link TextAsTree.(Tree:variable)} node.
 	 * @remarks
-	 * See {@link TextAsTree.Members} for the API.
-	 * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.
-	 * @internal
+	 * See {@link TextAsTree.Statics} for static APIs on this schema, including construction.
+	 * @alpha
 	 */
 	export const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);
+
+	/**
+	 * Node for the {@link TextAsTree.(Tree:type)} schema exposing the {@link TextAsTree.Members} API.
+	 * @remarks
+	 * Create using {@link TextAsTree.Statics.fromString}.
+	 * @alpha
+	 */
 	export type Tree = Members & TreeNode & WithType<"com.fluidframework.text.Text">;
 }

package/src/text/textDomainFormatted.ts

@@ -3,14 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, compareArrays, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey } from "../core/index.js";
+import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
+import { currentObserver } from "../feature-libraries/index.js";
 import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	enumFromStrings,
 	eraseSchemaDetails,
+	getInnerNode,
 	SchemaFactory,
 	SchemaFactoryAlpha,
 	TreeArrayNode,
@@ -22,7 +24,7 @@ import type {
 	TreeNodeFromImplicitAllowedTypes,
 	WithType,
 } from "../simple-tree/index.js";
-import { mapIterable } from "../util/index.js";
+import { mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
 
 import { charactersFromString, type TextAsTree } from "./textDomain.js";
 
@@ -43,16 +45,51 @@ class TextNode
 			TreeArrayNode.spread(textAtomsFromString(additionalCharacters, this.defaultFormat)),
 		);
 	}
-	public removeRange(index: number, length: number): void {
-		this.content.removeRange(index, length);
+
+	public removeRange(index: number | undefined, end: number | undefined): void {
+		this.content.removeRange(index, end);
 	}
+
 	public characters(): Iterable<string> {
 		return mapIterable(this.content, (atom) => atom.content.content);
 	}
+
+	public charactersCopy(): string[] {
+		const result = this.content.charactersCopy();
+		debugAssert(
+			() =>
+				compareArrays(result, this.charactersCopy_reference()) ||
+				"invalid charactersCopy optimizations",
+		);
+		return result;
+	}
+
+	public characterCount(): number {
+		return this.content.length;
+	}
+
 	public fullString(): string {
+		const result = this.content.fullString();
+		debugAssert(
+			() => result === this.fullString_reference() || "invalid fullString optimizations",
+		);
+		return result;
+	}
+
+	/**
+	 * A non-optimized reference implementation of fullString.
+	 */
+	public fullString_reference(): string {
 		return [...this.characters()].join("");
 	}
 
+	/**
+	 * Unoptimized trivially correct implementation of charactersCopy.
+	 */
+	public charactersCopy_reference(): string[] {
+		return [...this.characters()];
+	}
+
 	public static fromString(
 		value: string,
 		format?: FormattedTextAsTree.CharacterFormat,
@@ -70,7 +107,7 @@ class TextNode
 		});
 	}
 
-	public charactersWithFormatting(): Iterable<FormattedTextAsTree.StringAtom> {
+	public charactersWithFormatting(): readonly FormattedTextAsTree.StringAtom[] {
 		return this.content;
 	}
 	public insertWithFormattingAt(
@@ -80,14 +117,25 @@ class TextNode
 		this.content.insertAt(index, TreeArrayNode.spread(additionalCharacters));
 	}
 	public formatRange(
-		startIndex: number,
-		length: number,
+		start: number | undefined,
+		end: number | undefined,
 		format: Partial<FormattedTextAsTree.CharacterFormat>,
 	): void {
+		const formatStart = start ?? 0;
+		validateIndex(formatStart, this.content, "FormattedTextAsTree.formatRange", true);
+
+		const formatEnd = Math.min(this.content.length, end ?? this.content.length);
+		validateIndexRange(
+			formatStart,
+			formatEnd,
+			this.content,
+			"FormattedTextAsTree.formatRange",
+		);
+
 		const branch = TreeAlpha.branch(this);
 
 		const applyFormatting = (): void => {
-			for (let i = startIndex; i < startIndex + length; i++) {
+			for (let i = formatStart; i < formatEnd; i++) {
 				const atom = this.content[i];
 				if (atom === undefined) {
 					throw new UsageError("Index out of bounds while formatting text range.");
@@ -149,7 +197,61 @@ function textAtomsFromString(
 	return result;
 }
 
-class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.StringAtom]) {}
+class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.StringAtom]) {
+	public withBorrowedSequenceCursor<T>(f: (cursor: ITreeCursorSynchronous) => T): T {
+		const innerNode = getInnerNode(this);
+		// Since the cursor will be used to read content from the tree and won't track observations,
+		// treat it as if it observed the whole subtree.
+		currentObserver?.observeNodeDeep(innerNode);
+		const cursor = innerNode.borrowCursor();
+		cursor.enterField(EmptyKey);
+		const result = f(cursor);
+		cursor.exitField();
+		return result;
+	}
+
+	public charactersCopy(): string[] {
+		return this.withBorrowedSequenceCursor((cursor) =>
+			mapCursorField(cursor, () => {
+				debugAssert(
+					() =>
+						cursor.type === FormattedTextAsTree.StringAtom.identifier ||
+						"invalid fullString type optimizations",
+				);
+				cursor.enterField(EmptyKey);
+				cursor.enterNode(0);
+				let content: string;
+				switch (cursor.type) {
+					case FormattedTextAsTree.StringTextAtom.identifier: {
+						cursor.enterField(EmptyKey);
+						cursor.enterNode(0);
+						content = cursor.value as string;
+						debugAssert(
+							() => typeof content === "string" || "invalid fullString type optimizations",
+						);
+						cursor.exitNode();
+						cursor.exitField();
+						break;
+					}
+					case FormattedTextAsTree.StringLineAtom.identifier: {
+						content = "\n";
+						break;
+					}
+					default: {
+						fail(0xcde /* Unsupported node type in text array */, () => `${cursor.type}`);
+					}
+				}
+				cursor.exitNode();
+				cursor.exitField();
+				return content;
+			}),
+		);
+	}
+
+	public fullString(): string {
+		return this.charactersCopy().join("");
+	}
+}
 
 /**
  * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
@@ -284,11 +386,15 @@ export namespace FormattedTextAsTree {
 		defaultFormat: CharacterFormat;
 
 		/**
-		 * Gets an iterable over the characters currently in the text.
+		 * Gets an array type view of the characters currently in the text.
 		 * @remarks
 		 * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.
+		 * @privateRemarks
+		 * Currently this is implemented by a node and changes with the text over time.
+		 * We might not want to leak a node like this in the API.
+		 * Providing a way to index and iterate separately might be better.
 		 */
-		charactersWithFormatting(): Iterable<StringAtom>;
+		charactersWithFormatting(): readonly StringAtom[];
 
 		/**
 		 * Insert a range of characters into the string based on character index.
@@ -310,11 +416,17 @@ export namespace FormattedTextAsTree {
 
 		/**
 		 * Apply formatting to a range of characters based on character index.
-		 * @param startIndex - The starting index of the range to format.
-		 * @param length - The number of characters to format.
+		 * @param startIndex - The starting index (inclusive) of the range to format.
+		 * @param endIndex - The ending index (exclusive) of the range to format.
 		 * @param format - The formatting to apply to the specified range.
+		 * @remarks
+		 * The start and end behave the same as in {@link (TreeArrayNode:interface).removeRange}.
 		 */
-		formatRange(startIndex: number, length: number, format: Partial<CharacterFormat>): void;
+		formatRange(
+			startIndex: number | undefined,
+			endIndex: number | undefined,
+			format: Partial<CharacterFormat>,
+		): void;
 	}
 
 	/**

package/src/treeFactory.ts

@@ -26,9 +26,7 @@ import {
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
 import {
-	editManagerFormatVersionSelectorForDetachedRootEditing,
 	editManagerFormatVersionSelectorForSharedBranches,
-	messageFormatVersionSelectorForDetachedRootEditing,
 	messageFormatVersionSelectorForSharedBranches,
 } from "./shared-tree-core/index.js";
 import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
@@ -214,17 +212,12 @@ export function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInt
 }
 
 function resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {
-	if (options.enableSharedBranches === true && options.enableDetachedRootEditing === true) {
-		throw new UsageError(
-			"enableDetachedRootEditing cannot be used with enableSharedBranches.",
-		);
-	}
-	if (options.enableSharedBranches === true) {
+	const enableSharedBranches = options.enableSharedBranches ?? false;
+
+	if (enableSharedBranches) {
 		return sharedBranchesOptions;
 	}
-	if (options.enableDetachedRootEditing === true) {
-		return detachRootEditingOptions;
-	}
+
 	return {};
 }
 
@@ -232,8 +225,3 @@ const sharedBranchesOptions: SharedTreeOptionsInternal = {
 	messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
 	editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
 };
-const detachRootEditingOptions: SharedTreeOptionsInternal = {
-	messageFormatSelector: messageFormatVersionSelectorForDetachedRootEditing,
-	editManagerFormatSelector: editManagerFormatVersionSelectorForDetachedRootEditing,
-	enableDetachedRootEditing: true,
-};

package/src/util/index.ts

@@ -135,10 +135,7 @@ export {
 export {
 	RangeMap,
 	type RangeQueryResult,
-	type RangeQueryResultFragment,
-	type RangeQueryEntry,
 	newIntegerRangeMap,
-	areAdjacentIntegerRanges,
 } from "./rangeMap.js";
 
 export {