@fluidframework/sequence 2.0.0-internal.1.4.2 → 2.0.0-internal.2.0.0

package/dist/intervalCollection.js

@@ -15,13 +15,14 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.intervalLocatorFromEndpoint = exports.IntervalCollection = exports.IntervalCollectionIterator = exports.IntervalCollectionValueType = exports.SequenceIntervalCollectionValueType = exports.LocalIntervalCollection = exports.createIntervalIndex = exports.defaultIntervalConflictResolver = exports.SequenceInterval = exports.Interval = exports.IntervalType = void 0;
+exports.intervalLocatorFromEndpoint = exports.IntervalCollection = exports.IntervalCollectionIterator = exports.makeOpsMap = exports.IntervalCollectionValueType = exports.SequenceIntervalCollectionValueType = exports.compareSequenceIntervalEnds = exports.LocalIntervalCollection = exports.createIntervalIndex = exports.defaultIntervalConflictResolver = exports.createSequenceInterval = exports.SequenceInterval = exports.Interval = exports.IntervalType = void 0;
 /* eslint-disable no-bitwise */
 const common_utils_1 = require("@fluidframework/common-utils");
 const container_utils_1 = require("@fluidframework/container-utils");
 const merge_tree_1 = require("@fluidframework/merge-tree");
 const telemetry_utils_1 = require("@fluidframework/telemetry-utils");
 const uuid_1 = require("uuid");
