@fluidframework/sequence 2.0.0-dev.4.1.0.148229 → 2.0.0-dev.4.3.0.157531

package/dist/intervalCollection.js

@@ -15,7 +15,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.intervalLocatorFromEndpoint = exports.IntervalCollection = exports.IntervalCollectionIterator = exports.makeOpsMap = exports.IntervalCollectionValueType = exports.SequenceIntervalCollectionValueType = exports.compareSequenceIntervalEnds = exports.LocalIntervalCollection = exports.createIntervalIndex = 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");
@@ -87,9 +87,7 @@ class Interval {
     getIntervalId() {
         var _a;
         const id = (_a = this.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
-        if (id === undefined) {
-            return undefined;
-        }
+        (0, common_utils_1.assert)(id !== undefined, 0x5e1 /* interval ID should not be undefined */);
         return `${id}`;
     }
     /**
@@ -232,6 +230,22 @@ 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.
+ *
+ * @remarks - The endpoint's position should be treated exclusively to get reasonable behavior--i.e.
+ * an interval referring to "hello" in "hello world" should have a start position of 0 and an end
+ * position of 5.
+ *
+ * To see why, consider what happens if "llo wor" is removed from the string to make "held".
+ * The interval's startpoint remains on the "h" (it isn't altered), but the interval's endpoint
+ * slides forward to the next unremoved position, which is the "l" in "held".
+ * Users would generally expect the interval to now refer to "he" (as it is the subset of content
+ * remaining after the removal), hence the "l" should be excluded.
+ * If the interval endpoint was treated inclusively, the interval would now refer to "hel", which
+ * is undesirable.
+ *
+ * Since the end of an interval is treated exclusively but cannot be greater than or equal to the
+ * length of the associated sequence, application models which leverage interval collections should
+ * consider inserting a marker at the end of the sequence to represent the end of the content.
  */
 class SequenceInterval {
     constructor(client, 
@@ -360,9 +374,7 @@ class SequenceInterval {
     getIntervalId() {
         var _a;
         const id = (_a = this.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
-        if (id === undefined) {
-            return undefined;
-        }
+        (0, common_utils_1.assert)(id !== undefined, 0x5e2 /* interval ID should not be undefined */);
         return `${id}`;
     }
     /**
@@ -382,7 +394,6 @@ class SequenceInterval {
     }
     /**
      * @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);
@@ -433,7 +444,7 @@ class SequenceInterval {
     }
 }
 exports.SequenceInterval = SequenceInterval;
-function createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq) {
+function createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot) {
     if (segoff.segment) {
         const ref = client.createLocalReferencePosition(segoff.segment, segoff.offset, refType, undefined);
         return ref;
@@ -443,7 +454,10 @@ function createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq
     // - References coming from a remote client (location may have been concurrently removed)
     // - References being rebased to a new sequence number
     //   (segment they originally referred to may have been removed with no suitable replacement)
-    if (!op && !localSeq && !(0, merge_tree_1.refTypeIncludesFlag)(refType, merge_tree_1.ReferenceType.Transient)) {
+    if (!op &&
+        !localSeq &&
+        !fromSnapshot &&
+        !(0, merge_tree_1.refTypeIncludesFlag)(refType, merge_tree_1.ReferenceType.Transient)) {
         throw new container_utils_1.UsageError("Non-transient references need segment");
     }
     return (0, merge_tree_1.createDetachedLocalReferencePosition)(refType);
@@ -462,7 +476,7 @@ function createPositionReference(client, pos, refType, op, fromSnapshot, localSe
         (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, localSeq);
+    return createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot);
 }
 function createSequenceInterval(label, start, end, client, intervalType, op, fromSnapshot) {
     let beginRefType = merge_tree_1.ReferenceType.RangeBegin;
@@ -499,84 +513,24 @@ function createSequenceInterval(label, start, end, client, intervalType, op, fro
     return ival;
 }
 exports.createSequenceInterval = createSequenceInterval;
-function defaultIntervalConflictResolver(a, b) {
-    a.addPropertySet(b.properties);
-    return a;
-}
-exports.defaultIntervalConflictResolver = defaultIntervalConflictResolver;
-function createIntervalIndex(conflict) {
+function createIntervalIndex() {
     const helpers = {
         compareEnds: compareIntervalEnds,
         create: createInterval,
     };
     const lc = new LocalIntervalCollection(undefined, "", helpers);
-    if (conflict) {
-        lc.addConflictResolver(conflict);
-    }
-    else {
-        lc.addConflictResolver(defaultIntervalConflictResolver);
-    }
     return lc;
 }
 exports.createIntervalIndex = createIntervalIndex;
-class LocalIntervalCollection {
-    constructor(client, label, helpers, 
-    /** Callback invoked each time one of the endpoints of an interval slides. */
-    onPositionChange) {
+class OverlappingIntervalsIndex {
+    constructor(client, helpers) {
         this.client = client;
-        this.label = label;
         this.helpers = helpers;
-        this.onPositionChange = onPositionChange;
         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);
-    }
-    addConflictResolver(conflictResolver) {
-        this.conflictResolver = conflictResolver;
-        this.endConflictResolver = (key, currentKey) => {
-            const ival = conflictResolver(key, currentKey);
-            return {
-                data: ival,
-                key: ival,
-            };
-        };
     }
     map(fn) {
         this.intervalTree.map(fn);
     }
-    createLegacyId(start, end) {
-        // Create a non-unique ID based on start and end to be used on intervals that come from legacy clients
-        // without ID's.
-        return `${LocalIntervalCollection.legacyIdPrefix}${start}-${end}`;
-    }
-    /**
-     * Validates that a serialized interval has the ID property. Creates an ID
-     * if one does not already exist
-     *
-     * @param serializedInterval - The interval to be checked
-     * @returns The interval's existing or newly created id
-     */
-    ensureSerializedId(serializedInterval) {
-        var _a;
-        let id = (_a = serializedInterval.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
-        if (id === undefined) {
-            // An interval came over the wire without an ID, so create a non-unique one based on start/end.
-            // This will allow all clients to refer to this interval consistently.
-            id = this.createLegacyId(serializedInterval.start, serializedInterval.end);
-            const newProps = {
-                [reservedIntervalIdKey]: id,
-            };
-            serializedInterval.properties = (0, merge_tree_1.addProperties)(serializedInterval.properties, newProps);
-        }
-        // Make the ID immutable for safety's sake.
-        Object.defineProperty(serializedInterval.properties, reservedIntervalIdKey, {
-            configurable: false,
-            enumerable: true,
-            writable: false,
-        });
-        return id;
-    }
     mapUntil(fn) {
         this.intervalTree.mapUntil(fn);
     }
@@ -643,7 +597,7 @@ class LocalIntervalCollection {
     }
     /**
      * @returns an array of all intervals contained in this collection that overlap the range
-     * `[startPosition, endPosition]`.
+     * `[startPosition, endPosition)`.
      */
     findOverlappingIntervals(startPosition, endPosition) {
         if (endPosition < startPosition || this.intervalTree.intervals.isEmpty()) {
@@ -653,6 +607,47 @@ class LocalIntervalCollection {
         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();
+    }
+    add(interval) {
+        const id = interval.getIntervalId();
+        (0, common_utils_1.assert)(id !== undefined, 0x2c0 /* "ID must be created before adding interval to collection" */);
+        // Make the ID immutable.
+        Object.defineProperty(interval.properties, reservedIntervalIdKey, {
+            configurable: false,
+            enumerable: true,
+            writable: false,
+        });
+        this.intervalIdMap.set(id, interval);
+    }
+    remove(interval) {
+        const id = interval.getIntervalId();
+        (0, common_utils_1.assert)(id !== undefined, 0x311 /* expected id to exist on interval */);
+        this.intervalIdMap.delete(id);
+    }
+    getIntervalById(id) {
+        return this.intervalIdMap.get(id);
+    }
+    [Symbol.iterator]() {
+        return this.intervalIdMap.values();
+    }
+}
+class EndpointIndex {
+    constructor(client, helpers) {
+        this.client = client;
+        this.helpers = helpers;
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        this.endIntervalTree = new merge_tree_1.RedBlackTree(helpers.compareEnds);
+    }
     previousInterval(pos) {
         const transientInterval = this.helpers.create("transient", pos, pos, this.client, IntervalType.Transient);
         const rbNode = this.endIntervalTree.floor(transientInterval);
@@ -667,21 +662,70 @@ class LocalIntervalCollection {
             return rbNode.data;
         }
     }
-    removeInterval(startPosition, endPosition) {
-        const transientInterval = this.helpers.create("transient", startPosition, endPosition, this.client, IntervalType.Transient);
-        this.intervalTree.remove(transientInterval);
-        this.endIntervalTree.remove(transientInterval);
-        return transientInterval;
+    add(interval) {
+        this.endIntervalTree.put(interval, interval);
     }
-    removeIntervalFromIndex(interval) {
-        this.intervalTree.removeExisting(interval);
+    remove(interval) {
         this.endIntervalTree.remove(interval);
-        const id = interval.getIntervalId();
-        (0, common_utils_1.assert)(id !== undefined, 0x311 /* expected id to exist on interval */);
-        this.intervalIdMap.delete(id);
+    }
+}
+class LocalIntervalCollection {
+    constructor(client, label, helpers, 
+    /** Callback invoked each time one of the endpoints of an interval slides. */
+    onPositionChange) {
+        this.client = client;
+        this.label = label;
+        this.helpers = helpers;
+        this.onPositionChange = onPositionChange;
+        this.overlappingIntervalsIndex = new OverlappingIntervalsIndex(client, helpers);
+        this.idIntervalIndex = new IdIntervalIndex();
+        this.endIntervalIndex = new EndpointIndex(client, helpers);
+        this.indexes = [
+            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
+        // without ID's.
+        return `${LocalIntervalCollection.legacyIdPrefix}${start}-${end}`;
+    }
+    /**
+     * Validates that a serialized interval has the ID property. Creates an ID
+     * if one does not already exist
+     *
+     * @param serializedInterval - The interval to be checked
+     * @returns The interval's existing or newly created id
+     */
+    ensureSerializedId(serializedInterval) {
+        var _a;
+        let id = (_a = serializedInterval.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
+        if (id === undefined) {
+            // Back-compat: 0.39 and earlier did not have IDs on intervals. If an interval from such a client
+            // comes over the wire, create a non-unique one based on start/end.
+            // This will allow all clients to refer to this interval consistently.
+            id = this.createLegacyId(serializedInterval.start, serializedInterval.end);
+            const newProps = {
+                [reservedIntervalIdKey]: id,
+            };
+            serializedInterval.properties = (0, merge_tree_1.addProperties)(serializedInterval.properties, newProps);
+        }
+        // Make the ID immutable for safety's sake.
+        Object.defineProperty(serializedInterval.properties, reservedIntervalIdKey, {
+            configurable: false,
+            enumerable: true,
+            writable: false,
+        });
+        return id;
+    }
+    removeIntervalFromIndexes(interval) {
+        for (const index of this.indexes) {
+            index.remove(interval);
+        }
     }
     removeExistingInterval(interval) {
-        this.removeIntervalFromIndex(interval);
+        this.removeIntervalFromIndexes(interval);
         this.removeIntervalListeners(interval);
     }
     createInterval(start, end, intervalType, op) {
@@ -709,27 +753,16 @@ class LocalIntervalCollection {
             interval.end.addProperties({ interval });
         }
     }
-    addIntervalToIndex(interval) {
-        const id = interval.getIntervalId();
-        (0, common_utils_1.assert)(id !== undefined, 0x2c0 /* "ID must be created before adding interval to collection" */);
-        // Make the ID immutable.
-        Object.defineProperty(interval.properties, reservedIntervalIdKey, {
-            configurable: false,
-            enumerable: true,
-            writable: false,
-        });
-        this.intervalTree.put(interval, this.conflictResolver);
-        this.endIntervalTree.put(interval, interval, this.endConflictResolver);
-        this.intervalIdMap.set(id, interval);
+    addIntervalToIndexes(interval) {
+        for (const index of this.indexes) {
+            index.add(interval);
+        }
     }
     add(interval) {
         this.linkEndpointsToInterval(interval);
-        this.addIntervalToIndex(interval);
+        this.addIntervalToIndexes(interval);
         this.addIntervalListeners(interval);
     }
-    getIntervalById(id) {
-        return this.intervalIdMap.get(id);
-    }
     changeInterval(interval, start, end, op, localSeq) {
         const newInterval = interval.modify(this.label, start, end, op, localSeq);
         if (newInterval) {
@@ -739,10 +772,9 @@ class LocalIntervalCollection {
         return newInterval;
     }
     serialize() {
-        const intervals = this.intervalTree.intervals.keys();
         return {
             label: this.label,
-            intervals: intervals.map((interval) => compressInterval(interval.serialize())),
+            intervals: Array.from(this.idIntervalIndex, (interval) => compressInterval(interval.serialize())),
             version: 2,
         };
     }
@@ -767,14 +799,14 @@ class LocalIntervalCollection {
                     previousInterval = interval.clone();
                     previousInterval.start = cloneRef(previousInterval.start);
                     previousInterval.end = cloneRef(previousInterval.end);
-                    this.removeIntervalFromIndex(interval);
+                    this.removeIntervalFromIndexes(interval);
                 }
             }, () => {
                 var _a;
                 (0, common_utils_1.assert)(previousInterval !== undefined, 0x3fa /* Invalid interleaving of before/after slide */);
                 pendingChanges--;
                 if (pendingChanges === 0) {
-                    this.addIntervalToIndex(interval);
+                    this.addIntervalToIndexes(interval);
                     (_a = this.onPositionChange) === null || _a === void 0 ? void 0 : _a.call(this, interval, previousInterval);
                     previousInterval = undefined;
                 }
@@ -1055,15 +1087,17 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attach must be called before accessing intervals");
         }
-        return this.localCollection.getIntervalById(id);
+        return this.localCollection.idIntervalIndex.getIntervalById(id);
     }
     /**
      * Creates a new interval and add it to the collection.
-     * @param start - interval start position
-     * @param end - interval end position
+     * @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.
      */
     add(start, end, intervalType, props) {
         var _a, _b;
@@ -1120,7 +1154,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("Attach must be called before accessing intervals");
         }
-        const interval = this.localCollection.getIntervalById(id);
+        const interval = this.localCollection.idIntervalIndex.getIntervalById(id);
         if (interval) {
             this.deleteExistingInterval(interval, true, undefined);
         }
@@ -1307,14 +1341,19 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
             }
         }
     }
-    addConflictResolver(conflictResolver) {
+    /**
+     * @deprecated - This functionality was useful when adding two intervals at the same start/end positions resulted
+     * in a conflict. This is no longer the case (as of PR#6407), as interval collections support multiple intervals
+     * at the same location and gives each interval a unique id.
+     *
+     * As such, the conflict resolver is never invoked and unnecessary. This API will be removed in an upcoming release.
+     */
+    addConflictResolver(_) {
         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;
@@ -1322,9 +1361,9 @@ 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
-        (_a = this.localCollection) === null || _a === void 0 ? void 0 : _a.map((interval) => {
-            onDeserialize(interval);
-        });
+        if (this.attached) {
+            this.map(onDeserialize);
+        }
     }
     /**
      * Returns new interval after rebasing. If undefined, the interval was
@@ -1345,7 +1384,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         const { intervalType, properties } = serializedInterval;
         const { start: startRebased, end: endRebased } = (_a = this.localSeqToRebasedInterval.get(localSeq)) !== null && _a !== void 0 ? _a : this.computeRebasedPositions(localSeq);
         const intervalId = properties === null || properties === void 0 ? void 0 : properties[reservedIntervalIdKey];
-        const localInterval = (_b = this.localCollection) === null || _b === void 0 ? void 0 : _b.getIntervalById(intervalId);
+        const localInterval = (_b = this.localCollection) === null || _b === void 0 ? void 0 : _b.idIntervalIndex.getIntervalById(intervalId);
         const rebased = {
             start: startRebased,
             end: endRebased,
@@ -1498,7 +1537,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
             throw new telemetry_utils_1.LoggingError("attach must be called prior to deleting intervals");
         }
         const id = this.localCollection.ensureSerializedId(serializedInterval);
-        const interval = this.localCollection.getIntervalById(id);
+        const interval = this.localCollection.idIntervalIndex.getIntervalById(id);
         if (interval) {
             this.deleteExistingInterval(interval, local, op);
         }
@@ -1559,7 +1598,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         if (!this.localCollection) {
             return;
         }
-        this.localCollection.gatherIterationResults(results, iteratesForward, start, end);
+        this.localCollection.overlappingIntervalsIndex.gatherIterationResults(results, iteratesForward, start, end);
     }
     /**
      * @returns an array of all intervals in this collection that overlap with the interval
@@ -1569,7 +1608,7 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
-        return this.localCollection.findOverlappingIntervals(startPosition, endPosition);
+        return this.localCollection.overlappingIntervalsIndex.findOverlappingIntervals(startPosition, endPosition);
     }
     /**
      * Applies a function to each interval in this collection.
@@ -1578,19 +1617,21 @@ class IntervalCollection extends common_utils_1.TypedEventEmitter {
         if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
-        this.localCollection.map(fn);
+        for (const interval of this.localCollection.idIntervalIndex) {
+            fn(interval);
+        }
     }
     previousInterval(pos) {
         if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
-        return this.localCollection.previousInterval(pos);
+        return this.localCollection.endIntervalIndex.previousInterval(pos);
     }
     nextInterval(pos) {
         if (!this.localCollection) {
             throw new telemetry_utils_1.LoggingError("attachSequence must be called");
         }
-        return this.localCollection.nextInterval(pos);
+        return this.localCollection.endIntervalIndex.nextInterval(pos);
     }
 }
 exports.IntervalCollection = IntervalCollection;