@fluidframework/sequence 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

package/src/intervalIndex/endpointInRangeIndex.ts

@@ -0,0 +1,116 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-deprecated */
+
+import { Client, PropertyAction, RedBlackTree } from "@fluidframework/merge-tree";
+import {
+	IIntervalHelpers,
+	ISerializableInterval,
+	IntervalType,
+	SequenceInterval,
+	sequenceIntervalHelpers,
+} from "../intervals";
+import { SharedString } from "../sharedString";
+import { IntervalIndex } from "./intervalIndex";
+import { HasComparisonOverride, compareOverrideables, forceCompare } from "./intervalIndexUtils";
+
+/**
+ * Collection of intervals.
+ *
+ * Provide additional APIs to support efficiently querying a collection of intervals whose endpoints fall within a specified range.
+ * @internal
+ */
+export interface IEndpointInRangeIndex<TInterval extends ISerializableInterval>
+	extends IntervalIndex<TInterval> {
+	/**
+	 * @returns an array of all intervals contained in this collection whose endpoints locate in the range [start, end] (includes both ends)
+	 */
+	findIntervalsWithEndpointInRange(start: number, end: number): TInterval[];
+}
+
+export class EndpointInRangeIndex<TInterval extends ISerializableInterval>
+	implements IEndpointInRangeIndex<TInterval>
+{
+	private readonly intervalTree;
+
+	constructor(
+		private readonly client: Client,
+		private readonly helpers: IIntervalHelpers<TInterval>,
+	) {
+		this.intervalTree = new RedBlackTree<TInterval, TInterval>((a: TInterval, b: TInterval) => {
+			const compareEndsResult = a.compareEnd(b);
+			if (compareEndsResult !== 0) {
+				return compareEndsResult;
+			}
+
+			const overrideablesComparison = compareOverrideables(
+				a as Partial<HasComparisonOverride>,
+				b as Partial<HasComparisonOverride>,
+			);
+			if (overrideablesComparison !== 0) {
+				return overrideablesComparison;
+			}
+
+			const aId = a.getIntervalId();
+			const bId = b.getIntervalId();
+			if (aId !== undefined && bId !== undefined) {
+				return aId.localeCompare(bId);
+			}
+			return 0;
+		});
+	}
+
+	public add(interval: TInterval): void {
+		this.intervalTree.put(interval, interval);
+	}
+
+	public remove(interval: TInterval): void {
+		this.intervalTree.remove(interval);
+	}
+
+	public findIntervalsWithEndpointInRange(start: number, end: number): TInterval[] {
+		if (start <= 0 || start > end || this.intervalTree.isEmpty()) {
+			return [];
+		}
+		const results: TInterval[] = [];
+		const action: PropertyAction<TInterval, TInterval> = (node) => {
+			results.push(node.data);
+			return true;
+		};
+
+		const transientStartInterval = this.helpers.create(
+			"transient",
+			start,
+			start,
+			this.client,
+			IntervalType.Transient,
+		);
+
+		const transientEndInterval = this.helpers.create(
+			"transient",
+			end,
+			end,
+			this.client,
+			IntervalType.Transient,
+		);
+
+		// Add comparison overrides to the transient intervals
+		(transientStartInterval as Partial<HasComparisonOverride>)[forceCompare] = -1;
+		(transientEndInterval as Partial<HasComparisonOverride>)[forceCompare] = 1;
+
+		this.intervalTree.mapRange(action, results, transientStartInterval, transientEndInterval);
+		return results;
+	}
+}
+
+/**
+ * @internal
+ */
+export function createEndpointInRangeIndex(
+	sharedString: SharedString,
+): IEndpointInRangeIndex<SequenceInterval> {
+	const client = (sharedString as unknown as { client: Client }).client;
+	return new EndpointInRangeIndex<SequenceInterval>(client, sequenceIntervalHelpers);
+}

package/src/intervalIndex/endpointIndex.ts