+const intervalTree_1 = require("./intervalTree");
 const reservedIntervalIdKey = "intervalId";
 var IntervalType;
 (function (IntervalType) {
@@ -67,6 +68,9 @@ function compressInterval(interval) {
         Object.assign(Object.assign({}, properties), { [merge_tree_1.reservedRangeLabelsKey]: undefined }),
     ];
 }
+/**
+ * Serializable interval whose endpoints are plain-old numbers.
+ */
 class Interval {
     constructor(start, end, props) {
         this.start = start;
@@ -77,6 +81,9 @@ class Interval {
             this.addProperties(props);
         }
     }
+    /**
+     * {@inheritDoc ISerializableInterval.getIntervalId}
+     */
     getIntervalId() {
         var _a;
         const id = (_a = this.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
@@ -85,22 +92,36 @@ class Interval {
         }
         return `${id}`;
     }
+    /**
+     * @returns an array containing any auxiliary property sets added with `addPropertySet`.
+     */
     getAdditionalPropertySets() {
-        return this.auxProps;
+        var _a;
+        return (_a = this.auxProps) !== null && _a !== void 0 ? _a : [];
     }
+    /**
+     * 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>`
+     * (i.e. non-sequence-based interval collections). However, the additional properties don't get serialized.
+     * This functionality seems half-baked.
+     */
     addPropertySet(props) {
         if (this.auxProps === undefined) {
             this.auxProps = [];
         }
         this.auxProps.push(props);
     }
-    serialize(client) {
-        var _a;
-        const seq = (_a = client === null || client === void 0 ? void 0 : client.getCurrentSeq()) !== null && _a !== void 0 ? _a : 0;
+    /**
+     * {@inheritDoc ISerializableInterval.serialize}
+     * @internal
+     */
+    serialize() {
         const serializedInterval = {
             end: this.end,
             intervalType: 0,
-            sequenceNumber: seq,
+            sequenceNumber: 0,
             start: this.start,
         };
         if (this.properties) {
@@ -108,9 +129,15 @@ class Interval {
         }
         return serializedInterval;
     }
+    /**
+     * {@inheritDoc IInterval.clone}
+     */
     clone() {
         return new Interval(this.start, this.end, this.properties);
     }
+    /**
+     * {@inheritDoc IInterval.compare}
+     */
     compare(b) {
         const startResult = this.compareStart(b);
         if (startResult === 0) {
@@ -134,29 +161,47 @@ class Interval {
             return startResult;
         }
     }
+    /**
+     * {@inheritDoc IInterval.compareStart}
+     */
     compareStart(b) {
         return this.start - b.start;
     }
+    /**
+     * {@inheritDoc IInterval.compareEnd}
+     */
     compareEnd(b) {
         return this.end - b.end;
     }
+    /**
+     * {@inheritDoc IInterval.overlaps}
+     */
     overlaps(b) {
         const result = (this.start <= b.end) &&
             (this.end >= b.start);
         return result;
     }
+    /**
+     * {@inheritDoc IInterval.union}
+     */
     union(b) {
         return new Interval(Math.min(this.start, b.start), Math.max(this.end, b.end), this.properties);
     }
     getProperties() {
         return this.properties;
     }
+    /**
+     * {@inheritDoc ISerializableInterval.addProperties}
+     */
     addProperties(newProps, collaborating = false, seq, op) {
         if (newProps) {
             this.initializeProperties();
             return this.propertyManager.addProperties(this.properties, newProps, op, seq, collaborating);
         }
     }
+    /**
+     * {@inheritDoc IInterval.modify}
+     */
     modify(label, start, end, op) {
         const startPos = start !== null && start !== void 0 ? start : this.start;
         const endPos = end !== null && end !== void 0 ? end : this.end;
@@ -181,8 +226,23 @@ class Interval {
     }
 }
 exports.Interval = Interval;
+/**
+ * Interval impelmentation 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.
+ */
 class SequenceInterval {
-    constructor(client, start, end, intervalType, props) {
+    constructor(client, 
+    /**
+     * Start endpoint of this interval.
+     * @remarks - This endpoint can be resolved into a character position using the SharedString it's a part of.
+     */
+    start, 
+    /**
+     * 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) {
         this.client = client;
         this.start = start;
         this.end = end;
@@ -222,13 +282,17 @@ class SequenceInterval {
             this.end.callbacks = undefined;
         }
     }
-    serialize(client) {
-        const startPosition = client.localReferencePositionToPosition(this.start);
-        const endPosition = client.localReferencePositionToPosition(this.end);
+    /**
+     * {@inheritDoc ISerializableInterval.serialize}
+     * @internal
+     */
+    serialize() {
+        const startPosition = this.client.localReferencePositionToPosition(this.start);
+        const endPosition = this.client.localReferencePositionToPosition(this.end);
         const serializedInterval = {
             end: endPosition,
             intervalType: this.intervalType,
-            sequenceNumber: client.getCurrentSeq(),
+            sequenceNumber: this.client.getCurrentSeq(),
             start: startPosition,
         };
         if (this.properties) {
@@ -236,9 +300,15 @@ class SequenceInterval {
         }
         return serializedInterval;
     }
+    /**
+     * {@inheritDoc IInterval.clone}
+     */
     clone() {
         return new SequenceInterval(this.client, this.start, this.end, this.intervalType, this.properties);
     }
+    /**
+     * {@inheritDoc IInterval.compare}
+     */
     compare(b) {
         const startResult = this.compareStart(b);
         if (startResult === 0) {
@@ -262,17 +332,29 @@ class SequenceInterval {
             return startResult;
         }
     }
+    /**
+     * {@inheritDoc IInterval.compareStart}
+     */
     compareStart(b) {
         return (0, merge_tree_1.compareReferencePositions)(this.start, b.start);
     }
+    /**
+     * {@inheritDoc IInterval.compareEnd}
+     */
     compareEnd(b) {
         return (0, merge_tree_1.compareReferencePositions)(this.end, b.end);
     }
+    /**
+     * {@inheritDoc IInterval.overlaps}
+     */
     overlaps(b) {
         const result = ((0, merge_tree_1.compareReferencePositions)(this.start, b.end) <= 0) &&
             ((0, merge_tree_1.compareReferencePositions)(this.end, b.start) >= 0);
         return result;
     }
+    /**
+     * {@inheritDoc ISerializableInterval.getIntervalId}
+     */
     getIntervalId() {
         var _a;
         const id = (_a = this.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
@@ -281,18 +363,31 @@ class SequenceInterval {
         }
         return `${id}`;
     }
+    /**
+     * {@inheritDoc IInterval.union}
+     */
     union(b) {
         return new SequenceInterval(this.client, (0, merge_tree_1.minReferencePosition)(this.start, b.start), (0, merge_tree_1.maxReferencePosition)(this.end, b.end), this.intervalType);
     }
+    /**
+     * {@inheritDoc ISerializableInterval.addProperties}
+     */
     addProperties(newProps, collab = false, seq, op) {
         this.initializeProperties();
         return this.propertyManager.addProperties(this.properties, newProps, op, seq, collab);
     }
+    /**
+     * @returns whether this interval overlaps two numerical positions.
+     * @remarks - this is currently strict overlap, which doesn't align with the endpoint treatment of`.overlaps()`
+     */
     overlapsPos(bstart, bend) {
         const startPos = this.client.localReferencePositionToPosition(this.start);
         const endPos = this.client.localReferencePositionToPosition(this.end);
         return (endPos > bstart) && (startPos < bend);
     }
+    /**
+     * {@inheritDoc IInterval.modify}
+     */
     modify(label, start, end, op, localSeq) {
         const getRefType = (baseType) => {
             let refType = baseType;
@@ -305,12 +400,16 @@ class SequenceInterval {
         let startRef = this.start;
         if (start !== undefined) {
             startRef = createPositionReference(this.client, start, getRefType(this.start.refType), op, undefined, localSeq);
-            startRef.addProperties(this.start.properties);
+            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.addProperties(this.end.properties);
+            if (this.end.properties) {
+                endRef.addProperties(this.end.properties);
+            }
         }
         const newInterval = new SequenceInterval(this.client, startRef, endRef, this.intervalType);
         if (this.properties) {
@@ -348,7 +447,7 @@ function createPositionReference(client, pos, refType, op, fromSnapshot, localSe
         segoff = client.getSlideToSegment(segoff);
     }
     else {
-        (0, common_utils_1.assert)((refType & merge_tree_1.ReferenceType.SlideOnRemove) === 0 || fromSnapshot, 0x2f6 /* SlideOnRemove references must be op created */);
+        (0, common_utils_1.assert)((refType & merge_tree_1.ReferenceType.SlideOnRemove) === 0 || !!fromSnapshot, 0x2f6 /* SlideOnRemove references must be op created */);
         segoff = client.getContainingSegment(pos, undefined, localSeq);
     }
     return createPositionReferenceFromSegoff(client, segoff, refType, op);
@@ -387,6 +486,7 @@ function createSequenceInterval(label, start, end, client, intervalType, op, fro
     const ival = new SequenceInterval(client, startLref, endLref, intervalType, rangeProp);
     return ival;
 }
+exports.createSequenceInterval = createSequenceInterval;
 function defaultIntervalConflictResolver(a, b) {
     a.addPropertySet(b.properties);
     return a;
@@ -415,7 +515,7 @@ class LocalIntervalCollection {
         this.label = label;
         this.helpers = helpers;
         this.onPositionChange = onPositionChange;
-        this.intervalTree = new merge_tree_1.IntervalTree();
+        this.intervalTree = new intervalTree_1.IntervalTree();
         this.intervalIdMap = new Map();
         // eslint-disable-next-line @typescript-eslint/unbound-method
         this.endIntervalTree = new merge_tree_1.RedBlackTree(helpers.compareEnds);
@@ -530,6 +630,10 @@ class LocalIntervalCollection {
             }
         }
     }
+    /**
+     * @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 [];
@@ -624,20 +728,38 @@ class LocalIntervalCollection {
         return newInterval;
     }
     serialize() {
-        const client = this.client;
         const intervals = this.intervalTree.intervals.keys();
         return {
             label: this.label,
-            intervals: intervals.map((interval) => compressInterval(interval.serialize(client))),
+            intervals: intervals.map((interval) => compressInterval(interval.serialize())),
             version: 2,
         };
     }
     addIntervalListeners(interval) {
+        const cloneRef = (ref) => {
+            const segment = ref.getSegment();
+            if (segment === undefined) {
+                // Cloning is unnecessary: refs which have slid off the string entirely
+                // never get slid back on. Creation code for refs doesn't accept undefined segment
+                // either, so this must be special-cased.
+                return ref;
+            }
+            return this.client.createLocalReferencePosition(segment, ref.getOffset(), merge_tree_1.ReferenceType.Transient, ref.properties);
+        };
         if (interval instanceof SequenceInterval) {
-            interval.addPositionChangeListeners(() => this.removeIntervalFromIndex(interval), () => {
+            let previousInterval;
+            interval.addPositionChangeListeners(() => {
+                (0, common_utils_1.assert)(!previousInterval, 0x3f9 /* Invalid interleaving of before/after slide */);
+                previousInterval = interval.clone();
+                previousInterval.start = cloneRef(previousInterval.start);
+                previousInterval.end = cloneRef(previousInterval.end);
+                this.removeIntervalFromIndex(interval);
+            }, () => {
                 var _a;
+                (0, common_utils_1.assert)(previousInterval !== undefined, 0x3fa /* Invalid interleaving of before/after slide */);
                 this.addIntervalToIndex(interval);
-                (_a = this.onPositionChange) === null || _a === void 0 ? void 0 : _a.call(this, interval);
+                (_a = this.onPositionChange) === null || _a === void 0 ? void 0 : _a.call(this, interval, previousInterval);
+                previousInterval = undefined;
             });
         }
     }
@@ -650,10 +772,11 @@ class LocalIntervalCollection {
 exports.LocalIntervalCollection = LocalIntervalCollection;
 LocalIntervalCollection.legacyIdPrefix = "legacy";
 const compareSequenceIntervalEnds = (a, b) => (0, merge_tree_1.compareReferencePositions)(a.end, b.end);
+exports.compareSequenceIntervalEnds = compareSequenceIntervalEnds;
 class SequenceIntervalCollectionFactory {
     load(emitter, raw = []) {
         const helpers = {
-            compareEnds: compareSequenceIntervalEnds,
+            compareEnds: exports.compareSequenceIntervalEnds,
             create: createSequenceInterval,
         };
         return new IntervalCollection(helpers, true, emitter, raw);
@@ -730,6 +853,7 @@ function makeOpsMap() {
                     if (!params) {
                         return;
                     }
+                    (0, common_utils_1.assert)(op !== undefined, 0x3fb /* op should exist here */);
                     collection.ackAdd(params, local, op);
                 },
                 rebase,
@@ -739,6 +863,7 @@ function makeOpsMap() {
             "delete",
             {
                 process: (collection, params, local, op) => {
+                    (0, common_utils_1.assert)(op !== undefined, 0x3fc /* op should exist here */);
                     collection.ackDelete(params, local, op);
                 },
                 rebase: (collection, op, localOpMetadata) => {
@@ -756,12 +881,14 @@ function makeOpsMap() {
                     if (!params) {
                         return;
                     }
+                    (0, common_utils_1.assert)(op !== undefined, 0x3fd /* op should exist here */);
                     collection.ackChange(params, local, op);
                 },
                 rebase,
             },
         ]]);
 }
+exports.makeOpsMap = makeOpsMap;
 class IntervalCollectionIterator {
     constructor(collection, iteratesForward = true, start, end) {
         this.results = [];
@@ -769,19 +896,26 @@ class IntervalCollectionIterator {
         collection.gatherIterationResults(this.results, iteratesForward, start, end);
     }
     next() {
-        let _value;
-        let _done = true;
         if (this.index < this.results.length) {
-            _value = this.results[this.index++];
-            _done = false;
+            return {
+                value: this.results[this.index++],
+                done: false,
+            };
         }
         return {
-            value: _value,
-            done: _done,
+            value: undefined,
+            done: true,
         };
     }
 }
 exports.IntervalCollectionIterator = 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.
+ */
 class IntervalCollection extends common_utils_1.TypedEventEmitter {
     /** @internal */
     constructor(helpers, requiresClient, emitter, serializedIntervals) {
@@ -798,6 +932,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
     get attached() {
         return !!this.localCollection;
     }
+    /** @internal */
     attachGraph(client, label) {
         if (this.attached) {
             throw new telemetry_utils_1.LoggingError("Only supports one Sequence attach");
@@ -807,13 +942,15 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         }
         // Instantiate the local interval collection based on the saved intervals
         this.client = client;
-        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, (interval) => this.emit("changeInterval", interval, true, undefined));
+        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, (interval, previousInterval) => this.emitChange(interval, previousInterval, 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);
-                interval.addProperties(properties);
+                if (properties) {
+                    interval.addProperties(properties);
+                }
                 this.localCollection.add(interval);
             }
         }
@@ -828,14 +965,37 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         }
         return 0;
     }
+    emitChange(interval, previousInterval, local, 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.
+        let startRefType;
+        let endRefType;
+        if (previousInterval instanceof SequenceInterval) {
+            startRefType = previousInterval.start.refType;
+            endRefType = previousInterval.end.refType;
+            previousInterval.start.refType = merge_tree_1.ReferenceType.Transient;
+            previousInterval.end.refType = merge_tree_1.ReferenceType.Transient;
+            this.emit("changeInterval", interval, previousInterval, local, op);
+            previousInterval.start.refType = startRefType;
+            previousInterval.end.refType = endRefType;
+        }
+        else {
+            this.emit("changeInterval", interval, previousInterval, local, op);
+        }
+    }
+    /**
+     * @returns the interval in this collection that has the provided `id`.
+     * If no interval in the collection has this `id`, returns `undefined`.
+     */
     getIntervalById(id) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attach must be called before accessing intervals");
         }
         return this.localCollection.getIntervalById(id);
     }
     /**
-     * Create a new interval and add it to the collection
+     * Creates a new interval and add it to the collection.
      * @param start - interval start position
      * @param end - interval end position
      * @param intervalType - type of the interval. All intervals are SlideOnRemove. Intervals may not be Transient.
@@ -844,7 +1004,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
      */
     add(start, end, intervalType, props) {
         var _a, _b;
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attach must be called prior to adding intervals");
         }
         if (intervalType & IntervalType.Transient) {
@@ -866,12 +1026,15 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         return interval;
     }
     deleteExistingInterval(interval, local, op) {
+        if (!this.localCollection) {
+            throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
+        }
         // The given interval is known to exist in the collection.
         this.localCollection.removeExistingInterval(interval);
         if (interval) {
             // Local ops get submitted to the server. Remote ops have the deserializer run.
             if (local) {
-                this.emitter.emit("delete", undefined, interval.serialize(this.client), { localSeq: this.getNextLocalSeq() });
+                this.emitter.emit("delete", undefined, interval.serialize(), { localSeq: this.getNextLocalSeq() });
             }
             else {
                 if (this.onDeserialize) {
@@ -881,13 +1044,27 @@ class IntervalCollection extends common_utils_1.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
+     */
     removeIntervalById(id) {
+        if (!this.localCollection) {
+            throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
+        }
         const interval = this.localCollection.getIntervalById(id);
         if (interval) {
             this.deleteExistingInterval(interval, true, undefined);
         }
         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 }`.
+     */
     changeProperties(id, props) {
         if (!this.attached) {
             throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
@@ -902,7 +1079,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         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, merge_tree_1.UnassignedSequenceNumber);
-            const serializedInterval = interval.serialize(this.client);
+            const serializedInterval = interval.serialize();
             // Emit a change op that will only change properties. Add the ID to
             // the property bag provided by the caller.
             serializedInterval.start = undefined;
@@ -910,12 +1087,18 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
             serializedInterval.properties = props;
             serializedInterval.properties[reservedIntervalIdKey] = interval.getIntervalId();
             this.emitter.emit("change", undefined, serializedInterval, { localSeq: this.getNextLocalSeq() });
-            this.emit("propertyChanged", interval, deltaProps);
+            this.emit("propertyChanged", interval, deltaProps, true, undefined);
         }
-        this.emit("changeInterval", interval, true, undefined);
     }
+    /**
+     * 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.
+     */
     change(id, start, end) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
         }
         // Force id to be a string.
@@ -925,7 +1108,10 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         const interval = this.getIntervalById(id);
         if (interval) {
             const newInterval = this.localCollection.changeInterval(interval, start, end);
-            const serializedInterval = interval.serialize(this.client);
+            if (!newInterval) {
+                return undefined;
+            }
+            const serializedInterval = interval.serialize();
             serializedInterval.start = start;
             serializedInterval.end = end;
             // Emit a property bag containing only the ID, as we don't intend for this op to change any properties.
@@ -935,7 +1121,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
                 };
             this.emitter.emit("change", undefined, serializedInterval, { localSeq: this.getNextLocalSeq() });
             this.addPendingChange(id, serializedInterval);
-            this.emit("changeInterval", newInterval, true, undefined);
+            this.emitChange(newInterval, interval, true);
             return newInterval;
         }
         // No interval to change
@@ -992,65 +1178,70 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
     /** @internal */
     ackChange(serializedInterval, local, op) {
         var _a, _b, _c, _d;
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
         }
-        let interval;
         if (local) {
             // This is an ack from the server. Remove the pending change.
             this.removePendingChange(serializedInterval);
-            const id = (_a = serializedInterval.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
-            interval = this.getIntervalById(id);
-            if (interval) {
-                // Let the propertyManager prune its pending change-properties set.
-                (_b = interval.propertyManager) === null || _b === void 0 ? void 0 : _b.ackPendingProperties({
-                    type: merge_tree_1.MergeTreeDeltaType.ANNOTATE,
-                    props: (_c = serializedInterval.properties) !== null && _c !== void 0 ? _c : {},
-                });
-                this.ackInterval(interval, op);
-            }
+        }
+        // Note that the ID is in the property bag only to allow us to find the interval.
+        // This API cannot change the ID, and writing to the ID property will result in an exception. So we
+        // strip it out of the properties here.
+        const _e = (_a = serializedInterval.properties) !== null && _a !== void 0 ? _a : {}, _f = reservedIntervalIdKey, id = _e[_f], newProps = __rest(_e, [typeof _f === "symbol" ? _f : _f + ""]);
+        (0, common_utils_1.assert)(id !== undefined, 0x3fe /* id must exist on the interval */);
+        const interval = this.getIntervalById(id);
+        if (!interval) {
+            // The interval has been removed locally; no-op.
+            return;
+        }
+        if (local) {
+            // Let the propertyManager prune its pending change-properties set.
+            (_b = interval.propertyManager) === null || _b === void 0 ? void 0 : _b.ackPendingProperties({
+                type: merge_tree_1.MergeTreeDeltaType.ANNOTATE,
+                props: (_c = serializedInterval.properties) !== null && _c !== void 0 ? _c : {},
+            });
+            this.ackInterval(interval, op);
         }
         else {
             // If there are pending changes with this ID, don't apply the remote start/end change, as the local ack
             // should be the winning change.
-            // Note that the ID is in the property bag only to allow us to find the interval.
-            // This API cannot change the ID, and writing to the ID property will result in an exception. So we
-            // strip it out of the properties here.
-            const _e = serializedInterval.properties, _f = reservedIntervalIdKey, id = _e[_f], newProps = __rest(_e, [typeof _f === "symbol" ? _f : _f + ""]);
-            interval = this.getIntervalById(id);
-            if (interval) {
-                let start;
-                let end;
-                // Track pending start/end independently of one another.
-                if (!this.hasPendingChangeStart(id)) {
-                    start = serializedInterval.start;
-                }
-                if (!this.hasPendingChangeEnd(id)) {
-                    end = serializedInterval.end;
-                }
-                if (start !== undefined || end !== undefined) {
-                    // If changeInterval gives us a new interval, work with that one. Otherwise keep working with
-                    // the one we originally found in the tree.
-                    interval = (_d = this.localCollection.changeInterval(interval, start, end, op)) !== null && _d !== void 0 ? _d : interval;
-                }
-                const deltaProps = interval.addProperties(newProps, true, op.sequenceNumber);
-                if (this.onDeserialize) {
-                    this.onDeserialize(interval);
-                }
-                this.emit("propertyChanged", interval, deltaProps);
+            let start;
+            let end;
+            // Track pending start/end independently of one another.
+            if (!this.hasPendingChangeStart(id)) {
+                start = serializedInterval.start;
+            }
+            if (!this.hasPendingChangeEnd(id)) {
+                end = serializedInterval.end;
+            }
+            let newInterval = interval;
+            if (start !== undefined || end !== undefined) {
+                // If changeInterval gives us a new interval, work with that one. Otherwise keep working with
+                // the one we originally found in the tree.
+                newInterval = (_d = this.localCollection.changeInterval(interval, start, end, op)) !== null && _d !== void 0 ? _d : interval;
+            }
+            const deltaProps = newInterval.addProperties(newProps, true, op.sequenceNumber);
+            if (this.onDeserialize) {
+                this.onDeserialize(newInterval);
+            }
+            if (newInterval !== interval) {
+                this.emitChange(newInterval, interval, local, op);
+            }
+            const changedProperties = Object.keys(newProps).length > 0;
+            if (changedProperties) {
+                this.emit("propertyChanged", interval, deltaProps, local, op);
             }
-        }
-        if (interval) {
-            this.emit("changeInterval", interval, local, op);
         }
     }
     addConflictResolver(conflictResolver) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         this.localCollection.addConflictResolver(conflictResolver);
     }
     attachDeserializer(onDeserialize) {
+        var _a;
         // If no deserializer is specified can skip all processing work
         if (!onDeserialize) {
             return;
@@ -1058,7 +1249,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         // Start by storing the callbacks so that any subsequent modifications make use of them
         this.onDeserialize = onDeserialize;
         // Trigger the async prepare work across all values in the collection
-        this.localCollection.map((interval) => {
+        (_a = this.localCollection) === null || _a === void 0 ? void 0 : _a.map((interval) => {
             onDeserialize(interval);
         });
     }
@@ -1070,7 +1261,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
      * @internal
      */
     rebaseLocalInterval(opName, serializedInterval, localSeq) {
-        var _a, _b;
+        var _a, _b, _c, _d, _e, _f, _g;
         if (!this.client) {
             // If there's no associated mergeTree client, the originally submitted op is still correct.
             return serializedInterval;
@@ -1084,12 +1275,12 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         const endRebased = end === undefined ? undefined :
             this.client.rebasePosition(end, sequenceNumber, localSeq);
         const intervalId = properties === null || properties === void 0 ? void 0 : properties[reservedIntervalIdKey];
-        const localInterval = this.localCollection.getIntervalById(intervalId);
+        const localInterval = (_a = this.localCollection) === null || _a === void 0 ? void 0 : _a.getIntervalById(intervalId);
         const rebased = {
             start: startRebased,
             end: endRebased,
             intervalType,
-            sequenceNumber: (_b = (_a = this.client) === null || _a === void 0 ? void 0 : _a.getCurrentSeq()) !== null && _b !== void 0 ? _b : 0,
+            sequenceNumber: (_c = (_b = this.client) === null || _b === void 0 ? void 0 : _b.getCurrentSeq()) !== null && _c !== void 0 ? _c : 0,
             properties,
         };
         if (opName === "change" && (this.hasPendingChangeStart(intervalId) || this.hasPendingChangeEnd(intervalId))) {
@@ -1100,7 +1291,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         // delete the interval
         if (startRebased === merge_tree_1.DetachedReferencePosition || endRebased === merge_tree_1.DetachedReferencePosition) {
             if (localInterval) {
-                this.localCollection.removeExistingInterval(localInterval);
+                (_d = this.localCollection) === null || _d === void 0 ? void 0 : _d.removeExistingInterval(localInterval);
             }
             return undefined;
         }
@@ -1113,14 +1304,21 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         const endSegment = this.getSlideToSegment(localInterval.end);
         // we need to slide because the reference has been removed
         if (startSegment || endSegment) {
-            const newStart = startSegment && this.client.getPosition(startSegment.segment, localSeq) + startSegment.offset;
-            const newEnd = endSegment && this.client.getPosition(endSegment.segment, localSeq) + endSegment.offset;
-            this.localCollection.changeInterval(localInterval, newStart, newEnd, undefined, localSeq);
+            const newStart = startSegment && this.client.getPosition(startSegment.segment, localSeq) + ((_e = startSegment.offset) !== null && _e !== void 0 ? _e : 0);
+            const newEnd = endSegment && this.client.getPosition(endSegment.segment, localSeq) + ((_f = endSegment.offset) !== null && _f !== void 0 ? _f : 0);
+            (_g = this.localCollection) === null || _g === void 0 ? void 0 : _g.changeInterval(localInterval, newStart, newEnd, undefined, localSeq);
         }
         return rebased;
     }
     getSlideToSegment(lref) {
+        var _a, _b;
+        if (!this.client) {
+            throw new telemetry_utils_1.LoggingError("client does not exist");
+        }
         const segoff = { segment: lref.getSegment(), offset: lref.getOffset() };
+        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 value = (segoff.segment === newSegoff.segment && segoff.offset === newSegoff.offset) ? undefined : newSegoff;
         return value;
@@ -1132,6 +1330,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         lref.refType = refType;
     }
     ackInterval(interval, op) {
+        var _a, _b;
         // Only SequenceIntervals need potential sliding
         if (!(interval instanceof SequenceInterval)) {
             return;
@@ -1154,27 +1353,44 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         const needsStartUpdate = newStart !== undefined && !hasPendingStartChange;
         const needsEndUpdate = newEnd !== undefined && !hasPendingEndChange;
         if (needsStartUpdate || needsEndUpdate) {
+            if (!this.localCollection) {
+                throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
+            }
+            // `interval`'s endpoints will get modified in-place, so clone it prior to doing so for event emission.
+            const oldInterval = interval.clone();
             // In this case, where we change the start or end of an interval,
             // it is necessary to remove and re-add the interval listeners.
             // This ensures that the correct listeners are added to the LocalReferencePosition.
             this.localCollection.removeExistingInterval(interval);
+            if (!this.client) {
+                throw new telemetry_utils_1.LoggingError("client does not exist");
+            }
             if (needsStartUpdate) {
                 const props = interval.start.properties;
-                this.client.removeLocalReferencePosition(interval.start);
                 interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op);
                 if (props) {
                     interval.start.addProperties(props);
                 }
+                const oldSeg = oldInterval.start.getSegment();
+                // remove and rebuild start interval as transient for event
+                this.client.removeLocalReferencePosition(oldInterval.start);
+                oldInterval.start.refType = merge_tree_1.ReferenceType.Transient;
+                (_a = oldSeg === null || oldSeg === void 0 ? void 0 : oldSeg.localRefs) === null || _a === void 0 ? void 0 : _a.addLocalRef(oldInterval.start, oldInterval.start.getOffset());
             }
             if (needsEndUpdate) {
                 const props = interval.end.properties;
-                this.client.removeLocalReferencePosition(interval.end);
                 interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op);
                 if (props) {
                     interval.end.addProperties(props);
                 }
+                // remove and rebuild end interval as transient for event
+                const oldSeg = oldInterval.end.getSegment();
+                this.client.removeLocalReferencePosition(oldInterval.end);
+                oldInterval.end.refType = merge_tree_1.ReferenceType.Transient;
+                (_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);
         }
     }
     /** @internal */
@@ -1188,7 +1404,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
             }
             return;
         }
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         this.localCollection.ensureSerializedId(serializedInterval);
@@ -1209,7 +1425,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
             // locally deleted interval whenever a lookup happens.
             return;
         }
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attach must be called prior to deleting intervals");
         }
         const id = this.localCollection.ensureSerializedId(serializedInterval);
@@ -1222,57 +1438,87 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
      * @internal
      */
     serializeInternal() {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         return this.localCollection.serialize();
     }
+    /**
+     * @returns an iterator over all intervals in this collection.
+     */
     [Symbol.iterator]() {
         const iterator = new IntervalCollectionIterator(this);
         return iterator;
     }
+    /**
+     * @returns a forward iterator over all intervals in this collection with start point equal to `startPosition`.
+     */
     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`.
+     */
     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`.
+     */
     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`.
+     */
     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`.
+     */
     gatherIterationResults(results, iteratesForward, start, end) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             return;
         }
         this.localCollection.gatherIterationResults(results, iteratesForward, start, end);
     }
+    /**
+     * @returns an array of all intervals in this collection that overlap with the interval
+     * `[startPosition, endPosition]`.
+     */
     findOverlappingIntervals(startPosition, endPosition) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         return this.localCollection.findOverlappingIntervals(startPosition, endPosition);
     }
+    /**
+     * Applies a function to each interval in this collection.
+     */
     map(fn) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         this.localCollection.map(fn);
     }
     previousInterval(pos) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         return this.localCollection.previousInterval(pos);
     }
     nextInterval(pos) {
-        if (!this.attached) {
+        if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
         return this.localCollection.nextInterval(pos);