@fluidframework/tree 2.13.0 → 2.21.0

package/src/simple-tree/proxies.ts

@@ -24,9 +24,9 @@ import { type Mutable, fail, isReadonlyArray } from "../util/index.js";
 import {
 	getKernel,
 	type TreeNode,
-	tryGetTreeNodeFromMapNode,
 	getOrCreateNodeFromInnerNode,
 	tryUnhydratedFlexTreeNode,
+	unhydratedFlexTreeNodeToTreeNode,
 } from "./core/index.js";
 
 /**
@@ -146,7 +146,7 @@ function walkMapTree(
 		const [p, m] = next;
 		const mapTreeNode = tryUnhydratedFlexTreeNode(m);
 		if (mapTreeNode !== undefined) {
-			const treeNode = tryGetTreeNodeFromMapNode(mapTreeNode);
+			const treeNode = unhydratedFlexTreeNodeToTreeNode.get(mapTreeNode);
 			if (treeNode !== undefined) {
 				onVisitTreeNode(p, treeNode);
 			}

package/src/simple-tree/toMapTree.ts

@@ -196,7 +196,7 @@ function nodeDataToMapTree(
 			result = objectToMapTree(data, schema);
 			break;
 		default:
-			fail(`Unrecognized schema kind: ${schema.kind}.`);
+			fail("Unrecognized schema kind");
 	}
 
 	return result;

package/src/util/bTreeUtils.ts

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { BTree } from "@tylerbu/sorted-btree-es6";
+import { brand, type Brand } from "./brand.js";
+
+export type TupleBTree<K, V> = Brand<BTree<K, V>, "TupleBTree">;
+
+export function newTupleBTree<K extends readonly unknown[], V>(
+	entries?: [K, V][],
+): TupleBTree<K, V> {
+	return brand(new BTree<K, V>(entries, compareTuples));
+}
+
+// This assumes that the arrays are the same length.
+function compareTuples(arrayA: readonly unknown[], arrayB: readonly unknown[]): number {
+	for (let i = 0; i < arrayA.length; i++) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const a = arrayA[i] as any;
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const b = arrayB[i] as any;
+
+		// Less-than and greater-than always return false if either value is undefined,
+		// so we handle undefined separately, treating it as less than all other values.
+		if (a === undefined && b !== undefined) {
+			return -1;
+		} else if (b === undefined && a !== undefined) {
+			return 1;
+		} else if (a < b) {
+			return -1;
+		} else if (a > b) {
+			return 1;
+		}
+	}
+
+	return 0;
+}
+
+export function mergeTupleBTrees<K extends readonly unknown[], V>(
+	tree1: TupleBTree<K, V> | undefined,
+	tree2: TupleBTree<K, V> | undefined,
+	preferLeft = true,
+): TupleBTree<K, V> {
+	if (tree1 === undefined) {
+		return tree2 !== undefined ? brand(tree2.clone()) : newTupleBTree<K, V>();
+	}
+
+	const result: TupleBTree<K, V> = brand(tree1.clone());
+	if (tree2 === undefined) {
+		return result;
+	}
+
+	for (const [key, value] of tree2.entries()) {
+		result.set(key, value, !preferLeft);
+	}
+
+	return result;
+}

package/src/util/idAllocator.ts

@@ -26,8 +26,6 @@ export interface IdAllocationState {
 	maxId: number;
 }
 
-/**
- */
 export function idAllocatorFromMaxId(maxId: number | undefined = undefined): IdAllocator {
 	return idAllocatorFromState({ maxId: maxId ?? -1 });
 }

package/src/util/index.ts

