@fluidframework/sequence 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191457

package/src/intervalIndex/endpointInRangeIndex.ts

@@ -0,0 +1,104 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Client, PropertyAction, RedBlackTree } from "@fluidframework/merge-tree";
+import { IIntervalHelpers, ISerializableInterval, IntervalType } from "../intervals";
+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.
+ */
+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);
+}
+
+class EndpointInRangeIndex<TInterval extends ISerializableInterval>
+	implements IEndpointInRangeIndex<TInterval>
+{
+	private readonly intervalTree;
+
+	constructor(
+		private readonly helpers: IIntervalHelpers<TInterval>,
+		private readonly client: Client,
+	) {
+		this.intervalTree = new RedBlackTree<TInterval, TInterval>((a: TInterval, b: TInterval) => {
+			const compareEndsResult = helpers.compareEnds(a, 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) {
+		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;
+	}
+}
+
+export function createEndpointInRangeIndex<TInterval extends ISerializableInterval>(
+	helpers: IIntervalHelpers<TInterval>,
+	client: Client,
+): IEndpointInRangeIndex<TInterval> {
+	return new EndpointInRangeIndex<TInterval>(helpers, client);
+}

package/src/intervalIndex/endpointIndex.ts

@@ -0,0 +1,78 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Client, RedBlackTree } from "@fluidframework/merge-tree";
+import { IIntervalHelpers, ISerializableInterval, IntervalType } from "../intervals";
+import { IntervalIndex } from "./intervalIndex";
+
+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;
+}
+
+class EndpointIndex<TInterval extends ISerializableInterval> implements IEndpointIndex<TInterval> {
+	private readonly endIntervalTree: RedBlackTree<TInterval, TInterval>;
+
+	constructor(
+		private readonly client: Client,
+		private readonly helpers: IIntervalHelpers<TInterval>,
+	) {
+		// eslint-disable-next-line @typescript-eslint/unbound-method
+		this.endIntervalTree = new RedBlackTree<TInterval, TInterval>(helpers.compareEnds);
+	}
+
+	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);
+	}
+}
+
+export function createEndpointIndex<TInterval extends ISerializableInterval>(
+	client: Client,
+	helpers: IIntervalHelpers<TInterval>,
+): IEndpointIndex<TInterval> {
+	return new EndpointIndex<TInterval>(client, helpers);
+}

package/src/intervalIndex/idIntervalIndex.ts

@@ -0,0 +1,58 @@
+/*!
+ * 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";
+
+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: Map<string, TInterval> = new Map();
+
+	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();
+	}
+}
+
+export function createIdIntervalIndex<
+	TInterval extends ISerializableInterval,
+>(): IIdIntervalIndex<TInterval> {
+	return new IdIntervalIndex<TInterval>();
+}

package/src/intervalIndex/index.ts

@@ -3,6 +3,11 @@
  * Licensed under the MIT License.
  */
 
