Deprecate getStackContext (microsoft#16877)

Mark the getStackContext APIs and ReferenceType.NestBegin/NestEnd (only used for getStackContext) as deprecated. No one uses them and it causes bookkeeping in hierBlock (rangeStacks). It's also not really tested. The later removal is not yet scheduled (the functionality needs to be removed from a couple of our examples) but marking them deprecated should discourage new usages.
jatgarg · Aug 18, 2023 · d0f9c4b · d0f9c4b
1 parent 9dd1807
commit d0f9c4b
Show file tree

Hide file tree

Showing 7 changed files with 28 additions and 4 deletions.
diff --git a/.changeset/chilly-ideas-happen.md b/.changeset/chilly-ideas-happen.md
@@ -0,0 +1,9 @@
+---
+"@fluidframework/merge-tree": minor
+"@fluidframework/sequence": minor
+---
+
+Deprecate getStackContext and associated NestBegin/End
+
+Deprecate SharedSegmentSequence.getStackContext and Client.getStackContext (and the enums ReferenceType.NestBegin and NestEnd they use).
+This functionality is unused, poorly tested, and incurs performance overhead.
diff --git a/api-report/merge-tree.api.md b/api-report/merge-tree.api.md
@@ -145,7 +145,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
     };
     // (undocumented)
     getShortClientId(longClientId: string): number;
-    // (undocumented)
+    // @deprecated (undocumented)
     getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap;
     // (undocumented)
     insertAtReferencePositionLocal(refPos: ReferencePosition, segment: ISegment): IMergeTreeInsertMsg | undefined;
@@ -953,9 +953,9 @@ export interface ReferencePosition {
 
 // @public
 export enum ReferenceType {
-    // (undocumented)
+    // @deprecated (undocumented)
     NestBegin = 2,
-    // (undocumented)
+    // @deprecated (undocumented)
     NestEnd = 4,
     // (undocumented)
     RangeBegin = 16,

diff --git a/api-report/sequence.api.md b/api-report/sequence.api.md
@@ -547,7 +547,7 @@ export abstract class SharedSegmentSequence<T extends ISegment> extends SharedOb
         posStart: number | undefined;
         posAfterEnd: number | undefined;
     };
-    // (undocumented)
+    // @deprecated (undocumented)
     getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap;
     // @deprecated (undocumented)
     groupOperation(groupOp: IMergeTreeGroupMsg): void;

diff --git a/packages/dds/merge-tree/src/client.ts b/packages/dds/merge-tree/src/client.ts
@@ -1041,6 +1041,9 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		return loader.initialize(storage);
 	}
 
+	/**
+	 * @deprecated - this functionality is no longer supported and will be removed
+	 */
 	getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap {
 		return this._mergeTree.getStackContext(
 			startPos,

diff --git a/packages/dds/merge-tree/src/mergeTree.ts b/packages/dds/merge-tree/src/mergeTree.ts
@@ -1234,6 +1234,9 @@ export class MergeTree {
 		return DetachedReferencePosition;
 	}
 
+	/**
+	 * @deprecated - this functionality is no longer supported and will be removed
+	 */
 	public getStackContext(startPos: number, clientId: number, rangeLabels: string[]) {
 		const searchInfo: IMarkerSearchRangeInfo = {
 			mergeTree: this,

diff --git a/packages/dds/merge-tree/src/ops.ts b/packages/dds/merge-tree/src/ops.ts
@@ -12,7 +12,13 @@ export enum ReferenceType {
 	 * Allows this reference to be located using the `findTile` API on merge-tree.
 	 */
 	Tile = 0x1,
+	/**
+	 * @deprecated - this functionality is no longer supported and will be removed
+	 */
 	NestBegin = 0x2,
+	/**
+	 * @deprecated - this functionality is no longer supported and will be removed
+	 */
 	NestEnd = 0x4,
 	RangeBegin = 0x10,
 	RangeEnd = 0x20,

diff --git a/packages/dds/sequence/src/sequence.ts b/packages/dds/sequence/src/sequence.ts
@@ -415,6 +415,9 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		this.client.walkSegments(handler, start, end, accum as TClientData, splitRange);
 	}
 
+	/**
+	 * @deprecated - this functionality is no longer supported and will be removed
+	 */
 	public getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap {
 		return this.client.getStackContext(startPos, rangeLabels);
 	}