@@ -0,0 +1,91 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-deprecated */
+
+import { Client, RedBlackTree } from "@fluidframework/merge-tree";
+import {
+	IIntervalHelpers,
+	ISerializableInterval,
+	IntervalType,
+	SequenceInterval,
+	sequenceIntervalHelpers,
+} from "../intervals";
+import { SharedString } from "../sharedString";
+import { IntervalIndex } from "./intervalIndex";
+
+/**
+ * @internal
+ */
+export interface IEndpointIndex<TInterval extends ISerializableInterval>
+	extends IntervalIndex<TInterval> {
+	/**
+	 * @returns the previous interval based on the given position number.
+	 * If no such interval exists in this index, returns `undefined`
+	 */
+	previousInterval(pos: number): TInterval | undefined;
+
+	/**
+	 * @returns the next interval based on the given position number.
+	 * If no such interval exists in this index, returns `undefined`
+	 */
+	nextInterval(pos: number): TInterval | undefined;
+}
+
+export class EndpointIndex<TInterval extends ISerializableInterval>
+	implements IEndpointIndex<TInterval>
+{
+	private readonly endIntervalTree: RedBlackTree<TInterval, TInterval>;
+
+	constructor(
+		private readonly client: Client,
+		private readonly helpers: IIntervalHelpers<TInterval>,
+	) {
+		this.endIntervalTree = new RedBlackTree<TInterval, TInterval>((a, b) => a.compareEnd(b));
+	}
+
+	public previousInterval(pos: number): TInterval | undefined {
+		const transientInterval = this.helpers.create(
+			"transient",
+			pos,
+			pos,
+			this.client,
+			IntervalType.Transient,
+		);
+		const rbNode = this.endIntervalTree.floor(transientInterval);
+		if (rbNode) {
+			return rbNode.data;
+		}
+	}
+
+	public nextInterval(pos: number): TInterval | undefined {
+		const transientInterval = this.helpers.create(
+			"transient",
+			pos,
+			pos,
+			this.client,
+			IntervalType.Transient,
+		);
+		const rbNode = this.endIntervalTree.ceil(transientInterval);
+		if (rbNode) {
+			return rbNode.data;
+		}
+	}
+
+	public add(interval: TInterval): void {
+		this.endIntervalTree.put(interval, interval);
+	}
+
+	public remove(interval: TInterval): void {
+		this.endIntervalTree.remove(interval);
+	}
+}
+
+/**
+ * @internal
+ */
+export function createEndpointIndex(sharedString: SharedString): IEndpointIndex<SequenceInterval> {
+	const client = (sharedString as unknown as { client: Client }).client;
+	return new EndpointIndex<SequenceInterval>(client, sequenceIntervalHelpers);
+}

package/src/intervalIndex/idIntervalIndex.ts

@@ -0,0 +1,64 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { ISerializableInterval } from "../intervals";
+import { IntervalIndex } from "./intervalIndex";
+
+const reservedIntervalIdKey = "intervalId";
+
+/**
+ * @internal
+ */
+export interface IIdIntervalIndex<TInterval extends ISerializableInterval>
+	extends IntervalIndex<TInterval>,
+		Iterable<TInterval> {
+	getIntervalById(id: string): TInterval | undefined;
+
+	[Symbol.iterator](): Iterator<TInterval>;
+}
+class IdIntervalIndex<TInterval extends ISerializableInterval>
+	implements IIdIntervalIndex<TInterval>, Iterable<TInterval>
+{
+	private readonly intervalIdMap = new Map<string, TInterval>();
+
+	public add(interval: TInterval) {
+		const id = interval.getIntervalId();
+		assert(
+			id !== undefined,
+			0x2c0 /* "ID must be created before adding interval to collection" */,
+		);
+		// Make the ID immutable.
+		Object.defineProperty(interval.properties, reservedIntervalIdKey, {
+			configurable: false,
+			enumerable: true,
+			writable: false,
+		});
+		this.intervalIdMap.set(id, interval);
+	}
+
+	public remove(interval: TInterval) {
+		const id = interval.getIntervalId();
+		assert(id !== undefined, 0x311 /* expected id to exist on interval */);
+		this.intervalIdMap.delete(id);
+	}
+
+	public getIntervalById(id: string): TInterval | undefined {
+		return this.intervalIdMap.get(id);
+	}
+
+	public [Symbol.iterator](): IterableIterator<TInterval> {
+		return this.intervalIdMap.values();
+	}
+}
+
+/**
+ * @internal
+ */
+export function createIdIntervalIndex<
+	TInterval extends ISerializableInterval,
+>(): IIdIntervalIndex<TInterval> {
+	return new IdIntervalIndex<TInterval>();
+}

