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

package/lib/intervalCollection.js

@@ -3,26 +3,47 @@
  * Licensed under the MIT License.
  */
 /* eslint-disable no-bitwise */
+/* eslint-disable import/no-deprecated */
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import { assert } from "@fluidframework/core-utils";
-import { addProperties, createMap, getSlideToSegoff, MergeTreeDeltaType, ReferenceType, refTypeIncludesFlag, reservedRangeLabelsKey, UnassignedSequenceNumber, DetachedReferencePosition, } from "@fluidframework/merge-tree";
+import { addProperties, createMap, getSlideToSegoff, MergeTreeDeltaType, ReferenceType, refTypeIncludesFlag, reservedRangeLabelsKey, UnassignedSequenceNumber, DetachedReferencePosition, UniversalSequenceNumber, SlidingPreference, } from "@fluidframework/merge-tree";
 import { LoggingError, UsageError } from "@fluidframework/telemetry-utils";
 import { v4 as uuid } from "uuid";
 import { IntervalOpType, IntervalStickiness, IntervalType, SequenceInterval, createPositionReferenceFromSegoff, endReferenceSlidingPreference, startReferenceSlidingPreference, sequenceIntervalHelpers, createInterval, } from "./intervals";
-import { createEndpointIndex, createIdIntervalIndex, createOverlappingIntervalsIndex, } from "./intervalIndex";
+import { EndpointIndex, OverlappingIntervalsIndex, createIdIntervalIndex, } from "./intervalIndex";
+/**
+ * Defines a side relative to a character in a sequence.
+ *
+ * @remarks See {@link SequencePlace} for additional context on usage.
+ * @public
+ */
+export var Side;
+(function (Side) {
+    Side[Side["Before"] = 0] = "Before";
+    Side[Side["After"] = 1] = "After";
+})(Side || (Side = {}));
 const reservedIntervalIdKey = "intervalId";
