@fluidframework/sequence 2.0.0-dev.6.4.0.192049 → 2.0.0-dev.7.2.0.204906

package/src/intervals/intervalUtils.ts

@@ -12,8 +12,11 @@ import {
 	SlidingPreference,
 } from "@fluidframework/merge-tree";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { SequencePlace, Side } from "../intervalCollection";
+
 /**
  * Basic interval abstraction
+ * @public
  */
 export interface IInterval {
 	/**
@@ -46,10 +49,11 @@ export interface IInterval {
 	 */
 	modify(
 		label: string,
-		start: number | undefined,
-		end: number | undefined,
+		start: SequencePlace | undefined,
+		end: SequencePlace | undefined,
 		op?: ISequencedDocumentMessage,
 		localSeq?: number,
+		useNewSlidingBehavior?: boolean,
 	): IInterval | undefined;
 	/**
 	 * @returns whether this interval overlaps with `b`.
@@ -77,8 +81,14 @@ export const IntervalOpType = {
 	POSITION_REMOVE: "positionRemove",
 } as const;
 
+/**
+ * @public
+ */
 export enum IntervalType {
 	Simple = 0x0,
+	/**
+	 * @deprecated this functionality is no longer supported and will be removed
+	 */
 	Nest = 0x1,
 
 	/**
@@ -111,16 +121,24 @@ export interface ISerializedInterval {
 	 */
 	sequenceNumber: number;
 	/** Start position of the interval */
-	start: number;
+	start: number | "start" | "end";
 	/** End position of the interval */
-	end: number;
+	end: number | "start" | "end";
 	/** Interval type to create */
 	intervalType: IntervalType;
+	/**
+	 * The stickiness of this interval
+	 */
 	stickiness?: IntervalStickiness;
+	startSide?: Side;
+	endSide?: Side;
 	/** Any properties the interval has */
 	properties?: PropertySet;
 }
 
+/**
+ * @public
+ */
 export interface ISerializableInterval extends IInterval {
 	/** Serializable bag of properties associated with the interval. */
 	properties: PropertySet;
@@ -158,25 +176,34 @@ export type SerializedIntervalDelta = Omit<ISerializedInterval, "start" | "end"
  *
  * Intervals are of the format:
  *
- * [start, end, sequenceNumber, intervalType, properties, stickiness?]
+ * [
+ * start,
+ * end,
+ * sequenceNumber,
+ * intervalType,
+ * properties,
+ * stickiness?,
+ * startSide?,
+ * endSide?,
+ * ]
  */
 export type CompressedSerializedInterval =
-	| [number, number, number, IntervalType, PropertySet, IntervalStickiness]
-	| [number, number, number, IntervalType, PropertySet];
+	| [
+			number | "start" | "end",
+			number | "start" | "end",
+			number,
+			IntervalType,
+			PropertySet,
+			IntervalStickiness,
+	  ]
+	| [number | "start" | "end", number | "start" | "end", number, IntervalType, PropertySet];
 
 /**
  * @sealed
+ * @deprecated The methods within have substitutions
+ * @public
  */
 export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
-	/**
-	 * @deprecated Use the method `IInterval.compareEnd` instead
-	 */
-	compareEnds(a: TInterval, b: TInterval): number;
-
-	/**
-	 * @deprecated Use the method `IInterval.compareStart` instead
-	 */
-	compareStarts?(a: TInterval, b: TInterval): number;
 	/**
 	 *
 	 * @param label - label of the interval collection this interval is being added to. This parameter is
@@ -187,17 +214,20 @@ export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
 	 * @param intervalType - Type of interval to create. Default is SlideOnRemove
 	 * @param op - If this create came from a remote client, op that created it. Default is undefined (i.e. local)
 	 * @param fromSnapshot - If this create came from loading a snapshot. Default is false.
-	 * @param stickiness - {@link (IntervalStickiness:type)} to apply to the added interval.
+	 * @param startSide - The side on which the start position lays. See
+	 * {@link SequencePlace} for additional context
+	 * @param endSide - The side on which the end position lays. See
+	 * {@link SequencePlace} for additional context
 	 */
 	create(
 		label: string,
-		start: number | undefined,
-		end: number | undefined,
+		start: SequencePlace | undefined,
+		end: SequencePlace | undefined,
 		client: Client | undefined,
 		intervalType: IntervalType,
 		op?: ISequencedDocumentMessage,
 		fromSnapshot?: boolean,
-		stickiness?: IntervalStickiness,
+		useNewSlidingBehavior?: boolean,
 	): TInterval;
 }
 
@@ -207,6 +237,8 @@ export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
  *
  * Note that interval stickiness is currently an experimental feature and must
  * be explicitly enabled with the `intervalStickinessEnabled` flag
+ *
+ * @internal
  */
 export const IntervalStickiness = {
 	/**
@@ -238,19 +270,21 @@ export const IntervalStickiness = {
  *
  * Note that interval stickiness is currently an experimental feature and must
  * be explicitly enabled with the `intervalStickinessEnabled` flag
+ *
+ * @internal
  */
-export type IntervalStickiness = typeof IntervalStickiness[keyof typeof IntervalStickiness];
+export type IntervalStickiness = (typeof IntervalStickiness)[keyof typeof IntervalStickiness];
 
-export function endReferenceSlidingPreference(stickiness: IntervalStickiness): SlidingPreference {
-	// if any end stickiness, prefer sliding forwards
-	return (stickiness & IntervalStickiness.END) !== 0
+export function startReferenceSlidingPreference(stickiness: IntervalStickiness): SlidingPreference {
+	// if any start stickiness, prefer sliding backwards
+	return (stickiness & IntervalStickiness.START) === 0
 		? SlidingPreference.FORWARD
 		: SlidingPreference.BACKWARD;
 }
 
-export function startReferenceSlidingPreference(stickiness: IntervalStickiness): SlidingPreference {
-	// if any start stickiness, prefer sliding backwards
-	return (stickiness & IntervalStickiness.START) !== 0
+export function endReferenceSlidingPreference(stickiness: IntervalStickiness): SlidingPreference {
+	// if any end stickiness, prefer sliding forwards
+	return (stickiness & IntervalStickiness.END) === 0
 		? SlidingPreference.BACKWARD
 		: SlidingPreference.FORWARD;
 }

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,16 @@ 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.
+ * @public
  */
 export class SequenceInterval implements ISerializableInterval {
 	/**
@@ -70,6 +113,20 @@ 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,
 		/**
@@ -84,7 +141,8 @@ export class SequenceInterval implements ISerializableInterval {
 		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 +194,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 +222,8 @@ export class SequenceInterval implements ISerializableInterval {
 			this.end,
 			this.intervalType,
 			this.properties,
-			this.stickiness,
+			this.startSide,
+			this.endSide,
 		);
 	}
 
@@ -196,14 +256,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 +302,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 +361,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 +384,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 +402,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 +451,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 +477,7 @@ export function createPositionReferenceFromSegoff(
 			refType,
 			undefined,
 			slidingPreference,
+			canSlideToEndpoint,
 		);
 		return ref;
 	}
@@ -375,30 +501,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 +545,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 +584,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 +595,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 +629,16 @@ 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
+ * @public
+ */
 export const sequenceIntervalHelpers: IIntervalHelpers<SequenceInterval> = {
-	compareEnds: compareSequenceIntervalEnds,
-	compareStarts: compareSequenceIntervalStarts,
 	create: createSequenceInterval,
 };

package/src/localValues.ts

@@ -58,7 +58,10 @@ export class ValueTypeLocalValue<T> implements ILocalValue<T> {
 	 * @param value - The instance of the value type stored within
 	 * @param valueType - The type object of the value type stored within
 	 */
-	constructor(public readonly value: T, private readonly valueType: IValueType<T>) {}
+	constructor(
+		public readonly value: T,
+		private readonly valueType: IValueType<T>,
+	) {}
 
 	/**
 	 * {@inheritDoc ILocalValue."type"}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/sequence";
-export const pkgVersion = "2.0.0-dev.6.4.0.192049";
+export const pkgVersion = "2.0.0-dev.7.2.0.204906";