package/src/intervalIndex/index.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { IntervalIndex } from "./intervalIndex";
+export { IIdIntervalIndex, createIdIntervalIndex } from "./idIntervalIndex";
+export { IEndpointIndex, createEndpointIndex, EndpointIndex } from "./endpointIndex";
+export {
+	IEndpointInRangeIndex,
+	createEndpointInRangeIndex,
+	EndpointInRangeIndex,
+} from "./endpointInRangeIndex";
+export {
+	IStartpointInRangeIndex,
+	createStartpointInRangeIndex,
+	StartpointInRangeIndex,
+} from "./startpointInRangeIndex";
+export { SequenceIntervalIndexes } from "./sequenceIntervalIndexes";
+export {
+	IOverlappingIntervalsIndex,
+	createOverlappingIntervalsIndex,
+	OverlappingIntervalsIndex,
+} from "./overlappingIntervalsIndex";
+export { createOverlappingSequenceIntervalsIndex } from "./overlappingSequenceIntervalsIndex";

package/src/intervalIndex/intervalIndex.ts

@@ -0,0 +1,32 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ISerializableInterval } from "../intervals";
+
+/**
+ * Collection of intervals.
+ *
+ * Implementers of this interface will typically implement additional APIs to support efficiently querying a collection
+ * of intervals in some manner, for example:
+ * - "find all intervals with start endpoint between these two points"
+ * - "find all intervals which overlap this range"
+ * etc.
+ * @alpha
+ */
+export interface IntervalIndex<TInterval extends ISerializableInterval> {
+	/**
+	 * Adds an interval to the index.
+	 * @remarks Application code should never need to invoke this method on their index for production scenarios:
+	 * Fluid handles adding and removing intervals from an index in response to sequence or interval changes.
+	 */
+	add(interval: TInterval): void;
+
+	/**
+	 * Removes an interval from the index.
+	 * @remarks Application code should never need to invoke this method on their index for production scenarios:
+	 * Fluid handles adding and removing intervals from an index in response to sequence or interval changes.
+	 */
+	remove(interval: TInterval): void;
+}

package/src/intervalIndex/intervalIndexUtils.ts

@@ -0,0 +1,27 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Interface for intervals that have comparison override properties.
+ */
+export const forceCompare = Symbol();
+
+export interface HasComparisonOverride {
+	[forceCompare]: number;
+}
+
+/**
+ * Compares two objects based on their comparison override properties.
+ * @returns A number indicating the order of the intervals (negative for a is lower than b, 0 for tie, positive for a is greater than b).
+ */
+export function compareOverrideables(
+	a: Partial<HasComparisonOverride>,
+	b: Partial<HasComparisonOverride>,
+): number {
+	const forceCompareA = a[forceCompare] ?? 0;
+	const forceCompareB = b[forceCompare] ?? 0;
+
+	return forceCompareA - forceCompareB;
+}

package/src/intervalIndex/overlappingIntervalsIndex.ts

