@fluidframework/sequence 2.0.0-dev.6.4.0.192049 → 2.0.0-dev.7.2.0.204906

package/src/intervalIndex/endpointInRangeIndex.ts

@@ -2,9 +2,17 @@
  * 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 } from "../intervals";
+import {
+	IIntervalHelpers,
+	ISerializableInterval,
+	IntervalType,
+	SequenceInterval,
+	sequenceIntervalHelpers,
+} from "../intervals";
+import { SharedString } from "../sharedString";
 import { IntervalIndex } from "./intervalIndex";
 import { HasComparisonOverride, compareOverrideables, forceCompare } from "./intervalIndexUtils";
 
@@ -12,26 +20,27 @@ import { HasComparisonOverride, compareOverrideables, forceCompare } from "./int
  * Collection of intervals.
  *
  * Provide additional APIs to support efficiently querying a collection of intervals whose endpoints fall within a specified range.
+ * @public
  */
 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);
+	findIntervalsWithEndpointInRange(start: number, end: number): TInterval[];
 }
 
-class EndpointInRangeIndex<TInterval extends ISerializableInterval>
+export class EndpointInRangeIndex<TInterval extends ISerializableInterval>
 	implements IEndpointInRangeIndex<TInterval>
 {
 	private readonly intervalTree;
 
 	constructor(
-		private readonly helpers: IIntervalHelpers<TInterval>,
 		private readonly client: Client,
+		private readonly helpers: IIntervalHelpers<TInterval>,
 	) {
 		this.intervalTree = new RedBlackTree<TInterval, TInterval>((a: TInterval, b: TInterval) => {
-			const compareEndsResult = helpers.compareEnds(a, b);
+			const compareEndsResult = a.compareEnd(b);
 			if (compareEndsResult !== 0) {
 				return compareEndsResult;
 			}
@@ -61,7 +70,7 @@ class EndpointInRangeIndex<TInterval extends ISerializableInterval>
 		this.intervalTree.remove(interval);
 	}
 
-	public findIntervalsWithEndpointInRange(start: number, end: number) {
+	public findIntervalsWithEndpointInRange(start: number, end: number): TInterval[] {
 		if (start <= 0 || start > end || this.intervalTree.isEmpty()) {
 			return [];
 		}
@@ -96,9 +105,12 @@ class EndpointInRangeIndex<TInterval extends ISerializableInterval>
 	}
 }
 
-export function createEndpointInRangeIndex<TInterval extends ISerializableInterval>(
-	helpers: IIntervalHelpers<TInterval>,
-	client: Client,
-): IEndpointInRangeIndex<TInterval> {
-	return new EndpointInRangeIndex<TInterval>(helpers, client);
+/**
+ * @public
+ */
+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

@@ -2,11 +2,22 @@
  * 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 } from "../intervals";
+import {
+	IIntervalHelpers,
+	ISerializableInterval,
+	IntervalType,
+	SequenceInterval,
+	sequenceIntervalHelpers,
+} from "../intervals";
+import { SharedString } from "../sharedString";
 import { IntervalIndex } from "./intervalIndex";
 
+/**
+ * @public
+ */
 export interface IEndpointIndex<TInterval extends ISerializableInterval>
 	extends IntervalIndex<TInterval> {
 	/**
@@ -22,15 +33,16 @@ export interface IEndpointIndex<TInterval extends ISerializableInterval>
 	nextInterval(pos: number): TInterval | undefined;
 }
 
-class EndpointIndex<TInterval extends ISerializableInterval> implements IEndpointIndex<TInterval> {
+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>,
 	) {
-		// eslint-disable-next-line @typescript-eslint/unbound-method
-		this.endIntervalTree = new RedBlackTree<TInterval, TInterval>(helpers.compareEnds);
+		this.endIntervalTree = new RedBlackTree<TInterval, TInterval>((a, b) => a.compareEnd(b));
 	}
 
 	public previousInterval(pos: number): TInterval | undefined {
@@ -70,9 +82,10 @@ class EndpointIndex<TInterval extends ISerializableInterval> implements IEndpoin
 	}
 }
 
-export function createEndpointIndex<TInterval extends ISerializableInterval>(
-	client: Client,
-	helpers: IIntervalHelpers<TInterval>,
-): IEndpointIndex<TInterval> {
-	return new EndpointIndex<TInterval>(client, helpers);
+/**
+ * @public
+ */
+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

@@ -9,6 +9,9 @@ import { IntervalIndex } from "./intervalIndex";
 
 const reservedIntervalIdKey = "intervalId";
 
+/**
+ * @public
+ */
 export interface IIdIntervalIndex<TInterval extends ISerializableInterval>
 	extends IntervalIndex<TInterval>,
 		Iterable<TInterval> {
@@ -19,7 +22,7 @@ export interface IIdIntervalIndex<TInterval extends ISerializableInterval>
 class IdIntervalIndex<TInterval extends ISerializableInterval>
 	implements IIdIntervalIndex<TInterval>, Iterable<TInterval>
 {
-	private readonly intervalIdMap: Map<string, TInterval> = new Map();
+	private readonly intervalIdMap = new Map<string, TInterval>();
 
 	public add(interval: TInterval) {
 		const id = interval.getIntervalId();
@@ -51,6 +54,9 @@ class IdIntervalIndex<TInterval extends ISerializableInterval>
 	}
 }
 
+/**
+ * @public
+ */
 export function createIdIntervalIndex<
 	TInterval extends ISerializableInterval,
 >(): IIdIntervalIndex<TInterval> {

package/src/intervalIndex/index.ts

@@ -5,12 +5,21 @@
 
 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 { 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

@@ -13,6 +13,7 @@ import { ISerializableInterval } from "../intervals";
  * - "find all intervals with start endpoint between these two points"
  * - "find all intervals which overlap this range"
  * etc.
+ * @public
  */
 export interface IntervalIndex<TInterval extends ISerializableInterval> {
 	/**

package/src/intervalIndex/overlappingIntervalsIndex.ts

@@ -2,19 +2,31 @@
  * 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 } from "../intervals";
+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";
 
+/**
+ * @public
+ */
 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: number, end: number): TInterval[];
+	findOverlappingIntervals(start: SequencePlace, end: SequencePlace): TInterval[];
 
 	/**
 	 * Gathers the interval results based on specified parameters.
@@ -22,11 +34,14 @@ export interface IOverlappingIntervalsIndex<TInterval extends ISerializableInter
 	gatherIterationResults(
 		results: TInterval[],
 		iteratesForward: boolean,
-		start?: number,
-		end?: number,
+		start?: SequencePlace,
+		end?: SequencePlace,
 	): void;
 }
 
+/**
+ * @public
+ */
 export class OverlappingIntervalsIndex<TInterval extends ISerializableInterval>
 	implements IOverlappingIntervalsIndex<TInterval>
 {
@@ -50,8 +65,8 @@ export class OverlappingIntervalsIndex<TInterval extends ISerializableInterval>
 	public gatherIterationResults(
 		results: TInterval[],
 		iteratesForward: boolean,
-		start?: number,
-		end?: number,
+		start?: SequencePlace,
+		end?: SequencePlace,
 	): void {
 		if (this.intervalTree.intervals.isEmpty()) {
 			return;
@@ -71,8 +86,8 @@ export class OverlappingIntervalsIndex<TInterval extends ISerializableInterval>
 		} else {
 			const transientInterval: TInterval = this.helpers.create(
 				"transient",
-				start,
-				end,
+				start ?? "start",
+				end ?? "end",
 				this.client,
 				IntervalType.Transient,
 			);
@@ -129,8 +144,15 @@ export class OverlappingIntervalsIndex<TInterval extends ISerializableInterval>
 		}
 	}
 
-	public findOverlappingIntervals(start: number, end: number): TInterval[] {
-		if (end < start || this.intervalTree.intervals.isEmpty()) {
+	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(
@@ -154,9 +176,12 @@ export class OverlappingIntervalsIndex<TInterval extends ISerializableInterval>
 	}
 }
 
-export function createOverlappingIntervalsIndex<TInterval extends ISerializableInterval>(
-	client: Client,
-	helpers: IIntervalHelpers<TInterval>,
-): IOverlappingIntervalsIndex<TInterval> {
-	return new OverlappingIntervalsIndex<TInterval>(client, helpers);
+/**
+ * @public
+ */
+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

@@ -2,6 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+/* eslint-disable import/no-deprecated */
 
 import {
 	Client,
@@ -16,9 +17,13 @@ import {
 	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
@@ -64,8 +69,12 @@ class OverlappingSequenceIntervalsIndex
 	}
 }
 
+/**
+ * @public
+ */
 export function createOverlappingSequenceIntervalsIndex(
-	client: Client,
+	sharedString: SharedString,
 ): SequenceIntervalIndexes.Overlapping {
+	const client = (sharedString as unknown as { client: Client }).client;
 	return new OverlappingSequenceIntervalsIndex(client);
 }

package/src/intervalIndex/sequenceIntervalIndexes.ts

@@ -10,6 +10,7 @@ import { IOverlappingIntervalsIndex } from "./overlappingIntervalsIndex";
 /**
  * This namespace contains specialiazations of indexes which support spatial queries
  * specifically for `SequenceInterval`s.
+ * @public
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace SequenceIntervalIndexes {
@@ -27,6 +28,6 @@ export namespace SequenceIntervalIndexes {
 		findOverlappingIntervalsBySegoff(
 			startSegoff: { segment: ISegment | undefined; offset: number | undefined },
 			endSegoff: { segment: ISegment | undefined; offset: number | undefined },
-		);
+		): Iterable<SequenceInterval>;
 	}
 }

package/src/intervalIndex/startpointInRangeIndex.ts

@@ -2,10 +2,17 @@
  * 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 { assert } from "@fluidframework/core-utils";
-import { IIntervalHelpers, ISerializableInterval, IntervalType } from "../intervals";
+import {
+	IIntervalHelpers,
+	ISerializableInterval,
+	IntervalType,
+	SequenceInterval,
+	sequenceIntervalHelpers,
+} from "../intervals";
+import { SharedString } from "../sharedString";
 import { IntervalIndex } from "./intervalIndex";
 import { HasComparisonOverride, compareOverrideables, forceCompare } from "./intervalIndexUtils";
 
@@ -13,31 +20,27 @@ import { HasComparisonOverride, compareOverrideables, forceCompare } from "./int
  * Collection of intervals.
  *
  * Provide additional APIs to support efficiently querying a collection of intervals whose startpoints fall within a specified range.
+ * @public
  */
 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);
+	findIntervalsWithStartpointInRange(start: number, end: number): TInterval[];
 }
 
-class StartpointInRangeIndex<TInterval extends ISerializableInterval>
+export class StartpointInRangeIndex<TInterval extends ISerializableInterval>
 	implements IStartpointInRangeIndex<TInterval>
 {
 	private readonly intervalTree;
 
 	constructor(
-		private readonly helpers: IIntervalHelpers<TInterval>,
 		private readonly client: Client,
+		private readonly helpers: IIntervalHelpers<TInterval>,
 	) {
 		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);
+			const compareStartsResult = a.compareStart(b);
 			if (compareStartsResult !== 0) {
 				return compareStartsResult;
 			}
@@ -66,7 +69,7 @@ class StartpointInRangeIndex<TInterval extends ISerializableInterval>
 		this.intervalTree.remove(interval);
 	}
 
-	public findIntervalsWithStartpointInRange(start: number, end: number) {
+	public findIntervalsWithStartpointInRange(start: number, end: number): TInterval[] {
 		if (start <= 0 || start > end || this.intervalTree.isEmpty()) {
 			return [];
 		}
@@ -100,10 +103,12 @@ class StartpointInRangeIndex<TInterval extends ISerializableInterval>
 		return results;
 	}
 }
-
-export function createStartpointInRangeIndex<TInterval extends ISerializableInterval>(
-	helpers: IIntervalHelpers<TInterval>,
-	client: Client,
-): IStartpointInRangeIndex<TInterval> {
-	return new StartpointInRangeIndex<TInterval>(helpers, client);
+/**
+ * @public
+ */
+export function createStartpointInRangeIndex(
+	sharedString: SharedString,
+): IStartpointInRangeIndex<SequenceInterval> {
+	const client = (sharedString as unknown as { client: Client }).client;
+	return new StartpointInRangeIndex<SequenceInterval>(client, sequenceIntervalHelpers);
 }

package/src/intervals/interval.ts

@@ -2,6 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+/* eslint-disable import/no-deprecated */
 
 import {
 	ICombiningOp,
@@ -12,12 +13,15 @@ import {
 } from "@fluidframework/merge-tree";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import { assert } from "@fluidframework/core-utils";
+import { UsageError } from "@fluidframework/telemetry-utils";
+import { SequencePlace } from "../intervalCollection";
 import { IIntervalHelpers, ISerializableInterval, ISerializedInterval } from "./intervalUtils";
 
 const reservedIntervalIdKey = "intervalId";
 
 /**
  * Serializable interval whose endpoints are plain-old numbers.
+ * @public
  */
 export class Interval implements ISerializableInterval {
 	/**
@@ -31,7 +35,11 @@ export class Interval implements ISerializableInterval {
 	 * @internal
 	 */
 	public propertyManager: PropertiesManager;
-	constructor(public start: number, public end: number, props?: PropertySet) {
+	constructor(
+		public start: number,
+		public end: number,
+		props?: PropertySet,
+	) {
 		this.propertyManager = new PropertiesManager();
 		this.properties = {};
 
@@ -184,9 +192,21 @@ export class Interval implements ISerializableInterval {
 	 * {@inheritDoc IInterval.modify}
 	 * @internal
 	 */
-	public modify(label: string, start: number, end: number, op?: ISequencedDocumentMessage) {
-		const startPos = start ?? this.start;
-		const endPos = end ?? this.end;
+	public modify(
+		label: string,
+		start?: SequencePlace,
+		end?: SequencePlace,
+		op?: ISequencedDocumentMessage,
+	) {
+		if (typeof start === "string" || typeof end === "string") {
+			throw new UsageError(
+				"The start and end positions of a plain interval may not be on the special endpoint segments.",
+			);
+		}
+
+		const startPos = typeof start === "number" ? start : start?.pos ?? this.start;
+		const endPos = typeof end === "number" ? end : end?.pos ?? this.end;
+
 		if (this.start === startPos && this.end === endPos) {
 			// Return undefined to indicate that no change is necessary.
 			return;
@@ -213,18 +233,25 @@ export class Interval implements ISerializableInterval {
 	}
 }
 
-export function createInterval(label: string, start: number, end: number): Interval {
+export function createInterval(label: string, start: SequencePlace, end: SequencePlace): Interval {
+	if (typeof start === "string" || typeof end === "string") {
+		throw new UsageError(
+			"The start and end positions of a plain interval may not be on the special endpoint segments.",
+		);
+	}
+
 	const rangeProp: PropertySet = {};
 
 	if (label && label.length > 0) {
 		rangeProp[reservedRangeLabelsKey] = [label];
 	}
 
-	return new Interval(start, end, rangeProp);
+	const startPos = typeof start === "number" ? start : start.pos;
+	const endPos = typeof end === "number" ? end : end.pos;
+
+	return new Interval(startPos, endPos, rangeProp);
 }
 
 export const intervalHelpers: IIntervalHelpers<Interval> = {
-	compareEnds: (a: Interval, b: Interval) => a.end - b.end,
-	compareStarts: (a: Interval, b: Interval) => a.start - b.start,
 	create: createInterval,
 };