@fluidframework/tree 2.90.0 → 2.92.0

package/src/text/textDomainFormatted.ts

@@ -6,8 +6,13 @@
 import { assert, compareArrays, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
-import { currentObserver } from "../feature-libraries/index.js";
+import {
+	EmptyKey,
+	forEachNodeSubsequence,
+	type FieldKey,
+	type ITreeCursorSynchronous,
+} from "../core/index.js";
+import { currentObserver, buildNodeComparator } from "../feature-libraries/index.js";
 import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	enumFromStrings,
@@ -24,7 +29,7 @@ import type {
 	TreeNodeFromImplicitAllowedTypes,
 	WithType,
 } from "../simple-tree/index.js";
-import { mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
+import { brand, mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
 
 import { charactersFromString, type TextAsTree } from "./textDomain.js";
 
@@ -172,6 +177,12 @@ class TextNode
 			});
 		}
 	}
+	public getUniformRun(startIndex: number, endIndex?: number): number {
+		return this.content.getUniformRun(startIndex, endIndex);
+	}
+	public getString(startIndex: number, endIndex?: number): string {
+		return this.content.getString(startIndex, endIndex);
+	}
 }
 
 const defaultFormat = {
@@ -182,6 +193,8 @@ const defaultFormat = {
 	font: "Arial",
 } as const;
 
+const formatKey: FieldKey = brand("format");
+
 function textAtomsFromString(
 	value: string,
 	format: FormattedTextAsTree.CharacterFormat,
@@ -210,9 +223,10 @@ class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.Str
 		return result;
 	}
 
-	public charactersCopy(): string[] {
-		return this.withBorrowedSequenceCursor((cursor) =>
-			mapCursorField(cursor, () => {
+	private getCharactersSubarray(startIndex: number, endIndex: number): string[] {
+		return this.withBorrowedSequenceCursor((cursor) => {
+			const result: string[] = [];
+			forEachNodeSubsequence(cursor, startIndex, endIndex, () => {
 				debugAssert(
 					() =>
 						cursor.type === FormattedTextAsTree.StringAtom.identifier ||
@@ -243,14 +257,80 @@ class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.Str
 				}
 				cursor.exitNode();
 				cursor.exitField();
-				return content;
-			}),
-		);
+				result.push(content);
+			});
+			return result;
+		});
+	}
+
+	public charactersCopy(): string[] {
+		return this.getCharactersSubarray(0, this.length);
 	}
 
 	public fullString(): string {
 		return this.charactersCopy().join("");
 	}
+
+	public getString(startIndex: number, endIndex: number = this.length): string {
+		validateIndexRange(startIndex, endIndex, this, "FormattedTextAsTree.getString");
+		return this.getCharactersSubarray(startIndex, endIndex).join("");
+	}
+
+	public getUniformRun(startIndex: number, endIndex: number = this.length): number {
+		validateIndexRange(startIndex, endIndex, this, "FormattedTextAsTree.getUniformRun");
+		if (endIndex === startIndex) {
+			throw new UsageError("endIndex must be greater than startIndex for getUniformRun.");
+		}
+		const arrayLength = this.length;
+		return this.withBorrowedSequenceCursor((cursor) => {
+			cursor.enterNode(startIndex);
+
+			// Capture the content type of the first atom
+			cursor.enterField(EmptyKey);
+			cursor.enterNode(0);
+			const contentType = cursor.type;
+			cursor.exitNode();
+			cursor.exitField();
+
+			// Build a comparator from the format subtree of the first atom
+			// This compares by field key
+			cursor.enterField(formatKey);
+			cursor.enterNode(0);
+			const formatComparator = buildNodeComparator(cursor);
+			cursor.exitNode();
+			cursor.exitField();
+
+			let runLength = 1;
+			const limit = Math.min(endIndex, arrayLength) - startIndex;
+
+			while (runLength < limit && cursor.nextNode()) {
+				// Compare atom type
+				cursor.enterField(EmptyKey);
+				cursor.enterNode(0);
+				const typeMatches = cursor.type === contentType;
+				cursor.exitNode();
+				cursor.exitField();
+				if (!typeMatches) {
+					break;
+				}
+
+				// Compare format subtree using the compiled comparator
+				cursor.enterField(formatKey);
+				cursor.enterNode(0);
+				const formatMatches = formatComparator(cursor);
+				cursor.exitNode();
+				cursor.exitField();
+
+				if (formatMatches !== true) {
+					break;
+				}
+
+				runLength++;
+			}
+			cursor.exitNode();
+			return runLength;
+		});
+	}
 }
 
 /**
@@ -305,6 +385,11 @@ export namespace FormattedTextAsTree {
 		"h4",
 		"h5",
 		"li",
+		"ol",
+		"checked",
+		"unchecked",
+		"blockquote",
+		"codeBlock",
 	]);
 	/**
 	 * {@inheritdoc FormattedTextAsTree.(LineTag:variable)}
@@ -316,12 +401,16 @@ export namespace FormattedTextAsTree {
 	 * Unit in the string representing a new line character with line formatting.
 	 * @remarks
 	 * This aligns with how Quill represents line formatting.
-	 * Note that not all new lines will use this,
-	 * but only ones using this can have line specific formatting.
+	 * Quill formats line attributes (headers, list, blockquote, etc... ) on the newline character
+	 * and only lines using this atom can have line-specific formatting.
+	 * The optional indent level mirrors Quill's indent attribute,
+	 * which is applies to the line before the line break.
+	 * Any tagged line can be indented independently.
 	 * @internal
 	 */
 	export class StringLineAtom extends sf.object("StringLineAtom", {
 		tag: LineTag.schema,
+		indent: SchemaFactory.number,
 	}) {
 		public readonly content = "\n";
 	}
@@ -427,6 +516,19 @@ export namespace FormattedTextAsTree {
 			endIndex: number | undefined,
 			format: Partial<CharacterFormat>,
 		): void;
+
+		/**
+		 * Returns the length of the run of characters starting at `startIndex` which have the same formatting and atom type, up to `endIndex`.
+		 * @param startIndex - The starting index of the run.
+		 * @param endIndex - The ending index (exclusive) of the run. Defaults to the end of the text.
+		 */
+		getUniformRun(startIndex: number, endIndex?: number): number;
+		/**
+		 * Returns a substring of the text from `startIndex` to `endIndex`
+		 * @param startIndex - starting index (inclusive)
+		 * @param endIndex - Optional ending index (exclusive). Defaults to the end of the text.
+		 */
+		getString(startIndex: number, endIndex?: number): string;
 	}
 
 	/**

package/src/treeFactory.ts

@@ -16,7 +16,7 @@ import {
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { FluidClientVersion } from "./codec/index.js";
+import { FluidClientVersion, type FormatVersion } from "./codec/index.js";
 import {
 	SharedTreeKernel,
 	type ITreePrivate,
@@ -26,8 +26,10 @@ import {
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
 import {
-	editManagerFormatVersionSelectorForSharedBranches,
-	messageFormatVersionSelectorForSharedBranches,
+	editManagerCodecName,
+	EditManagerFormatVersion,
+	messageCodecName,
+	MessageFormatVersion,
 } from "./shared-tree-core/index.js";
 import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
 import type { ITree } from "./simple-tree/index.js";
@@ -222,6 +224,9 @@ function resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInte
 }
 
 const sharedBranchesOptions: SharedTreeOptionsInternal = {
-	messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
-	editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
+	writeVersionOverrides: new Map<string, FormatVersion>([
+		[editManagerCodecName, EditManagerFormatVersion.vSharedBranches],
+		[messageCodecName, MessageFormatVersion.vSharedBranches],
+	]),
+	allowPossiblyIncompatibleWriteVersionOverrides: true,
 };

package/src/util/rangeMap.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
 
 /**
@@ -29,13 +29,13 @@ export class RangeMap<K, V> {
 	 * When writing to a range of keys starting with `start`, the value of the nth key is interpreted to be
 	 * `offsetValue(firstValue, n - 1)`.
 	 * The same logic should be used when interpreting the values for keys after the first in a
-	 * `RangeQueryResult` or `RangeQueryEntry`.
+	 * `RangeQueryResult` or `RangeMapEntry`.
 	 *
 	 * If `offsetValue` is left unspecified, all keys in a block will be given the same value.
 	 */
 	public constructor(
-		private readonly offsetKey: (key: K, offset: number) => K,
-		private readonly subtractKeys: (a: K, b: K) => number,
+		public readonly offsetKey: (key: K, offset: number) => K,
+		public readonly subtractKeys: (a: K, b: K) => number,
 		public readonly offsetValue: (value: V, offset: number) => V = defaultValueOffsetFn,
 	) {
 		this.tree = new BTree(undefined, subtractKeys);
@@ -44,8 +44,8 @@ export class RangeMap<K, V> {
 	/**
 	 * Retrieves all entries from the RangeMap.
 	 */
-	public entries(): RangeQueryEntry<K, V>[] {
-		const entries: RangeQueryEntry<K, V>[] = [];
+	public entries(): RangeMapEntry<K, V>[] {
+		const entries: RangeMapEntry<K, V>[] = [];
 		for (const [start, entry] of this.tree.entries()) {
 			entries.push({ start, length: entry.length, value: entry.value });
 		}
@@ -62,34 +62,22 @@ export class RangeMap<K, V> {
 	 *
 	 * @param start - The first key in the range being queried
 	 * @param length - The length of the query range
-	 * @returns A list of entries, each describing the value for some subrange of the query.
-	 * The entries are in the same order as the keys, and there is an entry for every key with a non `undefined` value.
+	 * @returns A list of fragments, each describing the value for a subrange of the query.
+	 * The fragments are in the same order as the keys.
+	 * The key for each fragment is `start` offset by `fragment.offset`.
 	 */
-	public getAll(start: K, length: number): RangeQueryEntry<K, V>[] {
-		const entries = this.getIntersectingEntries(start, length);
-		if (entries.length === 0) {
-			return entries;
+	public getAll(start: K, length: number): RangeQueryResultFragment<V | undefined>[] {
+		let offset = 0;
+		const results: RangeQueryResultFragment<V | undefined>[] = [];
+
+		while (offset < length) {
+			const key = this.offsetKey(start, offset);
+			const result = this.getFirst(key, length - offset);
+			results.push({ offset, value: result.value, length: result.length });
+			offset += result.length;
 		}
 
-		const firstEntry = entries[0] ?? oob();
-		const lengthBefore = this.subtractKeys(start, firstEntry.start);
-		if (lengthBefore > 0) {
-			entries[0] = {
-				start,
-				length: firstEntry.length - lengthBefore,
-				value: this.offsetValue(firstEntry.value, lengthBefore),
-			};
-		}
-
-		const lastEntry = entries[entries.length - 1] ?? oob();
-		const lastEntryKey = this.offsetKey(lastEntry.start, lastEntry.length - 1);
-		const lastQueryKey = this.offsetKey(start, length - 1);
-		const lengthAfter = this.subtractKeys(lastEntryKey, lastQueryKey);
-		if (lengthAfter > 0) {
-			entries[entries.length - 1] = { ...lastEntry, length: lastEntry.length - lengthAfter };
-		}
-
-		return entries;
+		return results;
 	}
 
 	/**
@@ -100,7 +88,7 @@ export class RangeMap<K, V> {
 	 * @returns A RangeQueryResult containing the value associated with `start`,
 	 * and the number of consecutive keys with that same value (at least 1, at most `length`).
 	 */
-	public getFirst(start: K, length: number): RangeQueryResult<K, V> {
+	public getFirst(start: K, length: number): RangeQueryResult<V | undefined> {
 		{
 			// We first check for an entry with a key less than or equal to `start`.
 			const entry = this.tree.getPairOrNextLower(start);
@@ -114,7 +102,6 @@ export class RangeMap<K, V> {
 				if (overlappingLength > 0) {
 					return {
 						value: this.offsetValue(value, lengthBeforeQuery),
-						start,
 						length: overlappingLength,
 					};
 				}
@@ -130,11 +117,11 @@ export class RangeMap<K, V> {
 
 				const lastQueryKey = this.offsetKey(start, length - 1);
 				if (this.le(entryKey, lastQueryKey)) {
-					return { value: undefined, start, length: this.subtractKeys(entryKey, start) };
+					return { value: undefined, length: this.subtractKeys(entryKey, start) };
 				}
 			}
 
-			return { value: undefined, start, length };
+			return { value: undefined, length };
 		}
 	}
 
@@ -213,9 +200,14 @@ export class RangeMap<K, V> {
 
 	/**
 	 * Returns a new map which contains the entries from both input maps.
-	 * Whenever both maps contain entires for the same keys, the value from map `b` is used in the returned map.
+	 * Whenever both maps contain entries for the same keys, the value is determined by calling `mergeFunc`.
+	 * By default, `mergeFunc` chooses the value from `b`.
 	 */
-	public static union<K, V>(a: RangeMap<K, V>, b: RangeMap<K, V>): RangeMap<K, V> {
+	public static union<K, V>(
+		a: RangeMap<K, V>,
+		b: RangeMap<K, V>,
+		mergeFunc: (key: K, valueA: V, valueB: V) => V = (_k, _a, valB) => valB,
+	): RangeMap<K, V> {
 		assert(
 			a.offsetKey === b.offsetKey &&
 				a.subtractKeys === b.subtractKeys &&
@@ -224,15 +216,22 @@ export class RangeMap<K, V> {
 		);
 
 		const merged = a.clone();
-		for (const entry of b.entries()) {
-			merged.set(entry.start, entry.length, entry.value);
+		for (const entryB of b.entries()) {
+			for (const entryA of a.getAll(entryB.start, entryB.length)) {
+				const key = b.offsetKey(entryB.start, entryA.offset);
+				const valueB = b.offsetValue(entryB.value, entryA.offset);
+				const mergedValue =
+					entryA.value === undefined ? valueB : mergeFunc(key, entryA.value, valueB);
+
+				merged.set(key, entryA.length, mergedValue);
+			}
 		}
 
 		return merged;
 	}
 
-	private getIntersectingEntries(start: K, length: number): RangeQueryEntry<K, V>[] {
-		const entries: RangeQueryEntry<K, V>[] = [];
+	private getIntersectingEntries(start: K, length: number): RangeMapEntry<K, V>[] {
+		const entries: RangeMapEntry<K, V>[] = [];
 		const lastQueryKey = this.offsetKey(start, length - 1);
 		{
 			const entry = this.tree.getPairOrNextLower(start);
@@ -300,17 +299,11 @@ interface RangeEntry<V> {
 /**
  * Describes the result of a range query, including the value and length of the matching prefix.
  */
-export interface RangeQueryResult<K, V> {
-	/**
-	 * The key for the first element in the range.
-	 */
-	readonly start: K;
-
+export interface RangeQueryResult<V> {
 	/**
 	 * The value of the first key in the query range.
-	 * If no matching range is found, this will be undefined.
 	 */
-	readonly value: V | undefined;
+	readonly value: V;
 
 	/**
 	 * The length of the prefix of the query range which has the same value.
@@ -320,8 +313,19 @@ export interface RangeQueryResult<K, V> {
 	readonly length: number;
 }
 
-export interface RangeQueryEntry<K, V> extends RangeQueryResult<K, V> {
+export interface RangeQueryResultFragment<V> extends RangeQueryResult<V> {
+	/**
+	 * The offset from the query key to the key this result is associated with.
+	 * This is useful in the case where a query returns multiple `RangeQueryResults`
+	 * addressing the key range.
+	 */
+	readonly offset: number;
+}
+
+export interface RangeMapEntry<K, V> {
+	readonly start: K;
 	readonly value: V;
+	readonly length: number;
 }
 
 export function newIntegerRangeMap<V, K extends number = number>(): RangeMap<K, V> {

package/src/util/referenceCounting.ts

@@ -39,7 +39,6 @@ export interface ReferenceCounted {
  * Base class to assist with implementing ReferenceCounted.
  */
 export abstract class ReferenceCountedBase implements ReferenceCounted {
-	// eslint-disable-next-line @typescript-eslint/prefer-readonly -- false positive; modified in multiple places
 	protected constructor(private refCount: number = 1) {}
 
 	public referenceAdded(count = 1): void {

package/src/util/typeCheck.ts

@@ -84,6 +84,7 @@ export type { EnforceTypeCheckTests } from "./typeCheckTests.js";
  * See: {@link https://dev.azure.com/intentional/intent/_wiki/wikis/NP%20Platform/7146/Nominal-vs-Structural-Types}
  * @sealed @public
  */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- Intentionally empty; used as a nominal type brand.
 export interface MakeNominal {}
 
 /**

package/src/util/typeUtils.ts

@@ -191,13 +191,10 @@ export type PopUnion<
  * This implementation is inspired to those, but slightly different in implementation.
  * @system @beta
  */
-export type UnionToTuple<
-	Union,
-	A extends unknown[] = [],
-	First = PopUnion<Union>,
-> = IsUnion<Union> extends true
-	? UnionToTuple<Exclude<Union, First>, [First, ...A]>
-	: [Union, ...A];
+export type UnionToTuple<Union, A extends unknown[] = [], First = PopUnion<Union>> =
+	IsUnion<Union> extends true
+		? UnionToTuple<Exclude<Union, First>, [First, ...A]>
+		: [Union, ...A];
 
 /**
  * This is unsafe, meaning that the returned value might not match its type.

package/dist/beta.d.ts

@@ -1,152 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
- */
-
-export {
-	// #region Unrestricted APIs
-	InternalTypes,
-	// #endregion
-	 
-	// #region @public APIs
-	AllowedTypes, 
-	CommitKind, 
-	CommitMetadata, 
-	FieldKind, 
-	FieldProps, 
-	FieldSchema, 
-	FieldSchemaMetadata, 
-	ITree, 
-	ITreeConfigurationOptions, 
-	ITreeViewConfiguration, 
-	ImplicitAllowedTypes, 
-	ImplicitFieldSchema, 
-	Input, 
-	InsertableTreeFieldFromImplicitField, 
-	InsertableTreeNodeFromAllowedTypes, 
-	InsertableTreeNodeFromImplicitAllowedTypes, 
-	InsertableTypedNode, 
-	InternalTreeNode, 
-	IsListener, 
-	IsUnion, 
-	IterableTreeArrayContent, 
-	LazyItem, 
-	LeafSchema, 
-	Listenable, 
-	Listeners, 
-	MakeNominal, 
-	MapNodeInsertableData, 
-	NodeFromSchema, 
-	NodeInDocumentConstraint, 
-	NodeKind, 
-	NodeSchemaMetadata, 
-	NodeSchemaOptions, 
-	NumberKeys, 
-	ObjectFromSchemaRecord, 
-	Off, 
-	ReadonlyArrayNode, 
-	RestrictiveReadonlyRecord, 
-	RestrictiveStringRecord, 
-	Revertible, 
-	RevertibleFactory, 
-	RevertibleStatus, 
-	RunTransaction, 
-	SchemaCompatibilityStatus, 
-	SchemaFactory, 
-	SchemaFactory_base, 
-	SchemaStatics, 
-	SimpleNodeSchemaBase, 
-	System_Unsafe, 
-	TransactionConstraint, 
-	Tree, 
-	TreeArrayNode, 
-	TreeChangeEvents, 
-	TreeFieldFromImplicitField, 
-	TreeLeafValue, 
-	TreeMapNode, 
-	TreeNode, 
-	TreeNodeApi, 
-	TreeNodeFromImplicitAllowedTypes, 
-	TreeNodeSchema, 
-	TreeNodeSchemaClass, 
-	TreeNodeSchemaCore, 
-	TreeNodeSchemaNonClass, 
-	TreeObjectNode, 
-	TreeStatus, 
-	TreeView, 
-	TreeViewConfiguration, 
-	TreeViewEvents, 
-	Unenforced, 
-	Unhydrated, 
-	UnionToIntersection, 
-	ValidateRecursiveSchema, 
-	ValidateRecursiveSchemaTemplate, 
-	ViewableTree, 
-	WithType, 
-	rollback, 
-	typeSchemaSymbol,
-	// #endregion
- 
-	// #region @beta APIs
-	AllowedTypeMetadata, 
-	AllowedTypesFull, 
-	AllowedTypesFullEvaluated, 
-	AllowedTypesFullFromMixed, 
-	AllowedTypesFullFromMixedUnsafe, 
-	AllowedTypesMetadata, 
-	AnnotateAllowedTypesList, 
-	AnnotateAllowedTypesListUnsafe, 
-	AnnotatedAllowedType, 
-	AnnotatedAllowedTypeUnsafe, 
-	AnnotatedAllowedTypes, 
-	AnnotatedAllowedTypesUnsafe, 
-	CodecWriteOptionsBeta, 
-	ConciseTree, 
-	ExtensibleUnionNode, 
-	FixRecursiveArraySchema, 
-	FluidSerializableAsTree, 
-	ForestOptions, 
-	ForestType, 
-	ForestTypeExpensiveDebug, 
-	ForestTypeOptimized, 
-	ForestTypeReference, 
-	JsonCompatible, 
-	JsonCompatibleObject, 
-	KeyEncodingOptions, 
-	NodeChangedData, 
-	ObjectSchemaOptions, 
-	PopUnion, 
-	RecordNodeInsertableData, 
-	SchemaFactoryBeta, 
-	SchemaStaticsBeta, 
-	SchemaUpgrade, 
-	SharedTreeOptionsBeta, 
-	SnapshotFileSystem, 
-	SnapshotSchemaCompatibilityOptions, 
-	System_TableSchema, 
-	TableSchema, 
-	TreeBeta, 
-	TreeBranch, 
-	TreeChangeEventsBeta, 
-	TreeEncodingOptions, 
-	TreeRecordNode, 
-	TreeRecordNodeUnsafe, 
-	TreeViewBeta, 
-	UnannotateAllowedTypeUnsafe, 
-	UnannotateAllowedTypesList, 
-	UnannotateAllowedTypesListUnsafe, 
-	UnionToTuple, 
-	adaptEnum, 
-	asBeta, 
-	configuredSharedTreeBeta, 
-	createIndependentTreeBeta, 
-	enumFromStrings, 
-	singletonSchema, 
-	snapshotSchemaCompatibility
-	// #endregion
-} from "./index.js";