@@ -0,0 +1,187 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-deprecated */
+
+import { Client } from "@fluidframework/merge-tree";
+import {
+	IntervalType,
+	IIntervalHelpers,
+	ISerializableInterval,
+	sequenceIntervalHelpers,
+	SequenceInterval,
+} from "../intervals";
+import { IntervalNode, IntervalTree } from "../intervalTree";
+import { SharedString } from "../sharedString";
+import { SequencePlace, endpointPosAndSide } from "../intervalCollection";
+import { IntervalIndex } from "./intervalIndex";
+
+/**
+ * @internal
+ */
+export interface IOverlappingIntervalsIndex<TInterval extends ISerializableInterval>
+	extends IntervalIndex<TInterval> {
+	/**
+	 * @returns an array of all intervals contained in this collection that overlap the range
+	 * `[start end]`.
+	 */
+	findOverlappingIntervals(start: SequencePlace, end: SequencePlace): TInterval[];
+
+	/**
+	 * Gathers the interval results based on specified parameters.
+	 */
+	gatherIterationResults(
+		results: TInterval[],
+		iteratesForward: boolean,
+		start?: SequencePlace,
+		end?: SequencePlace,
+	): void;
+}
+
+/**
+ * @public
+ */
+export class OverlappingIntervalsIndex<TInterval extends ISerializableInterval>
+	implements IOverlappingIntervalsIndex<TInterval>
+{
+	protected readonly intervalTree = new IntervalTree<TInterval>();
+	protected readonly client: Client;
+	protected readonly helpers: IIntervalHelpers<TInterval>;
+
+	constructor(client: Client, helpers: IIntervalHelpers<TInterval>) {
+		this.client = client;
+		this.helpers = helpers;
+	}
+
+	public map(fn: (interval: TInterval) => void) {
+		this.intervalTree.map(fn);
+	}
+
+	public mapUntil(fn: (interval: TInterval) => boolean) {
+		this.intervalTree.mapUntil(fn);
+	}
+
+	public gatherIterationResults(
+		results: TInterval[],
+		iteratesForward: boolean,
+		start?: SequencePlace,
+		end?: SequencePlace,
+	): void {
+		if (this.intervalTree.intervals.isEmpty()) {
+			return;
+		}
+
+		if (start === undefined && end === undefined) {
+			// No start/end provided. Gather the whole tree in the specified order.
+			if (iteratesForward) {
+				this.intervalTree.map((interval: TInterval) => {
+					results.push(interval);
+				});
+			} else {
+				this.intervalTree.mapBackward((interval: TInterval) => {
+					results.push(interval);
+				});
+			}
+		} else {
+			const transientInterval: TInterval = this.helpers.create(
+				"transient",
+				start ?? "start",
+				end ?? "end",
+				this.client,
+				IntervalType.Transient,
+			);
+
+			if (start === undefined) {
+				// Only end position provided. Since the tree is not sorted by end position,
+				// walk the whole tree in the specified order, gathering intervals that match the end.
+				if (iteratesForward) {
+					this.intervalTree.map((interval: TInterval) => {
+						if (transientInterval.compareEnd(interval) === 0) {
+							results.push(interval);
+						}
+					});
+				} else {
+					this.intervalTree.mapBackward((interval: TInterval) => {
+						if (transientInterval.compareEnd(interval) === 0) {
+							results.push(interval);
+						}
+					});
+				}
+			} else {
+				// Start and (possibly) end provided. Walk the subtrees that may contain
+				// this start position.
+				const compareFn =
+					end === undefined
+						? (node: IntervalNode<TInterval>) => {
+								return transientInterval.compareStart(node.key);
+						  }
+						: (node: IntervalNode<TInterval>) => {
+								return transientInterval.compare(node.key);
+						  };
+				const continueLeftFn = (cmpResult: number) => cmpResult <= 0;
+				const continueRightFn = (cmpResult: number) => cmpResult >= 0;
+				const actionFn = (node: IntervalNode<TInterval>) => {
+					results.push(node.key);
+				};
+
+				if (iteratesForward) {
+					this.intervalTree.intervals.walkExactMatchesForward(
+						compareFn,
+						actionFn,
+						continueLeftFn,
+						continueRightFn,
+					);
+				} else {
+					this.intervalTree.intervals.walkExactMatchesBackward(
+						compareFn,
+						actionFn,
+						continueLeftFn,
+						continueRightFn,
+					);
+				}
+			}
+		}
+	}
+
+	public findOverlappingIntervals(start: SequencePlace, end: SequencePlace): TInterval[] {
+		const { startPos, endPos } = endpointPosAndSide(start, end);
+
+		if (
+			startPos === undefined ||
+			endPos === undefined ||
+			endPos < startPos ||
+			this.intervalTree.intervals.isEmpty()
+		) {
+			return [];
+		}
+		const transientInterval = this.helpers.create(
+			"transient",
+			start,
+			end,
+			this.client,
+			IntervalType.Transient,
+		);
+
+		const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
+		return overlappingIntervalNodes.map((node) => node.key);
+	}
+
+	public remove(interval: TInterval) {
+		this.intervalTree.removeExisting(interval);
+	}
+
+	public add(interval: TInterval) {
+		this.intervalTree.put(interval);
+	}
+}
+
+/**
+ * @internal
+ */
+export function createOverlappingIntervalsIndex(
+	sharedString: SharedString,
+): IOverlappingIntervalsIndex<SequenceInterval> {
+	const client = (sharedString as unknown as { client: Client }).client;
+	return new OverlappingIntervalsIndex<SequenceInterval>(client, sequenceIntervalHelpers);
+}

