@fluidframework/tree 2.81.1 → 2.83.0

package/src/text/textDomainFormatted.ts

@@ -7,6 +7,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { EmptyKey } from "../core/index.js";
+import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	enumFromStrings,
 	eraseSchemaDetails,
@@ -83,25 +84,44 @@ class TextNode
 		length: number,
 		format: Partial<FormattedTextAsTree.CharacterFormat>,
 	): void {
-		for (let i = startIndex; i < startIndex + length; i++) {
-			const atom = this.content[i];
-			if (atom === undefined) {
-				throw new UsageError("Index out of bounds while formatting text range.");
-			}
-			for (const [key, value] of Object.entries(format) as [
-				keyof FormattedTextAsTree.CharacterFormat,
-				unknown,
-			][]) {
-				// Object.entries should only return string keyed enumerable own properties.
-				// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
-				assert(typeof key === "string", "Object.entries returned a non-string key.");
-				const f = FormattedTextAsTree.CharacterFormat.fields.get(key);
-				if (f === undefined) {
-					throw new UsageError(`Unknown format key: ${key}`);
+		const branch = TreeAlpha.branch(this);
+
+		const applyFormatting = (): void => {
+			for (let i = startIndex; i < startIndex + length; i++) {
+				const atom = this.content[i];
+				if (atom === undefined) {
+					throw new UsageError("Index out of bounds while formatting text range.");
+				}
+				for (const [key, value] of Object.entries(format) as [
+					keyof FormattedTextAsTree.CharacterFormat,
+					unknown,
+				][]) {
+					// Object.entries should only return string keyed enumerable own properties.
+					// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
+					assert(
+						typeof key === "string",
+						0xcc8 /* Object.entries returned a non-string key. */,
+					);
+					const f = FormattedTextAsTree.CharacterFormat.fields.get(key);
+					if (f === undefined) {
+						throw new UsageError(`Unknown format key: ${key}`);
+					}
+					// Ensures that if the input is a node, it is cloned before being inserted into the tree.
+					atom.format[key] = TreeBeta.clone(TreeBeta.create(f, value as never)) as never;
 				}
-				// Ensures that if the input is a node, it is cloned before being inserted into the tree.
-				atom.format[key] = TreeBeta.clone(TreeBeta.create(f, value as never)) as never;
 			}
+		};
+
+		if (branch === undefined) {
+			// 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.
+			applyFormatting();
+		} else {
+			// Wrap all formatting operations in a single transaction for atomicity.
+			branch.runTransaction(() => {
+				applyFormatting();
+			});
 		}
 	}
 }

package/src/util/bTreeUtils.ts

@@ -5,13 +5,14 @@
 
 import { debugAssert } from "@fluidframework/core-utils/internal";
 import { BTree, defaultComparator, type DefaultComparable } from "@tylerbu/sorted-btree-es6";
+// eslint-disable-next-line import-x/no-internal-modules
+import { union } from "@tylerbu/sorted-btree-es6/extended/union";
 
 import { brand, type Brand } from "./brand.js";
 
 /**
  * A BTree which uses tuples (arrays) as the key.
- * @remarks
- * All keys must be the same length.
+ * @remarks All keys must be the same length.
  */
 export type TupleBTree<K extends readonly DefaultComparable[], V> = Brand<
 	BTree<K, V>,
@@ -20,53 +21,75 @@ export type TupleBTree<K extends readonly DefaultComparable[], V> = Brand<
 
 /**
  * Create a new {@link TupleBTree}.
+ * @param comparator - Either a single {@link TupleComparator | comparator} for all pairs of elements in the tuple or a {@link TupleComparators | tuple of comparators} that compares each pair of corresponding elements individually.
+ * @param entries - Optional initial entries for the btree.
  */
 export function newTupleBTree<const K extends readonly DefaultComparable[], V>(
+	comparator: (a: K, b: K) => number,
 	entries?: [K, V][],
 ): TupleBTree<K, V> {
-	return brand(new BTree<K, V>(entries, compareTuples));
+	return brand(new BTree<K, V>(entries, comparator));
 }
 
+/** A comparator which can compare any pair of corresponding elements in the key of a {@link TupleBTree} */
+type TupleComparator<T extends DefaultComparable> = (a: T, b: T) => number;
+
+/**
+ * A list of comparators for a {@link TupleBTree}.
+ * @remarks For each comparator _C_ at index _i_, C compares the pair of corresponding elements at index _i_ in the key of the btree.
+ */
+type TupleComparators<T extends readonly DefaultComparable[]> = {
+	[P in keyof T]: TupleComparator<T[P]>;
+};
+
 /**
  * Compares two tuples (arrays) element by element.
- * @param arrayA - The first tuple to compare.
- * @param arrayB - The second tuple to compare.
- * @returns A negative number if arrayA \< arrayB, a positive number if arrayA \> arrayB, or 0 if they are equal.
+ * @param a - The first tuple to compare.
+ * @param b - The second tuple to compare.
+ * @returns The comparison of the first pair of elements at the same index that differ, or 0 if all elements are equal.
+ * @remarks The tuples must be the same length and have the same type of elements in the same order.
  */
-function compareTuples(
-	arrayA: readonly DefaultComparable[],
-	arrayB: readonly DefaultComparable[],
-): number {
-	debugAssert(
-		() =>
-			arrayA.length === arrayB.length || "compareTuples requires arrays of the same length",
-	);
-	for (let i = 0; i < arrayA.length; i++) {
-		const result = defaultComparator(arrayA[i], arrayB[i]);
-		if (result !== 0) {
-			return result;
+export function createTupleComparator<const K extends readonly DefaultComparable[]>(
+	compare: TupleComparator<K[number]> | TupleComparators<K> = defaultComparator,
+): (a: K, b: K) => number {
+	return (a: K, b: K): number => {
+		debugAssert(
+			() => a.length === b.length || "compareTuples requires arrays of the same length",
+		);
+		const comparators = typeof compare === "function" ? undefined : compare;
+		for (let i = 0; i < a.length; i++) {
+			const comparator = comparators?.[i] ?? (compare as TupleComparator<K[number]>);
+			const result = comparator(a[i], b[i]);
+			if (result !== 0) {
+				return result;
+			}
 		}
-	}
-	return 0;
+		return 0;
+	};
 }
 
-export function mergeTupleBTrees<K extends readonly DefaultComparable[], V>(
-	tree1: TupleBTree<K, V> | undefined,
+/**
+ * Merge the entries of two {@link TupleBTree}s.
+ * @param tree1 - The first btree.
+ * @param tree2 - The second btree.
+ * This always returns a new btree and does not modify either input.
+ * @param preferLeft - If true, colliding keys will use the value from `tree1`, otherwise the value from `tree2` is used.
+ */
+export function mergeTupleBTrees<const K extends readonly DefaultComparable[], V>(
+	tree1: TupleBTree<K, V>,
 	tree2: TupleBTree<K, V> | undefined,
 	preferLeft = true,
 ): TupleBTree<K, V> {
-	if (tree1 === undefined) {
-		return tree2 === undefined ? newTupleBTree<K, V>() : brand(tree2.clone());
-	}
-
-	const result: TupleBTree<K, V> = brand(tree1.clone());
 	if (tree2 === undefined) {
-		return result;
+		return brand(tree1.clone());
 	}
 
-	for (const [key, value] of tree2.entries()) {
-		result.set(key, value, !preferLeft);
-	}
+	// Use efficient union operation from sorted-btree 2.x
+	const result = union<BTree<K, V>, K, V>(
+		tree1 as BTree<K, V>,
+		tree2 as BTree<K, V>,
+		(_key, val1, val2) => (preferLeft ? val1 : val2),
+	);
 
-	return result;
+	return brand(result);
 }

package/src/util/brand.ts

@@ -82,23 +82,15 @@ export abstract class BrandedType<out ValueType, Name> {
  * Implementation detail of type branding. Should not be used directly outside this file,
  * but shows up as part of branded types so API-Extractor requires it to be exported.
  */
-export type ValueFromBranded<T extends BrandedType<unknown, unknown>> = T extends BrandedType<
-	infer ValueType,
-	unknown
->
-	? ValueType
-	: never;
+export type ValueFromBranded<T extends BrandedType<unknown, unknown>> =
+	T extends BrandedType<infer ValueType, unknown> ? ValueType : never;
 
 /**
  * Implementation detail of type branding. Should not be used directly outside this file,
  * but shows up as part of branded types so API-Extractor requires it to be exported.
  */
-export type NameFromBranded<T extends BrandedType<unknown, unknown>> = T extends BrandedType<
-	unknown,
-	infer Name
->
-	? Name
-	: never;
+export type NameFromBranded<T extends BrandedType<unknown, unknown>> =
+	T extends BrandedType<unknown, infer Name> ? Name : never;
 
 /**
  * Adds a type {@link Brand} to a value.

package/src/util/brandedMap.ts

@@ -19,12 +19,8 @@ import { getOrCreate } from "./utils.js";
 export type BrandedKey<TKey, TContent> = Brand<TKey, ["BrandedKey", Invariant<TContent>]>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<
-	unknown,
-	infer TContent
->
-	? TContent
-	: never;
+export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> =
+	TKey extends BrandedKey<unknown, infer TContent> ? TContent : never;
 
 /**
  * A Map where the keys carry the types of values which they correspond to.

package/src/util/breakable.ts

@@ -215,7 +215,7 @@ export function breakingClass<Target extends abstract new (...args: any[]) => Wi
 	// Avoiding wrapping the constructor also avoids messing up the displayed name in the debugger.
 	const doNotWrap: Set<string | symbol> = new Set(["constructor"]);
 
-	let prototype: object | null = target.prototype;
+	let prototype: object | null = target.prototype as object;
 	while (prototype !== null) {
 		for (const key of Reflect.ownKeys(prototype)) {
 			if (!doNotWrap.has(key)) {
@@ -228,7 +228,8 @@ export function breakingClass<Target extends abstract new (...args: any[]) => Wi
 					!isBreaker(descriptor.value)
 				) {
 					// This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor
-					descriptor.value = breakingMethod(descriptor.value);
+					const method = descriptor.value as (...args: unknown[]) => unknown;
+					descriptor.value = breakingMethod(method);
 					Object.defineProperty(DecoratedBreakable.prototype, key, descriptor);
 				}
 			}

package/src/util/index.ts

@@ -89,14 +89,15 @@ export {
 	objectToMap,
 	invertMap,
 	oneFromIterable,
-	type Named,
-	compareNamed,
 	disposeSymbol,
 	type IDisposable,
 	capitalize,
 	assertValidRangeIndices,
 	transformObjectMap,
+	compareNumbers,
+	comparePartialNumbers,
 	compareStrings,
+	comparePartialStrings,
 	find,
 	count,
 	getLast,
@@ -153,7 +154,12 @@ export {
 	breakingClass,
 } from "./breakable.js";
 
-export { type TupleBTree, newTupleBTree, mergeTupleBTrees } from "./bTreeUtils.js";
+export {
+	type TupleBTree,
+	newTupleBTree,
+	mergeTupleBTrees,
+	createTupleComparator,
+} from "./bTreeUtils.js";
 
 export { cloneWithReplacements } from "./cloneWithReplacements.js";
 

package/src/util/opaque.ts

@@ -24,12 +24,8 @@ import type { isAny } from "./typeCheck.js";
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Opaque<T extends Brand<any, unknown>> = T extends BrandedType<
-	infer ValueType,
-	infer Name
->
-	? BrandedType<ValueType, Name>
-	: never;
+export type Opaque<T extends Brand<any, unknown>> =
+	T extends BrandedType<infer ValueType, infer Name> ? BrandedType<ValueType, Name> : never;
 
 /**
  * See {@link extractFromOpaque}.

package/src/util/rangeMap.ts

@@ -5,6 +5,8 @@
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
+// eslint-disable-next-line import-x/no-internal-modules
+import { union } from "@tylerbu/sorted-btree-es6/extended/union";
 
 /**
  * RangeMap represents a mapping from keys of type K to values of type V or undefined.
@@ -171,18 +173,22 @@ export class RangeMap<K, V> {
 	 *
 	 * @param start - The start of the range to delete (inclusive).
 	 * @param length - The length of the range to delete.
+	 * @returns The number of keys/value pairs deleted (integer between 0 and `length`, inclusive).
 	 */
-	public delete(start: K, length: number): void {
+	public delete(start: K, length: number): number {
+		let deleteCount = 0;
 		const lastDeleteKey = this.offsetKey(start, length - 1);
 		for (const { start: key, length: entryLength, value } of this.getIntersectingEntries(
 			start,
 			length,
 		)) {
+			deleteCount += entryLength;
 			this.tree.delete(key);
 			const lengthBefore = this.subtractKeys(start, key);
 			if (lengthBefore > 0) {
 				// A portion of this entry comes before the deletion range, so we reinsert that portion.
 				this.tree.set(key, { length: lengthBefore, value });
+				deleteCount -= lengthBefore;
 			}
 
 			const lastEntryKey = this.offsetKey(key, entryLength - 1);
@@ -195,8 +201,10 @@ export class RangeMap<K, V> {
 					length: lengthAfter,
 					value: this.offsetValue(value, difference),
 				});
+				deleteCount -= lengthAfter;
 			}
 		}
+		return deleteCount;
 	}
 
 	public clone(): RangeMap<K, V> {
@@ -218,12 +226,13 @@ export class RangeMap<K, V> {
 
 		const merged = new RangeMap<K, V>(a.offsetKey, a.subtractKeys, a.offsetValue);
 
-		// TODO: Is there a good pattern that lets us make `tree` readonly?
-		merged.tree = a.tree.clone();
-		for (const [key, value] of b.tree.entries()) {
-			// TODO: Handle key collisions
-			merged.tree.set(key, value);
-		}
+		merged.tree = union<BTree<K, RangeEntry<V>>, K, RangeEntry<V>>(
+			a.tree,
+			b.tree,
+			(_key, _val1, val2) => {
+				return val2;
+			},
+		);
 
 		return merged;
 	}
@@ -321,15 +330,15 @@ export interface RangeQueryEntry<K, V> extends RangeQueryResult<K, V> {
 	readonly value: V;
 }
 
-export function newIntegerRangeMap<V>(): RangeMap<number, V> {
+export function newIntegerRangeMap<V, K extends number = number>(): RangeMap<K, V> {
 	return new RangeMap(offsetInteger, subtractIntegers);
 }
 
-function offsetInteger(key: number, offset: number): number {
-	return key + offset;
+function offsetInteger<K extends number>(key: K, offset: number): K {
+	return (key + offset) as K;
 }
 
-function subtractIntegers(a: number, b: number): number {
+function subtractIntegers<K extends number>(a: K, b: K): number {
 	return a - b;
 }
 

package/src/util/readSnapshotBlob.ts

@@ -14,12 +14,12 @@ import type { JsonCompatible } from "./utils.js";
 /**
  * Reads and parses a snapshot blob from storage service.
  */
-export const readAndParseSnapshotBlob = async <T extends JsonCompatible<IFluidHandle>>(
+export const readAndParseSnapshotBlob = async (
 	blobPath: string,
 	service: IChannelStorageService,
 	parse: SummaryElementParser,
-): Promise<T> => {
+): Promise<JsonCompatible<IFluidHandle>> => {
 	const treeBuffer = await service.readBlob(blobPath);
 	const treeBufferString = bufferToString(treeBuffer, "utf8");
-	return parse(treeBufferString) as T;
+	return parse(treeBufferString) as JsonCompatible<IFluidHandle>;
 };

package/src/util/typeCheck.ts

@@ -154,22 +154,24 @@ export type isAssignableTo<Source, Destination> = [Source] extends [Destination]
 /**
  * Returns a type parameter that is true iff Subset is a strict subset of Superset.
  */
-export type isStrictSubset<Subset, Superset> = isAssignableTo<Subset, Superset> extends false
-	? false
-	: isAssignableTo<Superset, Subset> extends true
+export type isStrictSubset<Subset, Superset> =
+	isAssignableTo<Subset, Superset> extends false
 		? false
-		: true;
+		: isAssignableTo<Superset, Subset> extends true
+			? false
+			: true;
 
 /**
  * Returns a type parameter that is true iff A and B are assignable to each other, and neither is any.
  * This is useful for checking if the output of a type meta-function is the expected type.
  * @internal
  */
-export type areSafelyAssignable<A, B> = eitherIsAny<A, B> extends true
-	? false
-	: isAssignableTo<A, B> extends true
-		? isAssignableTo<B, A>
-		: false;
+export type areSafelyAssignable<A, B> =
+	eitherIsAny<A, B> extends true
+		? false
+		: isAssignableTo<A, B> extends true
+			? isAssignableTo<B, A>
+			: false;
 
 /**
  * Returns a type parameter that is true iff A is any or B is any.

package/src/util/utils.ts

@@ -4,8 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { Type } from "@sinclair/typebox";
-import structuredClone from "@ungap/structured-clone";
+import { Type, type TUnsafe } from "@sinclair/typebox";
 
 /**
  * Subset of Map interface.
@@ -45,7 +44,7 @@ export function asMutable<T>(readonly: T): Mutable<T> {
 	return readonly as Mutable<T>;
 }
 
-export const clone = structuredClone;
+export { default as clone } from "@ungap/structured-clone";
 
 /**
  * Checks whether or not the given object is a `readonly` array.
@@ -377,7 +376,8 @@ export type JsonCompatibleReadOnlyObject = { readonly [P in string]?: JsonCompat
  * expressed using composition of schemas for runtime validation, even if we don't think making the types
  * generic is worth the maintenance cost.
  */
-export const JsonCompatibleReadOnlySchema = Type.Any();
+export const JsonCompatibleReadOnlySchema =
+	Type.Any() as unknown as TUnsafe<JsonCompatibleReadOnly>;
 
 /**
  * Returns if a particular json compatible value is an object.
@@ -471,8 +471,11 @@ export function transformObjectMap<
 >(
 	objectMap: Record<MapKey, MapValue>,
 	transformer: (value: MapValue, key: MapKey) => NewMapValue,
-): Record<MapKey, MapValue> {
-	const output: Record<MapKey, MapValue> = Object.create(null);
+): Record<MapKey, NewMapValue> {
+	const output: Record<MapKey, NewMapValue> = Object.create(null) as Record<
+		MapKey,
+		NewMapValue
+	>;
 	// This function must only be used with objects specifically intended to encode map like information.
 	for (const key of Object.keys(objectMap)) {
 		const element = objectMap[key as MapKey];
@@ -500,27 +503,6 @@ export function invertMap<Key, Value>(input: Map<Key, Value>): Map<Value, Key> {
 	return result;
 }
 
-/**
- * Type with a name describing what it is.
- * Typically used with values (like schema) that can be stored in a map, but in some representations have their name/key as a field.
- */
-export interface Named<TName> {
-	readonly name: TName;
-}
-
-/**
- * Order {@link Named} objects by their name.
- */
-export function compareNamed(a: Named<string>, b: Named<string>): -1 | 0 | 1 {
-	if (a.name < b.name) {
-		return -1;
-	}
-	if (a.name > b.name) {
-		return 1;
-	}
-	return 0;
-}
-
 /**
  * Placeholder for `Symbol.dispose`.
  * @privateRemarks
@@ -570,12 +552,59 @@ export function capitalize<S extends string>(s: S): Capitalize<S> {
 }
 
 /**
- * Compares strings lexically to form a strict partial ordering.
+ * Compares two numbers to form a strict total ordering.
+ * @remarks NaN is treated as less than all other numbers and equal to itself.
+ * Infinity is considered equal to itself.
  */
+export function compareNumbers<T extends number>(a: T, b: T): number {
+	if (Number.isNaN(a)) {
+		return Number.isNaN(b) ? 0 : -1;
+	} else if (Number.isNaN(b)) {
+		return 1;
+	} else if (a === b) {
+		return 0; // Infinity - Infinity = NaN (not 0), so use explicit comparison
+	}
+	return a - b;
+}
+
+/**
+ * Compares two numbers to form a strict total ordering while allowing for `undefined` values.
+ * @remarks `undefined` is considered less than any number and equal to itself.
+ * NaN is treated as less than all other numbers (but greater than undefined) and equal to itself.
+ */
+export function comparePartialNumbers<T extends number>(
+	a: T | undefined,
+	b: T | undefined,
+): number {
+	if (a === undefined) {
+		return b === undefined ? 0 : -1;
+	} else if (b === undefined) {
+		return 1;
+	}
+	return compareNumbers(a, b);
+}
+
+/** Compares two strings lexically to form a strict total ordering. */
 export function compareStrings<T extends string>(a: T, b: T): number {
 	return a > b ? 1 : a === b ? 0 : -1;
 }
 
+/**
+ * Compares two strings lexically to form a strict total ordering while allowing for `undefined` values.
+ * @remarks `undefined` is considered less than any string and equal to itself.
+ */
+export function comparePartialStrings<T extends string>(
+	a: T | undefined,
+	b: T | undefined,
+): number {
+	if (a === undefined) {
+		return b === undefined ? 0 : -1;
+	} else if (b === undefined) {
+		return 1;
+	}
+	return compareStrings(a, b);
+}
+
 /**
  * Defines a property on an object that is lazily initialized and cached.
  * @remarks This is useful for properties that are expensive to compute and it is not guaranteed that they will be accessed.

package/api-extractor-lint.json

@@ -1,4 +0,0 @@
-{
-	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-lint.esm.primary.json"
-}

package/biome.jsonc

@@ -1,4 +0,0 @@
-{
-	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
-	"extends": ["../../../biome.jsonc"]
-}