@fluidframework/sequence 2.0.0-dev.4.4.0.162253 → 2.0.0-dev.5.2.0.169897

package/src/intervalCollection.ts

@@ -28,6 +28,8 @@ import {
 	maxReferencePosition,
 	createDetachedLocalReferencePosition,
 	DetachedReferencePosition,
+	SlidingPreference,
+	PropertyAction,
 } from "@fluidframework/merge-tree";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import { LoggingError } from "@fluidframework/telemetry-utils";
@@ -39,11 +41,24 @@ import {
 	IValueOperation,
 	IValueType,
 	IValueTypeOperationValue,
+	SequenceOptions,
 } from "./defaultMapInterfaces";
 import { IInterval, IntervalConflictResolver, IntervalTree, IntervalNode } from "./intervalTree";
 
 const reservedIntervalIdKey = "intervalId";
 
+/**
+ * Values are used in persisted formats (ops) and revertibles.
+ * @alpha
+ */
+export const IntervalOpType = {
+	ADD: "add",
+	DELETE: "delete",
+	CHANGE: "change",
+	PROPERTY_CHANGED: "propertyChanged",
+	POSITION_REMOVE: "positionRemove",
+} as const;
+
 export enum IntervalType {
 	Simple = 0x0,
 	Nest = 0x1,
@@ -51,7 +66,7 @@ export enum IntervalType {
 	/**
 	 * SlideOnRemove indicates that the ends of the interval will slide if the segment
 	 * they reference is removed and acked.
-	 * See `packages\dds\merge-tree\REFERENCEPOSITIONS.md` for details
+	 * See `packages\dds\merge-tree\docs\REFERENCEPOSITIONS.md` for details
 	 * SlideOnRemove is the default interval behavior and does not need to be specified.
 	 */
 	SlideOnRemove = 0x2, // SlideOnRemove is default behavior - all intervals are SlideOnRemove
@@ -83,6 +98,7 @@ export interface ISerializedInterval {
 	end: number;
 	/** Interval type to create */
 	intervalType: IntervalType;
+	stickiness?: IntervalStickiness;
 	/** Any properties the interval has */
 	properties?: PropertySet;
 }
@@ -101,13 +117,12 @@ export type SerializedIntervalDelta = Omit<ISerializedInterval, "start" | "end"
  *
  * Intervals are of the format:
  *
- * [start, end, sequenceNumber, intervalType, properties]
+ * [start, end, sequenceNumber, intervalType, properties, stickiness?]
  */
-export type CompressedSerializedInterval = [number, number, number, IntervalType, PropertySet];
+export type CompressedSerializedInterval =
+	| [number, number, number, IntervalType, PropertySet, IntervalStickiness]
+	| [number, number, number, IntervalType, PropertySet];
 
-/**
- * @internal
- */
 export interface ISerializedIntervalCollectionV2 {
 	label: string;
 	version: 2;
@@ -128,6 +143,7 @@ function decompressInterval(
 		sequenceNumber: interval[2],
 		intervalType: interval[3],
 		properties: { ...interval[4], [reservedRangeLabelsKey]: [label] },
+		stickiness: interval[5],
 	};
 }
 
@@ -138,7 +154,7 @@ function decompressInterval(
 function compressInterval(interval: ISerializedInterval): CompressedSerializedInterval {
 	const { start, end, sequenceNumber, intervalType, properties } = interval;
 
-	return [
+	const base: CompressedSerializedInterval = [
 		start,
 		end,
 		sequenceNumber,
@@ -147,6 +163,26 @@ function compressInterval(interval: ISerializedInterval): CompressedSerializedIn
 		// in the `label` field of the summary
 		{ ...properties, [reservedRangeLabelsKey]: undefined },
 	];
+
+	if (interval.stickiness !== undefined && interval.stickiness !== IntervalStickiness.END) {
+		base.push(interval.stickiness);
+	}
+
+	return base;
+}
+
+function startReferenceSlidingPreference(stickiness: IntervalStickiness): SlidingPreference {
+	// if any start stickiness, prefer sliding backwards
+	return (stickiness & IntervalStickiness.START) !== 0
+		? SlidingPreference.BACKWARD
+		: SlidingPreference.FORWARD;
+}
+
+function endReferenceSlidingPreference(stickiness: IntervalStickiness): SlidingPreference {
+	// if any end stickiness, prefer sliding forwards
+	return (stickiness & IntervalStickiness.END) !== 0
+		? SlidingPreference.FORWARD
+		: SlidingPreference.BACKWARD;
 }
 
 export interface ISerializableInterval extends IInterval {
@@ -172,14 +208,18 @@ export interface ISerializableInterval extends IInterval {
 	getIntervalId(): string | undefined;
 }
 
+/**
+ * @sealed
+ */
 export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
 	compareEnds(a: TInterval, b: TInterval): number;
+	compareStarts?(a: TInterval, b: TInterval): number;
 	/**
 	 *
 	 * @param label - label of the interval collection this interval is being added to. This parameter is
 	 * irrelevant for transient intervals.
 	 * @param start - numerical start position of the interval
-	 * @param end - numberical end position of the interval
+	 * @param end - numerical end position of the interval
 	 * @param client - client creating the interval
 	 * @param intervalType - Type of interval to create. Default is SlideOnRemove
 	 * @param op - If this create came from a remote client, op that created it. Default is undefined (i.e. local)
@@ -193,9 +233,50 @@ export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
 		intervalType: IntervalType,
 		op?: ISequencedDocumentMessage,
 		fromSnapshot?: boolean,
+		stickiness?: IntervalStickiness,
 	): TInterval;
 }
 
+/**
+ * Determines how an interval should expand when segments are inserted adjacent
+ * to the range it spans
+ *
+ * Note that interval stickiness is currently an experimental feature and must
+ * be explicitly enabled with the `intervalStickinessEnabled` flag
+ */
+export const IntervalStickiness = {
+	/**
+	 * Interval does not expand to include adjacent segments
+	 */
+	NONE: 0b00,
+
+	/**
+	 * Interval expands to include segments inserted adjacent to the start
+	 */
+	START: 0b01,
+
+	/**
+	 * Interval expands to include segments inserted adjacent to the end
+	 *
+	 * This is the default stickiness
+	 */
+	END: 0b10,
+
+	/**
+	 * Interval expands to include all segments inserted adjacent to it
+	 */
+	FULL: 0b11,
+} as const;
+
+/**
+ * Determines how an interval should expand when segments are inserted adjacent
+ * to the range it spans
+ *
+ * Note that interval stickiness is currently an experimental feature and must
+ * be explicitly enabled with the `intervalStickinessEnabled` flag
+ */
+export type IntervalStickiness = typeof IntervalStickiness[keyof typeof IntervalStickiness];
+
 /**
  * Serializable interval whose endpoints are plain-old numbers.
  */
@@ -240,7 +321,7 @@ export class Interval implements ISerializableInterval {
 	 * Adds an auxiliary set of properties to this interval.
 	 * These properties can be recovered using `getAdditionalPropertySets`
 	 * @param props - set of properties to add
-	 * @remarks - This gets called as part of the default conflict resolver for `IntervalCollection<Interval>`
+	 * @remarks - This gets called as part of the default conflict resolver for `IIntervalCollection<Interval>`
 	 * (i.e. non-sequence-based interval collections). However, the additional properties don't get serialized.
 	 * This functionality seems half-baked.
 	 */
@@ -394,7 +475,7 @@ export class Interval implements ISerializableInterval {
 }
 
 /**
- * Interval impelmentation whose ends are associated with positions in a mutatable sequence.
+ * Interval implementation whose ends are associated with positions in a mutatable sequence.
  * As such, when content is inserted into the middle of the interval, the interval expands to
  * include that content.
  *
@@ -439,6 +520,7 @@ export class SequenceInterval implements ISerializableInterval {
 		public end: LocalReferencePosition,
 		public intervalType: IntervalType,
 		props?: PropertySet,
+		public readonly stickiness: IntervalStickiness = IntervalStickiness.END,
 	) {
 		this.propertyManager = new PropertiesManager();
 		this.properties = {};
@@ -500,6 +582,9 @@ export class SequenceInterval implements ISerializableInterval {
 		if (this.properties) {
 			serializedInterval.properties = this.properties;
 		}
+		if (this.stickiness !== IntervalStickiness.END) {
+			serializedInterval.stickiness = this.stickiness;
+		}
 
 		return serializedInterval;
 	}
@@ -514,6 +599,7 @@ export class SequenceInterval implements ISerializableInterval {
 			this.end,
 			this.intervalType,
 			this.properties,
+			this.stickiness,
 		);
 	}
 
@@ -621,6 +707,7 @@ export class SequenceInterval implements ISerializableInterval {
 		end: number,
 		op?: ISequencedDocumentMessage,
 		localSeq?: number,
+		stickiness: IntervalStickiness = IntervalStickiness.END,
 	) {
 		const getRefType = (baseType: ReferenceType): ReferenceType => {
 			let refType = baseType;
@@ -640,6 +727,7 @@ export class SequenceInterval implements ISerializableInterval {
 				op,
 				undefined,
 				localSeq,
+				startReferenceSlidingPreference(stickiness),
 			);
 			if (this.start.properties) {
 				startRef.addProperties(this.start.properties);
@@ -655,6 +743,7 @@ export class SequenceInterval implements ISerializableInterval {
 				op,
 				undefined,
 				localSeq,
+				endReferenceSlidingPreference(stickiness),
 			);
 			if (this.end.properties) {
 				endRef.addProperties(this.end.properties);
@@ -690,6 +779,7 @@ function createPositionReferenceFromSegoff(
 	op?: ISequencedDocumentMessage,
 	localSeq?: number,
 	fromSnapshot?: boolean,
+	slidingPreference?: SlidingPreference,
 ): LocalReferencePosition {
 	if (segoff.segment) {
 		const ref = client.createLocalReferencePosition(
@@ -697,6 +787,7 @@ function createPositionReferenceFromSegoff(
 			segoff.offset,
 			refType,
 			undefined,
+			slidingPreference,
 		);
 		return ref;
 	}
@@ -725,6 +816,7 @@ function createPositionReference(
 	op?: ISequencedDocumentMessage,
 	fromSnapshot?: boolean,
 	localSeq?: number,
+	slidingPreference?: SlidingPreference,
 ): LocalReferencePosition {
 	let segoff;
 	if (op) {
@@ -744,7 +836,16 @@ function createPositionReference(
 		);
 		segoff = client.getContainingSegment(pos, undefined, localSeq);
 	}
-	return createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot);
+
+	return createPositionReferenceFromSegoff(
+		client,
+		segoff,
+		refType,
+		op,
+		localSeq,
+		fromSnapshot,
+		slidingPreference,
+	);
 }
 
 export function createSequenceInterval(
@@ -755,6 +856,7 @@ export function createSequenceInterval(
 	intervalType: IntervalType,
 	op?: ISequencedDocumentMessage,
 	fromSnapshot?: boolean,
+	stickiness: IntervalStickiness = IntervalStickiness.END,
 ): SequenceInterval {
 	let beginRefType = ReferenceType.RangeBegin;
 	let endRefType = ReferenceType.RangeEnd;
@@ -778,15 +880,38 @@ export function createSequenceInterval(
 		}
 	}
 
-	const startLref = createPositionReference(client, start, beginRefType, op, fromSnapshot);
-	const endLref = createPositionReference(client, end, endRefType, op, fromSnapshot);
+	const startLref = createPositionReference(
+		client,
+		start,
+		beginRefType,
+		op,
+		fromSnapshot,
+		undefined,
+		startReferenceSlidingPreference(stickiness),
+	);
+	const endLref = createPositionReference(
+		client,
+		end,
+		endRefType,
+		op,
+		fromSnapshot,
+		undefined,
+		endReferenceSlidingPreference(stickiness),
+	);
 	const rangeProp = {
 		[reservedRangeLabelsKey]: [label],
 	};
 	startLref.addProperties(rangeProp);
 	endLref.addProperties(rangeProp);
 
-	const ival = new SequenceInterval(client, startLref, endLref, intervalType, rangeProp);
+	const ival = new SequenceInterval(
+		client,
+		startLref,
+		endLref,
+		intervalType,
+		rangeProp,
+		stickiness,
+	);
 	return ival;
 }
 
@@ -1036,12 +1161,229 @@ class EndpointIndex<TInterval extends ISerializableInterval> implements Interval
 	}
 }
 
+/**
+ * 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);
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Interface for intervals that have comparison override properties.
+ */
+const forceCompare = Symbol();
+
+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).
+ */
+function compareOverrideables(
+	a: Partial<HasComparisonOverride>,
+	b: Partial<HasComparisonOverride>,
+): number {
+	const forceCompareA = a[forceCompare] ?? 0;
+	const forceCompareB = b[forceCompare] ?? 0;
+
+	return forceCompareA - forceCompareB;
+}
+
+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;
+	}
+}
+
+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 createEndpointInRangeIndex<TInterval extends ISerializableInterval>(
+	helpers: IIntervalHelpers<TInterval>,
+	client: Client,
+): IEndpointInRangeIndex<TInterval> {
+	return new EndpointInRangeIndex<TInterval>(helpers, client);
+}
+
+export function createStartpointInRangeIndex<TInterval extends ISerializableInterval>(
+	helpers: IIntervalHelpers<TInterval>,
+	client: Client,
+): IStartpointInRangeIndex<TInterval> {
+	return new StartpointInRangeIndex<TInterval>(helpers, client);
+}
+
 export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 	private static readonly legacyIdPrefix = "legacy";
 	public readonly overlappingIntervalsIndex: OverlappingIntervalsIndex<TInterval>;
 	public readonly idIntervalIndex: IdIntervalIndex<TInterval>;
 	public readonly endIntervalIndex: EndpointIndex<TInterval>;
-	private readonly indexes: IntervalIndex<TInterval>[];
+	private readonly indexes: Set<IntervalIndex<TInterval>>;
 
 	constructor(
 		private readonly client: Client,
@@ -1056,11 +1398,11 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 		this.overlappingIntervalsIndex = new OverlappingIntervalsIndex(client, helpers);
 		this.idIntervalIndex = new IdIntervalIndex();
 		this.endIntervalIndex = new EndpointIndex(client, helpers);
-		this.indexes = [
+		this.indexes = new Set([
 			this.overlappingIntervalsIndex,
 			this.idIntervalIndex,
 			this.endIntervalIndex,
-		];
+		]);
 	}
 
 	public createLegacyId(start: number, end: number): string {
@@ -1104,6 +1446,14 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 		}
 	}
 
+	public appendIndex(index: IntervalIndex<TInterval>) {
+		this.indexes.add(index);
+	}
+
+	public removeIndex(index: IntervalIndex<TInterval>): boolean {
+		return this.indexes.delete(index);
+	}
+
 	public removeExistingInterval(interval: TInterval) {
 		this.removeIntervalFromIndexes(interval);
 		this.removeIntervalListeners(interval);
@@ -1114,8 +1464,18 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 		end: number,
 		intervalType: IntervalType,
 		op?: ISequencedDocumentMessage,
+		stickiness: IntervalStickiness = IntervalStickiness.END,
 	): TInterval {
-		return this.helpers.create(this.label, start, end, this.client, intervalType, op);
+		return this.helpers.create(
+			this.label,
+			start,
+			end,
+			this.client,
+			intervalType,
+			op,
+			undefined,
+			stickiness,
+		);
 	}
 
 	public addInterval(
@@ -1124,8 +1484,9 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 		intervalType: IntervalType,
 		props?: PropertySet,
 		op?: ISequencedDocumentMessage,
+		stickiness: IntervalStickiness = IntervalStickiness.END,
 	) {
-		const interval: TInterval = this.createInterval(start, end, intervalType, op);
+		const interval: TInterval = this.createInterval(start, end, intervalType, op, stickiness);
 		if (interval) {
 			if (!interval.properties) {
 				interval.properties = createMap<any>();
@@ -1201,6 +1562,7 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 				ref.getOffset(),
 				ReferenceType.Transient,
 				ref.properties,
+				ref.slidingPreference,
 			);
 		};
 		if (interval instanceof SequenceInterval) {
@@ -1243,18 +1605,36 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
 export const compareSequenceIntervalEnds = (a: SequenceInterval, b: SequenceInterval): number =>
 	compareReferencePositions(a.end, b.end);
 
+export const compareSequenceIntervalStarts = (a: SequenceInterval, b: SequenceInterval): number =>
+	compareReferencePositions(a.start, b.start);
+
+export const sequenceIntervalHelpers: IIntervalHelpers<SequenceInterval> = {
+	compareEnds: compareSequenceIntervalEnds,
+	compareStarts: compareSequenceIntervalStarts,
+	create: createSequenceInterval,
+};
+
+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,
+};
+
 class SequenceIntervalCollectionFactory
 	implements IValueFactory<IntervalCollection<SequenceInterval>>
 {
 	public load(
 		emitter: IValueOpEmitter,
 		raw: ISerializedInterval[] | ISerializedIntervalCollectionV2 = [],
+		options?: Partial<SequenceOptions>,
 	): IntervalCollection<SequenceInterval> {
-		const helpers: IIntervalHelpers<SequenceInterval> = {
-			compareEnds: compareSequenceIntervalEnds,
-			create: createSequenceInterval,
-		};
-		return new IntervalCollection<SequenceInterval>(helpers, true, emitter, raw);
+		return new IntervalCollection<SequenceInterval>(
+			sequenceIntervalHelpers,
+			true,
+			emitter,
+			raw,
+			options,
+		);
 	}
 
 	public store(
@@ -1289,7 +1669,15 @@ export class SequenceIntervalCollectionValueType
 
 const compareIntervalEnds = (a: Interval, b: Interval) => a.end - b.end;
 
-function createInterval(label: string, start: number, end: number, client: Client): Interval {
+function createInterval(
+	label: string,
+	start: number,
+	end: number,
+	client: Client,
+	intervalType?: IntervalType,
+	op?: ISequencedDocumentMessage,
+	fromSnapshot?: boolean,
+): Interval {
 	const rangeProp: PropertySet = {};
 
 	if (label && label.length > 0) {
@@ -1303,12 +1691,13 @@ class IntervalCollectionFactory implements IValueFactory<IntervalCollection<Inte
 	public load(
 		emitter: IValueOpEmitter,
 		raw: ISerializedInterval[] | ISerializedIntervalCollectionV2 = [],
+		options?: Partial<SequenceOptions>,
 	): IntervalCollection<Interval> {
 		const helpers: IIntervalHelpers<Interval> = {
 			compareEnds: compareIntervalEnds,
 			create: createInterval,
 		};
-		const collection = new IntervalCollection<Interval>(helpers, false, emitter, raw);
+		const collection = new IntervalCollection<Interval>(helpers, false, emitter, raw, options);
 		collection.attachGraph(undefined as any as Client, "");
 		return collection;
 	}
@@ -1355,7 +1744,7 @@ export function makeOpsMap<T extends ISerializableInterval>(): Map<
 
 	return new Map<string, IValueOperation<IntervalCollection<T>>>([
 		[
-			"add",
+			IntervalOpType.ADD,
 			{
 				process: (collection, params, local, op, localOpMetadata) => {
 					// if params is undefined, the interval was deleted during
@@ -1370,7 +1759,7 @@ export function makeOpsMap<T extends ISerializableInterval>(): Map<
 			},
 		],
 		[
-			"delete",
+			IntervalOpType.DELETE,
 			{
 				process: (collection, params, local, op) => {
 					assert(op !== undefined, 0x3fc /* op should exist here */);
@@ -1383,7 +1772,7 @@ export function makeOpsMap<T extends ISerializableInterval>(): Map<
 			},
 		],
 		[
-			"change",
+			IntervalOpType.CHANGE,
 			{
 				process: (collection, params, local, op, localOpMetadata) => {
 					// if params is undefined, the interval was deleted during
@@ -1402,7 +1791,7 @@ export function makeOpsMap<T extends ISerializableInterval>(): Map<
 
 export type DeserializeCallback = (properties: PropertySet) => void;
 
-export class IntervalCollectionIterator<TInterval extends ISerializableInterval>
+class IntervalCollectionIterator<TInterval extends ISerializableInterval>
 	implements Iterator<TInterval>
 {
 	private readonly results: TInterval[];
@@ -1495,14 +1884,137 @@ export interface IIntervalCollectionEvent<TInterval extends ISerializableInterva
 
 /**
  * Collection of intervals that supports addition, modification, removal, and efficient spatial querying.
- * This class is not a DDS in its own right, but emits events on mutating operations such that it's possible to
- * integrate into a DDS.
- * This aligns with its usage in `SharedSegmentSequence`, which allows associating intervals to positions in the
- * sequence DDS which are broadcast to all other clients in an eventually consistent fashion.
+ * Changes to this collection will be incur updates on collaborating clients (i.e. they are not local-only).
  */
-export class IntervalCollection<TInterval extends ISerializableInterval> extends TypedEventEmitter<
-	IIntervalCollectionEvent<TInterval>
-> {
+export interface IIntervalCollection<TInterval extends ISerializableInterval>
+	extends TypedEventEmitter<IIntervalCollectionEvent<TInterval>> {
+	readonly attached: boolean;
+	/**
+	 * Attaches an index to this collection.
+	 * All intervals which are part of this collection will be added to the index, and the index will automatically
+	 * be updated when this collection updates due to local or remote changes.
+	 *
+	 * @remarks - After attaching an index to an interval collection, applications should typically store this
+	 * index somewhere in their in-memory data model for future reference and querying.
+	 */
+	attachIndex(index: IntervalIndex<TInterval>): void;
+	/**
+	 * Detaches an index from this collection.
+	 * All intervals which are part of this collection will be removed from the index, and updates to this collection
+	 * due to local or remote changes will no longer incur updates to the index.
+	 *
+	 * @returns - Return false if the target index cannot be found in the indexes, otherwise remove all intervals in the index and return true
+	 */
+	detachIndex(index: IntervalIndex<TInterval>): boolean;
+	/**
+	 * @returns the interval in this collection that has the provided `id`.
+	 * If no interval in the collection has this `id`, returns `undefined`.
+	 */
+	getIntervalById(id: string): TInterval | undefined;
+	/**
+	 * Creates a new interval and add it to the collection.
+	 * @param start - interval start position (inclusive)
+	 * @param end - interval end position (exclusive)
+	 * @param intervalType - type of the interval. All intervals are SlideOnRemove. Intervals may not be Transient.
+	 * @param props - properties of the interval
+	 * @param stickiness - {@link (IntervalStickiness:type)} to apply to the added interval.
+	 * @returns - the created interval
+	 * @remarks - See documentation on {@link SequenceInterval} for comments on interval endpoint semantics: there are subtleties
+	 * with how the current half-open behavior is represented.
+	 */
+	add(
+		start: number,
+		end: number,
+		intervalType: IntervalType,
+		props?: PropertySet,
+		stickiness?: IntervalStickiness,
+	): TInterval;
+	/**
+	 * Removes an interval from the collection.
+	 * @param id - Id of the interval to remove
+	 * @returns the removed interval
+	 */
+	removeIntervalById(id: string): TInterval | undefined;
+	/**
+	 * Changes the properties on an existing interval.
+	 * @param id - Id of the interval whose properties should be changed
+	 * @param props - Property set to apply to the interval. Shallow merging is used between any existing properties
+	 * and `prop`, i.e. the interval will end up with a property object equivalent to `{ ...oldProps, ...props }`.
+	 */
+	changeProperties(id: string, props: PropertySet);
+	/**
+	 * Changes the endpoints of an existing interval.
+	 * @param id - Id of the interval to change
+	 * @param start - New start value, if defined. `undefined` signifies this endpoint should be left unchanged.
+	 * @param end - New end value, if defined. `undefined` signifies this endpoint should be left unchanged.
+	 * @returns the interval that was changed, if it existed in the collection.
+	 */
+	change(id: string, start?: number, end?: number): TInterval | undefined;
+
+	attachDeserializer(onDeserialize: DeserializeCallback): void;
+	/**
+	 * @returns an iterator over all intervals in this collection.
+	 */
+	[Symbol.iterator](): Iterator<TInterval>;
+
+	/**
+	 * @returns a forward iterator over all intervals in this collection with start point equal to `startPosition`.
+	 */
+	CreateForwardIteratorWithStartPosition(startPosition: number): Iterator<TInterval>;
+
+	/**
+	 * @returns a backward iterator over all intervals in this collection with start point equal to `startPosition`.
+	 */
+	CreateBackwardIteratorWithStartPosition(startPosition: number): Iterator<TInterval>;
+
+	/**
+	 * @returns a forward iterator over all intervals in this collection with end point equal to `endPosition`.
+	 */
+	CreateForwardIteratorWithEndPosition(endPosition: number): Iterator<TInterval>;
+
+	/**
+	 * @returns a backward iterator over all intervals in this collection with end point equal to `endPosition`.
+	 */
+	CreateBackwardIteratorWithEndPosition(endPosition: number): Iterator<TInterval>;
+
+	/**
+	 * Gathers iteration results that optionally match a start/end criteria into the provided array.
+	 * @param results - Array to gather the results into. In lieu of a return value, this array will be populated with
+	 * intervals matching the query upon edit.
+	 * @param iteratesForward - whether or not iteration should be in the forward direction
+	 * @param start - If provided, only match intervals whose start point is equal to `start`.
+	 * @param end - If provided, only match intervals whose end point is equal to `end`.
+	 */
+	gatherIterationResults(
+		results: TInterval[],
+		iteratesForward: boolean,
+		start?: number,
+		end?: number,
+	): void;
+
+	/**
+	 * @returns an array of all intervals in this collection that overlap with the interval
+	 * `[startPosition, endPosition]`.
+	 */
+	findOverlappingIntervals(startPosition: number, endPosition: number): TInterval[];
+
+	/**
+	 * Applies a function to each interval in this collection.
+	 */
+	map(fn: (interval: TInterval) => void): void;
+
+	previousInterval(pos: number): TInterval | undefined;
+
+	nextInterval(pos: number): TInterval | undefined;
+}
+
+/**
+ * {@inheritdoc IIntervalCollection}
+ */
+export class IntervalCollection<TInterval extends ISerializableInterval>
+	extends TypedEventEmitter<IIntervalCollectionEvent<TInterval>>
+	implements IIntervalCollection<TInterval>
+{
 	private savedSerializedIntervals?: ISerializedInterval[];
 	private localCollection: LocalIntervalCollection<TInterval> | undefined;
 	private onDeserialize: DeserializeCallback | undefined;
@@ -1534,6 +2046,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 		private readonly requiresClient: boolean,
 		private readonly emitter: IValueOpEmitter,
 		serializedIntervals: ISerializedInterval[] | ISerializedIntervalCollectionV2,
+		private readonly options: Partial<SequenceOptions> = {},
 	) {
 		super();
 
@@ -1544,6 +2057,40 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 			  );
 	}
 
+	/**
+	 * {@inheritdoc IIntervalCollection.attachIndex}
+	 */
+	public attachIndex(index: IntervalIndex<TInterval>): void {
+		if (!this.attached) {
+			throw new LoggingError("The local interval collection must exist");
+		}
+		for (const interval of this) {
+			index.add(interval);
+		}
+
+		this.localCollection?.appendIndex(index);
+	}
+
+	/**
+	 * {@inheritdoc IIntervalCollection.detachIndex}
+	 */
+	public detachIndex(index: IntervalIndex<TInterval>): boolean {
+		if (!this.attached) {
+			throw new LoggingError("The local interval collection must exist");
+		}
+
+		// Avoid removing intervals if the index does not exist
+		if (!this.localCollection?.removeIndex(index)) {
+			return false;
+		}
+
+		for (const interval of this) {
+			index.remove(interval);
+		}
+
+		return true;
+	}
+
 	private rebasePositionWithSegmentSlide(
 		pos: number,
 		seqNumberFrom: number,
@@ -1634,7 +2181,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 		if (this.savedSerializedIntervals) {
 			for (const serializedInterval of this.savedSerializedIntervals) {
 				this.localCollection.ensureSerializedId(serializedInterval);
-				const { start, end, intervalType, properties } = serializedInterval;
+				const { start, end, intervalType, properties, stickiness } = serializedInterval;
 				const interval = this.helpers.create(
 					label,
 					start,
@@ -1643,6 +2190,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 					intervalType,
 					undefined,
 					true,
+					stickiness,
 				);
 				if (properties) {
 					interval.addProperties(properties);
@@ -1689,8 +2237,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * @returns the interval in this collection that has the provided `id`.
-	 * If no interval in the collection has this `id`, returns `undefined`.
+	 * {@inheritdoc IIntervalCollection.getIntervalById}
 	 */
 	public getIntervalById(id: string) {
 		if (!this.localCollection) {
@@ -1700,20 +2247,14 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * Creates a new interval and add it to the collection.
-	 * @param start - interval start position (inclusive)
-	 * @param end - interval end position (exclusive)
-	 * @param intervalType - type of the interval. All intervals are SlideOnRemove. Intervals may not be Transient.
-	 * @param props - properties of the interval
-	 * @returns - the created interval
-	 * @remarks - See documentation on {@link SequenceInterval} for comments on interval endpoint semantics: there are subtleties
-	 * with how the current half-open behavior is represented.
+	 * {@inheritdoc IIntervalCollection.add}
 	 */
 	public add(
 		start: number,
 		end: number,
 		intervalType: IntervalType,
 		props?: PropertySet,
+		stickiness: IntervalStickiness = IntervalStickiness.END,
 	): TInterval {
 		if (!this.localCollection) {
 			throw new LoggingError("attach must be called prior to adding intervals");
@@ -1721,12 +2262,19 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 		if (intervalType & IntervalType.Transient) {
 			throw new LoggingError("Can not add transient intervals");
 		}
+		if (stickiness !== IntervalStickiness.END && !this.options.intervalStickinessEnabled) {
+			throw new UsageError(
+				"attempted to set interval stickiness without enabling `intervalStickinessEnabled` feature flag",
+			);
+		}
 
 		const interval: TInterval = this.localCollection.addInterval(
 			start,
 			end,
 			intervalType,
 			props,
+			undefined,
+			stickiness,
 		);
 
 		if (interval) {
@@ -1736,6 +2284,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 				properties: interval.properties,
 				sequenceNumber: this.client?.getCurrentSeq() ?? 0,
 				start,
+				stickiness,
 			};
 			const localSeq = this.getNextLocalSeq();
 			this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
@@ -1776,9 +2325,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * Removes an interval from the collection.
-	 * @param id - Id of the interval to remove
-	 * @returns the removed interval
+	 * {@inheritdoc IIntervalCollection.removeIntervalById}
 	 */
 	public removeIntervalById(id: string) {
 		if (!this.localCollection) {
@@ -1792,10 +2339,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * Changes the properties on an existing interval.
-	 * @param id - Id of the interval whose properties should be changed
-	 * @param props - Property set to apply to the interval. Shallow merging is used between any existing properties
-	 * and `prop`, i.e. the interval will end up with a property object equivalent to `{ ...oldProps, ...props }`.
+	 * {@inheritdoc IIntervalCollection.changeProperties}
 	 */
 	public changeProperties(id: string, props: PropertySet) {
 		if (!this.attached) {
@@ -1829,11 +2373,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * Changes the endpoints of an existing interval.
-	 * @param id - Id of the interval to change
-	 * @param start - New start value, if defined. `undefined` signifies this endpoint should be left unchanged.
-	 * @param end - New end value, if defined. `undefined` signifies this endpoint should be left unchanged.
-	 * @returns the interval that was changed, if it existed in the collection.
+	 * {@inheritdoc IIntervalCollection.change}
 	 */
 	public change(id: string, start?: number, end?: number): TInterval | undefined {
 		if (!this.localCollection) {
@@ -2021,6 +2561,9 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 		}
 	}
 
+	/**
+	 * {@inheritdoc IIntervalCollection.attachDeserializer}
+	 */
 	public attachDeserializer(onDeserialize: DeserializeCallback): void {
 		// If no deserializer is specified can skip all processing work
 		if (!onDeserialize) {
@@ -2188,6 +2731,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 					newStart,
 					interval.start.refType,
 					op,
+					startReferenceSlidingPreference(interval.stickiness),
 				);
 				if (props) {
 					interval.start.addProperties(props);
@@ -2205,6 +2749,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 					newEnd,
 					interval.end.refType,
 					op,
+					endReferenceSlidingPreference(interval.stickiness),
 				);
 				if (props) {
 					interval.end.addProperties(props);
@@ -2253,6 +2798,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 			serializedInterval.intervalType,
 			serializedInterval.properties,
 			op,
+			serializedInterval.stickiness,
 		);
 
 		if (interval) {
@@ -2310,7 +2856,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * @returns a forward iterator over all intervals in this collection with start point equal to `startPosition`.
+	 * {@inheritdoc IIntervalCollection.CreateForwardIteratorWithStartPosition}
 	 */
 	public CreateForwardIteratorWithStartPosition(
 		startPosition: number,
@@ -2320,7 +2866,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * @returns a backward iterator over all intervals in this collection with start point equal to `startPosition`.
+	 * {@inheritdoc IIntervalCollection.CreateBackwardIteratorWithStartPosition}
 	 */
 	public CreateBackwardIteratorWithStartPosition(
 		startPosition: number,
@@ -2330,7 +2876,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * @returns a forward iterator over all intervals in this collection with end point equal to `endPosition`.
+	 * {@inheritdoc IIntervalCollection.CreateForwardIteratorWithEndPosition}
 	 */
 	public CreateForwardIteratorWithEndPosition(
 		endPosition: number,
@@ -2345,7 +2891,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * @returns a backward iterator over all intervals in this collection with end point equal to `endPosition`.
+	 * {@inheritdoc IIntervalCollection.CreateBackwardIteratorWithEndPosition}
 	 */
 	public CreateBackwardIteratorWithEndPosition(
 		endPosition: number,
@@ -2360,12 +2906,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * Gathers iteration results that optionally match a start/end criteria into the provided array.
-	 * @param results - Array to gather the results into. In lieu of a return value, this array will be populated with
-	 * intervals matching the query upon edit.
-	 * @param iteratesForward - whether or not iteration should be in the forward direction
-	 * @param start - If provided, only match intervals whose start point is equal to `start`.
-	 * @param end - If provided, only match intervals whose end point is equal to `end`.
+	 * {@inheritdoc IIntervalCollection.gatherIterationResults}
 	 */
 	public gatherIterationResults(
 		results: TInterval[],
@@ -2386,8 +2927,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * @returns an array of all intervals in this collection that overlap with the interval
-	 * `[startPosition, endPosition]`.
+	 * {@inheritdoc IIntervalCollection.findOverlappingIntervals}
 	 */
 	public findOverlappingIntervals(startPosition: number, endPosition: number): TInterval[] {
 		if (!this.localCollection) {
@@ -2401,7 +2941,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 	}
 
 	/**
-	 * Applies a function to each interval in this collection.
+	 * {@inheritdoc IIntervalCollection.map}
 	 */
 	public map(fn: (interval: TInterval) => void) {
 		if (!this.localCollection) {
@@ -2413,6 +2953,9 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 		}
 	}
 
+	/**
+	 * {@inheritdoc IIntervalCollection.previousInterval}
+	 */
 	public previousInterval(pos: number): TInterval | undefined {
 		if (!this.localCollection) {
 			throw new LoggingError("attachSequence must be called");
@@ -2421,6 +2964,9 @@ export class IntervalCollection<TInterval extends ISerializableInterval> extends
 		return this.localCollection.endIntervalIndex.previousInterval(pos);
 	}
 
+	/**
+	 * {@inheritdoc IIntervalCollection.nextInterval}
+	 */
 	public nextInterval(pos: number): TInterval | undefined {
 		if (!this.localCollection) {
 			throw new LoggingError("attachSequence must be called");