@fluidframework/merge-tree 2.41.0 → 2.43.0-343119

package/src/client.ts

@@ -27,7 +27,7 @@ import {
 
 import { MergeTreeTextHelper, type IMergeTreeTextHelper } from "./MergeTreeTextHelper.js";
 import { DoublyLinkedList, RedBlackTree } from "./collections/index.js";
-import { NonCollabClient, UniversalSequenceNumber } from "./constants.js";
+import { NonCollabClient, SquashClient, UniversalSequenceNumber } from "./constants.js";
 import { LocalReferencePosition, SlidingPreference } from "./localReference.js";
 import {
 	MergeTree,
@@ -84,6 +84,7 @@ import {
 } from "./ops.js";
 import {
 	LocalReconnectingPerspective,
+	LocalSquashPerspective,
 	PriorPerspective,
 	type Perspective,
 } from "./perspective.js";
@@ -95,6 +96,7 @@ import {
 	overwriteInfo,
 	toRemovalInfo,
 	type IHasInsertionInfo,
+	type IHasRemovalInfo,
 } from "./segmentInfos.js";
 import { Side, type InteriorSequencePlace } from "./sequencePlace.js";
 import { SnapshotLoader } from "./snapshotLoader.js";
@@ -363,6 +365,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		end: number | undefined,
 		accum: TClientData,
 		splitRange?: boolean,
+		perspective?: Pick<ISequencedDocumentMessage, "clientId" | "referenceSequenceNumber">,
 	): void;
 	public walkSegments(
 		handler: ISegmentAction<undefined>,
@@ -370,6 +373,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		end?: number,
 		accum?: undefined,
 		splitRange?: boolean,
+		perspective?: Pick<ISequencedDocumentMessage, "clientId" | "referenceSequenceNumber">,
 	): void;
 	public walkSegments<TClientData>(
 		handler: ISegmentAction<TClientData>,
@@ -377,10 +381,13 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		end: number | undefined,
 		accum: TClientData,
 		splitRange: boolean = false,
+		perspective?: Pick<ISequencedDocumentMessage, "clientId" | "referenceSequenceNumber">,
 	): void {
 		this._mergeTree.mapRange(
 			handler,
-			this._mergeTree.localPerspective,
+			perspective === undefined
+				? this.getCollabWindow().localPerspective
+				: this.getOperationPerspective(perspective),
 			accum,
 			start,
 			end,
@@ -556,7 +563,9 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 	}
 
 	private getOperationPerspective(
-		sequencedMessage: ISequencedDocumentMessage | undefined,
+		sequencedMessage:
+			| Pick<ISequencedDocumentMessage, "clientId" | "referenceSequenceNumber">
+			| undefined,
 	): Perspective {
 		if (!sequencedMessage) {
 			return this._mergeTree.localPerspective;
@@ -869,17 +878,20 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		const useNewSlidingBehavior = true;
 		// Destructuring segment + offset is convenient and segment is reassigned
 		// eslint-disable-next-line prefer-const
-		let { segment: newSegment, offset: newOffset } = getSlideToSegoff(
+		const segOff = getSlideToSegoff(
 			{ segment: oldSegment, offset: oldOffset },
 			slidePreference,
 			reconnectingPerspective,
 			useNewSlidingBehavior,
 		);
 
-		newSegment ??=
-			slidePreference === SlidingPreference.FORWARD
-				? this._mergeTree.endOfTree
-				: this._mergeTree.startOfTree;
+		const { segment: newSegment, offset: newOffset } = segOff ?? {
+			segment:
+				slidePreference === SlidingPreference.FORWARD
+					? this._mergeTree.endOfTree
+					: this._mergeTree.startOfTree,
+			offset: 0,
+		};
 
 		assert(
 			isSegmentLeaf(newSegment) && newOffset !== undefined,
@@ -898,16 +910,17 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		return { segment: newSegment, offset: newOffset, side: newSide };
 	}
 
-	private computeNewObliterateEndpoints(obliterateInfo: ObliterateInfo): {
+	private computeNewObliterateEndpoints(
+		obliterateInfo: ObliterateInfo,
+		squash: boolean,
+	): {
 		start: RebasedObliterateEndpoint;
 		end: RebasedObliterateEndpoint;
 	} {
 		const { currentSeq, clientId } = this.getCollabWindow();
-		const reconnectingPerspective = new LocalReconnectingPerspective(
-			currentSeq,
-			clientId,
-			obliterateInfo.stamp.localSeq! - 1,
-		);
+		const reconnectingPerspective = new (
+			squash ? LocalSquashPerspective : LocalReconnectingPerspective
+		)(currentSeq, clientId, obliterateInfo.stamp.localSeq! - 1);
 
 		const newStart = this.rebaseSidedLocalReference(
 			obliterateInfo.start,
@@ -932,6 +945,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		resetOp: IMergeTreeDeltaOp,
 
 		segmentGroup: SegmentGroup,
+		squash: boolean,
 	): IMergeTreeDeltaOp[] {
 		assert(!!segmentGroup, 0x033 /* "Segment group undefined" */);
 		const NACKedSegmentGroup = this.pendingRebase?.shift()?.data;
@@ -991,13 +1005,20 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 					);
 					const lastRemove = segment.removes[segment.removes.length - 1];
 					assert(
-						lastRemove.type === "sliceRemove" && lastRemove.localSeq === segmentGroup.localSeq,
-						0xb67 /* Last remove should be the obliterate that is being resubmitted. */,
+						(lastRemove.type === "sliceRemove" &&
+							lastRemove.localSeq === segmentGroup.localSeq) ||
+							opstampUtils.isSquashedOp(lastRemove),
+						0xbad /* Last remove should be the obliterate that is being resubmitted. */,
 					);
-					// The original obliterate affected this segment, but it has since been removed and overlapping removes
-					// are only possible when they are concurrent. We adjust the metadata on that segment now to reflect
-					// the fact that the obliterate no longer affects it.
-					segment.removes.pop();
+
+					// The original obliterate affected this segment, but it has since been removed.
+					// This can happen when a concurrent obliterate also removed the segment, as well as when the segment was
+					// only locally inserted and its insertion was squashed upon reconnecting.
+					// In the concurrent removal case (where we didn't avoid sending the segment's insertion in the first place due
+					// to squashing), we adjust the metadata on that segment to reflect the fact that this obliterate no longer removes it.
+					if (!opstampUtils.isSquashedOp(lastRemove)) {
+						segment.removes.pop();
+					}
 				}
 
 				this._mergeTree.rebaseObliterateTo(obliterateInfo, undefined);
@@ -1047,10 +1068,11 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 					0x035 /* "Segment group not in segment pending queue" */,
 				);
 				if (
-					(segment.ordinal > newStartSegment.ordinal &&
+					!isRemovedAndAcked(segment) &&
+					((segment.ordinal > newStartSegment.ordinal &&
 						segment.ordinal < newEndSegment.ordinal) ||
-					(segment === newStartSegment && newStartSide === Side.Before) ||
-					(segment === newEndSegment && newEndSide === Side.After)
+						(segment === newStartSegment && newStartSide === Side.Before) ||
+						(segment === newEndSegment && newEndSide === Side.After))
 				) {
 					segment.segmentGroups.enqueue(newObliterate.segmentGroup);
 				} else {
@@ -1060,12 +1082,17 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 					);
 					const lastRemove = segment.removes[segment.removes.length - 1];
 					assert(
-						lastRemove.type === "sliceRemove" && lastRemove.localSeq === segmentGroup.localSeq,
-						0xb6a /* Last remove should be the obliterate that is being resubmitted. */,
+						(lastRemove.type === "sliceRemove" &&
+							lastRemove.localSeq === segmentGroup.localSeq) ||
+							opstampUtils.isSquashedOp(lastRemove),
+						0xbae /* Last remove should be the obliterate that is being resubmitted. */,
 					);
-					// The original obliterate affected this segment, but it has since been removed and it's impossible to apply the
-					// local obliterate so that is so. We adjust the metadata on that segment now.
-					segment.removes.pop();
+
+					if (!opstampUtils.isSquashedOp(lastRemove)) {
+						// The original obliterate affected this segment, but it has since been removed and it's impossible to apply the
+						// local obliterate so that is so. We adjust the metadata on that segment now.
+						segment.removes.pop();
+					}
 				}
 			}
 
@@ -1154,13 +1181,25 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 				}
 
 				case MergeTreeDeltaType.INSERT: {
+					if (isInserted(segment) && opstampUtils.isSquashedOp(segment.insert)) {
+						break;
+					}
 					assert(
 						isInserted(segment) && opstampUtils.isLocal(segment.insert),
 						0x037 /* "Segment already has assigned sequence number" */,
 					);
 					const removeInfo = toRemovalInfo(segment);
 
-					if (removeInfo !== undefined && opstampUtils.isAcked(removeInfo.removes[0])) {
+					const unusedStamp: OperationStamp = { seq: 0, clientId: 0 };
+					if (removeInfo !== undefined && squash) {
+						assert(
+							removeInfo.removes.length === 1 ||
+								opstampUtils.isAcked(removeInfo.removes[removeInfo.removes.length - 2]),
+							0xbaf /* Expected only one local remove */,
+						);
+						this.squashInsertion(segment);
+						break;
+					} else if (removeInfo !== undefined && opstampUtils.isAcked(removeInfo.removes[0])) {
 						assert(
 							removeInfo.removes[0].type === "sliceRemove",
 							0xb5c /* Remove on insertion must be caused by obliterate. */,
@@ -1181,6 +1220,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 								clientId: NonCollabClient,
 							},
 						});
+						this._mergeTree.blockUpdatePathLengths(segment.parent, unusedStamp, true);
 						break;
 					}
 
@@ -1360,13 +1400,40 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		{ start: RebasedObliterateEndpoint; end: RebasedObliterateEndpoint }
 	> = new Map();
 
+	private squashInsertion(segment: ISegmentLeaf): void {
+		overwriteInfo<IHasInsertionInfo & IHasRemovalInfo>(segment, {
+			insert: {
+				type: "insert",
+				seq: UniversalSequenceNumber,
+				localSeq: undefined,
+				clientId: SquashClient,
+			},
+			removes: [
+				{
+					type: "setRemove",
+					seq: UniversalSequenceNumber,
+					localSeq: undefined,
+					clientId: SquashClient,
+				},
+			],
+		});
+
+		this._mergeTree.blockUpdatePathLengths(segment.parent, { seq: 0, clientId: 0 }, true);
+	}
+
 	/**
 	 * Given a pending operation and segment group, regenerate the op, so it
 	 * can be resubmitted
 	 * @param resetOp - The op to reset
 	 * @param segmentGroup - The segment group associated with the op
+	 * @param squash - whether intermediate states should be squashed. See `IDeltaHandler.reSubmit`'s squash parameter
+	 * documentation for more details.
 	 */
-	public regeneratePendingOp(resetOp: IMergeTreeOp, localOpMetadata: unknown): IMergeTreeOp {
+	public regeneratePendingOp(
+		resetOp: IMergeTreeOp,
+		localOpMetadata: unknown,
+		squash: boolean,
+	): IMergeTreeOp {
 		const segmentGroup = localOpMetadata as SegmentGroup | SegmentGroup[];
 		if (this.pendingRebase === undefined || this.pendingRebase.empty) {
 			let firstGroup: SegmentGroup;
@@ -1396,13 +1463,14 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 			collabWindow.currentSeq !== this.lastNormalization.refSeq ||
 			collabWindow.localSeq !== this.lastNormalization.localRefSeq
 		) {
+			const allPendingSegments = [...this._mergeTree.pendingSegments, ...this.pendingRebase];
 			// Compute obliterate endpoint destinations before segments are normalized.
 			// Segment normalization can affect what should be the semantically correct segments for the endpoints to be placed on.
 			this.cachedObliterateRebases.clear();
-			for (const group of [...this._mergeTree.pendingSegments, ...this.pendingRebase]) {
+			for (const group of allPendingSegments) {
 				const { obliterateInfo } = group.data;
 				if (obliterateInfo !== undefined) {
-					const { start, end } = this.computeNewObliterateEndpoints(obliterateInfo);
+					const { start, end } = this.computeNewObliterateEndpoints(obliterateInfo, squash);
 					const { localSeq } = obliterateInfo.stamp;
 					assert(localSeq !== undefined, 0xb6d /* Local seq must be defined */);
 					this.cachedObliterateRebases.set(localSeq, { start, end });
@@ -1426,7 +1494,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 				);
 
 				for (let i = 0; i < resetOp.ops.length; i++) {
-					opList.push(...this.resetPendingDeltaToOps(resetOp.ops[i], segmentGroup[i]));
+					opList.push(...this.resetPendingDeltaToOps(resetOp.ops[i], segmentGroup[i], squash));
 				}
 			} else {
 				// A group op containing a single op will pass a direct reference to 'segmentGroup'
@@ -1435,7 +1503,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 					resetOp.ops.length === 1,
 					0x03b /* "Number of ops in 'resetOp' must match the number of segment groups provided." */,
 				);
-				opList.push(...this.resetPendingDeltaToOps(resetOp.ops[0], segmentGroup));
+				opList.push(...this.resetPendingDeltaToOps(resetOp.ops[0], segmentGroup, squash));
 			}
 		} else {
 			assert(
@@ -1446,7 +1514,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 				!Array.isArray(segmentGroup),
 				0x03d /* "segmentGroup is array rather than singleton!" */,
 			);
-			opList.push(...this.resetPendingDeltaToOps(resetOp, segmentGroup));
+			opList.push(...this.resetPendingDeltaToOps(resetOp, segmentGroup, squash));
 		}
 
 		return opList.length === 1 ? opList[0] : createGroupOp(...opList);
@@ -1547,10 +1615,12 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		pos: number,
 		sequenceArgs?: Pick<ISequencedDocumentMessage, "referenceSequenceNumber" | "clientId">,
 		localSeq?: number,
-	): {
-		segment: T | undefined;
-		offset: number | undefined;
-	} {
+	):
+		| {
+				segment: T;
+				offset: number;
+		  }
+		| undefined {
 		let perspective: Perspective;
 		const clientId =
 			sequenceArgs === undefined
@@ -1565,20 +1635,17 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 			perspective = new PriorPerspective(refSeq, clientId);
 		}
 
-		return this._mergeTree.getContainingSegment(pos, perspective) as {
-			segment: T | undefined;
-			offset: number | undefined;
-		};
+		return this._mergeTree.getContainingSegment(pos, perspective) as
+			| {
+					segment: T;
+					offset: number;
+			  }
+			| undefined;
 	}
 
 	getPropertiesAtPosition(pos: number): PropertySet | undefined {
-		let propertiesAtPosition: PropertySet | undefined;
 		const segoff = this.getContainingSegment(pos);
-		const seg = segoff.segment;
-		if (seg) {
-			propertiesAtPosition = seg.properties;
-		}
-		return propertiesAtPosition;
+		return segoff?.segment?.properties;
 	}
 
 	getRangeExtentsOfPosition(pos: number): {
@@ -1589,7 +1656,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		let posAfterEnd: number | undefined;
 
 		const segoff = this.getContainingSegment(pos);
-		const seg = segoff.segment;
+		const seg = segoff?.segment;
 		if (seg) {
 			posStart = this.getPosition(seg);
 			posAfterEnd = posStart + seg.cachedLength;

package/src/collections/list.ts

@@ -5,15 +5,46 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
+/**
+ * Represents a node in a doubly linked list.
+ * @internal
+ */
 export interface ListNode<T> {
+	/**
+	 * The list this node belongs to, or undefined if not attached.
+	 */
 	readonly list: DoublyLinkedList<T> | undefined;
+	/**
+	 * The data value stored in this node.
+	 */
 	readonly data: T;
+	/**
+	 * The next node in the list, or undefined if this is the last node.
+	 */
 	readonly next: ListNode<T> | undefined;
+	/**
+	 * The previous node in the list, or undefined if this is the first node.
+	 */
 	readonly prev: ListNode<T> | undefined;
+	/**
+	 * Removes this node from its list.
+	 * @returns The removed node, or undefined if not in a list.
+	 */
+	remove(): ListNode<T> | undefined;
 }
 
+/**
+ * Represents a range of nodes in a doubly linked list.
+ * @internal
+ */
 export interface ListNodeRange<T> {
+	/**
+	 * The first node in the range.
+	 */
 	first: ListNode<T>;
+	/**
+	 * The last node in the range.
+	 */
 	last: ListNode<T>;
 }
 
@@ -50,6 +81,9 @@ class DataNode<T> extends HeadNode<T> implements ListNode<T> {
 		super(undefined);
 		this.headNode = headNode;
 	}
+	remove(): ListNode<T> | undefined {
+		return this.list?.remove(this);
+	}
 }
 
 function insertAfter<T>(node: DataNode<T> | HeadNode<T>, items: T[]): ListNodeRange<T> {
@@ -80,6 +114,11 @@ function insertAfter<T>(node: DataNode<T> | HeadNode<T>, items: T[]): ListNodeRa
 	return newRange;
 }
 
+/**
+ * A doubly linked list implementation with array-like methods and node access.
+ * @typeParam T - The type of data stored in the list nodes.
+ * @internal
+ */
 export class DoublyLinkedList<T>
 	implements
 		Iterable<ListNode<T>>,
@@ -87,12 +126,21 @@ export class DoublyLinkedList<T>
 		// try to match array signature and semantics where possible
 		Pick<ListNode<T>[], "pop" | "shift" | "length" | "includes">
 {
+	/**
+	 * Creates a new doubly linked list optionally initialized with values.
+	 * @param values - Optional iterable of values to populate the list.
+	 */
 	constructor(values?: Iterable<T>) {
 		if (values !== undefined) {
 			this.push(...values);
 		}
 	}
 
+	/**
+	 * Finds the first node matching the predicate.
+	 * @param predicate - Function to test each node.
+	 * @returns The first matching node, or undefined if none found.
+	 */
 	find(
 		predicate: (value: ListNode<T>, obj: DoublyLinkedList<T>) => unknown,
 	): ListNode<T> | undefined {
@@ -106,6 +154,10 @@ export class DoublyLinkedList<T>
 		return found;
 	}
 
+	/**
+	 * Returns an iterable that maps each node to a new value.
+	 * @param callbackfn - Function to produce a new value for each node.
+	 */
 	map<U>(callbackfn: (value: ListNode<T>) => U): Iterable<U> {
 		let node = this.first;
 		const iterator: IterableIterator<U> = {
@@ -124,6 +176,12 @@ export class DoublyLinkedList<T>
 		return iterator;
 	}
 
+	/**
+	 * Inserts items after the specified node.
+	 * @param preceding - The node to insert after.
+	 * @param items - Items to insert.
+	 * @returns The range of newly inserted nodes.
+	 */
 	insertAfter(preceding: ListNode<T>, ...items: T[]): ListNodeRange<T> {
 		if (!this._includes(preceding)) {
 			throw new Error("preceding not in list");
@@ -132,10 +190,19 @@ export class DoublyLinkedList<T>
 		return insertAfter(preceding, items);
 	}
 
+	/**
+	 * Removes and returns the last node in the list.
+	 * @returns The removed node, or undefined if the list is empty.
+	 */
 	pop(): ListNode<T> | undefined {
 		return this.remove(this.last);
 	}
 
+	/**
+	 * Appends items to the end of the list.
+	 * @param items - Items to append.
+	 * @returns The range of newly inserted nodes.
+	 */
 	push(...items: T[]): ListNodeRange<T> {
 		this._len += items.length;
 		const start = this.headNode._prev;
@@ -143,14 +210,17 @@ export class DoublyLinkedList<T>
 	}
 
 	/**
-	 * Remove and return the first element
+	 * Removes and returns the first node in the list.
+	 * @returns The removed node, or undefined if the list is empty.
 	 */
 	shift(): ListNode<T> | undefined {
 		return this.remove(this.first);
 	}
 
 	/**
-	 * Insert `items` at start of list
+	 * Inserts items at the start of the list.
+	 * @param items - Items to insert.
+	 * @returns The range of newly inserted nodes.
 	 */
 	unshift(...items: T[]): ListNodeRange<T> {
 		this._len += items.length;
@@ -158,9 +228,10 @@ export class DoublyLinkedList<T>
 	}
 
 	/**
-	 * Remove nodes starting at `start` until either the `end` node is reached
-	 * or until `count` nodes have been removed. Returns the removed nodes as
-	 * a separate linked list
+	 * Removes nodes starting at `start` until `end` or `count` is reached.
+	 * @param start - The node to start removing from.
+	 * @param countOrEnd - The number of nodes to remove or the end node.
+	 * @returns A new list containing the removed nodes.
 	 */
 	splice(start: ListNode<T>, countOrEnd?: ListNode<T> | number): DoublyLinkedList<T> {
 		const newList = new DoublyLinkedList<T>();
@@ -187,6 +258,11 @@ export class DoublyLinkedList<T>
 		return newList;
 	}
 
+	/**
+	 * Checks if the node is in this list.
+	 * @param node - The node to check.
+	 * @returns True if the node is in the list.
+	 */
 	public includes(node: ListNode<T> | undefined): node is ListNode<T> {
 		return this._includes(node);
 	}
@@ -207,6 +283,11 @@ export class DoublyLinkedList<T>
 		return undefined;
 	}
 
+	/**
+	 * Removes the specified node from the list.
+	 * @param node - The node to remove.
+	 * @returns The removed node, or undefined if not in the list.
+	 */
 	public remove(node: ListNode<T> | undefined): ListNode<T> | undefined {
 		return this._remove(node);
 	}
@@ -231,16 +312,31 @@ export class DoublyLinkedList<T>
 
 	private _len: number = 0;
 	private readonly headNode: HeadNode<T> | DataNode<T> = new HeadNode(this);
+
+	/**
+	 * The number of nodes in the list.
+	 */
 	public get length(): number {
 		return this._len;
 	}
+
+	/**
+	 * Whether the list is empty.
+	 */
 	public get empty(): boolean {
 		return this._len === 0;
 	}
+
+	/**
+	 * The first node in the list, or undefined if empty.
+	 */
 	public get first(): ListNode<T> | undefined {
 		return this.headNode.next;
 	}
 
+	/**
+	 * The last node in the list, or undefined if empty.
+	 */
 	public get last(): ListNode<T> | undefined {
 		return this.headNode.prev;
 	}

package/src/constants.ts

@@ -34,3 +34,9 @@ export const LocalClientId = -1;
  * @internal
  */
 export const NonCollabClient = -2;
+
+/**
+ * Used as the client id for operations that were squashed upon resubmission and should therefore
+ * never be seen by other clients.
+ */
+export const SquashClient = -3;

package/src/index.ts

@@ -30,6 +30,9 @@ export {
 	RBNodeActions,
 	RedBlackTree,
 	SortedDictionary,
+	DoublyLinkedList,
+	ListNode,
+	ListNodeRange,
 } from "./collections/index.js";
 export { UnassignedSequenceNumber, UniversalSequenceNumber } from "./constants.js";
 export {