Deprecate previousInterval/nextInterval APi from IntervalCollection

.changeset/soft-taxis-thank.md

@@ -0,0 +1,14 @@
+---
+"@fluidframework/sequence": minor
+"@fluid-experimental/sequence-deprecated": minor
+---
+
+Deprecate API `previousInterval` and `nextInterval` from `IntervalCollection`, these functionalities are moved to the `EndpointIndex`. Users are advised to independently attach the index to the collection and utilize the API accordingly, for instance:
+
+```typescript
+const endpointIndex = createEndpointIndex(sharedString);
+collection.attachIndex(endpointIndex);
+
+const result1 = endpointIndex.previousInterval(pos);
+const result2 = endpointIndex.nextInterval(pos);
+```

examples/data-objects/table-document/src/document.ts

@@ -7,7 +7,12 @@ import { DataObject, DataObjectFactory } from "@fluidframework/aqueduct";
 import { IEvent, IFluidHandle } from "@fluidframework/core-interfaces";
 import { ICombiningOp, ReferencePosition, PropertySet } from "@fluidframework/merge-tree";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
-import { IntervalType, SequenceDeltaEvent } from "@fluidframework/sequence";
+import {
+	IntervalType,
+	SequenceDeltaEvent,
+	SharedString,
+	createEndpointIndex,
+} from "@fluidframework/sequence";
 import {
 	positionToRowCol,
 	rowColToPosition,
@@ -77,9 +82,12 @@ export class TableDocument extends DataObject<{ Events: ITableDocumentEvents }>
 		this.matrix.setItems(row, col, [value], properties);
 	}
 
-	public async getRange(label: string) {
+	public async getRange(label: string): Promise<CellRange> {
+		const endpointIndex = createEndpointIndex(this.matrix as unknown as SharedString);
 		const intervals = this.matrix.getIntervalCollection(label);
-		const interval = intervals.nextInterval(0);
+		intervals.attachIndex(endpointIndex);
+		const interval = endpointIndex.nextInterval(0);
+		intervals.detachIndex(endpointIndex);
 		return new CellRange(interval, this.localRefToRowCol);
 	}
 

packages/dds/sequence/api-report/sequence.api.md

@@ -165,9 +165,9 @@ export interface IIntervalCollection<TInterval extends ISerializableInterval> ex
     // (undocumented)
     getIntervalById(id: string): TInterval | undefined;
     map(fn: (interval: TInterval) => void): void;
-    // (undocumented)
+    // @deprecated (undocumented)
     nextInterval(pos: number): TInterval | undefined;
-    // (undocumented)
+    // @deprecated (undocumented)
     previousInterval(pos: number): TInterval | undefined;
     removeIntervalById(id: string): TInterval | undefined;
 }

packages/dds/sequence/src/intervalCollection.ts

@@ -939,8 +939,29 @@ export interface IIntervalCollection<TInterval extends ISerializableInterval>
 	 */
 	map(fn: (interval: TInterval) => void): void;
 
+	/**
+	 * @deprecated - due to the forthcoming change where the endpointIndex will no longer be
+	 * automatically added to the collection. Users are advised to independently attach the
+	 * index to the collection and utilize the API accordingly, for instance:
+	 * ```typescript
+	 * const endpointIndex = createEndpointIndex(sharedString);
+	 * collection.attachIndex(endpointIndex);
+	 * const result1 = endpointIndex.previousInterval(pos);
+	 * ```
+	 * If an index is used repeatedly, applications should generally attach it once and store it in memory.
+	 */
 	previousInterval(pos: number): TInterval | undefined;
 
+	/**
+	 * @deprecated - due to the forthcoming change where the endpointIndex will no longer be
+	 * automatically added to the collection. Users are advised to independently attach the
+	 * index to the collection and utilize the API accordingly, for instance:
+	 * ```typescript
+	 * const endpointIndex = createEndpointIndex(sharedString);
+	 * collection.attachIndex(endpointIndex);
+	 * const result2 = endpointIndex.nextInterval(pos);
+	 * ```
+	 */
 	nextInterval(pos: number): TInterval | undefined;
 }