@fluidframework/merge-tree 2.4.0-294316 → 2.4.0-297027

package/src/client.ts

@@ -56,6 +56,7 @@ import {
 	createGroupOp,
 	createInsertSegmentOp,
 	createObliterateRangeOp,
+	createObliterateRangeOpSided,
 	createRemoveRangeOp,
 } from "./opBuilder.js";
 import {
@@ -72,9 +73,11 @@ import {
 	IRelativePosition,
 	MergeTreeDeltaType,
 	ReferenceType,
+	type IMergeTreeObliterateSidedMsg,
 } from "./ops.js";
 import { PropertySet } from "./properties.js";
 import { DetachedReferencePosition, ReferencePosition } from "./referencePositions.js";
+import { Side, type InteriorSequencePlace } from "./sequencePlace.js";
 import { SnapshotLoader } from "./snapshotLoader.js";
 import { SnapshotV1 } from "./snapshotV1.js";
 import { SnapshotLegacy } from "./snapshotlegacy.js";
@@ -99,6 +102,7 @@ export interface IIntegerRange {
  * 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
  */
 export interface IClientEvents {
 	(event: "normalize", listener: (target: IEventThisPlaceHolder) => void): void;
@@ -252,15 +256,26 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 	 * Obliterates the range. This is similar to removing the range, but also
 	 * includes any concurrently inserted content.
 	 *
-	 * @param start - The inclusive start of the range to obliterate
-	 * @param end - The exclusive end of the range to obliterate
+	 * @param start - The start of the range to obliterate. Inclusive is side is Before (default).
+	 * @param end - The end of the range to obliterate. Exclusive is side is After
+	 * (default is to be after the last included character, but number index is exclusive).
 	 */
 	public obliterateRangeLocal(
-		start: number,
-		end: number,
+		start: number | InteriorSequencePlace,
+		end: number | InteriorSequencePlace,
+		// eslint-disable-next-line import/no-deprecated
+	): IMergeTreeObliterateMsg | IMergeTreeObliterateSidedMsg {
 		// eslint-disable-next-line import/no-deprecated
-	): IMergeTreeObliterateMsg {
-		const obliterateOp = createObliterateRangeOp(start, end);
+		let obliterateOp: IMergeTreeObliterateMsg | IMergeTreeObliterateSidedMsg;
+		if (this._mergeTree.options?.mergeTreeEnableSidedObliterate) {
+			obliterateOp = createObliterateRangeOpSided(start, end);
+		} else {
+			assert(
+				typeof start === "number" && typeof end === "number",
+				"Start and end must be numbers if mergeTreeEnableSidedObliterate is not enabled.",
+			);
+			obliterateOp = createObliterateRangeOp(start, end);
+		}
 		this.applyObliterateRangeOp({ op: obliterateOp });
 		return obliterateOp;
 	}
@@ -472,22 +487,39 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 
 	private applyObliterateRangeOp(opArgs: IMergeTreeDeltaOpArgs): void {
 		assert(
-			opArgs.op.type === MergeTreeDeltaType.OBLITERATE,
+			opArgs.op.type === MergeTreeDeltaType.OBLITERATE ||
+				opArgs.op.type === MergeTreeDeltaType.OBLITERATE_SIDED,
 			0x866 /* Unexpected op type on range obliterate! */,
 		);
 		const op = opArgs.op;
 		const clientArgs = this.getClientSequenceArgs(opArgs);
-		const range = this.getValidOpRange(op, clientArgs);
-
-		this._mergeTree.obliterateRange(
-			range.start,
-			range.end,
-			clientArgs.referenceSequenceNumber,
-			clientArgs.clientId,
-			clientArgs.sequenceNumber,
-			false,
-			opArgs,
-		);
+		if (this._mergeTree.options?.mergeTreeEnableSidedObliterate) {
+			const { start, end } = this.getValidSidedRange(op, clientArgs);
+			this._mergeTree.obliterateRange(
+				start,
+				end,
+				clientArgs.referenceSequenceNumber,
+				clientArgs.clientId,
+				clientArgs.sequenceNumber,
+				false,
+				opArgs,
+			);
+		} else {
+			assert(
+				op.type === MergeTreeDeltaType.OBLITERATE,
+				"Unexpected sided obliterate while mergeTreeEnableSidedObliterate is disabled",
+			);
+			const range = this.getValidOpRange(op, clientArgs);
+			this._mergeTree.obliterateRange(
+				range.start,
+				range.end,
+				clientArgs.referenceSequenceNumber,
+				clientArgs.clientId,
+				clientArgs.sequenceNumber,
+				false,
+				opArgs,
+			);
+		}
 	}
 
 	/**
@@ -565,6 +597,82 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		);
 	}
 
+	/**
+	 * Returns a valid range for the op, or throws if the range is invalid
+	 * @param op - The op to generate the range for
+	 * @param clientArgs - The client args for the op
+	 * @throws LoggingError if the range is invalid
+	 */
+	private getValidSidedRange(
+		// eslint-disable-next-line import/no-deprecated
+		op: IMergeTreeObliterateSidedMsg | IMergeTreeObliterateMsg,
+		clientArgs: IMergeTreeClientSequenceArgs,
+	): {
+		start: InteriorSequencePlace;
+		end: InteriorSequencePlace;
+	} {
+		const invalidPositions: string[] = [];
+		let start: InteriorSequencePlace | undefined;
+		let end: InteriorSequencePlace | undefined;
+		if (op.pos1 === undefined) {
+			invalidPositions.push("start");
+		} else {
+			start =
+				typeof op.pos1 === "object"
+					? { pos: op.pos1.pos, side: op.pos1.before ? Side.Before : Side.After }
+					: { pos: op.pos1, side: Side.Before };
+		}
+		if (op.pos2 === undefined) {
+			invalidPositions.push("end");
+		} else {
+			end =
+				typeof op.pos2 === "object"
+					? { pos: op.pos2.pos, side: op.pos2.before ? Side.Before : Side.After }
+					: { pos: op.pos2 - 1, side: Side.After };
+		}
+
+		// Validate if local op
+		if (clientArgs.clientId === this.getClientId()) {
+			const length = this._mergeTree.getLength(
+				this.getCollabWindow().currentSeq,
+				this.getClientId(),
+			);
+			if (start !== undefined && (start.pos >= length || start.pos < 0)) {
+				// start out of bounds
+				invalidPositions.push("start");
+			}
+			if (end !== undefined && (end.pos >= length || end.pos < 0)) {
+				invalidPositions.push("end");
+			}
+			if (
+				start !== undefined &&
+				end !== undefined &&
+				(start.pos > end.pos ||
+					(start.pos === end.pos && start.side !== end.side && start.side === Side.After))
+			) {
+				// end is before start
+				invalidPositions.push("inverted");
+			}
+			if (invalidPositions.length > 0) {
+				throw new LoggingError("InvalidRange", {
+					usageError: true,
+					invalidPositions: invalidPositions.toString(),
+					length,
+					opType: op.type,
+					opPos1Relative: op.relativePos1 !== undefined,
+					opPos2Relative: op.relativePos2 !== undefined,
+					opPos1: JSON.stringify(op.pos1),
+					opPos2: JSON.stringify(op.pos2),
+					start: JSON.stringify(start),
+					end: JSON.stringify(end),
+				});
+			}
+		}
+
+		assert(start !== undefined && end !== undefined, "Missing start or end of range");
+		return { start, end };
+	}
+
 	/**
 	 * Returns a valid range for the op, or undefined
 	 * @param op - The op to generate the range for
@@ -614,7 +722,6 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 				invalidPositions.push("start");
 			}
 			// Validate end if not insert, or insert has end
-			//
 			if (
 				(op.type !== MergeTreeDeltaType.INSERT || end !== undefined) &&
 				(end === undefined || end <= start!)
@@ -892,7 +999,12 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 
 				const first = opList[0];
 
-				if (!!first && first.pos2 !== undefined) {
+				if (
+					!!first &&
+					first.pos2 !== undefined &&
+					first.type !== MergeTreeDeltaType.OBLITERATE_SIDED &&
+					newOp.type !== MergeTreeDeltaType.OBLITERATE_SIDED
+				) {
 					first.pos2 += newOp.pos2! - newOp.pos1!;
 				} else {
 					opList.push(newOp);
@@ -939,7 +1051,8 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 				this.applyAnnotateRangeOp(opArgs);
 				break;
 			}
-			case MergeTreeDeltaType.OBLITERATE: {
+			case MergeTreeDeltaType.OBLITERATE:
+			case MergeTreeDeltaType.OBLITERATE_SIDED: {
 				this.applyObliterateRangeOp(opArgs);
 				break;
 			}
@@ -973,6 +1086,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 				this.applyAnnotateRangeOp({ op });
 				break;
 			}
+			case MergeTreeDeltaType.OBLITERATE_SIDED:
 			case MergeTreeDeltaType.OBLITERATE: {
 				this.applyObliterateRangeOp({ op });
 				break;
@@ -1205,6 +1319,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 					this.applyRemoveRangeOp(opArgs);
 					break;
 				}
+				case MergeTreeDeltaType.OBLITERATE_SIDED:
 				case MergeTreeDeltaType.OBLITERATE: {
 					this.applyObliterateRangeOp(opArgs);
 					break;

package/src/index.ts

@@ -100,6 +100,7 @@ export {
 	MergeTreeDeltaType,
 	ReferenceType,
 	IMergeTreeObliterateMsg,
+	IMergeTreeObliterateSidedMsg,
 } from "./ops.js";
 export {
 	addProperties,

package/src/mergeTree.ts

@@ -90,6 +90,7 @@ import {
 } from "./referencePositions.js";
 // eslint-disable-next-line import/no-deprecated
 import { PropertiesRollback } from "./segmentPropertiesManager.js";
+import { Side, type InteriorSequencePlace } from "./sequencePlace.js";
 import { SortedSegmentSet } from "./sortedSegmentSet.js";
 import { zamboniSegments } from "./zamboni.js";
 
@@ -197,6 +198,17 @@ export interface IMergeTreeOptions {
 	 * @defaultValue `false`
 	 */
 	mergeTreeEnableObliterateReconnect?: boolean;
+
+	/**
+	 * Enables support for obliterate endpoint expansion.
+	 * When enabled, obliterate operations can have sidedness specified for their endpoints.
+	 * If an endpoint is externally anchored
+	 * (aka the start is after a given position, or the end is before a given position),
+	 * then concurrent inserts adjacent to the exclusive endpoint of an obliterated range will be included in the obliteration
+	 *
+	 * @defaultValue `false`
+	 */
+	mergeTreeEnableSidedObliterate?: boolean;
 }
 export function errorIfOptionNotTrue(
 	options: IMergeTreeOptions | undefined,
@@ -210,6 +222,7 @@ export function errorIfOptionNotTrue(
 /**
  * @legacy
  * @alpha
+ * @deprecated  This functionality was not meant to be exported and will be removed in a future release
  */
 export interface IMergeTreeAttributionOptions {
 	/**
@@ -237,6 +250,7 @@ export interface IMergeTreeAttributionOptions {
  * @sealed
  * @legacy
  * @alpha
+ * @deprecated This functionality was not meant to be exported and will be removed in a future release
  */
 export interface AttributionPolicy {
 	/**
@@ -1234,7 +1248,10 @@ export class MergeTree {
 				});
 			});
 
-			if (opArgs.op.type === MergeTreeDeltaType.OBLITERATE) {
+			if (
+				opArgs.op.type === MergeTreeDeltaType.OBLITERATE ||
+				opArgs.op.type === MergeTreeDeltaType.OBLITERATE_SIDED
+			) {
 				this.obliterates.addOrUpdate(pendingSegmentGroup.obliterateInfo!);
 			}
 
@@ -1242,7 +1259,8 @@ export class MergeTree {
 			// positions after slide are final
 			if (
 				opArgs.op.type === MergeTreeDeltaType.REMOVE ||
-				opArgs.op.type === MergeTreeDeltaType.OBLITERATE
+				opArgs.op.type === MergeTreeDeltaType.OBLITERATE ||
+				opArgs.op.type === MergeTreeDeltaType.OBLITERATE_SIDED
 			) {
 				this.slideAckedRemovedSegmentReferences(pendingSegmentGroup.segments);
 			}
@@ -1510,11 +1528,11 @@ export class MergeTree {
 				}
 
 				this.updateRoot(splitNode);
-				saveIfLocal(newSegment);
 
 				insertPos += newSegment.cachedLength;
 
 				if (!this.options?.mergeTreeEnableObliterate || this.obliterates.empty()) {
+					saveIfLocal(newSegment);
 					continue;
 				}
 
@@ -1542,13 +1560,13 @@ export class MergeTree {
 							movedClientIds.unshift(ob.clientId);
 							movedSeqs.unshift(ob.seq);
 						} else {
-							if (newest === undefined || normalizedNewestSeq < normalizedObSeq) {
-								normalizedNewestSeq = normalizedObSeq;
-								newest = ob;
-							}
 							movedClientIds.push(ob.clientId);
 							movedSeqs.push(ob.seq);
 						}
+						if (newest === undefined || normalizedNewestSeq < normalizedObSeq) {
+							normalizedNewestSeq = normalizedObSeq;
+							newest = ob;
+						}
 					}
 				}
 
@@ -1575,7 +1593,11 @@ export class MergeTree {
 					if (newSegment.parent) {
 						this.blockUpdatePathLengths(newSegment.parent, seq, clientId);
 					}
+				} else if (oldest && newest?.clientId === clientId) {
+					newSegment.prevObliterateByInserter = newest;
 				}
+
+				saveIfLocal(newSegment);
 			}
 		}
 	}
@@ -1866,19 +1888,20 @@ export class MergeTree {
 		}
 	}
 
-	public obliterateRange(
-		start: number,
-		end: number,
+	private obliterateRangeSided(
+		start: InteriorSequencePlace,
+		end: InteriorSequencePlace,
 		refSeq: number,
 		clientId: number,
 		seq: number,
 		overwrite: boolean = false,
 		opArgs: IMergeTreeDeltaOpArgs,
 	): void {
-		errorIfOptionNotTrue(this.options, "mergeTreeEnableObliterate");
+		const startPos = start.side === Side.Before ? start.pos : start.pos + 1;
+		const endPos = end.side === Side.Before ? end.pos : end.pos + 1;
 
-		this.ensureIntervalBoundary(start, refSeq, clientId);
-		this.ensureIntervalBoundary(end, refSeq, clientId);
+		this.ensureIntervalBoundary(startPos, refSeq, clientId);
+		this.ensureIntervalBoundary(endPos, refSeq, clientId);
 
 		let _overwrite = overwrite;
 		const localOverlapWithRefs: ISegment[] = [];
@@ -1896,8 +1919,8 @@ export class MergeTree {
 			segmentGroup: undefined,
 		};
 
-		const { segment: startSeg } = this.getContainingSegment(start, refSeq, clientId);
-		const { segment: endSeg } = this.getContainingSegment(end - 1, refSeq, clientId);
+		const { segment: startSeg } = this.getContainingSegment(start.pos, refSeq, clientId);
+		const { segment: endSeg } = this.getContainingSegment(end.pos, refSeq, clientId);
 		assert(
 			startSeg !== undefined && endSeg !== undefined,
 			0xa3f /* segments cannot be undefined */,
@@ -1905,7 +1928,7 @@ export class MergeTree {
 
 		obliterate.start = this.createLocalReferencePosition(
 			startSeg,
-			0,
+			start.side === Side.Before ? 0 : Math.max(startSeg.cachedLength - 1, 0),
 			ReferenceType.StayOnRemove,
 			{
 				obliterate,
@@ -1914,20 +1937,53 @@ export class MergeTree {
 
 		obliterate.end = this.createLocalReferencePosition(
 			endSeg,
-			endSeg.cachedLength - 1,
+			end.side === Side.Before ? 0 : Math.max(endSeg.cachedLength - 1, 0),
 			ReferenceType.StayOnRemove,
 			{
 				obliterate,
 			},
 		);
 
+		// Always create a segment group for obliterate,
+		// even if there are no segments currently in the obliteration range.
+		// Segments may be concurrently inserted into the obliteration range,
+		// at which point they are added to the segment group.
+		obliterate.segmentGroup = {
+			segments: [],
+			localSeq,
+			refSeq: this.collabWindow.currentSeq,
+			obliterateInfo: obliterate,
+		};
+		if (this.collabWindow.collaborating && clientId === this.collabWindow.clientId) {
+			this.pendingSegments.push(obliterate.segmentGroup);
+		}
+		this.obliterates.addOrUpdate(obliterate);
+
 		const markMoved = (
 			segment: ISegment,
 			pos: number,
 			_start: number,
 			_end: number,
 		): boolean => {
+			if (
+				(start.side === Side.After && startPos === pos + segment.cachedLength) || // exclusive start segment
+				(end.side === Side.Before &&
+					endPos === pos &&
+					isSegmentPresent(segment, { refSeq, localSeq })) // exclusive end segment
+			) {
+				// We walk these segments because we want to also walk any concurrently inserted segments between here and the obliterated segments.
+				// These segments are outside of the obliteration range though, so return true to keep walking.
+				return true;
+			}
 			const existingMoveInfo = toMoveInfo(segment);
+
+			if (segment.prevObliterateByInserter?.seq === UnassignedSequenceNumber) {
+				// We chose to not obliterate this segment because we are aware of an unacked local obliteration.
+				// The local obliterate has not been sequenced yet, so it is still the newest obliterate we are aware of.
+				// Other clients will also choose not to obliterate this segment because the most recent obliteration has the same clientId
+				return true;
+			}
+
 			if (
 				clientId !== segment.clientId &&
 				segment.seq !== undefined &&
@@ -1978,7 +2034,6 @@ export class MergeTree {
 						obliterate.segmentGroup,
 						localSeq,
 					);
-					obliterate.segmentGroup.obliterateInfo ??= obliterate;
 				} else {
 					if (MergeTree.options.zamboniSegments) {
 						this.addToLRUSet(segment, seq);
@@ -2008,14 +2063,12 @@ export class MergeTree {
 			markMoved,
 			undefined,
 			afterMarkMoved,
-			start,
-			end,
+			start.pos,
+			end.pos + 1, // include the segment containing the end reference
 			undefined,
 			seq === UnassignedSequenceNumber ? undefined : seq,
 		);
 
-		this.obliterates.addOrUpdate(obliterate);
-
 		this.slideAckedRemovedSegmentReferences(localOverlapWithRefs);
 		// opArgs == undefined => test code
 		if (movedSegments.length > 0) {
@@ -2041,6 +2094,39 @@ export class MergeTree {
 		}
 	}
 
+	public obliterateRange(
+		start: number | InteriorSequencePlace,
+		end: number | InteriorSequencePlace,
+		refSeq: number,
+		clientId: number,
+		seq: number,
+		overwrite: boolean = false,
+		opArgs: IMergeTreeDeltaOpArgs,
+	): void {
+		errorIfOptionNotTrue(this.options, "mergeTreeEnableObliterate");
+		if (this.options?.mergeTreeEnableSidedObliterate) {
+			assert(
+				typeof start === "object" && typeof end === "object",
+				"Start and end must be of type InteriorSequencePlace if mergeTreeEnableSidedObliterate is enabled.",
+			);
+			this.obliterateRangeSided(start, end, refSeq, clientId, seq, overwrite, opArgs);
+		} else {
+			assert(
+				typeof start === "number" && typeof end === "number",
+				"Start and end must be numbers if mergeTreeEnableSidedObliterate is not enabled.",
+			);
+			this.obliterateRangeSided(
+				{ pos: start, side: Side.Before },
+				{ pos: end - 1, side: Side.After },
+				refSeq,
+				clientId,
+				seq,
+				overwrite,
+				opArgs,
+			);
+		}
+	}
+
 	public markRangeRemoved(
 		start: number,
 		end: number,

package/src/mergeTreeNodes.ts

@@ -160,6 +160,13 @@ export interface IMoveInfo {
 	 * calculations
 	 */
 	wasMovedOnInsert: boolean;
+
+	/**
+	 * If a segment is inserted into an obliterated range,
+	 * but the newest obliteration of that range was by the inserting client,
+	 * then the segment is not obliterated because it is aware of the latest obliteration.
+	 */
+	prevObliterateByInserter?: ObliterateInfo;
 }
 
 export function toMoveInfo(maybe: Partial<IMoveInfo> | undefined): IMoveInfo | undefined {
@@ -661,7 +668,8 @@ export abstract class BaseSegment implements ISegment {
 				return false;
 			}
 
-			case MergeTreeDeltaType.OBLITERATE: {
+			case MergeTreeDeltaType.OBLITERATE:
+			case MergeTreeDeltaType.OBLITERATE_SIDED: {
 				const moveInfo: IMoveInfo | undefined = toMoveInfo(this);
 				assert(moveInfo !== undefined, 0x86e /* On obliterate ack, missing move info! */);
 				const obliterateInfo = segmentGroup.obliterateInfo;

package/src/opBuilder.ts

@@ -14,8 +14,10 @@ import {
 	IMergeTreeObliterateMsg,
 	IMergeTreeRemoveMsg,
 	MergeTreeDeltaType,
+	type IMergeTreeObliterateSidedMsg,
 } from "./ops.js";
 import { PropertySet } from "./properties.js";
+import { normalizePlace, Side, type SequencePlace } from "./sequencePlace.js";
 
 /**
  * Creates the op for annotating the markers with the provided properties
@@ -97,6 +99,36 @@ export function createObliterateRangeOp(start: number, end: number): IMergeTreeO
 	};
 }
 
+/**
+ * Creates the op to obliterate a range
+ *
+ * @param start - The start of the range to obliterate.
+ * If a number is provided, the range will start before that index.
+ * @param end - The end of the range to obliterate.
+ * If a number is provided, the range will end after that index -1.
+ * This preserves the previous behavior of not expanding obliteration ranges at the endpoints
+ * for uses which predate the availability of endpoint expansion.
+ *
+ * @internal
+ */
+export function createObliterateRangeOpSided(
+	start: SequencePlace,
+	end: SequencePlace,
+): IMergeTreeObliterateSidedMsg {
+	const startPlace = normalizePlace(start);
+	// If a number is provided, default to after the previous index.
+	// This preserves the behavior of obliterate prior to the introduction of endpoint expansion.
+	const endPlace =
+		typeof end === "number"
+			? { pos: end - 1, side: Side.After } // default to inclusive bounds
+			: normalizePlace(end);
+	return {
+		type: MergeTreeDeltaType.OBLITERATE_SIDED,
+		pos1: { pos: startPlace.pos, before: startPlace.side === Side.Before },
+		pos2: { pos: endPlace.pos, before: endPlace.side === Side.Before },
+	};
+}
+
 /**
  * Creates an op for inserting a segment at the specified position.
  *

package/src/ops.ts

@@ -70,6 +70,7 @@ export const MergeTreeDeltaType = {
 	 */
 	GROUP: 3,
 	OBLITERATE: 4,
+	OBLITERATE_SIDED: 5,
 } as const;
 
 /**
@@ -162,6 +163,26 @@ export interface IMergeTreeObliterateMsg extends IMergeTreeDelta {
 	relativePos2?: never;
 }
 
+/**
+ * @legacy
+ * @alpha
+ */
+export interface IMergeTreeObliterateSidedMsg extends IMergeTreeDelta {
+	type: typeof MergeTreeDeltaType.OBLITERATE_SIDED;
+	pos1: { pos: number; before: boolean };
+	/**
+	 * This field is currently unused, but we keep it around to make the union
+	 * type of all merge-tree messages have the same fields
+	 */
+	relativePos1?: never;
+	pos2: { pos: number; before: boolean };
+	/**
+	 * This field is currently unused, but we keep it around to make the union
+	 * type of all merge-tree messages have the same fields
+	 */
+	relativePos2?: never;
+}
+
 /**
  * @legacy
  * @alpha
@@ -206,7 +227,8 @@ export type IMergeTreeDeltaOp =
 	| IMergeTreeInsertMsg
 	| IMergeTreeRemoveMsg
 	| IMergeTreeAnnotateMsg
-	| IMergeTreeObliterateMsg;
+	| IMergeTreeObliterateMsg
+	| IMergeTreeObliterateSidedMsg;
 
 /**
  * @legacy

package/src/sequencePlace.ts

@@ -87,3 +87,19 @@ export function endpointPosAndSide(
 		endPos,
 	};
 }
+
+/**
+ * Returns the given place in InteriorSequencePlace form.
+ */
+export function normalizePlace(place: SequencePlace): InteriorSequencePlace {
+	if (typeof place === "number") {
+		return { pos: place, side: Side.Before };
+	}
+	if (place === "start") {
+		return { pos: -1, side: Side.After };
+	}
+	if (place === "end") {
+		return { pos: -1, side: Side.Before };
+	}
+	return place;
+}