package/src/intervalIndex/overlappingSequenceIntervalsIndex.ts

@@ -0,0 +1,80 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-deprecated */
+
+import {
+	Client,
+	ISegment,
+	ReferenceType,
+	compareReferencePositions,
+	reservedRangeLabelsKey,
+} from "@fluidframework/merge-tree";
+import {
+	sequenceIntervalHelpers,
+	IntervalType,
+	SequenceInterval,
+	createPositionReferenceFromSegoff,
+} from "../intervals";
+import { SharedString } from "../sharedString";
+import { SequenceIntervalIndexes } from "./sequenceIntervalIndexes";
+import { OverlappingIntervalsIndex } from "./overlappingIntervalsIndex";
+
+/**
+ * @public
+ */
+class OverlappingSequenceIntervalsIndex
+	extends OverlappingIntervalsIndex<SequenceInterval>
+	implements SequenceIntervalIndexes.Overlapping
+{
+	constructor(client: Client) {
+		super(client, sequenceIntervalHelpers);
+	}
+
+	public findOverlappingIntervalsBySegoff(
+		startSegoff: { segment: ISegment | undefined; offset: number | undefined },
+		endSegoff: { segment: ISegment | undefined; offset: number | undefined },
+	): Iterable<SequenceInterval> {
+		if (this.intervalTree.intervals.isEmpty()) {
+			return [];
+		}
+
+		const startLref = createPositionReferenceFromSegoff(
+			this.client,
+			startSegoff,
+			ReferenceType.Transient,
+		);
+
+		const endLref = createPositionReferenceFromSegoff(
+			this.client,
+			endSegoff,
+			ReferenceType.Transient,
+		);
+
+		if (compareReferencePositions(startLref, endLref) > 0) {
+			return [];
+		}
+
+		const transientInterval = new SequenceInterval(
+			this.client,
+			startLref,
+			endLref,
+			IntervalType.Transient,
+			{ [reservedRangeLabelsKey]: ["transient"] },
+		);
+
+		const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
+		return overlappingIntervalNodes.map((node) => node.key);
+	}
+}
+
+/**
+ * @internal
+ */
+export function createOverlappingSequenceIntervalsIndex(
+	sharedString: SharedString,
+): SequenceIntervalIndexes.Overlapping {
+	const client = (sharedString as unknown as { client: Client }).client;
+	return new OverlappingSequenceIntervalsIndex(client);
+}

package/src/intervalIndex/sequenceIntervalIndexes.ts

@@ -0,0 +1,34 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ISegment } from "@fluidframework/merge-tree";
+import { SequenceInterval } from "../intervals";
+import { IOverlappingIntervalsIndex } from "./overlappingIntervalsIndex";
+
+/**
+ * This namespace contains specialiazations of indexes which support spatial queries
+ * specifically for `SequenceInterval`s.
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace SequenceIntervalIndexes {
+	/**
+	 * Collection of intervals.
+	 *
+	 * Provides additional APIs to support efficiently querying a collection of intervals based on segments and offset.
+	 * @internal
+	 */
+	export interface Overlapping extends IOverlappingIntervalsIndex<SequenceInterval> {
+		/**
+		 * Finds overlapping intervals within the specified range.
+		 *
+		 * @returns an array of all intervals that overlap with the specified SegOff range (includes both ends)
+		 */
+		findOverlappingIntervalsBySegoff(
+			startSegoff: { segment: ISegment | undefined; offset: number | undefined },
+			endSegoff: { segment: ISegment | undefined; offset: number | undefined },
+		): Iterable<SequenceInterval>;
+	}
+}