@fluidframework/tree 2.12.0 → 2.20.0

package/src/util/rangeMap.ts

@@ -3,232 +3,307 @@
  * 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";
 
 /**
- * A map keyed on integers allowing reading and writing contiguous ranges of integer keys.
- *
- * TODO: We should avoid the direct exposure of RangeEntry. AB#7414
+ * 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 type RangeMap<T> = RangeEntry<T>[];
+export class RangeMap<K, V> {
+	private tree: BTree<K, RangeEntry<V>>;
 
-export interface RangeEntry<T> {
-	start: number;
-	length: number;
-	value: T;
-}
+	/**
+	 * @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.
+	 */
+	public constructor(
+		private readonly offsetKey: (key: K, offset: number) => K,
+		private readonly subtractKeys: (a: K, b: K) => number,
+	) {
+		this.tree = new BTree(undefined, subtractKeys);
+	}
 
-/**
- * The result of a query about a range of keys.
- */
-export interface RangeQueryResult<T> {
 	/**
-	 * The value of the first key in the query range.
+	 * Retrieves all entries from the RangeMap.
 	 */
-	value: T | undefined;
+	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();
+	}
 
 	/**
-	 * The length of the prefix of the query range which have the same value.
-	 * For example, if a RangeMap has the same value for keys 5, 6, and 7,
-	 * a query about the range [5, 10] would give a result with length 3.
+	 * 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.
 	 */
