@fluidframework/sequence 2.0.0-internal.6.3.3 → 2.0.0-internal.7.0.0

package/src/intervals/sequenceInterval.ts

@@ -4,6 +4,7 @@
  */
 
 /* eslint-disable no-bitwise */
+/* eslint-disable import/no-deprecated */
 
 import {
 	Client,
@@ -26,6 +27,13 @@ import {
 import { assert } from "@fluidframework/core-utils";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import { UsageError } from "@fluidframework/telemetry-utils";
+import {
+	SequencePlace,
+	Side,
+	computeStickinessFromSide,
+	endpointPosAndSide,
+	sidesFromStickiness,
+} from "../intervalCollection";
 import {
 	IIntervalHelpers,
 	ISerializableInterval,
@@ -38,14 +46,42 @@ import {
 
 const reservedIntervalIdKey = "intervalId";
 
+function compareSides(sideA: Side, sideB: Side): number {
+	if (sideA === sideB) {
+		return 0;
+	}
+
+	if (sideA === Side.Before) {
+		return 1;
+	}
+
+	return -1;
+}
+
+function minSide(sideA: Side, sideB: Side): Side {
+	if (sideA === Side.After && sideB === Side.After) {
+		return Side.After;
+	}
+
+	return Side.Before;
+}
+
+function maxSide(sideA: Side, sideB: Side): Side {
+	if (sideA === Side.Before && sideB === Side.Before) {
+		return Side.Before;
+	}
+
+	return Side.After;
+}
+
 /**
  * Interval implementation whose ends are associated with positions in a mutatable sequence.
  * As such, when content is inserted into the middle of the interval, the interval expands to
  * include that content.
  *
- * @remarks - The endpoint's position should be treated exclusively to get reasonable behavior--i.e.
- * an interval referring to "hello" in "hello world" should have a start position of 0 and an end
- * position of 5.
+ * @remarks The endpoints' positions should be treated exclusively to get
+ * reasonable behavior. E.g., an interval referring to "hello" in "hello world"
+ * should have a start position of 0 and an end position of 5.
  *
  * To see why, consider what happens if "llo wor" is removed from the string to make "held".
  * The interval's startpoint remains on the "h" (it isn't altered), but the interval's endpoint
@@ -55,9 +91,15 @@ const reservedIntervalIdKey = "intervalId";
  * If the interval endpoint was treated inclusively, the interval would now refer to "hel", which
  * is undesirable.
  *
- * Since the end of an interval is treated exclusively but cannot be greater than or equal to the
- * length of the associated sequence, application models which leverage interval collections should
- * consider inserting a marker at the end of the sequence to represent the end of the content.
+ * Since the endpoints of an interval are treated exclusively but cannot be greater
+ * than or equal to the length of the associated sequence, there exist special
+ * endpoint segments, "start" and "end", which represent the position immediately
+ * before or immediately after the string respectively.
+ *
+ * If a `SequenceInterval` is created on a sequence with the
+ * `mergeTreeReferencesCanSlideToEndpoint` feature flag set to true, the endpoints
+ * of the interval that are exclusive will have the ability to slide to these
+ * special endpoint segments.
  */
 export class SequenceInterval implements ISerializableInterval {
 	/**
@@ -70,21 +112,36 @@ export class SequenceInterval implements ISerializableInterval {
 	 */
 	public propertyManager: PropertiesManager;
 
+	/**
+	 * @internal
+	 */
+	public get stickiness(): IntervalStickiness {
+		const startSegment = this.start.getSegment();
+		const endSegment = this.end.getSegment();
+		return computeStickinessFromSide(
+			startSegment?.endpointType,
+			this.startSide,
+			endSegment?.endpointType,
+			this.endSide,
+		);
+	}
+
 	constructor(
 		private readonly client: Client,
 		/**
 		 * Start endpoint of this interval.
-		 * @remarks - This endpoint can be resolved into a character position using the SharedString it's a part of.
+		 * @remarks This endpoint can be resolved into a character position using the SharedString it's a part of.
 		 */
 		public start: LocalReferencePosition,
 		/**
 		 * End endpoint of this interval.
-		 * @remarks - This endpoint can be resolved into a character position using the SharedString it's a part of.
+		 * @remarks This endpoint can be resolved into a character position using the SharedString it's a part of.
 		 */
 		public end: LocalReferencePosition,
 		public intervalType: IntervalType,
 		props?: PropertySet,
-		public readonly stickiness: IntervalStickiness = IntervalStickiness.END,
+		public readonly startSide: Side = Side.Before,
+		public readonly endSide: Side = Side.Before,
 	) {
 		this.propertyManager = new PropertiesManager();
 		this.properties = {};
@@ -136,19 +193,20 @@ export class SequenceInterval implements ISerializableInterval {
 	public serialize(): ISerializedInterval {
 		const startPosition = this.client.localReferencePositionToPosition(this.start);
 		const endPosition = this.client.localReferencePositionToPosition(this.end);
+		const { startSide, endSide } = sidesFromStickiness(this.stickiness);
 		const serializedInterval: ISerializedInterval = {
 			end: endPosition,
 			intervalType: this.intervalType,
 			sequenceNumber: this.client.getCurrentSeq(),
 			start: startPosition,
+			stickiness: this.stickiness,
+			startSide,
+			endSide,
 		};
 
 		if (this.properties) {
 			serializedInterval.properties = this.properties;
 		}
-		if (this.stickiness !== IntervalStickiness.END) {
-			serializedInterval.stickiness = this.stickiness;
-		}
 
 		return serializedInterval;
 	}
@@ -163,7 +221,8 @@ export class SequenceInterval implements ISerializableInterval {
 			this.end,
 			this.intervalType,
 			this.properties,
-			this.stickiness,
+			this.startSide,
+			this.endSide,
 		);
 	}
 
@@ -196,14 +255,26 @@ export class SequenceInterval implements ISerializableInterval {
 	 * {@inheritDoc IInterval.compareStart}
 	 */
 	public compareStart(b: SequenceInterval) {
-		return compareReferencePositions(this.start, b.start);
+		const dist = compareReferencePositions(this.start, b.start);
+
+		if (dist === 0) {
+			return compareSides(this.startSide, b.startSide);
+		}
+
+		return dist;
 	}
 
 	/**
 	 * {@inheritDoc IInterval.compareEnd}
 	 */
-	public compareEnd(b: SequenceInterval) {
-		return compareReferencePositions(this.end, b.end);
+	public compareEnd(b: SequenceInterval): number {
+		const dist = compareReferencePositions(this.end, b.end);
+
+		if (dist === 0) {
+			return compareSides(b.endSide, this.endSide);
+		}
+
+		return dist;
 	}
 
 	/**
@@ -230,11 +301,33 @@ export class SequenceInterval implements ISerializableInterval {
 	 * @internal
 	 */
 	public union(b: SequenceInterval) {
+		const newStart = minReferencePosition(this.start, b.start);
+		const newEnd = maxReferencePosition(this.end, b.end);
+
+		let startSide: Side;
+
+		if (this.start === b.start) {
+			startSide = minSide(this.startSide, b.startSide);
+		} else {
+			startSide = this.start === newStart ? this.startSide : b.startSide;
+		}
+
+		let endSide: Side;
+
+		if (this.end === b.end) {
+			endSide = maxSide(this.endSide, b.endSide);
+		} else {
+			endSide = this.end === newEnd ? this.endSide : b.endSide;
+		}
+
 		return new SequenceInterval(
 			this.client,
-			minReferencePosition(this.start, b.start),
-			maxReferencePosition(this.end, b.end),
+			newStart,
+			newEnd,
 			this.intervalType,
+			undefined,
+			startSide,
+			endSide,
 		);
 	}
 
@@ -267,12 +360,19 @@ export class SequenceInterval implements ISerializableInterval {
 	 */
 	public modify(
 		label: string,
-		start: number,
-		end: number,
+		start: SequencePlace | undefined,
+		end: SequencePlace | undefined,
 		op?: ISequencedDocumentMessage,
 		localSeq?: number,
-		stickiness: IntervalStickiness = IntervalStickiness.END,
+		useNewSlidingBehavior: boolean = false,
 	) {
+		const { startSide, endSide, startPos, endPos } = endpointPosAndSide(start, end);
+		const stickiness = computeStickinessFromSide(
+			startPos ?? this.start.getSegment()?.endpointType,
+			startSide ?? this.startSide,
+			endPos ?? this.end.getSegment()?.endpointType,
+			endSide ?? this.endSide,
+		);
 		const getRefType = (baseType: ReferenceType): ReferenceType => {
 			let refType = baseType;
 			if (op === undefined) {
@@ -283,15 +383,17 @@ export class SequenceInterval implements ISerializableInterval {
 		};
 
 		let startRef = this.start;
-		if (start !== undefined) {
+		if (startPos !== undefined) {
 			startRef = createPositionReference(
 				this.client,
-				start,
+				startPos,
 				getRefType(this.start.refType),
 				op,
 				undefined,
 				localSeq,
 				startReferenceSlidingPreference(stickiness),
+				startReferenceSlidingPreference(stickiness) === SlidingPreference.BACKWARD,
+				useNewSlidingBehavior,
 			);
 			if (this.start.properties) {
 				startRef.addProperties(this.start.properties);
@@ -299,22 +401,32 @@ export class SequenceInterval implements ISerializableInterval {
 		}
 
 		let endRef = this.end;
-		if (end !== undefined) {
+		if (endPos !== undefined) {
 			endRef = createPositionReference(
 				this.client,
-				end,
+				endPos,
 				getRefType(this.end.refType),
 				op,
 				undefined,
 				localSeq,
 				endReferenceSlidingPreference(stickiness),
+				endReferenceSlidingPreference(stickiness) === SlidingPreference.FORWARD,
+				useNewSlidingBehavior,
 			);
 			if (this.end.properties) {
 				endRef.addProperties(this.end.properties);
 			}
 		}
 
-		const newInterval = new SequenceInterval(this.client, startRef, endRef, this.intervalType);
+		const newInterval = new SequenceInterval(
+			this.client,
+			startRef,
+			endRef,
+			this.intervalType,
+			undefined,
+			startSide ?? this.startSide,
+			endSide ?? this.endSide,
+		);
 		if (this.properties) {
 			newInterval.initializeProperties();
 			this.propertyManager.copyTo(
@@ -338,13 +450,25 @@ export class SequenceInterval implements ISerializableInterval {
 
 export function createPositionReferenceFromSegoff(
 	client: Client,
-	segoff: { segment: ISegment | undefined; offset: number | undefined },
+	segoff: { segment: ISegment | undefined; offset: number | undefined } | "start" | "end",
 	refType: ReferenceType,
 	op?: ISequencedDocumentMessage,
 	localSeq?: number,
 	fromSnapshot?: boolean,
 	slidingPreference?: SlidingPreference,
+	canSlideToEndpoint?: boolean,
 ): LocalReferencePosition {
+	if (segoff === "start" || segoff === "end") {
+		return client.createLocalReferencePosition(
+			segoff,
+			undefined,
+			refType,
+			undefined,
+			slidingPreference,
+			canSlideToEndpoint,
+		);
+	}
+
 	if (segoff.segment) {
 		const ref = client.createLocalReferencePosition(
 			segoff.segment,
@@ -352,6 +476,7 @@ export function createPositionReferenceFromSegoff(
 			refType,
 			undefined,
 			slidingPreference,
+			canSlideToEndpoint,
 		);
 		return ref;
 	}
@@ -375,30 +500,40 @@ export function createPositionReferenceFromSegoff(
 
 function createPositionReference(
 	client: Client,
-	pos: number,
+	pos: number | "start" | "end",
 	refType: ReferenceType,
 	op?: ISequencedDocumentMessage,
 	fromSnapshot?: boolean,
 	localSeq?: number,
 	slidingPreference?: SlidingPreference,
+	exclusive: boolean = false,
+	useNewSlidingBehavior: boolean = false,
 ): LocalReferencePosition {
 	let segoff;
+
 	if (op) {
 		assert(
 			(refType & ReferenceType.SlideOnRemove) !== 0,
 			0x2f5 /* op create references must be SlideOnRemove */,
 		);
-		segoff = client.getContainingSegment(pos, {
-			referenceSequenceNumber: op.referenceSequenceNumber,
-			clientId: op.clientId,
-		});
-		segoff = getSlideToSegoff(segoff);
+		if (pos === "start" || pos === "end") {
+			segoff = pos;
+		} else {
+			segoff = client.getContainingSegment(pos, {
+				referenceSequenceNumber: op.referenceSequenceNumber,
+				clientId: op.clientId,
+			});
+			segoff = getSlideToSegoff(segoff, undefined, useNewSlidingBehavior);
+		}
 	} else {
 		assert(
 			(refType & ReferenceType.SlideOnRemove) === 0 || !!fromSnapshot,
 			0x2f6 /* SlideOnRemove references must be op created */,
 		);
-		segoff = client.getContainingSegment(pos, undefined, localSeq);
+		segoff =
+			pos === "start" || pos === "end"
+				? pos
+				: client.getContainingSegment(pos, undefined, localSeq);
 	}
 
 	return createPositionReferenceFromSegoff(
@@ -409,19 +544,32 @@ function createPositionReference(
 		localSeq,
 		fromSnapshot,
 		slidingPreference,
+		exclusive,
 	);
 }
 
 export function createSequenceInterval(
 	label: string,
-	start: number,
-	end: number,
+	start: SequencePlace | undefined,
+	end: SequencePlace | undefined,
 	client: Client,
 	intervalType: IntervalType,
 	op?: ISequencedDocumentMessage,
 	fromSnapshot?: boolean,
-	stickiness: IntervalStickiness = IntervalStickiness.END,
+	useNewSlidingBehavior: boolean = false,
 ): SequenceInterval {
+	const { startPos, startSide, endPos, endSide } = endpointPosAndSide(
+		start ?? "start",
+		end ?? "end",
+	);
+	assert(
+		startPos !== undefined &&
+			endPos !== undefined &&
+			startSide !== undefined &&
+			endSide !== undefined,
+		0x794 /* start and end cannot be undefined because they were not passed in as undefined */,
+	);
+	const stickiness = computeStickinessFromSide(startPos, startSide, endPos, endSide);
 	let beginRefType = ReferenceType.RangeBegin;
 	let endRefType = ReferenceType.RangeEnd;
 	if (intervalType === IntervalType.Transient) {
@@ -435,7 +583,7 @@ export function createSequenceInterval(
 		// All non-transient interval references must eventually be SlideOnRemove
 		// To ensure eventual consistency, they must start as StayOnRemove when
 		// pending (created locally and creation op is not acked)
-		if (op || fromSnapshot) {
+		if (op ?? fromSnapshot) {
 			beginRefType |= ReferenceType.SlideOnRemove;
 			endRefType |= ReferenceType.SlideOnRemove;
 		} else {
@@ -446,22 +594,26 @@ export function createSequenceInterval(
 
 	const startLref = createPositionReference(
 		client,
-		start,
+		startPos,
 		beginRefType,
 		op,
 		fromSnapshot,
 		undefined,
 		startReferenceSlidingPreference(stickiness),
+		startReferenceSlidingPreference(stickiness) === SlidingPreference.BACKWARD,
+		useNewSlidingBehavior,
 	);
 
 	const endLref = createPositionReference(
 		client,
-		end,
+		endPos,
 		endRefType,
 		op,
 		fromSnapshot,
 		undefined,
 		endReferenceSlidingPreference(stickiness),
+		endReferenceSlidingPreference(stickiness) === SlidingPreference.FORWARD,
+		useNewSlidingBehavior,
 	);
 
 	const rangeProp = {
@@ -476,19 +628,15 @@ export function createSequenceInterval(
 		endLref,
 		intervalType,
 		rangeProp,
-		stickiness,
+		startSide,
+		endSide,
 	);
 	return ival;
 }
 
-export const compareSequenceIntervalEnds = (a: SequenceInterval, b: SequenceInterval): number =>
-	compareReferencePositions(a.end, b.end);
-
-export const compareSequenceIntervalStarts = (a: SequenceInterval, b: SequenceInterval): number =>
-	compareReferencePositions(a.start, b.start);
-
+/**
+ * @deprecated The methods within have substitutions
+ */
 export const sequenceIntervalHelpers: IIntervalHelpers<SequenceInterval> = {
-	compareEnds: compareSequenceIntervalEnds,
-	compareStarts: compareSequenceIntervalStarts,
 	create: createSequenceInterval,
 };

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/sequence";
-export const pkgVersion = "2.0.0-internal.6.3.3";
+export const pkgVersion = "2.0.0-internal.7.0.0";

package/src/revertibles.ts

@@ -27,9 +27,6 @@ import { ISequenceDeltaRange, SequenceDeltaEvent } from "./sequenceDeltaEvent";
 /**
  * Data for undoing edits on SharedStrings and Intervals.
  *
- * Revertibles are new and require the option mergeTreeUseNewLengthCalculations to
- * be set as true on the underlying merge tree in order to function correctly.
- *
  * @alpha
  */
 export type SharedStringRevertible = MergeTreeDeltaRevertible | IntervalRevertible;
@@ -41,9 +38,6 @@ type IntervalOpType = typeof IntervalOpType[keyof typeof IntervalOpType];
 /**
  * Data for undoing edits affecting Intervals.
  *
- * Revertibles are new and require the option mergeTreeUseNewLengthCalculations to
- * be set as true on the underlying merge tree in order to function correctly.
- *
  * @alpha
  */
 export type IntervalRevertible =
@@ -271,9 +265,6 @@ function addIfRevertibleRef(
  * Create revertibles for SharedStringDeltas, handling indirectly modified intervals
  * (e.g. reverting remove of a range that contains an interval will move the interval back)
  *
- * Revertibles are new and require the option mergeTreeUseNewLengthCalculations to
- * be set as true on the underlying merge tree in order to function correctly.
- *
  * @alpha
  */
 export function appendSharedStringDeltaToRevertibles(
@@ -537,27 +528,14 @@ function revertLocalSequenceRemove(
 		const intervalId = getUpdatedId(intervalInfo.intervalId);
 		const interval = intervalCollection.getIntervalById(intervalId);
 		if (interval !== undefined) {
-			const newStart = newEndpointPosition(
-				intervalInfo.startOffset,
-				restoredRanges,
-				sharedString,
-			);
-			const newEnd = newEndpointPosition(
-				intervalInfo.endOffset,
-				restoredRanges,
-				sharedString,
-			);
-			// only move interval if start <= end
-			if (
-				(newStart === undefined &&
-					newEnd !== undefined &&
-					sharedString.localReferencePositionToPosition(interval.start) <= newEnd) ||
-				(newEnd === undefined &&
-					newStart !== undefined &&
-					sharedString.localReferencePositionToPosition(interval.end) >= newStart) ||
-				(newStart !== undefined && newEnd !== undefined && newStart <= newEnd)
-			) {
-				intervalCollection.change(intervalId, newStart, newEnd);
+			const start =
+				newEndpointPosition(intervalInfo.startOffset, restoredRanges, sharedString) ??
+				sharedString.localReferencePositionToPosition(interval.start);
+			const end =
+				newEndpointPosition(intervalInfo.endOffset, restoredRanges, sharedString) ??
+				sharedString.localReferencePositionToPosition(interval.end);
+			if (start <= end) {
+				intervalCollection.change(intervalId, start, end);
 			}
 		}
 	});
@@ -597,9 +575,6 @@ function revertLocalSequenceRemove(
 /**
  * Invoke revertibles to reverse prior edits
  *
- * Revertibles are new and require the option mergeTreeUseNewLengthCalculations to
- * be set as true on the underlying merge tree in order to function correctly.
- *
  * @alpha
  */
 export function revertSharedStringRevertibles(

package/src/sequence.ts

@@ -340,6 +340,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		refType: ReferenceType,
 		properties: PropertySet | undefined,
 		slidingPreference?: SlidingPreference,
+		canSlideToEndpoint?: boolean,
 	): LocalReferencePosition {
 		return this.client.createLocalReferencePosition(
 			segment,
@@ -347,6 +348,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 			refType,
 			properties,
 			slidingPreference,
+			canSlideToEndpoint,
 		);
 	}
 
@@ -452,7 +454,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	}
 
 	/**
-	 * @returns - The most recent sequence number which has been acked by the server and processed by this
+	 * @returns The most recent sequence number which has been acked by the server and processed by this
 	 * SharedSegmentSequence.
 	 */
 	public getCurrentSeq() {
@@ -489,6 +491,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	 * @returns An iterable object that enumerates the IntervalCollection labels.
 	 *
 	 * @example
+	 *
 	 * ```typescript
 	 * const iter = this.getIntervalCollectionKeys();
 	 * for (key of iter)
@@ -704,7 +707,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	 * {@inheritDoc @fluidframework/shared-object-base#SharedObjectCore.applyStashedOp}
 	 */
 	protected applyStashedOp(content: any): unknown {
-		return this.client.applyStashedOp(content);
+		return this.client.applyStashedOp(parseHandles(content, this.serializer));
 	}
 
 	private summarizeMergeTree(serializer: IFluidSerializer): ISummaryTreeWithStats {

package/src/sequenceDeltaEvent.ts

@@ -147,25 +147,33 @@ export interface ISequenceDeltaRange<
 > {
 	/**
 	 * The type of operation that changed this range.
-	 * @remarks - Consuming code should typically compare this to the enum values defined in
+	 *
+	 * @remarks Consuming code should typically compare this to the enum values defined in
 	 * `MergeTreeDeltaOperationTypes`.
 	 */
 	operation: TOperation;
+
 	/**
 	 * The index of the start of the range.
 	 */
 	position: number;
+
 	/**
 	 * The segment that corresponds to the range.
 	 */
 	segment: ISegment;
+
 	/**
 	 * Deltas object which contains all modified properties with their previous values.
 	 * Since `undefined` doesn't survive a round-trip through JSON serialization, the old value being absent
 	 * is instead encoded with `null`.
-	 * @remarks - This object is motivated by undo/redo scenarios, and provides a convenient "inverse op" to apply to
+	 *
+	 * @remarks This object is motivated by undo/redo scenarios, and provides a convenient "inverse op" to apply to
 	 * undo a property change.
-	 * @example - If a segment initially had properties `{ foo: "1", bar: 2 }` and it was annotated with
+	 *
+	 * @example
+	 *
+	 * If a segment initially had properties `{ foo: "1", bar: 2 }` and it was annotated with
 	 * `{ foo: 3, baz: 5 }`, the corresponding event would have a `propertyDeltas` of `{ foo: "1", baz: null }`.
 	 */
 	propertyDeltas: PropertySet;

package/src/sequenceFactory.ts

@@ -15,7 +15,7 @@ import { SharedString, SharedStringSegment } from "./sharedString";
 
 export class SharedStringFactory implements IChannelFactory {
 	// TODO rename back to https://graph.microsoft.com/types/mergeTree/string once paparazzi is able to dynamically
-	// load code
+	// load code (UPDATE: paparazzi is gone... anything to do here?)
 	public static Type = "https://graph.microsoft.com/types/mergeTree";
 
 	public static readonly Attributes: IChannelAttributes = {

package/src/sharedString.ts

@@ -406,7 +406,8 @@ const gatherTextAndMarkers: ISegmentAction<ITextAndMarkerAccumulator> = (
 		if (placeholder && placeholder.length > 0) {
 			const placeholderText =
 				placeholder === "*"
-					? `\n${segment.toString()}`
+					? // eslint-disable-next-line @typescript-eslint/no-base-to-string
+					  `\n${segment.toString()}`
 					: placeholder.repeat(segment.cachedLength);
 			textSegment.text += placeholderText;
 		} else {