Test/internal merge tree client

packages/dds/merge-tree/api-report/merge-tree.legacy.alpha.api.md

@@ -7,15 +7,6 @@
 // @alpha
 export function appendToMergeTreeDeltaRevertibles(deltaArgs: IMergeTreeDeltaCallbackArgs, revertibles: MergeTreeDeltaRevertible[]): void;
 
-// @alpha @sealed @deprecated
-export interface AttributionPolicy {
-    attach: (client: Client) => void;
-    detach: () => void;
-    // (undocumented)
-    isAttached: boolean;
-    serializer: IAttributionCollectionSerializer;
-}
-
 // @alpha (undocumented)
 export abstract class BaseSegment implements ISegment {
     constructor(properties?: PropertySet);
@@ -87,104 +78,6 @@ export abstract class BaseSegment implements ISegment {
     wasMovedOnInsert?: boolean | undefined;
 }
 
-// @alpha @deprecated (undocumented)
-export class Client extends TypedEventEmitter<IClientEvents> {
-    constructor(specToSegment: (spec: IJSONSegment) => ISegment, logger: ITelemetryLoggerExt, options?: IMergeTreeOptions & PropertySet, getMinInFlightRefSeq?: () => number | undefined);
-    // (undocumented)
-    addLongClientId(longClientId: string): void;
-    annotateMarker(marker: Marker, props: PropertySet): IMergeTreeAnnotateMsg | undefined;
-    annotateRangeLocal(start: number, end: number, props: PropertySet): IMergeTreeAnnotateMsg | undefined;
-    // (undocumented)
-    applyMsg(msg: ISequencedDocumentMessage, local?: boolean): void;
-    // (undocumented)
-    applyStashedOp(op: IMergeTreeOp): void;
-    createLocalReferencePosition(segment: ISegment | "start" | "end", offset: number | undefined, refType: ReferenceType, properties: PropertySet | undefined, slidingPreference?: SlidingPreference, canSlideToEndpoint?: boolean): LocalReferencePosition;
-    // (undocumented)
-    createTextHelper(): IMergeTreeTextHelper;
-    findReconnectionPosition(segment: ISegment, localSeq: number): number;
-    // (undocumented)
-    getClientId(): number;
-    // (undocumented)
-    getCollabWindow(): CollaborationWindow;
-    // (undocumented)
-    getContainingSegment<T extends ISegment>(pos: number, sequenceArgs?: Pick<ISequencedDocumentMessage, "referenceSequenceNumber" | "clientId">, localSeq?: number): {
-        segment: T | undefined;
-        offset: number | undefined;
-    };
-    // (undocumented)
-    getCurrentSeq(): number;
-    // (undocumented)
-    getLength(): number;
-    // (undocumented)
-    getLongClientId(shortClientId: number): string;
-    // (undocumented)
-    getMarkerFromId(id: string): ISegment | undefined;
-    // (undocumented)
-    getOrAddShortClientId(longClientId: string): number;
-    getPosition(segment: ISegment | undefined, localSeq?: number): number;
-    // (undocumented)
-    getPropertiesAtPosition(pos: number): PropertySet | undefined;
-    // (undocumented)
-    getRangeExtentsOfPosition(pos: number): {
-        posStart: number | undefined;
-        posAfterEnd: number | undefined;
-    };
-    // (undocumented)
-    protected getShortClientId(longClientId: string): number;
-    insertAtReferencePositionLocal(refPos: ReferencePosition, segment: ISegment): IMergeTreeInsertMsg | undefined;
-    insertSegmentLocal(pos: number, segment: ISegment): IMergeTreeInsertMsg | undefined;
-    // (undocumented)
-    load(runtime: IFluidDataStoreRuntime, storage: IChannelStorageService, serializer: IFluidSerializer): Promise<{
-        catchupOpsP: Promise<ISequencedDocumentMessage[]>;
-    }>;
-    localReferencePositionToPosition(lref: ReferencePosition): number;
-    // (undocumented)
-    localTransaction(groupOp: IMergeTreeGroupMsg): void;
-    // (undocumented)
-    readonly logger: ITelemetryLoggerExt;
-    // (undocumented)
-    longClientId: string | undefined;
-    obliterateRangeLocal(start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): IMergeTreeObliterateMsg | IMergeTreeObliterateSidedMsg;
-    peekPendingSegmentGroups(): SegmentGroup | undefined;
-    // (undocumented)
-    peekPendingSegmentGroups(count: number): SegmentGroup | SegmentGroup[] | undefined;
-    posFromRelativePos(relativePos: IRelativePosition): number;
-    regeneratePendingOp(resetOp: IMergeTreeOp, segmentGroup: SegmentGroup | SegmentGroup[]): IMergeTreeOp;
-    removeLocalReferencePosition(lref: LocalReferencePosition): LocalReferencePosition | undefined;
-    removeRangeLocal(start: number, end: number): IMergeTreeRemoveMsg;
-    resolveRemoteClientPosition(remoteClientPosition: number, remoteClientRefSeq: number, remoteClientId: string): number | undefined;
-    rollback?(op: unknown, localOpMetadata: unknown): void;
-    searchForMarker(startPos: number, markerLabel: string, forwards?: boolean): Marker | undefined;
-    serializeGCData(handle: IFluidHandle, handleCollectingSerializer: IFluidSerializer): void;
-    // (undocumented)
-    readonly specToSegment: (spec: IJSONSegment) => ISegment;
-    // (undocumented)
-    startOrUpdateCollaboration(longClientId: string | undefined, minSeq?: number, currentSeq?: number): void;
-    // (undocumented)
-    summarize(runtime: IFluidDataStoreRuntime, handle: IFluidHandle, serializer: IFluidSerializer, catchUpMsgs: ISequencedDocumentMessage[]): ISummaryTreeWithStats;
-    // (undocumented)
-    updateMinSeq(minSeq: number): void;
-    // (undocumented)
-    protected walkAllSegments<TClientData>(action: (segment: ISegment, accum?: TClientData) => boolean, accum?: TClientData): boolean;
-    // (undocumented)
-    walkSegments<TClientData>(handler: ISegmentAction<TClientData>, start: number | undefined, end: number | undefined, accum: TClientData, splitRange?: boolean): void;
-    // (undocumented)
-    walkSegments(handler: ISegmentAction<undefined>, start?: number, end?: number, accum?: undefined, splitRange?: boolean): void;
-}
-
-// @alpha @deprecated (undocumented)
-export class CollaborationWindow {
-    // (undocumented)
-    clientId: number;
-    // (undocumented)
-    collaborating: boolean;
-    currentSeq: number;
-    // (undocumented)
-    loadFrom(a: CollaborationWindow): void;
-    localSeq: number;
-    minSeq: number;
-}
-
 // @alpha
 export function discardMergeTreeDeltaRevertible(revertibles: MergeTreeDeltaRevertible[]): void;
 
@@ -244,16 +137,6 @@ export interface IAttributionCollectionSpec<T> {
     }>;
 }
 
