@fluidframework/sequence 2.0.0-dev.4.4.0.162574 → 2.0.0-dev.5.3.2.178189

package/lib/intervalCollection.js

@@ -16,11 +16,22 @@ var __rest = (this && this.__rest) || function (s, e) {
 /* eslint-disable no-bitwise */
 import { assert, TypedEventEmitter } from "@fluidframework/common-utils";
 import { UsageError } from "@fluidframework/container-utils";
-import { addProperties, compareReferencePositions, createMap, MergeTreeDeltaType, minReferencePosition, PropertiesManager, RedBlackTree, ReferenceType, refTypeIncludesFlag, reservedRangeLabelsKey, UnassignedSequenceNumber, maxReferencePosition, createDetachedLocalReferencePosition, DetachedReferencePosition, } from "@fluidframework/merge-tree";
+import { addProperties, compareReferencePositions, createMap, getSlideToSegoff, MergeTreeDeltaType, minReferencePosition, PropertiesManager, RedBlackTree, ReferenceType, refTypeIncludesFlag, reservedRangeLabelsKey, UnassignedSequenceNumber, maxReferencePosition, createDetachedLocalReferencePosition, DetachedReferencePosition, SlidingPreference, } from "@fluidframework/merge-tree";
 import { LoggingError } from "@fluidframework/telemetry-utils";
 import { v4 as uuid } from "uuid";
-import { IntervalTree } from "./intervalTree";
+import { createOverlappingIntervalsIndex } from "./intervalIndex";
 const reservedIntervalIdKey = "intervalId";
+/**
+ * Values are used in persisted formats (ops) and revertibles.
+ * @alpha
+ */
+export const IntervalOpType = {
+    ADD: "add",
+    DELETE: "delete",
+    CHANGE: "change",
+    PROPERTY_CHANGED: "propertyChanged",
+    POSITION_REMOVE: "positionRemove",
+};
 export var IntervalType;
 (function (IntervalType) {
     IntervalType[IntervalType["Simple"] = 0] = "Simple";
@@ -28,7 +39,7 @@ export var IntervalType;
     /**
      * SlideOnRemove indicates that the ends of the interval will slide if the segment
      * they reference is removed and acked.
-     * See `packages\dds\merge-tree\REFERENCEPOSITIONS.md` for details
+     * See `packages\dds\merge-tree\docs\REFERENCEPOSITIONS.md` for details
      * SlideOnRemove is the default interval behavior and does not need to be specified.
      */
     IntervalType[IntervalType["SlideOnRemove"] = 2] = "SlideOnRemove";
@@ -49,6 +60,7 @@ function decompressInterval(interval, label) {
         sequenceNumber: interval[2],
         intervalType: interval[3],
         properties: Object.assign(Object.assign({}, interval[4]), { [reservedRangeLabelsKey]: [label] }),
+        stickiness: interval[5],
     };
 }
 /**
@@ -57,14 +69,57 @@ function decompressInterval(interval, label) {
  */
 function compressInterval(interval) {
     const { start, end, sequenceNumber, intervalType, properties } = interval;
-    return [
+    const base = [
         start,
         end,
         sequenceNumber,
         intervalType,
         Object.assign(Object.assign({}, properties), { [reservedRangeLabelsKey]: undefined }),
     ];
+    if (interval.stickiness !== undefined && interval.stickiness !== IntervalStickiness.END) {
+        base.push(interval.stickiness);
+    }
+    return base;
+}
+function startReferenceSlidingPreference(stickiness) {
+    // if any start stickiness, prefer sliding backwards
+    return (stickiness & IntervalStickiness.START) !== 0
+        ? SlidingPreference.BACKWARD
+        : SlidingPreference.FORWARD;
+}
+function endReferenceSlidingPreference(stickiness) {
+    // if any end stickiness, prefer sliding forwards
+    return (stickiness & IntervalStickiness.END) !== 0
+        ? SlidingPreference.FORWARD
+        : SlidingPreference.BACKWARD;
 }
+/**
+ * Determines how an interval should expand when segments are inserted adjacent
+ * to the range it spans
+ *
+ * Note that interval stickiness is currently an experimental feature and must
+ * be explicitly enabled with the `intervalStickinessEnabled` flag
+ */
+export const IntervalStickiness = {
+    /**
+     * Interval does not expand to include adjacent segments
+     */
+    NONE: 0b00,
+    /**
+     * Interval expands to include segments inserted adjacent to the start
+     */
+    START: 0b01,
+    /**
+     * Interval expands to include segments inserted adjacent to the end
+     *
+     * This is the default stickiness
+     */
+    END: 0b10,
+    /**
+     * Interval expands to include all segments inserted adjacent to it
+     */
+    FULL: 0b11,
+};
 /**
  * Serializable interval whose endpoints are plain-old numbers.
  */
@@ -98,7 +153,7 @@ export class Interval {
      * Adds an auxiliary set of properties to this interval.
      * These properties can be recovered using `getAdditionalPropertySets`
      * @param props - set of properties to add
-     * @remarks - This gets called as part of the default conflict resolver for `IntervalCollection<Interval>`
+     * @remarks - This gets called as part of the default conflict resolver for `IIntervalCollection<Interval>`
      * (i.e. non-sequence-based interval collections). However, the additional properties don't get serialized.
      * This functionality seems half-baked.
      */
@@ -223,7 +278,7 @@ export class Interval {
     }
 }
 /**
- * Interval impelmentation whose ends are associated with positions in a mutatable sequence.
+ * 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.
  *
@@ -254,11 +309,12 @@ export class SequenceInterval {
      * End endpoint of this interval.
      * @remarks - This endpoint can be resolved into a character position using the SharedString it's a part of.
      */
-    end, intervalType, props) {
+    end, intervalType, props, stickiness = IntervalStickiness.END) {
         this.client = client;
         this.start = start;
         this.end = end;
         this.intervalType = intervalType;
+        this.stickiness = stickiness;
         this.propertyManager = new PropertiesManager();
         this.properties = {};
         if (props) {
@@ -310,13 +366,16 @@ export class SequenceInterval {
         if (this.properties) {
             serializedInterval.properties = this.properties;
         }
+        if (this.stickiness !== IntervalStickiness.END) {
+            serializedInterval.stickiness = this.stickiness;
+        }
         return serializedInterval;
     }
     /**
      * {@inheritDoc IInterval.clone}
      */
     clone() {
-        return new SequenceInterval(this.client, this.start, this.end, this.intervalType, this.properties);
+        return new SequenceInterval(this.client, this.start, this.end, this.intervalType, this.properties, this.stickiness);
     }
     /**
      * {@inheritDoc IInterval.compare}
@@ -400,7 +459,7 @@ export class SequenceInterval {
      * {@inheritDoc IInterval.modify}
      * @deprecated - This API was never intended to be public and will be marked internal in a future release.
      */
-    modify(label, start, end, op, localSeq) {
+    modify(label, start, end, op, localSeq, stickiness = IntervalStickiness.END) {
         const getRefType = (baseType) => {
             let refType = baseType;
             if (op === undefined) {
@@ -411,14 +470,14 @@ export class SequenceInterval {
         };
         let startRef = this.start;
         if (start !== undefined) {
-            startRef = createPositionReference(this.client, start, getRefType(this.start.refType), op, undefined, localSeq);
+            startRef = createPositionReference(this.client, start, getRefType(this.start.refType), op, undefined, localSeq, startReferenceSlidingPreference(stickiness));
             if (this.start.properties) {
                 startRef.addProperties(this.start.properties);
             }
         }
         let endRef = this.end;
         if (end !== undefined) {
-            endRef = createPositionReference(this.client, end, getRefType(this.end.refType), op, undefined, localSeq);
+            endRef = createPositionReference(this.client, end, getRefType(this.end.refType), op, undefined, localSeq, endReferenceSlidingPreference(stickiness));
             if (this.end.properties) {
                 endRef.addProperties(this.end.properties);
             }
@@ -439,9 +498,9 @@ export class SequenceInterval {
         }
     }
 }
-function createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot) {
+export function createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot, slidingPreference) {
     if (segoff.segment) {
-        const ref = client.createLocalReferencePosition(segoff.segment, segoff.offset, refType, undefined);
+        const ref = client.createLocalReferencePosition(segoff.segment, segoff.offset, refType, undefined, slidingPreference);
         return ref;
     }
     // Creating references on detached segments is allowed for:
@@ -457,7 +516,7 @@ function createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq
     }
     return createDetachedLocalReferencePosition(refType);
 }
-function createPositionReference(client, pos, refType, op, fromSnapshot, localSeq) {
+function createPositionReference(client, pos, refType, op, fromSnapshot, localSeq, slidingPreference) {
     let segoff;
     if (op) {
         assert((refType & ReferenceType.SlideOnRemove) !== 0, 0x2f5 /* op create references must be SlideOnRemove */);
@@ -465,15 +524,15 @@ function createPositionReference(client, pos, refType, op, fromSnapshot, localSe
             referenceSequenceNumber: op.referenceSequenceNumber,
             clientId: op.clientId,
         });
-        segoff = client.getSlideToSegment(segoff);
+        segoff = getSlideToSegoff(segoff);
     }
     else {
         assert((refType & ReferenceType.SlideOnRemove) === 0 || !!fromSnapshot, 0x2f6 /* SlideOnRemove references must be op created */);
         segoff = client.getContainingSegment(pos, undefined, localSeq);
     }
-    return createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot);
+    return createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot, slidingPreference);
 }
-export function createSequenceInterval(label, start, end, client, intervalType, op, fromSnapshot) {
+export function createSequenceInterval(label, start, end, client, intervalType, op, fromSnapshot, stickiness = IntervalStickiness.END) {
     let beginRefType = ReferenceType.RangeBegin;
     let endRefType = ReferenceType.RangeEnd;
     if (intervalType === IntervalType.Transient) {
@@ -497,14 +556,14 @@ export function createSequenceInterval(label, start, end, client, intervalType,
             endRefType |= ReferenceType.StayOnRemove;
         }
     }
-    const startLref = createPositionReference(client, start, beginRefType, op, fromSnapshot);
-    const endLref = createPositionReference(client, end, endRefType, op, fromSnapshot);
+    const startLref = createPositionReference(client, start, beginRefType, op, fromSnapshot, undefined, startReferenceSlidingPreference(stickiness));
+    const endLref = createPositionReference(client, end, endRefType, op, fromSnapshot, undefined, endReferenceSlidingPreference(stickiness));
     const rangeProp = {
         [reservedRangeLabelsKey]: [label],
     };
     startLref.addProperties(rangeProp);
     endLref.addProperties(rangeProp);
-    const ival = new SequenceInterval(client, startLref, endLref, intervalType, rangeProp);
+    const ival = new SequenceInterval(client, startLref, endLref, intervalType, rangeProp, stickiness);
     return ival;
 }
 export function createIntervalIndex() {
@@ -515,98 +574,6 @@ export function createIntervalIndex() {
     const lc = new LocalIntervalCollection(undefined, "", helpers);
     return lc;
 }
-class OverlappingIntervalsIndex {
-    constructor(client, helpers) {
-        this.client = client;
-        this.helpers = helpers;
-        this.intervalTree = new IntervalTree();
-    }
-    map(fn) {
-        this.intervalTree.map(fn);
-    }
-    mapUntil(fn) {
-        this.intervalTree.mapUntil(fn);
-    }
-    gatherIterationResults(results, iteratesForward, start, end) {
-        if (this.intervalTree.intervals.isEmpty()) {
-            return;
-        }
-        if (start === undefined && end === undefined) {
-            // No start/end provided. Gather the whole tree in the specified order.
-            if (iteratesForward) {
-                this.intervalTree.map((interval) => {
-                    results.push(interval);
-                });
-            }
-            else {
-                this.intervalTree.mapBackward((interval) => {
-                    results.push(interval);
-                });
-            }
-        }
-        else {
-            const transientInterval = this.helpers.create("transient", start, end, this.client, IntervalType.Transient);
-            if (start === undefined) {
-                // Only end position provided. Since the tree is not sorted by end position,
-                // walk the whole tree in the specified order, gathering intervals that match the end.
-                if (iteratesForward) {
-                    this.intervalTree.map((interval) => {
-                        if (transientInterval.compareEnd(interval) === 0) {
-                            results.push(interval);
-                        }
-                    });
-                }
-                else {
-                    this.intervalTree.mapBackward((interval) => {
-                        if (transientInterval.compareEnd(interval) === 0) {
-                            results.push(interval);
-                        }
-                    });
-                }
-            }
-            else {
-                // Start and (possibly) end provided. Walk the subtrees that may contain
-                // this start position.
-                const compareFn = end === undefined
-                    ? (node) => {
-                        return transientInterval.compareStart(node.key);
-                    }
-                    : (node) => {
-                        return transientInterval.compare(node.key);
-                    };
-                const continueLeftFn = (cmpResult) => cmpResult <= 0;
-                const continueRightFn = (cmpResult) => cmpResult >= 0;
-                const actionFn = (node) => {
-                    results.push(node.key);
-                };
-                if (iteratesForward) {
-                    this.intervalTree.intervals.walkExactMatchesForward(compareFn, actionFn, continueLeftFn, continueRightFn);
-                }
-                else {
-                    this.intervalTree.intervals.walkExactMatchesBackward(compareFn, actionFn, continueLeftFn, continueRightFn);
-                }
-            }
-        }
-    }
-    /**
-     * @returns an array of all intervals contained in this collection that overlap the range
-     * `[startPosition, endPosition)`.
-     */
-    findOverlappingIntervals(startPosition, endPosition) {
-        if (endPosition < startPosition || this.intervalTree.intervals.isEmpty()) {
-            return [];
-        }
-        const transientInterval = this.helpers.create("transient", startPosition, endPosition, this.client, IntervalType.Transient);
-        const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
-        return overlappingIntervalNodes.map((node) => node.key);
-    }
-    remove(interval) {
-        this.intervalTree.removeExisting(interval);
-    }
-    add(interval) {
-        this.intervalTree.put(interval);
-    }
-}
 class IdIntervalIndex {
     constructor() {
         this.intervalIdMap = new Map();
@@ -662,6 +629,117 @@ class EndpointIndex {
         this.endIntervalTree.remove(interval);
     }
 }
+/**
+ * Interface for intervals that have comparison override properties.
+ */
+const forceCompare = Symbol();
+/**
+ * Compares two objects based on their comparison override properties.
+ * @returns A number indicating the order of the intervals (negative for a is lower than b, 0 for tie, positive for a is greater than b).
+ */
+function compareOverrideables(a, b) {
+    var _a, _b;
+    const forceCompareA = (_a = a[forceCompare]) !== null && _a !== void 0 ? _a : 0;
+    const forceCompareB = (_b = b[forceCompare]) !== null && _b !== void 0 ? _b : 0;
+    return forceCompareA - forceCompareB;
+}
+class EndpointInRangeIndex {
+    constructor(helpers, client) {
+        this.helpers = helpers;
+        this.client = client;
+        this.intervalTree = new RedBlackTree((a, b) => {
+            const compareEndsResult = helpers.compareEnds(a, b);
+            if (compareEndsResult !== 0) {
+                return compareEndsResult;
+            }
+            const overrideablesComparison = compareOverrideables(a, b);
+            if (overrideablesComparison !== 0) {
+                return overrideablesComparison;
+            }
+            const aId = a.getIntervalId();
+            const bId = b.getIntervalId();
+            if (aId !== undefined && bId !== undefined) {
+                return aId.localeCompare(bId);
+            }
+            return 0;
+        });
+    }
+    add(interval) {
+        this.intervalTree.put(interval, interval);
+    }
+    remove(interval) {
+        this.intervalTree.remove(interval);
+    }
+    findIntervalsWithEndpointInRange(start, end) {
+        if (start <= 0 || start > end || this.intervalTree.isEmpty()) {
+            return [];
+        }
+        const results = [];
+        const action = (node) => {
+            results.push(node.data);
+            return true;
+        };
+        const transientStartInterval = this.helpers.create("transient", start, start, this.client, IntervalType.Transient);
+        const transientEndInterval = this.helpers.create("transient", end, end, this.client, IntervalType.Transient);
+        // Add comparison overrides to the transient intervals
+        transientStartInterval[forceCompare] = -1;
+        transientEndInterval[forceCompare] = 1;
+        this.intervalTree.mapRange(action, results, transientStartInterval, transientEndInterval);
+        return results;
+    }
+}
+class StartpointInRangeIndex {
+    constructor(helpers, client) {
+        this.helpers = helpers;
+        this.client = client;
+        this.intervalTree = new RedBlackTree((a, b) => {
+            assert(typeof helpers.compareStarts === "function", 0x6d1 /* compareStarts does not exist in the helpers */);
+            const compareStartsResult = helpers.compareStarts(a, b);
+            if (compareStartsResult !== 0) {
+                return compareStartsResult;
+            }
+            const overrideablesComparison = compareOverrideables(a, b);
+            if (overrideablesComparison !== 0) {
+                return overrideablesComparison;
+            }
+            const aId = a.getIntervalId();
+            const bId = b.getIntervalId();
+            if (aId !== undefined && bId !== undefined) {
+                return aId.localeCompare(bId);
+            }
+            return 0;
+        });
+    }
+    add(interval) {
+        this.intervalTree.put(interval, interval);
+    }
+    remove(interval) {
+        this.intervalTree.remove(interval);
+    }
+    findIntervalsWithStartpointInRange(start, end) {
+        if (start <= 0 || start > end || this.intervalTree.isEmpty()) {
+            return [];
+        }
+        const results = [];
+        const action = (node) => {
+            results.push(node.data);
+            return true;
+        };
+        const transientStartInterval = this.helpers.create("transient", start, start, this.client, IntervalType.Transient);
+        const transientEndInterval = this.helpers.create("transient", end, end, this.client, IntervalType.Transient);
+        // Add comparison overrides to the transient intervals
+        transientStartInterval[forceCompare] = -1;
+        transientEndInterval[forceCompare] = 1;
+        this.intervalTree.mapRange(action, results, transientStartInterval, transientEndInterval);
+        return results;
+    }
+}
+export function createEndpointInRangeIndex(helpers, client) {
+    return new EndpointInRangeIndex(helpers, client);
+}
+export function createStartpointInRangeIndex(helpers, client) {
+    return new StartpointInRangeIndex(helpers, client);
+}
 export class LocalIntervalCollection {
     constructor(client, label, helpers, 
     /** Callback invoked each time one of the endpoints of an interval slides. */
@@ -670,14 +748,14 @@ export class LocalIntervalCollection {
         this.label = label;
         this.helpers = helpers;
         this.onPositionChange = onPositionChange;
-        this.overlappingIntervalsIndex = new OverlappingIntervalsIndex(client, helpers);
+        this.overlappingIntervalsIndex = createOverlappingIntervalsIndex(client, helpers);
         this.idIntervalIndex = new IdIntervalIndex();
         this.endIntervalIndex = new EndpointIndex(client, helpers);
-        this.indexes = [
+        this.indexes = new Set([
             this.overlappingIntervalsIndex,
             this.idIntervalIndex,
             this.endIntervalIndex,
-        ];
+        ]);
     }
     createLegacyId(start, end) {
         // Create a non-unique ID based on start and end to be used on intervals that come from legacy clients
@@ -717,22 +795,35 @@ export class LocalIntervalCollection {
             index.remove(interval);
         }
     }
+    appendIndex(index) {
+        this.indexes.add(index);
+    }
+    removeIndex(index) {
+        return this.indexes.delete(index);
+    }
     removeExistingInterval(interval) {
         this.removeIntervalFromIndexes(interval);
         this.removeIntervalListeners(interval);
     }
-    createInterval(start, end, intervalType, op) {
-        return this.helpers.create(this.label, start, end, this.client, intervalType, op);
+    createInterval(start, end, intervalType, op, stickiness = IntervalStickiness.END) {
+        return this.helpers.create(this.label, start, end, this.client, intervalType, op, undefined, stickiness);
     }
-    addInterval(start, end, intervalType, props, op) {
+    addInterval(start, end, intervalType, props, op, stickiness = IntervalStickiness.END) {
         var _a;
         var _b;
-        const interval = this.createInterval(start, end, intervalType, op);
+        const interval = this.createInterval(start, end, intervalType, op, stickiness);
         if (interval) {
             if (!interval.properties) {
                 interval.properties = createMap();
             }
             if (props) {
+                // This check is intended to prevent scenarios where a random interval is created and then
+                // inserted into a collection. The aim is to ensure that the collection is created first
+                // then the user can create/add intervals based on the collection
+                if (props[reservedRangeLabelsKey] !== undefined &&
+                    props[reservedRangeLabelsKey][0] !== this.label) {
+                    throw new LoggingError("Adding an interval that belongs to another interval collection is not permitted");
+                }
                 interval.addProperties(props);
             }
             (_a = (_b = interval.properties)[reservedIntervalIdKey]) !== null && _a !== void 0 ? _a : (_b[reservedIntervalIdKey] = uuid());
@@ -780,7 +871,7 @@ export class LocalIntervalCollection {
                 // either, so this must be special-cased.
                 return ref;
             }
-            return this.client.createLocalReferencePosition(segment, ref.getOffset(), ReferenceType.Transient, ref.properties);
+            return this.client.createLocalReferencePosition(segment, ref.getOffset(), ReferenceType.Transient, ref.properties, ref.slidingPreference);
         };
         if (interval instanceof SequenceInterval) {
             let previousInterval;
@@ -814,13 +905,20 @@ export class LocalIntervalCollection {
 }
 LocalIntervalCollection.legacyIdPrefix = "legacy";
 export const compareSequenceIntervalEnds = (a, b) => compareReferencePositions(a.end, b.end);
+export const compareSequenceIntervalStarts = (a, b) => compareReferencePositions(a.start, b.start);
+export const sequenceIntervalHelpers = {
+    compareEnds: compareSequenceIntervalEnds,
+    compareStarts: compareSequenceIntervalStarts,
+    create: createSequenceInterval,
+};
+export const intervalHelpers = {
+    compareEnds: (a, b) => a.end - b.end,
+    compareStarts: (a, b) => a.start - b.start,
+    create: createInterval,
+};
 class SequenceIntervalCollectionFactory {
-    load(emitter, raw = []) {
-        const helpers = {
-            compareEnds: compareSequenceIntervalEnds,
-            create: createSequenceInterval,
-        };
-        return new IntervalCollection(helpers, true, emitter, raw);
+    load(emitter, raw = [], options) {
+        return new IntervalCollection(sequenceIntervalHelpers, true, emitter, raw, options);
     }
     store(value) {
         return value.serializeInternal();
@@ -841,7 +939,7 @@ SequenceIntervalCollectionValueType.Name = "sharedStringIntervalCollection";
 SequenceIntervalCollectionValueType._factory = new SequenceIntervalCollectionFactory();
 SequenceIntervalCollectionValueType._ops = makeOpsMap();
 const compareIntervalEnds = (a, b) => a.end - b.end;
-function createInterval(label, start, end, client) {
+function createInterval(label, start, end, client, intervalType, op, fromSnapshot) {
     const rangeProp = {};
     if (label && label.length > 0) {
         rangeProp[reservedRangeLabelsKey] = [label];
@@ -849,12 +947,12 @@ function createInterval(label, start, end, client) {
     return new Interval(start, end, rangeProp);
 }
 class IntervalCollectionFactory {
-    load(emitter, raw = []) {
+    load(emitter, raw = [], options) {
         const helpers = {
             compareEnds: compareIntervalEnds,
             create: createInterval,
         };
-        const collection = new IntervalCollection(helpers, false, emitter, raw);
+        const collection = new IntervalCollection(helpers, false, emitter, raw, options);
         collection.attachGraph(undefined, "");
         return collection;
     }
@@ -885,7 +983,7 @@ export function makeOpsMap() {
     };
     return new Map([
         [
-            "add",
+            IntervalOpType.ADD,
             {
                 process: (collection, params, local, op, localOpMetadata) => {
                     // if params is undefined, the interval was deleted during
@@ -900,7 +998,7 @@ export function makeOpsMap() {
             },
         ],
         [
-            "delete",
+            IntervalOpType.DELETE,
             {
                 process: (collection, params, local, op) => {
                     assert(op !== undefined, 0x3fc /* op should exist here */);
@@ -913,7 +1011,7 @@ export function makeOpsMap() {
             },
         ],
         [
-            "change",
+            IntervalOpType.CHANGE,
             {
                 process: (collection, params, local, op, localOpMetadata) => {
                     // if params is undefined, the interval was deleted during
@@ -929,7 +1027,7 @@ export function makeOpsMap() {
         ],
     ]);
 }
-export class IntervalCollectionIterator {
+class IntervalCollectionIterator {
     constructor(collection, iteratesForward = true, start, end) {
         this.results = [];
         this.index = 0;
@@ -949,19 +1047,16 @@ export class IntervalCollectionIterator {
     }
 }
 /**
- * Collection of intervals that supports addition, modification, removal, and efficient spatial querying.
- * This class is not a DDS in its own right, but emits events on mutating operations such that it's possible to
- * integrate into a DDS.
- * This aligns with its usage in `SharedSegmentSequence`, which allows associating intervals to positions in the
- * sequence DDS which are broadcast to all other clients in an eventually consistent fashion.
+ * {@inheritdoc IIntervalCollection}
  */
 export class IntervalCollection extends TypedEventEmitter {
     /** @internal */
-    constructor(helpers, requiresClient, emitter, serializedIntervals) {
+    constructor(helpers, requiresClient, emitter, serializedIntervals, options = {}) {
         super();
         this.helpers = helpers;
         this.requiresClient = requiresClient;
         this.emitter = emitter;
+        this.options = options;
         this.localSeqToSerializedInterval = new Map();
         this.localSeqToRebasedInterval = new Map();
         this.pendingChangesStart = new Map();
@@ -973,6 +1068,36 @@ export class IntervalCollection extends TypedEventEmitter {
     get attached() {
         return !!this.localCollection;
     }
+    /**
+     * {@inheritdoc IIntervalCollection.attachIndex}
+     */
+    attachIndex(index) {
+        var _a;
+        if (!this.attached) {
+            throw new LoggingError("The local interval collection must exist");
+        }
+        for (const interval of this) {
+            index.add(interval);
+        }
+        (_a = this.localCollection) === null || _a === void 0 ? void 0 : _a.appendIndex(index);
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.detachIndex}
+     */
+    detachIndex(index) {
+        var _a;
+        if (!this.attached) {
+            throw new LoggingError("The local interval collection must exist");
+        }
+        // Avoid removing intervals if the index does not exist
+        if (!((_a = this.localCollection) === null || _a === void 0 ? void 0 : _a.removeIndex(index))) {
+            return false;
+        }
+        for (const interval of this) {
+            index.remove(interval);
+        }
+        return true;
+    }
     rebasePositionWithSegmentSlide(pos, seqNumberFrom, localSeq) {
         var _a;
         if (!this.client) {
@@ -985,7 +1110,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 = (_a = this.client.getSlideToSegment({ segment, offset })) !== null && _a !== void 0 ? _a : segment;
+        const segoff = (_a = getSlideToSegoff({ segment, offset })) !== null && _a !== void 0 ? _a : segment;
         // case happens when rebasing op, but concurrently entire string has been deleted
         if (segoff.segment === undefined || segoff.offset === undefined) {
             return DetachedReferencePosition;
@@ -1024,12 +1149,12 @@ export class IntervalCollection extends TypedEventEmitter {
                 }
             });
         }
-        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, (interval, previousInterval) => this.emitChange(interval, previousInterval, true));
+        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, (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 } = serializedInterval;
-                const interval = this.helpers.create(label, start, end, client, intervalType, undefined, true);
+                const { start, end, intervalType, properties, stickiness } = serializedInterval;
+                const interval = this.helpers.create(label, start, end, client, intervalType, undefined, true, stickiness);
                 if (properties) {
                     interval.addProperties(properties);
                 }
@@ -1047,7 +1172,7 @@ export class IntervalCollection extends TypedEventEmitter {
         }
         return 0;
     }
-    emitChange(interval, previousInterval, local, op) {
+    emitChange(interval, previousInterval, local, slide, op) {
         // Temporarily make references transient so that positional queries work (non-transient refs
         // on resolve to DetachedPosition on any segments that don't contain them). The original refType
         // is restored as single-endpoint changes re-use previous references.
@@ -1058,17 +1183,16 @@ export class IntervalCollection extends TypedEventEmitter {
             endRefType = previousInterval.end.refType;
             previousInterval.start.refType = ReferenceType.Transient;
             previousInterval.end.refType = ReferenceType.Transient;
-            this.emit("changeInterval", interval, previousInterval, local, op);
+            this.emit("changeInterval", interval, previousInterval, local, op, slide);
             previousInterval.start.refType = startRefType;
             previousInterval.end.refType = endRefType;
         }
         else {
-            this.emit("changeInterval", interval, previousInterval, local, op);
+            this.emit("changeInterval", interval, previousInterval, local, op, slide);
         }
     }
     /**
-     * @returns the interval in this collection that has the provided `id`.
-     * If no interval in the collection has this `id`, returns `undefined`.
+     * {@inheritdoc IIntervalCollection.getIntervalById}
      */
     getIntervalById(id) {
         if (!this.localCollection) {
@@ -1077,16 +1201,9 @@ export class IntervalCollection extends TypedEventEmitter {
         return this.localCollection.idIntervalIndex.getIntervalById(id);
     }
     /**
-     * Creates a new interval and add it to the collection.
-     * @param start - interval start position (inclusive)
-     * @param end - interval end position (exclusive)
-     * @param intervalType - type of the interval. All intervals are SlideOnRemove. Intervals may not be Transient.
-     * @param props - properties of the interval
-     * @returns - the created interval
-     * @remarks - See documentation on {@link SequenceInterval} for comments on interval endpoint semantics: there are subtleties
-     * with how the current half-open behavior is represented.
+     * {@inheritdoc IIntervalCollection.add}
      */
-    add(start, end, intervalType, props) {
+    add(start, end, intervalType, props, stickiness = IntervalStickiness.END) {
         var _a, _b;
         if (!this.localCollection) {
             throw new LoggingError("attach must be called prior to adding intervals");
@@ -1094,7 +1211,10 @@ export class IntervalCollection extends TypedEventEmitter {
         if (intervalType & IntervalType.Transient) {
             throw new LoggingError("Can not add transient intervals");
         }
-        const interval = this.localCollection.addInterval(start, end, intervalType, props);
+        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);
         if (interval) {
             const serializedInterval = {
                 end,
@@ -1102,6 +1222,7 @@ export class IntervalCollection extends TypedEventEmitter {
                 properties: interval.properties,
                 sequenceNumber: (_b = (_a = this.client) === null || _a === void 0 ? void 0 : _a.getCurrentSeq()) !== null && _b !== void 0 ? _b : 0,
                 start,
+                stickiness,
             };
             const localSeq = this.getNextLocalSeq();
             this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
@@ -1133,9 +1254,7 @@ export class IntervalCollection extends TypedEventEmitter {
         this.emit("deleteInterval", interval, local, op);
     }
     /**
-     * Removes an interval from the collection.
-     * @param id - Id of the interval to remove
-     * @returns the removed interval
+     * {@inheritdoc IIntervalCollection.removeIntervalById}
      */
     removeIntervalById(id) {
         if (!this.localCollection) {
@@ -1148,10 +1267,7 @@ export class IntervalCollection extends TypedEventEmitter {
         return interval;
     }
     /**
-     * Changes the properties on an existing interval.
-     * @param id - Id of the interval whose properties should be changed
-     * @param props - Property set to apply to the interval. Shallow merging is used between any existing properties
-     * and `prop`, i.e. the interval will end up with a property object equivalent to `{ ...oldProps, ...props }`.
+     * {@inheritdoc IIntervalCollection.changeProperties}
      */
     changeProperties(id, props) {
         if (!this.attached) {
@@ -1163,6 +1279,11 @@ export class IntervalCollection extends TypedEventEmitter {
         if (!props) {
             throw new LoggingError("changeProperties should be called with a property set");
         }
+        // prevent the overwriting of an interval label, it should remain unchanged
+        // once it has been inserted into the collection.
+        if (props[reservedRangeLabelsKey] !== undefined) {
+            throw new LoggingError("The label property should not be modified once inserted to the collection");
+        }
         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.
@@ -1181,11 +1302,7 @@ export class IntervalCollection extends TypedEventEmitter {
         }
     }
     /**
-     * Changes the endpoints of an existing interval.
-     * @param id - Id of the interval to change
-     * @param start - New start value, if defined. `undefined` signifies this endpoint should be left unchanged.
-     * @param end - New end value, if defined. `undefined` signifies this endpoint should be left unchanged.
-     * @returns the interval that was changed, if it existed in the collection.
+     * {@inheritdoc IIntervalCollection.change}
      */
     change(id, start, end) {
         if (!this.localCollection) {
@@ -1212,7 +1329,7 @@ export class IntervalCollection extends TypedEventEmitter {
             this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
             this.emitter.emit("change", undefined, serializedInterval, { localSeq });
             this.addPendingChange(id, serializedInterval);
-            this.emitChange(newInterval, interval, true);
+            this.emitChange(newInterval, interval, true, false);
             return newInterval;
         }
         // No interval to change
@@ -1320,7 +1437,7 @@ export class IntervalCollection extends TypedEventEmitter {
                 this.onDeserialize(newInterval);
             }
             if (newInterval !== interval) {
-                this.emitChange(newInterval, interval, local, op);
+                this.emitChange(newInterval, interval, local, false, op);
             }
             const changedProperties = Object.keys(newProps).length > 0;
             if (changedProperties) {
@@ -1340,6 +1457,9 @@ export class IntervalCollection extends TypedEventEmitter {
             throw new LoggingError("attachSequence must be called");
         }
     }
+    /**
+     * {@inheritdoc IIntervalCollection.attachDeserializer}
+     */
     attachDeserializer(onDeserialize) {
         // If no deserializer is specified can skip all processing work
         if (!onDeserialize) {
@@ -1410,7 +1530,7 @@ export class IntervalCollection extends TypedEventEmitter {
         if (((_b = (_a = segoff.segment) === null || _a === void 0 ? void 0 : _a.localRefs) === null || _b === void 0 ? void 0 : _b.has(lref)) !== true) {
             return undefined;
         }
-        const newSegoff = this.client.getSlideToSegment(segoff);
+        const newSegoff = getSlideToSegoff(segoff);
         const value = segoff.segment === newSegoff.segment && segoff.offset === newSegoff.offset
             ? undefined
             : newSegoff;
@@ -1460,7 +1580,7 @@ export class IntervalCollection extends TypedEventEmitter {
             }
             if (needsStartUpdate) {
                 const props = interval.start.properties;
-                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op);
+                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op, startReferenceSlidingPreference(interval.stickiness));
                 if (props) {
                     interval.start.addProperties(props);
                 }
@@ -1472,7 +1592,7 @@ export class IntervalCollection extends TypedEventEmitter {
             }
             if (needsEndUpdate) {
                 const props = interval.end.properties;
-                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op);
+                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op, endReferenceSlidingPreference(interval.stickiness));
                 if (props) {
                     interval.end.addProperties(props);
                 }
@@ -1483,7 +1603,7 @@ export class IntervalCollection extends TypedEventEmitter {
                 (_b = oldSeg === null || oldSeg === void 0 ? void 0 : oldSeg.localRefs) === null || _b === void 0 ? void 0 : _b.addLocalRef(oldInterval.end, oldInterval.end.getOffset());
             }
             this.localCollection.add(interval);
-            this.emitChange(interval, oldInterval, true, op);
+            this.emitChange(interval, oldInterval, true, true, op);
         }
     }
     /** @internal */
@@ -1503,7 +1623,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);
+        const interval = this.localCollection.addInterval(serializedInterval.start, serializedInterval.end, serializedInterval.intervalType, serializedInterval.properties, op, serializedInterval.stickiness);
         if (interval) {
             if (this.onDeserialize) {
                 this.onDeserialize(interval);
@@ -1546,40 +1666,35 @@ export class IntervalCollection extends TypedEventEmitter {
         return iterator;
     }
     /**
-     * @returns a forward iterator over all intervals in this collection with start point equal to `startPosition`.
+     * {@inheritdoc IIntervalCollection.CreateForwardIteratorWithStartPosition}
      */
     CreateForwardIteratorWithStartPosition(startPosition) {
         const iterator = new IntervalCollectionIterator(this, true, startPosition);
         return iterator;
     }
     /**
-     * @returns a backward iterator over all intervals in this collection with start point equal to `startPosition`.
+     * {@inheritdoc IIntervalCollection.CreateBackwardIteratorWithStartPosition}
      */
     CreateBackwardIteratorWithStartPosition(startPosition) {
         const iterator = new IntervalCollectionIterator(this, false, startPosition);
         return iterator;
     }
     /**
-     * @returns a forward iterator over all intervals in this collection with end point equal to `endPosition`.
+     * {@inheritdoc IIntervalCollection.CreateForwardIteratorWithEndPosition}
      */
     CreateForwardIteratorWithEndPosition(endPosition) {
         const iterator = new IntervalCollectionIterator(this, true, undefined, endPosition);
         return iterator;
     }
     /**
-     * @returns a backward iterator over all intervals in this collection with end point equal to `endPosition`.
+     * {@inheritdoc IIntervalCollection.CreateBackwardIteratorWithEndPosition}
      */
     CreateBackwardIteratorWithEndPosition(endPosition) {
         const iterator = new IntervalCollectionIterator(this, false, undefined, endPosition);
         return iterator;
     }
     /**
-     * Gathers iteration results that optionally match a start/end criteria into the provided array.
-     * @param results - Array to gather the results into. In lieu of a return value, this array will be populated with
-     * intervals matching the query upon edit.
-     * @param iteratesForward - whether or not iteration should be in the forward direction
-     * @param start - If provided, only match intervals whose start point is equal to `start`.
-     * @param end - If provided, only match intervals whose end point is equal to `end`.
+     * {@inheritdoc IIntervalCollection.gatherIterationResults}
      */
     gatherIterationResults(results, iteratesForward, start, end) {
         if (!this.localCollection) {
@@ -1588,8 +1703,7 @@ export class IntervalCollection extends TypedEventEmitter {
         this.localCollection.overlappingIntervalsIndex.gatherIterationResults(results, iteratesForward, start, end);
     }
     /**
-     * @returns an array of all intervals in this collection that overlap with the interval
-     * `[startPosition, endPosition]`.
+     * {@inheritdoc IIntervalCollection.findOverlappingIntervals}
      */
     findOverlappingIntervals(startPosition, endPosition) {
         if (!this.localCollection) {
@@ -1598,7 +1712,7 @@ export class IntervalCollection extends TypedEventEmitter {
         return this.localCollection.overlappingIntervalsIndex.findOverlappingIntervals(startPosition, endPosition);
     }
     /**
-     * Applies a function to each interval in this collection.
+     * {@inheritdoc IIntervalCollection.map}
      */
     map(fn) {
         if (!this.localCollection) {
@@ -1608,12 +1722,18 @@ export class IntervalCollection extends TypedEventEmitter {
             fn(interval);
         }
     }
+    /**
+     * {@inheritdoc IIntervalCollection.previousInterval}
+     */
     previousInterval(pos) {
         if (!this.localCollection) {
             throw new LoggingError("attachSequence must be called");
         }
         return this.localCollection.endIntervalIndex.previousInterval(pos);
     }
+    /**
+     * {@inheritdoc IIntervalCollection.nextInterval}
+     */
     nextInterval(pos) {
         if (!this.localCollection) {
             throw new LoggingError("attachSequence must be called");