-	length: number;
-}
+	public getAll(start: K, length: number): RangeQueryEntry<K, V>[] {
+		const entries = this.getIntersectingEntries(start, length);
+		if (entries.length === 0) {
+			return entries;
+		}
 
-/**
- * See comments on `RangeQueryResult`.
- */
-export function getFromRangeMap<T>(
-	map: RangeMap<T>,
-	start: number,
-	length: number,
-): RangeQueryResult<T> {
-	for (const range of map) {
-		if (range.start > start) {
-			return { value: undefined, length: Math.min(range.start - start, length) };
+		const firstEntry = entries[0] ?? oob();
+		const lengthBefore = this.subtractKeys(start, firstEntry.start);
+		if (lengthBefore > 0) {
+			entries[0] = { ...firstEntry, start, length: firstEntry.length - lengthBefore };
 		}
 
-		const lastRangeKey = range.start + range.length - 1;
-		if (lastRangeKey >= start) {
-			// This range contains `start`.
-			const overlapLength = lastRangeKey - start + 1;
-			return { value: range.value, length: Math.min(overlapLength, length) };
+		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;
 	}
 
-	// There were no entries intersecting the query range, so the entire query range has undefined value.
-	return { value: undefined, length };
-}
+	/**
+	 * Retrieves the value for some prefix of the query range.
+	 *
+	 * @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 (at least 1, at most `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];
 
-export function getFirstEntryFromRangeMap<T>(
-	map: RangeMap<T>,
-	start: number,
-	length: number,
-): RangeEntry<T> | undefined {
-	const lastQueryKey = start + length - 1;
-	for (const range of map) {
-		if (range.start > lastQueryKey) {
-			// We've passed the end of the query range.
-			break;
+				const entryLastKey = this.offsetKey(entryKey, entryLength - 1);
+				const overlappingLength = Math.min(this.subtractKeys(entryLastKey, start) + 1, length);
+				if (overlappingLength > 0) {
+					return { value, start, length: overlappingLength };
+				}
+			}
 		}
 
-		const lastRangeKey = range.start + range.length - 1;
-		if (lastRangeKey >= start) {
-			return range;
+		{
+			// 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 };
 		}
 	}
 
-	return undefined;
-}
+	/**
+	 * Sets the value for a specified range.
+	 *
+	 * @param start - The first key in the range being set.
+	 * @param length - The length of the range.
+	 * @param value - The value to associate with the range.
+	 */
+	public set(start: K, length: number, value: V | undefined): void {
+		this.delete(start, length);
+		if (value !== undefined) {
+			this.tree.set(start, { value, length });
+		}
+	}
 
-/**
- * Sets the keys from `start` to `start + length - 1` to `value`.
- */
-export function setInRangeMap<T>(
-	map: RangeMap<T>,
-	start: number,
-	length: number,
-	value: T,
-): void {
-	const end = start + length - 1;
-	const newEntry: RangeEntry<T> = { start, length, value };
-
-	let iBefore = -1;
-	let iAfter = map.length;
-	for (const [i, entry] of map.entries()) {
-		const entryLastKey = entry.start + entry.length - 1;
-		if (entryLastKey < start) {
-			iBefore = i;
-		} else if (entry.start > end) {
-			iAfter = i;
-			break;
+	/**
+	 * Deletes values within a specified range, updating or removing existing entries.
+	 *
+	 * 1. If an entry is completely included in the deletion range, the whole entry will be deleted
+	 * e.g.: map = [[1, 2], [4, 6]], delete range: [3, 6]
+	 * map becomes [[1, 2]] after deletion
+	 * (Note: the notation [a, b] represents start = a, end = b for simpler visualization, instead of `b`
+	 * representing the length)
+	 *
+	 * 2. If an entry is partially overlapped with the deletion range, the start or end point will be shifted
+	 * e.g.: map = [[1, 2], [4, 6]], delete range: [2, 4]
+	 * map becomes [[1, 1], [5, 6]] after deletion
+	 *
+	 * 3. If an entry completely includes the deletion range, the original entry may be split into two.
+	 * e.g.: map = [[1, 6]], delete range: [2, 4]
+	 * map becomes [[1, 1], [5, 6]]
+	 *
+	 * @param start - The start of the range to delete (inclusive).
+	 * @param length - The length of the range to delete.
+	 */
+	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.
+				this.tree.set(this.offsetKey(lastDeleteKey, 1), { length: lengthAfter, value });
+			}
 		}
 	}
 
-	const numOverlappingEntries = iAfter - iBefore - 1;
-	if (numOverlappingEntries === 0) {
-		map.splice(iAfter, 0, newEntry);
-		return;
+	public clone(): RangeMap<K, V> {
+		const cloned = new RangeMap<K, V>(this.offsetKey, this.subtractKeys);
+		cloned.tree = this.tree.clone();
+		return cloned;
+	}
+
+	/**
+	 * 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,
+			0xaae /* Maps should have the same behavior */,
+		);
+
+		const merged = new RangeMap<K, V>(a.offsetKey, a.subtractKeys);
+
+		// 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);
+		}
+
+		return merged;
 	}
 
-	const iFirst = iBefore + 1;
-	const firstEntry = map[iFirst] ?? oob();
-	const iLast = iAfter - 1;
-	const lastEntry = map[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`
-		map.splice(iFirst, 1, { ...firstEntry, length: lengthBeforeFirst }, newEntry, {
-			...lastEntry,
-			start: end + 1,
-			length: lengthAfterLast,
-		});
-		return;
+	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 });
+				}
+			}
+		}
+
+		{
+			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;
 	}
 
-	if (lengthBeforeFirst > 0) {
-		map[iFirst] = { ...firstEntry, length: lengthBeforeFirst };
+	private gt(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) > 0;
+	}
 
-		// The entry at `iFirst` is no longer overlapping with `newEntry`.
-		iBefore = iFirst;
+	private ge(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) >= 0;
 	}
 
-	if (lengthAfterLast > 0) {
-		map[iLast] = {
-			...lastEntry,
-			start: end + 1,
-			length: lengthAfterLast,
-		};
+	private lt(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) < 0;
+	}
 
-		// The entry at `iLast` is no longer overlapping with `newEntry`.
-		iAfter = iLast;
+	private le(a: K, b: K): boolean {
+		return this.subtractKeys(a, b) <= 0;
 	}
+}
 
-	const numContainedEntries = iAfter - iBefore - 1;
-	map.splice(iBefore + 1, numContainedEntries, newEntry);
+/**
+ * Represents a contiguous range of values in the RangeMap.
+ */
+interface RangeEntry<V> {
+	/**
+	 * The length of the range.
+	 */
+	readonly length: number;
+
+	/**
+	 * The value associated with this range.
+	 */
+	readonly value: V;
 }
 
 /**
- * Delete the keys from `start` to `start + length - 1`
- *
- * 1. If an entry is completely included in the deletion range, the whole entry will be deleted
- * e.g.: map = [[1, 2], [4, 6]], delete range: [3, 6]
- * map becomes [[1, 2]] after deletion
- * (Note: the notation [a, b] represents start = a, end = b for simpler visiualization, instead of `b`
- * representing the length)
- *
- * 2. If an entry is partially overlapped with the deletion range, the start or end point will be shifted
- * e.g.: map = [[1, 2], [4, 6]], delete range: [2, 4]
- * map becomes [[1, 1], [5, 6]] after deletion
- *
- * 3. If an entry completely includes the deletion range, the original entry may be split into two.
- * e.g.: map = [[1, 6]], delete range: [2, 4]
- * map becomes [[1, 1], [5, 6]]
- *
- * TODO: We may find ways to mitigate the code duplication between set and delete, and we need to better
- * document the API.  AB#7413
+ * Describes the result of a range query, including the value and length of the matching prefix.
  */
-export function deleteFromRangeMap<T>(map: RangeMap<T>, start: number, length: number): void {
-	const end = start + length - 1;
-
-	let iBefore = -1;
-	let iAfter = map.length;
-
-	for (const [i, entry] of map.entries()) {
-		const entryLastKey = entry.start + entry.length - 1;
-		if (entryLastKey < start) {
-			iBefore = i;
-		} else if (entry.start > end) {
-			iAfter = i;
-			break;
-		}
-	}
+export interface RangeQueryResult<K, V> {
+	/**
+	 * The key for the first element in the range.
+	 */
+	readonly start: K;
 
-	const numOverlappingEntries = iAfter - iBefore - 1;
+	/**
+	 * The value of the first key in the query range.
+	 * If no matching range is found, this will be undefined.
+	 */
+	readonly value: V | undefined;
 
-	if (numOverlappingEntries === 0) {
-		// No entry will be removed
-		return;
-	}
+	/**
+	 * The length of the prefix of the query range which has the same value.
+	 * For example, if a RangeMap has the same value for keys 5, 6, and 7,
+	 * a query about the range [5, 10] would give a result with length 3.
+	 */
+	readonly length: number;
+}
 
-	const iFirst = iBefore + 1;
-	const iLast = iAfter - 1;
-
-	// Update or remove the overlapping entries
-	for (let i = iFirst; i <= iLast; ++i) {
-		const entry = map[i] ?? oob();
-		const entryLastKey = entry.start + entry.length - 1;
-		let isDirty = false;
-
-		// If the entry lies within the range to be deleted, remove it
-		if (entry.start >= start && entryLastKey <= end) {
-			map.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;
-				map[i] = { ...entry, length: lengthBefore };
-				isDirty = true;
-			}
+export interface RangeQueryEntry<K, V> extends RangeQueryResult<K, V> {
+	readonly value: V;
+}
 
-			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;
-				map.splice(isDirty ? i + 1 : i, isDirty ? 0 : 1, {
-					start: newStart,
-					length: newLength,
-					value: entry.value,
-				});
-			}
-		}
-	}
+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;
 }

package/src/util/utils.ts

@@ -16,7 +16,7 @@ export interface MapGetSet<K, V> {
 }
 
 /**
- * Make all transitive properties in T readonly
+ * Make all transitive properties in `T` readonly
  */
 export type RecursiveReadonly<T> = {
 	readonly [P in keyof T]: RecursiveReadonly<T[P]>;
@@ -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);
 }
 
 /**
@@ -563,3 +570,49 @@ export function defineLazyCachedProperty<
 	});
 	return obj as typeof obj & { [P in K]: V };
 }
+
+/**
+ * Copies a given property from one object to another if and only if the property is defined.
+ * @param source - The object to copy the property from.
+ * If `source` is undefined or does not have the property defined, then this function will do nothing.
+ * @param property - The property to copy.
+ * @param destination - The object to copy the property to.
+ * @remarks This function is useful for copying properties from one object to another while minimizing the presence of `undefined` values.
+ * If `property` is not present on `source` - or if `property` is present, but has a value of `undefined` - then this function will not modify `destination`.
+ * This is different from doing `destination.foo = source.foo`, which would define a `"foo"` property on `destination` with the value `undefined`.
+ *
+ * If the type of `source` is known to have `property`, then this function asserts that the type of `destination` has `property` as well after the call.
+ *
+ * This function first reads the property value (if present) from `source` and then sets it on `destination`, as opposed to e.g. directly copying the property descriptor.
+ * @privateRemarks The first overload of this function allows auto-complete to suggest property names from `source`, but by having the second overload we still allow for arbitrary property names.
+ */
+export function copyPropertyIfDefined<S extends object, K extends keyof S, D extends object>(
+	source: S | undefined,
+	property: K,
+	destination: D,
+): asserts destination is K extends keyof S ? D & { [P in K]: S[K] } : D;
+export function copyPropertyIfDefined<
+	S extends object,
+	K extends string | number | symbol,
+	D extends object,
+>(
+	source: S | undefined,
+	property: K,
+	destination: D,
+): asserts destination is K extends keyof S ? D & { [P in K]: S[K] } : D;
+export function copyPropertyIfDefined<
+	S extends object,
+	K extends string | number | symbol,
+	D extends object,
+>(
+	source: S | undefined,
+	property: K,
+	destination: D,
+): asserts destination is K extends keyof S ? D & { [P in K]: S[K] } : D {
+	if (source !== undefined) {
+		const value = (source as { [P in K]?: unknown })[property];
+		if (value !== undefined) {
+			(destination as { [P in K]: unknown })[property] = value;
+		}
+	}
+}

package/dist/feature-libraries/memoizedIdRangeAllocator.d.ts

@@ -1,38 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { ChangesetLocalId, RevisionTag } from "../core/index.js";
-/**
- * A unique ID allocator that returns the output ID for the same input ID.
- */
-export interface MemoizedIdRangeAllocator {
-    /**
-     * A unique ID allocator that returns the output ID for the same input ID.
-     *
-     * "The same" here includes cases where a prior call allocated a range of IDs that partially or fully overlap with the
-     * current call.
-     * @param revision - The revision associated with the range of IDs to allocate.
-     * @param startId - The first ID to allocate.
-     * @param count - The number of IDs to allocate. Interpreted as 1 if undefined.
-     */
-    allocate(revision: RevisionTag | undefined, startId: ChangesetLocalId, count?: number): IdRange[];
-    /**
-     * Allocates a new range of IDs.
-     *
-     * @param count - The number of IDs to allocate. Interpreted as 1 if undefined.
-     */
-    mint(count?: number): ChangesetLocalId;
-}
-/**
- */
-export interface IdRange {
-    readonly first: ChangesetLocalId;
-    readonly count: number;
-}
-/**
- */
-export declare const MemoizedIdRangeAllocator: {
-    fromNextId(nextId?: number): MemoizedIdRangeAllocator;
-};
-//# sourceMappingURL=memoizedIdRangeAllocator.d.ts.map

package/dist/feature-libraries/memoizedIdRangeAllocator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memoizedIdRangeAllocator.d.ts","sourceRoot":"","sources":["../../src/feature-libraries/memoizedIdRangeAllocator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAUtE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;OAQG;IACH,QAAQ,CACP,QAAQ,EAAE,WAAW,GAAG,SAAS,EACjC,OAAO,EAAE,gBAAgB,EACzB,KAAK,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;CACvC;AAED;GACG;AACH,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;GACG;AACH,eAAO,MAAM,wBAAwB;wBACjB,MAAM,GAAO,wBAAwB;CA4DxD,CAAC"}