-// @alpha @deprecated
-export interface IClientEvents {
-    // (undocumented)
-    (event: "normalize", listener: (target: IEventThisPlaceHolder) => void): void;
-    // (undocumented)
-    (event: "delta", listener: (opArgs: IMergeTreeDeltaOpArgs, deltaArgs: IMergeTreeDeltaCallbackArgs, target: IEventThisPlaceHolder) => void): void;
-    // (undocumented)
-    (event: "maintenance", listener: (args: IMergeTreeMaintenanceCallbackArgs, deltaArgs: IMergeTreeDeltaOpArgs | undefined, target: IEventThisPlaceHolder) => void): void;
-}
-
 // @alpha (undocumented)
 export interface IJSONMarkerSegment extends IJSONSegment {
     // (undocumented)
@@ -302,12 +185,6 @@ export interface IMergeTreeAnnotateMsg extends IMergeTreeDelta {
     type: typeof MergeTreeDeltaType.ANNOTATE;
 }
 
-// @alpha @deprecated (undocumented)
-export interface IMergeTreeAttributionOptions {
-    policyFactory?: () => AttributionPolicy;
-    track?: boolean;
-}
-
 // @alpha (undocumented)
 export interface IMergeTreeDelta {
     type: MergeTreeDeltaType;
@@ -392,7 +269,6 @@ export type IMergeTreeOp = IMergeTreeDeltaOp | IMergeTreeGroupMsg;
 
 // @alpha (undocumented)
 export interface IMergeTreeOptions {
-    attribution?: IMergeTreeAttributionOptions;
     // (undocumented)
     catchUpBlobName?: string;
     mergeTreeEnableObliterate?: boolean;

packages/dds/merge-tree/src/client.ts

@@ -29,7 +29,11 @@ import { MergeTreeTextHelper } from "./MergeTreeTextHelper.js";
 import { DoublyLinkedList, RedBlackTree } from "./collections/index.js";
 import { UnassignedSequenceNumber, UniversalSequenceNumber } from "./constants.js";
 import { LocalReferencePosition, SlidingPreference } from "./localReference.js";
-import { IMergeTreeOptions, MergeTree, errorIfOptionNotTrue } from "./mergeTree.js";
+import {
+	MergeTree,
+	errorIfOptionNotTrue,
+	type IMergeTreeOptionsInternal,
+} from "./mergeTree.js";
 import type {
 	IMergeTreeClientSequenceArgs,
 	IMergeTreeDeltaCallbackArgs,
@@ -100,9 +104,7 @@ export interface IIntegerRange {
  * Emitted before this client's merge-tree normalizes its segments on reconnect, potentially
  * ordering them. Useful for DDS-like consumers built atop the merge-tree to compute any information
  * they need for rebasing their ops on reconnection.
- * @legacy
- * @alpha
- * @deprecated  This functionality was not meant to be exported and will be removed in a future release
+ * @internal
  */
 export interface IClientEvents {
 	(event: "normalize", listener: (target: IEventThisPlaceHolder) => void): void;
@@ -125,9 +127,7 @@ export interface IClientEvents {
 }
 
 /**
- * @deprecated This functionality was not meant to be exported and will be removed in a future release
- * @legacy
- * @alpha
+ * @internal
  */
 export class Client extends TypedEventEmitter<IClientEvents> {
 	public longClientId: string | undefined;
@@ -155,7 +155,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 	constructor(
 		public readonly specToSegment: (spec: IJSONSegment) => ISegment,
 		public readonly logger: ITelemetryLoggerExt,
-		options?: IMergeTreeOptions & PropertySet,
+		options?: IMergeTreeOptionsInternal & PropertySet,
 		private readonly getMinInFlightRefSeq: () => number | undefined = (): undefined =>
 			undefined,
 	) {

packages/dds/merge-tree/src/index.ts

@@ -42,6 +42,7 @@ export {
 	AttributionPolicy,
 	IMergeTreeAttributionOptions,
 	IMergeTreeOptions,
+	IMergeTreeOptionsInternal,
 	getSlideToSegoff,
 } from "./mergeTree.js";
 export {

packages/dds/merge-tree/src/mergeTree.ts

@@ -10,7 +10,6 @@ import { assert, Heap, IComparer } from "@fluidframework/core-utils/internal";
 import { DataProcessingError, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { IAttributionCollectionSerializer } from "./attributionCollection.js";
-// eslint-disable-next-line import/no-deprecated
 import { Client } from "./client.js";
 import { DoublyLinkedList, ListNode } from "./collections/index.js";
 import {
@@ -177,11 +176,6 @@ export interface IMergeTreeOptions {
 	 */
 	newMergeTreeSnapshotFormat?: boolean;
 
-	/**
-	 * Options related to attribution
-	 */
-	attribution?: IMergeTreeAttributionOptions;
-
 	/**
 	 * Enables support for the obliterate operation -- a stronger form of remove
 	 * which deletes concurrently inserted segments
@@ -212,6 +206,17 @@ export interface IMergeTreeOptions {
 	 */
 	mergeTreeEnableSidedObliterate?: boolean;
 }
+
+/**
+ * @internal
+ */
+export interface IMergeTreeOptionsInternal extends IMergeTreeOptions {
+	/**
+	 * Options related to attribution
+	 */
+	attribution?: IMergeTreeAttributionOptions;
+}
+
 export function errorIfOptionNotTrue(
 	options: IMergeTreeOptions | undefined,
 	option: keyof IMergeTreeOptions,
@@ -222,9 +227,7 @@ export function errorIfOptionNotTrue(
 }
 
 /**
- * @legacy
- * @alpha
- * @deprecated  This functionality was not meant to be exported and will be removed in a future release
+ * @internal
  */
 export interface IMergeTreeAttributionOptions {
 	/**
@@ -250,9 +253,7 @@ export interface IMergeTreeAttributionOptions {
 /**
  * Implements policy dictating which kinds of operations should be attributed and how.
  * @sealed
- * @legacy
- * @alpha
- * @deprecated This functionality was not meant to be exported and will be removed in a future release
+ * @internal
  */
 export interface AttributionPolicy {
 	/**
@@ -262,7 +263,6 @@ export interface AttributionPolicy {
 	 *
 	 * This must be done in an eventually consistent fashion.
 	 */
-	// eslint-disable-next-line import/no-deprecated
 	attach: (client: Client) => void;
 	/**
 	 * Disables tracking attribution information on segments.
@@ -527,7 +527,7 @@ export class MergeTree {
 
 	private readonly obliterates = new Obliterates(this);
 
-	public constructor(public options?: IMergeTreeOptions) {
+	public constructor(public options?: IMergeTreeOptionsInternal) {
 		this._root = this.makeBlock(0);
 		this._root.mergeTree = this;
 		this.attributionPolicy = options?.attribution?.policyFactory?.();

packages/dds/merge-tree/src/mergeTreeNodes.ts

@@ -265,7 +265,6 @@ export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Parti
 	 * This is defined if and only if the insertion of the segment is pending ack, i.e. `seq` is UnassignedSequenceNumber.
 	 * Once the segment is acked, this field is cleared.
 	 *
-	 * See {@link CollaborationWindow.localSeq} for more information on the semantics of localSeq.
 	 */
 	localSeq?: number;
 	/**
@@ -274,7 +273,6 @@ export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Parti
 	 * will be updated to the seq at which that client removed this segment.
 	 *
 	 * Like {@link ISegment.localSeq}, this field is cleared once the local removal of the segment is acked.
-	 * See {@link CollaborationWindow.localSeq} for more information on the semantics of localSeq.
 	 */
 	localRemovedSeq?: number;
 	/**
@@ -896,9 +894,7 @@ export class Marker extends BaseSegment implements ReferencePosition, ISegment {
 }
 
 /**
- * @deprecated This functionality was not meant to be exported and will be removed in a future release
- * @legacy
- * @alpha
+ * @internal
  */
 export class CollaborationWindow {
 	clientId = LocalClientId;

packages/dds/merge-tree/src/test/index.ts

@@ -39,7 +39,12 @@ export {
 	runMergeTreeOperationRunner,
 	TestOperation,
 } from "./mergeTreeOperationRunner.js";
-export { LRUSegment, MergeTree } from "../mergeTree.js";
+export {
+	LRUSegment,
+	MergeTree,
+	IMergeTreeOptions,
+	IMergeTreeOptionsInternal,
+} from "../mergeTree.js";
 export { MergeTreeTextHelper } from "../MergeTreeTextHelper.js";
 export { SnapshotLegacy } from "../snapshotlegacy.js";
 export {

packages/dds/merge-tree/src/test/snapshot.spec.ts

@@ -9,12 +9,12 @@ import {
 	createInsertOnlyAttributionPolicy,
 	createPropertyTrackingAttributionPolicyFactory,
 } from "../attributionPolicy.js";
-import { IMergeTreeOptions } from "../mergeTree.js";
+import { IMergeTreeOptionsInternal } from "../mergeTree.js";
 import { SnapshotV1 } from "../snapshotV1.js";
 
 import { TestString, loadSnapshot } from "./snapshot.utils.js";
 
-function makeSnapshotSuite(options?: IMergeTreeOptions): void {
+function makeSnapshotSuite(options?: IMergeTreeOptionsInternal): void {
 	describe("from an empty initial state", () => {
 		let str: TestString;
 		beforeEach(() => {

packages/dds/merge-tree/src/test/snapshot.utils.ts

@@ -12,7 +12,7 @@ import { ISummaryTree } from "@fluidframework/driver-definitions";
 import { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import { MockStorage } from "@fluidframework/test-runtime-utils/internal";
 
-import { IMergeTreeOptions } from "../mergeTree.js";
+import { type IMergeTreeOptionsInternal } from "../mergeTree.js";
 import { ISegment } from "../mergeTreeNodes.js";
 import { IMergeTreeOp, ReferenceType } from "../ops.js";
 import { PropertySet } from "../properties.js";
@@ -25,7 +25,7 @@ import { TestSerializer } from "./testSerializer.js";
 // Reconstitutes a MergeTree client from a summary
 export async function loadSnapshot(
 	summary: ISummaryTree,
-	options?: IMergeTreeOptions,
+	options?: IMergeTreeOptionsInternal,
 ): Promise<TestClient> {
 	const services = MockStorage.createFromSummary(summary);
 	const client2 = new TestClient(options);
@@ -52,7 +52,7 @@ export class TestString {
 
 	constructor(
 		id: string,
-		private readonly options?: IMergeTreeOptions,
+		private readonly options?: IMergeTreeOptionsInternal,
 		initialState: string = "",
 	) {
 		this.client = createClientsAtInitialState({ initialState, options }, id)[id];
@@ -109,7 +109,7 @@ export class TestString {
 	}
 
 	// Ensures the MergeTree client's contents successfully roundtrip through a snapshot.
-	public async checkSnapshot(options?: IMergeTreeOptions): Promise<void> {
+	public async checkSnapshot(options?: IMergeTreeOptionsInternal): Promise<void> {
 		this.applyPendingOps();
 		const expectedAttributionKeys = this.client.getAllAttributionSeqs();
 		const summary = this.getSummary();