@@ -123,6 +123,7 @@ export {
 export {
 	RangeMap,
 	type RangeQueryResult,
+	newIntegerRangeMap,
 } from "./rangeMap.js";
 
 export {
@@ -140,3 +141,5 @@ export {
 	throwIfBroken,
 	breakingClass,
 } from "./breakable.js";
+
+export { type TupleBTree, newTupleBTree, mergeTupleBTrees } from "./bTreeUtils.js";

package/src/util/rangeMap.ts

@@ -3,25 +3,93 @@
  * Licensed under the MIT License.
  */
 
-import { oob } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
+import { BTree } from "@tylerbu/sorted-btree-es6";
 
 /**
- * RangeMap represents a mapping from integers to values of type T or undefined.
+ * RangeMap represents a mapping from keys of type K to values of type V or undefined.
+ * The set of all possible keys is assumed to be fully ordered,
+ * and for each key there should be a single next higher key.
  * The values for a range of consecutive keys can be changed or queried in a single operation.
+ * The structure of the keys is described by the `offsetKey` and `subtractKeys` functions provided in the constructor.
  */
-export class RangeMap<T> {
-	private readonly entries: RangeEntry<T>[];
+export class RangeMap<K, V> {
+	private tree: BTree<K, RangeEntry<V>>;
 
-	public constructor(initialEntries?: RangeEntry<T>[]) {
-		this.entries = initialEntries ? [...initialEntries] : [];
+	/**
+	 * @param offsetKey - Function which returns a new key which is `offset` keys after `key`.
+	 * When `offset` is negative, the returned key should come before `key`.
+	 *
+	 * @param subtractKeys - Function which returns the difference between `b` and `a`.
+	 * Offsetting `b` by this difference should return `a`.
+	 * The difference can be infinite if `a` cannot be reached from `b` by offsetting,
+	 * but the difference should still be positive if `a` is larger than `b` and negative if smaller.
+	 *
+	 * @param offsetValue - Function used to associate a range of values with a range of keys.
+	 * 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`.
+	 *
+	 * 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 offsetValue: (value: V, offset: number) => V = defaultValueOffsetFn,
+	) {
+		this.tree = new BTree(undefined, subtractKeys);
 	}
 
 	/**
-	 * Retrieves all entries from the rangeMap.
-	 * @returns An array of RangeEntryResult objects, each containing the start index, length, and value of a contiguous range.
+	 * Retrieves all entries from the RangeMap.
 	 */
-	public getAllEntries(): readonly RangeQueryResult<T>[] {
-		return this.entries;
+	public entries(): RangeQueryEntry<K, V>[] {
+		const entries: RangeQueryEntry<K, V>[] = [];
+		for (const [start, entry] of this.tree.entries()) {
+			entries.push({ start, length: entry.length, value: entry.value });
+		}
+
+		return entries;
+	}
+
+	public clear(): void {
+		this.tree.clear();
+	}
+
+	/**
+	 * Retrieves the values for all keys in the query range.
+	 *
+	 * @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.
+	 */
+	public getAll(start: K, length: number): RangeQueryEntry<K, V>[] {
+		const entries = this.getIntersectingEntries(start, length);
+		if (entries.length === 0) {
+			return entries;
+		}
+
+		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;
 	}
 
 	/**
@@ -30,23 +98,44 @@ export class RangeMap<T> {
 	 * @param start - The first key in the query range.
 	 * @param length - The length of the query range.
 	 * @returns A RangeQueryResult containing the value associated with `start`,
-	 * and the number of consecutive keys with that same value.
+	 * and the number of consecutive keys with that same value (at least 1, at most `length`).
 	 */
-	public get(start: number, length: number): RangeQueryResult<T> {
-		for (const entry of this.entries) {
-			if (entry.start > start) {
-				return { value: undefined, length: Math.min(entry.start - start, length) };
-			}
+	public getFirst(start: K, length: number): RangeQueryResult<K, V> {
+		{
+			// We first check for an entry with a key less than or equal to `start`.
+			const entry = this.tree.getPairOrNextLower(start);
+			if (entry !== undefined) {
+				const entryKey = entry[0];
+				const { value, length: entryLength } = entry[1];
 
-			const lastRangeKey = entry.start + entry.length - 1;
-			if (lastRangeKey >= start) {
-				const overlapLength = lastRangeKey - start + 1;
-				return { value: entry.value, length: Math.min(overlapLength, length) };
+				const entryLastKey = this.offsetKey(entryKey, entryLength - 1);
+				const lengthBeforeQuery = this.subtractKeys(start, entryKey);
+				const overlappingLength = Math.min(this.subtractKeys(entryLastKey, start) + 1, length);
+				if (overlappingLength > 0) {
+					return {
+						value: this.offsetValue(value, lengthBeforeQuery),
+						start,
+						length: overlappingLength,
+					};
+				}
 			}
 		}
 
-		// There were no entries intersecting the query range, so the entire query range has undefined value.
-		return { value: undefined, length };
+		{
+			// There is no value associated with `start`.
+			// Now we need to determine how many of the following keys are also undefined.
+			const key = this.tree.nextHigherKey(start);
+			if (key !== undefined) {
+				const entryKey = key;
+
+				const lastQueryKey = this.offsetKey(start, length - 1);
+				if (this.le(entryKey, lastQueryKey)) {
+					return { value: undefined, start, length: this.subtractKeys(entryKey, start) };
+				}
+			}
+
+			return { value: undefined, start, length };
+		}
 	}
 
 	/**
@@ -56,74 +145,11 @@ export class RangeMap<T> {
 	 * @param length - The length of the range.
 	 * @param value - The value to associate with the range.
 	 */
-	public set(start: number, length: number, value: T | undefined): void {
-		if (value === undefined) {
-			this.delete(start, length);
-			return;
-		}
-
-		const end = start + length - 1;
-		const newEntry: RangeEntry<T> = { start, length, value };
-
-		let iBefore = -1;
-		let iAfter = this.entries.length;
-		for (const [i, entry] of this.entries.entries()) {
-			const entryLastKey = entry.start + entry.length - 1;
-			if (entryLastKey < start) {
-				iBefore = i;
-			} else if (entry.start > end) {
-				iAfter = i;
-				break;
-			}
-		}
-
-		const numOverlappingEntries = iAfter - iBefore - 1;
-		if (numOverlappingEntries === 0) {
-			this.entries.splice(iAfter, 0, newEntry);
-			return;
-		}
-
-		const iFirst = iBefore + 1;
-		const firstEntry = this.entries[iFirst] ?? oob();
-		const iLast = iAfter - 1;
-		const lastEntry = this.entries[iLast] ?? oob();
-		const lengthBeforeFirst = start - firstEntry.start;
-		const lastEntryKey = lastEntry.start + lastEntry.length - 1;
-		const lengthAfterLast = lastEntryKey - end;
-
-		if (lengthBeforeFirst > 0 && lengthAfterLast > 0 && iFirst === iLast) {
-			// The new entry fits in the middle of an existing entry.
-			// We replace the existing entry with:
-			// 1) the portion which comes before `newEntry`
-			// 2) `newEntry`
-			// 3) the portion which comes after `newEntry`
-			this.entries.splice(iFirst, 1, { ...firstEntry, length: lengthBeforeFirst }, newEntry, {
-				...lastEntry,
-				start: end + 1,
-				length: lengthAfterLast,
-			});
-			return;
-		}
-
-		if (lengthBeforeFirst > 0) {
-			this.entries[iFirst] = { ...firstEntry, length: lengthBeforeFirst };
-			// The entry at `iFirst` is no longer overlapping with `newEntry`.
-			iBefore = iFirst;
-		}
-
-		if (lengthAfterLast > 0) {
-			this.entries[iLast] = {
-				...lastEntry,
-				start: end + 1,
-				length: lengthAfterLast,
-			};
-
-			// The entry at `iLast` is no longer overlapping with `newEntry`.
-			iAfter = iLast;
+	public set(start: K, length: number, value: V | undefined): void {
+		this.delete(start, length);
+		if (value !== undefined) {
+			this.tree.set(start, { value, length });
 		}
-
-		const numContainedEntries = iAfter - iBefore - 1;
-		this.entries.splice(iBefore + 1, numContainedEntries, newEntry);
 	}
 
 	/**
@@ -146,74 +172,117 @@ export class RangeMap<T> {
 	 * @param start - The start of the range to delete (inclusive).
 	 * @param length - The length of the range to delete.
 	 */
-	public delete(start: number, length: number): void {
-		const end = start + length - 1;
-
-		let iBefore = -1;
-		let iAfter = this.entries.length;
-
-		for (const [i, entry] of this.entries.entries()) {
-			const entryLastKey = entry.start + entry.length - 1;
-			if (entryLastKey < start) {
-				iBefore = i;
-			} else if (entry.start > end) {
-				iAfter = i;
-				break;
+	public delete(start: K, length: number): void {
+		const lastDeleteKey = this.offsetKey(start, length - 1);
+		for (const { start: key, length: entryLength, value } of this.getIntersectingEntries(
+			start,
+			length,
+		)) {
+			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 });
+			}
+
+			const lastEntryKey = this.offsetKey(key, entryLength - 1);
+			const lengthAfter = this.subtractKeys(lastEntryKey, lastDeleteKey);
+			if (lengthAfter > 0) {
+				// A portion of this entry comes after the deletion range, so we reinsert that portion.
+				const newKey = this.offsetKey(lastDeleteKey, 1);
+				const difference = this.subtractKeys(newKey, key);
+				this.tree.set(newKey, {
+					length: lengthAfter,
+					value: this.offsetValue(value, difference),
+				});
 			}
 		}
+	}
+
+	public clone(): RangeMap<K, V> {
+		const cloned = new RangeMap<K, V>(this.offsetKey, this.subtractKeys, this.offsetValue);
+		cloned.tree = this.tree.clone();
+		return cloned;
+	}
 
-		const numOverlappingEntries = iAfter - iBefore - 1;
+	/**
+	 * Returns a new map which contains the entries from both input maps.
+	 */
+	public static union<K, V>(a: RangeMap<K, V>, b: RangeMap<K, V>): RangeMap<K, V> {
+		assert(
+			a.offsetKey === b.offsetKey &&
+				a.subtractKeys === b.subtractKeys &&
+				a.offsetValue === b.offsetValue,
+			0xaae /* Maps should have the same behavior */,
+		);
 
-		if (numOverlappingEntries === 0) {
-			// No entry will be removed
-			return;
+		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);
 		}
 
-		const iFirst = iBefore + 1;
-		const iLast = iAfter - 1;
-
-		for (let i = iFirst; i <= iLast; ++i) {
-			const entry = this.entries[i] ?? oob();
-			const entryLastKey = entry.start + entry.length - 1;
-			let isDirty = false;
-
-			if (entry.start >= start && entryLastKey <= end) {
-				// If the entry lies within the range to be deleted, remove it
-				this.entries.splice(i, 1);
-			} else {
-				// If the entry partially or completely overlaps with the range to be deleted
-				if (entry.start < start) {
-					// Update the endpoint and length of the portion before the range to be deleted
-					const lengthBefore = start - entry.start;
-					this.entries[i] = { ...entry, length: lengthBefore };
-					isDirty = true;
+		return merged;
+	}
+
+	private getIntersectingEntries(start: K, length: number): RangeQueryEntry<K, V>[] {
+		const entries: RangeQueryEntry<K, V>[] = [];
+		const lastQueryKey = this.offsetKey(start, length - 1);
+		{
+			const entry = this.tree.getPairOrNextLower(start);
+			if (entry !== undefined) {
+				const key = entry[0];
+				const { length: entryLength, value } = entry[1];
+				const lastEntryKey = this.offsetKey(key, entryLength - 1);
+				if (this.ge(lastEntryKey, start)) {
+					entries.push({ start: key, length: entryLength, value });
 				}
+			}
+		}
 
-				if (entryLastKey > end) {
-					// Update the startpoint and length of the portion after the range to be deleted
-					const newStart = end + 1;
-					const newLength = entryLastKey - end;
-					this.entries.splice(isDirty ? i + 1 : i, isDirty ? 0 : 1, {
-						start: newStart,
-						length: newLength,
-						value: entry.value,
-					});
+		{
+			let entry = this.tree.nextHigherPair(start);
+			while (entry !== undefined) {
+				const key = entry[0];
+				if (this.gt(key, lastQueryKey)) {
+					break;
 				}
+
+				const { length: entryLength, value } = entry[1];
+				const lastEntryKey = this.offsetKey(key, entryLength - 1);
+
+				entries.push({ start: key, length: entryLength, value });
+				entry = this.tree.nextHigherPair(lastEntryKey);
 			}
 		}
+
+		return entries;
+	}
+
+	private gt(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) > 0;
+	}
+
+	private ge(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) >= 0;
+	}
+
+	private lt(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) < 0;
+	}
+
+	private le(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) <= 0;
 	}
 }
 
 /**
  * Represents a contiguous range of values in the RangeMap.
- * This interface is used internally and should not be exposed to consumers.
  */
-interface RangeEntry<T> {
-	/**
-	 * The starting index of the range (inclusive).
-	 */
-	readonly start: number;
-
+interface RangeEntry<V> {
 	/**
 	 * The length of the range.
 	 */
@@ -222,18 +291,23 @@ interface RangeEntry<T> {
 	/**
 	 * The value associated with this range.
 	 */
-	readonly value: T;
+	readonly value: V;
 }
 
 /**
  * Describes the result of a range query, including the value and length of the matching prefix.
  */
-export interface RangeQueryResult<T> {
+export interface RangeQueryResult<K, V> {
+	/**
+	 * The key for the first element in the range.
+	 */
+	readonly start: K;
+
 	/**
 	 * The value of the first key in the query range.
 	 * If no matching range is found, this will be undefined.
 	 */
-	readonly value: T | undefined;
+	readonly value: V | undefined;
 
 	/**
 	 * The length of the prefix of the query range which has the same value.
@@ -242,3 +316,23 @@ export interface RangeQueryResult<T> {
 	 */
 	readonly length: number;
 }
+
+export interface RangeQueryEntry<K, V> extends RangeQueryResult<K, V> {
+	readonly value: V;
+}
+
+export function newIntegerRangeMap<V>(): RangeMap<number, V> {
+	return new RangeMap(offsetInteger, subtractIntegers);
+}
+
+function offsetInteger(key: number, offset: number): number {
+	return key + offset;
+}
+
+function subtractIntegers(a: number, b: number): number {
+	return a - b;
+}
+
+function defaultValueOffsetFn<T>(value: T, offset: number): T {
+	return value;
+}

package/src/util/utils.ts

@@ -48,9 +48,16 @@ export function asMutable<T>(readonly: T): Mutable<T> {
 export const clone = structuredClone;
 
 /**
- */
-export function fail(message: string): never {
-	throw new Error(message);
+ * Throw an error with a constant message.
+ * @remarks
+ * Works like {@link @fluidframework/core-utils/internal#assert}.
+ */
+export function fail(message: string | number): never {
+	// Declaring this here aliased to a different name avoids the assert tagging objecting to the usages of `assert` below.
+	// Since users of `fail` do the assert message tagging instead, suppressing tagging errors here makes sense.
+	const assertNoTag: (condition: boolean, message: string | number) => asserts condition =
+		assert;
+	assertNoTag(false, message);
 }
 
 /**

package/lib/package.json

@@ -1,3 +0,0 @@
-{
-	"type": "module"
-}