+export { IntervalIndex } from "./intervalIndex";
+export { IIdIntervalIndex, createIdIntervalIndex } from "./idIntervalIndex";
+export { IEndpointIndex, createEndpointIndex } from "./endpointIndex";
+export { IEndpointInRangeIndex, createEndpointInRangeIndex } from "./endpointInRangeIndex";
+export { IStartpointInRangeIndex, createStartpointInRangeIndex } from "./startpointInRangeIndex";
 export { SequenceIntervalIndexes } from "./sequenceIntervalIndexes";
 export {
 	IOverlappingIntervalsIndex,

package/src/intervalIndex/intervalIndex.ts

@@ -0,0 +1,31 @@
+/*!
+ * 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.
+ */
+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

@@ -4,13 +4,9 @@
  */
 
 import { Client } from "@fluidframework/merge-tree";
-import {
-	IntervalType,
-	IIntervalHelpers,
-	IntervalIndex,
-	ISerializableInterval,
-} from "../intervalCollection";
+import { IntervalType, IIntervalHelpers, ISerializableInterval } from "../intervals";
 import { IntervalNode, IntervalTree } from "../intervalTree";
+import { IntervalIndex } from "./intervalIndex";
 
 export interface IOverlappingIntervalsIndex<TInterval extends ISerializableInterval>
 	extends IntervalIndex<TInterval> {

package/src/intervalIndex/overlappingSequenceIntervalsIndex.ts

@@ -15,7 +15,7 @@ import {
 	IntervalType,
 	SequenceInterval,
 	createPositionReferenceFromSegoff,
-} from "../intervalCollection";
+} from "../intervals";
 import { SequenceIntervalIndexes } from "./sequenceIntervalIndexes";
 import { OverlappingIntervalsIndex } from "./overlappingIntervalsIndex";
 

package/src/intervalIndex/sequenceIntervalIndexes.ts

@@ -4,7 +4,7 @@
  */
 
 import { ISegment } from "@fluidframework/merge-tree";
-import { SequenceInterval } from "../intervalCollection";
+import { SequenceInterval } from "../intervals";
 import { IOverlappingIntervalsIndex } from "./overlappingIntervalsIndex";
 
 /**

package/src/intervalIndex/startpointInRangeIndex.ts

@@ -0,0 +1,109 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Client, PropertyAction, RedBlackTree } from "@fluidframework/merge-tree";
+import { assert } from "@fluidframework/core-utils";
+import { IIntervalHelpers, ISerializableInterval, IntervalType } from "../intervals";
+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 startpoints fall within a specified range.
+ */
+export interface IStartpointInRangeIndex<TInterval extends ISerializableInterval>
+	extends IntervalIndex<TInterval> {
+	/**
+	 * @returns an array of all intervals contained in this collection whose startpoints locate in the range [start, end] (includes both ends)
+	 */
+	findIntervalsWithStartpointInRange(start: number, end: number);
+}
+
+class StartpointInRangeIndex<TInterval extends ISerializableInterval>
+	implements IStartpointInRangeIndex<TInterval>
+{
+	private readonly intervalTree;
+
+	constructor(
+		private readonly helpers: IIntervalHelpers<TInterval>,
+		private readonly client: Client,
+	) {
+		this.intervalTree = new RedBlackTree<TInterval, TInterval>((a: TInterval, b: TInterval) => {
+			assert(
+				typeof helpers.compareStarts === "function",
+				0x6d1 /* compareStarts does not exist in the helpers */,
+			);
+
+			const compareStartsResult = helpers.compareStarts(a, b);
+			if (compareStartsResult !== 0) {
+				return compareStartsResult;
+			}
+
+			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 findIntervalsWithStartpointInRange(start: number, end: number) {
+		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;
+	}
+}
+
+export function createStartpointInRangeIndex<TInterval extends ISerializableInterval>(
+	helpers: IIntervalHelpers<TInterval>,
+	client: Client,
+): IStartpointInRangeIndex<TInterval> {
+	return new StartpointInRangeIndex<TInterval>(helpers, client);
+}

package/src/intervalTree.ts

@@ -9,10 +9,9 @@ import {
 	IRBAugmentation,
 	IRBMatcher,
 	RedBlackTree,
-	ConflictAction,
 	RBNodeActions,
 } from "@fluidframework/merge-tree";
-import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { IInterval } from "./intervals";
 
 export interface AugmentedIntervalNode {
 	minmax: IInterval;
@@ -20,72 +19,10 @@ export interface AugmentedIntervalNode {
 
 export const integerRangeToString = (range: IIntegerRange) => `[${range.start},${range.end})`;
 
-/**
- * Basic interval abstraction
- */
-export interface IInterval {
-	/**
-	 * @returns a new interval object with identical semantics.
-	 */
-	clone(): IInterval;
-	/**
-	 * Compares this interval to `b` with standard comparator semantics:
-	 * - returns -1 if this is less than `b`
-	 * - returns 1 if this is greater than `b`
-	 * - returns 0 if this is equivalent to `b`
-	 * @param b - Interval to compare against
-	 */
-	compare(b: IInterval): number;
-	/**
-	 * Compares the start endpoint of this interval to `b`'s start endpoint.
-	 * Standard comparator semantics apply.
-	 * @param b - Interval to compare against
-	 */
-	compareStart(b: IInterval): number;
-	/**
-	 * Compares the end endpoint of this interval to `b`'s end endpoint.
-	 * Standard comparator semantics apply.
-	 * @param b - Interval to compare against
-	 */
-	compareEnd(b: IInterval): number;
-	/**
-	 * Modifies one or more of the endpoints of this interval, returning a new interval representing the result.
-	 * @internal
-	 */
-	modify(
-		label: string,
-		start: number | undefined,
-		end: number | undefined,
-		op?: ISequencedDocumentMessage,
-		localSeq?: number,
-	): IInterval | undefined;
-	/**
-	 * @returns whether this interval overlaps with `b`.
-	 * Intervals are considered to overlap if their intersection is non-empty.
-	 */
-	overlaps(b: IInterval): boolean;
-	/**
-	 * Unions this interval with `b`, returning a new interval.
-	 * The union operates as a convex hull, i.e. if the two intervals are disjoint, the return value includes
-	 * intermediate values between the two intervals.
-	 * @internal
-	 */
-	union(b: IInterval): IInterval;
-}
-
 const intervalComparer = (a: IInterval, b: IInterval) => a.compare(b);
 
 export type IntervalNode<T extends IInterval> = RBNode<T, AugmentedIntervalNode>;
 
-/**
- * @deprecated - This functionality was useful when adding two intervals at the same start/end positions resulted
- * in a conflict. This is no longer the case (as of PR#6407), as interval collections support multiple intervals
- * at the same location and gives each interval a unique id.
- *
- * As such, conflict resolvers are never invoked and unnecessary. They will be removed in an upcoming release.
- */
-export type IntervalConflictResolver<TInterval> = (a: TInterval, b: TInterval) => TInterval;
-
 export class IntervalTree<T extends IInterval>
 	implements IRBAugmentation<T, AugmentedIntervalNode>, IRBMatcher<T, AugmentedIntervalNode>
 {
@@ -99,17 +36,8 @@ export class IntervalTree<T extends IInterval>
 		this.intervals.removeExisting(x);
 	}
 
-	public put(x: T, conflict?: IntervalConflictResolver<T>) {
-		let rbConflict: ConflictAction<T, AugmentedIntervalNode> | undefined;
-		if (conflict) {
-			rbConflict = (key: T, currentKey: T) => {
-				const ival = conflict(key, currentKey);
-				return {
-					key: ival,
-				};
-			};
-		}
-		this.intervals.put(x, { minmax: x.clone() }, rbConflict);
+	public put(x: T) {
+		this.intervals.put(x, { minmax: x.clone() });
 	}
 
 	public map(fn: (x: T) => void) {

package/src/intervals/index.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	IInterval,
+	ISerializedInterval,
+	ISerializableInterval,
+	IntervalOpType,
+	IntervalType,
+	IIntervalHelpers,
+	IntervalStickiness,
+	SerializedIntervalDelta,
+	CompressedSerializedInterval,
+	endReferenceSlidingPreference,
+	startReferenceSlidingPreference,
+} from "./intervalUtils";
+export { Interval, createInterval, intervalHelpers } from "./interval";
+export {
+	SequenceInterval,
+	createSequenceInterval,
+	createPositionReferenceFromSegoff,
+	sequenceIntervalHelpers,
+} from "./sequenceInterval";