+export function sidesFromStickiness(stickiness) {
+    const startSide = (stickiness & IntervalStickiness.START) !== 0 ? Side.After : Side.Before;
+    const endSide = (stickiness & IntervalStickiness.END) !== 0 ? Side.Before : Side.After;
+    return { startSide, endSide };
+}
 /**
  * Decompress an interval after loading a summary from JSON. The exact format
  * of this compression is unspecified and subject to change
  */
 function decompressInterval(interval, label) {
+    const stickiness = interval[5] ?? IntervalStickiness.END;
+    const { startSide, endSide } = sidesFromStickiness(stickiness);
     return {
         start: interval[0],
         end: interval[1],
         sequenceNumber: interval[2],
         intervalType: interval[3],
         properties: { ...interval[4], [reservedRangeLabelsKey]: [label] },
-        stickiness: interval[5],
+        stickiness,
+        startSide,
+        endSide,
     };
 }
 /**
@@ -31,7 +52,7 @@ function decompressInterval(interval, label) {
  */
 function compressInterval(interval) {
     const { start, end, sequenceNumber, intervalType, properties } = interval;
-    const base = [
+    let base = [
         start,
         end,
         sequenceNumber,
@@ -41,29 +62,60 @@ function compressInterval(interval) {
         { ...properties, [reservedRangeLabelsKey]: undefined },
     ];
     if (interval.stickiness !== undefined && interval.stickiness !== IntervalStickiness.END) {
-        base.push(interval.stickiness);
+        // reassignment to make it easier for typescript to reason about types
+        base = [...base, interval.stickiness];
     }
     return base;
 }
+export function endpointPosAndSide(start, end) {
+    const startIsPlainEndpoint = typeof start === "number" || start === "start" || start === "end";
+    const endIsPlainEndpoint = typeof end === "number" || end === "start" || end === "end";
+    const startSide = startIsPlainEndpoint ? Side.Before : start?.side;
+    const endSide = endIsPlainEndpoint ? Side.Before : end?.side;
+    const startPos = startIsPlainEndpoint ? start : start?.pos;
+    const endPos = endIsPlainEndpoint ? end : end?.pos;
+    return {
+        startSide,
+        endSide,
+        startPos,
+        endPos,
+    };
+}
+function toSequencePlace(pos, side) {
+    return typeof pos === "number" ? { pos, side } : pos;
+}
+function toOptionalSequencePlace(pos, side = Side.Before) {
+    return typeof pos === "number" ? { pos, side } : pos;
+}
+export function computeStickinessFromSide(startPos = -1, startSide = Side.Before, endPos = -1, endSide = Side.Before) {
+    let stickiness = IntervalStickiness.NONE;
+    if (startSide === Side.After || startPos === "start") {
+        stickiness |= IntervalStickiness.START;
+    }
+    if (endSide === Side.Before || endPos === "end") {
+        stickiness |= IntervalStickiness.END;
+    }
+    return stickiness;
+}
 export function createIntervalIndex() {
     const helpers = {
-        compareEnds: (a, b) => a.end - b.end,
         create: createInterval,
     };
-    const lc = new LocalIntervalCollection(undefined, "", helpers);
+    const lc = new LocalIntervalCollection(undefined, "", helpers, {});
     return lc;
 }
 export class LocalIntervalCollection {
-    constructor(client, label, helpers, 
+    constructor(client, label, helpers, options, 
     /** Callback invoked each time one of the endpoints of an interval slides. */
     onPositionChange) {
         this.client = client;
         this.label = label;
         this.helpers = helpers;
+        this.options = options;
         this.onPositionChange = onPositionChange;
-        this.overlappingIntervalsIndex = createOverlappingIntervalsIndex(client, helpers);
+        this.overlappingIntervalsIndex = new OverlappingIntervalsIndex(client, helpers);
         this.idIntervalIndex = createIdIntervalIndex();
-        this.endIntervalIndex = createEndpointIndex(client, helpers);
+        this.endIntervalIndex = new EndpointIndex(client, helpers);
         this.indexes = new Set([
             this.overlappingIntervalsIndex,
             this.idIntervalIndex,
@@ -117,12 +169,12 @@ export class LocalIntervalCollection {
         this.removeIntervalFromIndexes(interval);
         this.removeIntervalListeners(interval);
     }
-    createInterval(start, end, intervalType, op, stickiness = IntervalStickiness.END) {
-        return this.helpers.create(this.label, start, end, this.client, intervalType, op, undefined, stickiness);
+    createInterval(start, end, intervalType, op) {
+        return this.helpers.create(this.label, start, end, this.client, intervalType, op, undefined, this.options.mergeTreeReferencesCanSlideToEndpoint);
     }
-    addInterval(start, end, intervalType, props, op, stickiness = IntervalStickiness.END) {
+    addInterval(start, end, intervalType, props, op) {
         var _a;
-        const interval = this.createInterval(start, end, intervalType, op, stickiness);
+        const interval = this.createInterval(start, end, intervalType, op);
         if (interval) {
             if (!interval.properties) {
                 interval.properties = createMap();
@@ -159,7 +211,7 @@ export class LocalIntervalCollection {
         this.addIntervalListeners(interval);
     }
     changeInterval(interval, start, end, op, localSeq) {
-        const newInterval = interval.modify(this.label, start, end, op, localSeq);
+        const newInterval = interval.modify(this.label, start, end, op, localSeq, this.options.mergeTreeReferencesCanSlideToEndpoint);
         if (newInterval) {
             this.removeExistingInterval(interval);
             this.add(newInterval);
@@ -182,7 +234,7 @@ export class LocalIntervalCollection {
                 // either, so this must be special-cased.
                 return ref;
             }
-            return this.client.createLocalReferencePosition(segment, ref.getOffset(), ReferenceType.Transient, ref.properties, ref.slidingPreference);
+            return this.client.createLocalReferencePosition(segment, ref.getOffset(), ReferenceType.Transient, ref.properties, ref.slidingPreference, ref.canSlideToEndpoint);
         };
         if (interval instanceof SequenceInterval) {
             let previousInterval;
@@ -239,7 +291,6 @@ SequenceIntervalCollectionValueType._ops = makeOpsMap();
 class IntervalCollectionFactory {
     load(emitter, raw = [], options) {
         const helpers = {
-            compareEnds: (a, b) => a.end - b.end,
             create: createInterval,
         };
         const collection = new IntervalCollection(helpers, false, emitter, raw, options);
@@ -336,10 +387,18 @@ class IntervalCollectionIterator {
         };
     }
 }
+// solely for type checking in the implementation of add - will be removed once
+// deprecated signatures are removed
+const isSequencePlace = (place) => {
+    return typeof place === "number" || typeof place === "string" || place.pos !== undefined;
+};
 /**
  * {@inheritdoc IIntervalCollection}
  */
 export class IntervalCollection extends TypedEventEmitter {
+    get attached() {
+        return !!this.localCollection;
+    }
     /** @internal */
     constructor(helpers, requiresClient, emitter, serializedIntervals, options = {}) {
         super();
@@ -355,9 +414,6 @@ export class IntervalCollection extends TypedEventEmitter {
             ? serializedIntervals
             : serializedIntervals.intervals.map((i) => decompressInterval(i, serializedIntervals.label));
     }
-    get attached() {
-        return !!this.localCollection;
-    }
     /**
      * {@inheritdoc IIntervalCollection.attachIndex}
      */
@@ -390,6 +446,9 @@ export class IntervalCollection extends TypedEventEmitter {
         if (!this.client) {
             throw new LoggingError("mergeTree client must exist");
         }
+        if (pos === "start" || pos === "end") {
+            return pos;
+        }
         const { clientId } = this.client.getCollabWindow();
         const { segment, offset } = this.client.getContainingSegment(pos, {
             referenceSequenceNumber: seqNumberFrom,
@@ -397,7 +456,7 @@ export class IntervalCollection extends TypedEventEmitter {
         }, localSeq);
         // if segment is undefined, it slid off the string
         assert(segment !== undefined, 0x54e /* No segment found */);
-        const segoff = getSlideToSegoff({ segment, offset }) ?? segment;
+        const segoff = getSlideToSegoff({ segment, offset }, undefined, this.options.mergeTreeReferencesCanSlideToEndpoint) ?? segment;
         // case happens when rebasing op, but concurrently entire string has been deleted
         if (segoff.segment === undefined || segoff.offset === undefined) {
             return DetachedReferencePosition;
@@ -436,12 +495,18 @@ export class IntervalCollection extends TypedEventEmitter {
                 }
             });
         }
-        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, (interval, previousInterval) => this.emitChange(interval, previousInterval, true, true));
+        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, this.options, (interval, previousInterval) => this.emitChange(interval, previousInterval, true, true));
         if (this.savedSerializedIntervals) {
             for (const serializedInterval of this.savedSerializedIntervals) {
                 this.localCollection.ensureSerializedId(serializedInterval);
-                const { start, end, intervalType, properties, stickiness } = serializedInterval;
-                const interval = this.helpers.create(label, start, end, client, intervalType, undefined, true, stickiness);
+                const { start: startPos, end: endPos, intervalType, properties, startSide, endSide, } = serializedInterval;
+                const start = typeof startPos === "number" && startSide !== undefined
+                    ? { pos: startPos, side: startSide }
+                    : startPos;
+                const end = typeof endPos === "number" && endSide !== undefined
+                    ? { pos: endPos, side: endSide }
+                    : endPos;
+                const interval = this.helpers.create(label, start, end, client, intervalType, undefined, true, this.options.mergeTreeReferencesCanSlideToEndpoint);
                 if (properties) {
                     interval.addProperties(properties);
                 }
@@ -487,28 +552,59 @@ export class IntervalCollection extends TypedEventEmitter {
         }
         return this.localCollection.idIntervalIndex.getIntervalById(id);
     }
-    /**
-     * {@inheritdoc IIntervalCollection.add}
-     */
-    add(start, end, intervalType, props, stickiness = IntervalStickiness.END) {
+    assertStickinessEnabled(start, end) {
+        if (!(typeof start === "number" && typeof end === "number") &&
+            !this.options.intervalStickinessEnabled) {
+            throw new UsageError("attempted to set interval stickiness without enabling `intervalStickinessEnabled` feature flag");
+        }
+    }
+    add(start, end, intervalType, props) {
+        let intStart;
+        let intEnd;
+        let type;
+        let properties;
+        if (isSequencePlace(start)) {
+            intStart = start;
+            assert(end !== undefined, 0x7c0 /* end must be defined */);
+            intEnd = end;
+            assert(intervalType !== undefined, 0x7c1 /* intervalType must be defined */);
+            type = intervalType;
+            properties = props;
+        }
+        else {
+            intStart = start.start;
+            intEnd = start.end;
+            type = IntervalType.SlideOnRemove;
+            properties = start.props;
+        }
         if (!this.localCollection) {
             throw new LoggingError("attach must be called prior to adding intervals");
         }
-        if (intervalType & IntervalType.Transient) {
+        if (type & IntervalType.Transient) {
             throw new LoggingError("Can not add transient intervals");
         }
-        if (stickiness !== IntervalStickiness.END && !this.options.intervalStickinessEnabled) {
-            throw new UsageError("attempted to set interval stickiness without enabling `intervalStickinessEnabled` feature flag");
-        }
-        const interval = this.localCollection.addInterval(start, end, intervalType, props, undefined, stickiness);
+        const { startSide, endSide, startPos, endPos } = endpointPosAndSide(intStart, intEnd);
+        assert(startPos !== undefined &&
+            endPos !== undefined &&
+            startSide !== undefined &&
+            endSide !== undefined, 0x793 /* start and end cannot be undefined because they were not passed in as undefined */);
+        const stickiness = computeStickinessFromSide(startPos, startSide, endPos, endSide);
+        this.assertStickinessEnabled(intStart, intEnd);
+        const interval = this.localCollection.addInterval(toSequencePlace(startPos, startSide), toSequencePlace(endPos, endSide), type, properties);
         if (interval) {
+            if (!this.isCollaborating && interval instanceof SequenceInterval) {
+                setSlideOnRemove(interval.start);
+                setSlideOnRemove(interval.end);
+            }
             const serializedInterval = {
-                end,
-                intervalType,
+                start: startPos,
+                end: endPos,
+                intervalType: type,
                 properties: interval.properties,
                 sequenceNumber: this.client?.getCurrentSeq() ?? 0,
-                start,
                 stickiness,
+                startSide,
+                endSide,
             };
             const localSeq = this.getNextLocalSeq();
             this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
@@ -572,8 +668,7 @@ export class IntervalCollection extends TypedEventEmitter {
         }
         const interval = this.getIntervalById(id);
         if (interval) {
-            // Pass Unassigned as the sequence number to indicate that this is a local op that is waiting for an ack.
-            const deltaProps = interval.addProperties(props, true, UnassignedSequenceNumber);
+            const deltaProps = interval.addProperties(props, true, this.isCollaborating ? UnassignedSequenceNumber : UniversalSequenceNumber);
             const serializedInterval = interval.serialize();
             // Emit a change op that will only change properties. Add the ID to
             // the property bag provided by the caller.
@@ -604,9 +699,18 @@ export class IntervalCollection extends TypedEventEmitter {
             if (!newInterval) {
                 return undefined;
             }
+            if (!this.isCollaborating && newInterval instanceof SequenceInterval) {
+                setSlideOnRemove(newInterval.start);
+                setSlideOnRemove(newInterval.end);
+            }
             const serializedInterval = interval.serialize();
-            serializedInterval.start = start;
-            serializedInterval.end = end;
+            const { startPos, startSide, endPos, endSide } = endpointPosAndSide(start, end);
+            const stickiness = computeStickinessFromSide(startPos, startSide, endPos, endSide);
+            serializedInterval.start = startPos;
+            serializedInterval.end = endPos;
+            serializedInterval.startSide = startSide;
+            serializedInterval.endSide = endSide;
+            serializedInterval.stickiness = stickiness;
             // Emit a property bag containing only the ID, as we don't intend for this op to change any properties.
             serializedInterval.properties = {
                 [reservedIntervalIdKey]: interval.getIntervalId(),
@@ -621,7 +725,13 @@ export class IntervalCollection extends TypedEventEmitter {
         // No interval to change
         return undefined;
     }
+    get isCollaborating() {
+        return this.client?.getCollabWindow().collaborating ?? false;
+    }
     addPendingChange(id, serializedInterval) {
+        if (!this.isCollaborating) {
+            return;
+        }
         if (serializedInterval.start !== undefined) {
             this.addPendingChangeHelper(id, this.pendingChangesStart, serializedInterval);
         }
@@ -714,7 +824,7 @@ export class IntervalCollection extends TypedEventEmitter {
                 // If changeInterval gives us a new interval, work with that one. Otherwise keep working with
                 // the one we originally found in the tree.
                 newInterval =
-                    this.localCollection.changeInterval(interval, start, end, op) ?? interval;
+                    this.localCollection.changeInterval(interval, toOptionalSequencePlace(start, serializedInterval.startSide), toOptionalSequencePlace(end, serializedInterval.endSide), op) ?? interval;
             }
             const deltaProps = newInterval.addProperties(newProps, true, op.sequenceNumber);
             if (this.onDeserialize) {
@@ -759,7 +869,7 @@ export class IntervalCollection extends TypedEventEmitter {
         if (!this.attached) {
             throw new LoggingError("attachSequence must be called");
         }
-        const { intervalType, properties } = serializedInterval;
+        const { intervalType, properties, stickiness, startSide, endSide } = serializedInterval;
         const { start: startRebased, end: endRebased } = this.localSeqToRebasedInterval.get(localSeq) ?? this.computeRebasedPositions(localSeq);
         const intervalId = properties?.[reservedIntervalIdKey];
         const localInterval = this.localCollection?.idIntervalIndex.getIntervalById(intervalId);
@@ -769,8 +879,12 @@ export class IntervalCollection extends TypedEventEmitter {
             intervalType,
             sequenceNumber: this.client?.getCurrentSeq() ?? 0,
             properties,
+            stickiness,
+            startSide,
+            endSide,
         };
         if (opName === "change" &&
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- ?? is not logically equivalent when .hasPendingChangeStart returns false.
             (this.hasPendingChangeStart(intervalId) || this.hasPendingChangeEnd(intervalId))) {
             this.removePendingChange(serializedInterval);
             this.addPendingChange(intervalId, rebased);
@@ -788,7 +902,7 @@ export class IntervalCollection extends TypedEventEmitter {
             assert(localInterval instanceof SequenceInterval, 0x3a0 /* localInterval must be `SequenceInterval` when used with client */);
             // The rebased op may place this interval's endpoints on different segments. Calling `changeInterval` here
             // updates the local client's state to be consistent with the emitted op.
-            this.localCollection?.changeInterval(localInterval, startRebased, endRebased, undefined, localSeq);
+            this.localCollection?.changeInterval(localInterval, toOptionalSequencePlace(startRebased, startSide), toOptionalSequencePlace(endRebased, endSide), undefined, localSeq);
         }
         return rebased;
     }
@@ -800,18 +914,12 @@ export class IntervalCollection extends TypedEventEmitter {
         if (segoff.segment?.localRefs?.has(lref) !== true) {
             return undefined;
         }
-        const newSegoff = getSlideToSegoff(segoff);
+        const newSegoff = getSlideToSegoff(segoff, undefined, this.options.mergeTreeReferencesCanSlideToEndpoint);
         const value = segoff.segment === newSegoff.segment && segoff.offset === newSegoff.offset
             ? undefined
             : newSegoff;
         return value;
     }
-    setSlideOnRemove(lref) {
-        let refType = lref.refType;
-        refType = refType & ~ReferenceType.StayOnRemove;
-        refType = refType | ReferenceType.SlideOnRemove;
-        lref.refType = refType;
-    }
     ackInterval(interval, op) {
         // Only SequenceIntervals need potential sliding
         if (!(interval instanceof SequenceInterval)) {
@@ -827,10 +935,10 @@ export class IntervalCollection extends TypedEventEmitter {
         const hasPendingStartChange = this.hasPendingChangeStart(id);
         const hasPendingEndChange = this.hasPendingChangeEnd(id);
         if (!hasPendingStartChange) {
-            this.setSlideOnRemove(interval.start);
+            setSlideOnRemove(interval.start);
         }
         if (!hasPendingEndChange) {
-            this.setSlideOnRemove(interval.end);
+            setSlideOnRemove(interval.end);
         }
         const needsStartUpdate = newStart !== undefined && !hasPendingStartChange;
         const needsEndUpdate = newEnd !== undefined && !hasPendingEndChange;
@@ -849,7 +957,8 @@ export class IntervalCollection extends TypedEventEmitter {
             }
             if (needsStartUpdate) {
                 const props = interval.start.properties;
-                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op, startReferenceSlidingPreference(interval.stickiness));
+                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op, undefined, undefined, startReferenceSlidingPreference(interval.stickiness), startReferenceSlidingPreference(interval.stickiness) ===
+                    SlidingPreference.BACKWARD);
                 if (props) {
                     interval.start.addProperties(props);
                 }
@@ -861,7 +970,8 @@ export class IntervalCollection extends TypedEventEmitter {
             }
             if (needsEndUpdate) {
                 const props = interval.end.properties;
-                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op, endReferenceSlidingPreference(interval.stickiness));
+                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op, undefined, undefined, endReferenceSlidingPreference(interval.stickiness), endReferenceSlidingPreference(interval.stickiness) ===
+                    SlidingPreference.FORWARD);
                 if (props) {
                     interval.end.addProperties(props);
                 }
@@ -891,7 +1001,7 @@ export class IntervalCollection extends TypedEventEmitter {
             throw new LoggingError("attachSequence must be called");
         }
         this.localCollection.ensureSerializedId(serializedInterval);
-        const interval = this.localCollection.addInterval(serializedInterval.start, serializedInterval.end, serializedInterval.intervalType, serializedInterval.properties, op, serializedInterval.stickiness);
+        const interval = this.localCollection.addInterval(toSequencePlace(serializedInterval.start, serializedInterval.startSide ?? Side.Before), toSequencePlace(serializedInterval.end, serializedInterval.endSide ?? Side.Before), serializedInterval.intervalType, serializedInterval.properties, op);
         if (interval) {
             if (this.onDeserialize) {
                 this.onDeserialize(interval);
@@ -1009,11 +1119,18 @@ export class IntervalCollection extends TypedEventEmitter {
         return this.localCollection.endIntervalIndex.nextInterval(pos);
     }
 }
+function setSlideOnRemove(lref) {
+    let refType = lref.refType;
+    refType = refType & ~ReferenceType.StayOnRemove;
+    refType = refType | ReferenceType.SlideOnRemove;
+    lref.refType = refType;
+}
 /**
  * Returns an object that can be used to find the interval a given LocalReferencePosition belongs to.
  * @returns undefined if the reference position is not the endpoint of any interval (e.g. it was created
  * on the merge tree directly by app code), otherwise an {@link IntervalLocator} for the interval this
  * endpoint is a part of.
+ * @public
  */
 export function intervalLocatorFromEndpoint(potentialEndpoint) {
     const { interval, [reservedRangeLabelsKey]: collectionNameArray } = potentialEndpoint.properties ?? {};