@fluidframework/sequence 2.0.0-dev.3.1.0.125672 → 2.0.0-dev.4.2.0.153917

package/lib/intervalCollection.js

@@ -84,9 +84,7 @@ export class Interval {
     getIntervalId() {
         var _a;
         const id = (_a = this.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
-        if (id === undefined) {
-            return undefined;
-        }
+        assert(id !== undefined, 0x5e1 /* interval ID should not be undefined */);
         return `${id}`;
     }
     /**
@@ -179,6 +177,7 @@ export class Interval {
     }
     /**
      * {@inheritDoc IInterval.union}
+     * @deprecated - This API was never intended to be public and will be marked internal in a future release.
      */
     union(b) {
         return new Interval(Math.min(this.start, b.start), Math.max(this.end, b.end), this.properties);
@@ -188,6 +187,7 @@ export class Interval {
     }
     /**
      * {@inheritDoc ISerializableInterval.addProperties}
+     * @deprecated - This API was never intended to be public and will be marked internal in a future release.
      */
     addProperties(newProps, collaborating = false, seq, op) {
         if (newProps) {
@@ -197,6 +197,7 @@ export class Interval {
     }
     /**
      * {@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) {
         const startPos = start !== null && start !== void 0 ? start : this.start;
@@ -225,6 +226,22 @@ export class 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.
  */
 export class SequenceInterval {
     constructor(client, 
@@ -353,19 +370,19 @@ export class SequenceInterval {
     getIntervalId() {
         var _a;
         const id = (_a = this.properties) === null || _a === void 0 ? void 0 : _a[reservedIntervalIdKey];
-        if (id === undefined) {
-            return undefined;
-        }
+        assert(id !== undefined, 0x5e2 /* interval ID should not be undefined */);
         return `${id}`;
     }
     /**
      * {@inheritDoc IInterval.union}
+     * @deprecated - This API was never intended to be public and will be marked internal in a future release.
      */
     union(b) {
         return new SequenceInterval(this.client, minReferencePosition(this.start, b.start), maxReferencePosition(this.end, b.end), this.intervalType);
     }
     /**
      * {@inheritDoc ISerializableInterval.addProperties}
+     * @deprecated - This API was never intended to be public and will be marked internal in a future release.
      */
     addProperties(newProps, collab = false, seq, op) {
         this.initializeProperties();
@@ -373,7 +390,6 @@ export 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);
@@ -382,6 +398,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) {
         const getRefType = (baseType) => {
@@ -422,7 +439,7 @@ export class 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;
@@ -432,7 +449,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 && !refTypeIncludesFlag(refType, ReferenceType.Transient)) {
+    if (!op &&
+        !localSeq &&
+        !fromSnapshot &&
+        !refTypeIncludesFlag(refType, ReferenceType.Transient)) {
         throw new UsageError("Non-transient references need segment");
     }
     return createDetachedLocalReferencePosition(refType);
@@ -451,7 +471,7 @@ function createPositionReference(client, pos, refType, op, fromSnapshot, localSe
         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);
+    return createPositionReferenceFromSegoff(client, segoff, refType, op, localSeq, fromSnapshot);
 }
 export function createSequenceInterval(label, start, end, client, intervalType, op, fromSnapshot) {
     let beginRefType = ReferenceType.RangeBegin;
@@ -629,7 +649,7 @@ export 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()) {
@@ -1039,11 +1059,13 @@ export class IntervalCollection extends TypedEventEmitter {
     }
     /**
      * 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;
@@ -1287,6 +1309,13 @@ export class IntervalCollection extends TypedEventEmitter {
             }
         }
     }
+    /**
+     * @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(conflictResolver) {
         if (!this.localCollection) {
             throw new LoggingError("attachSequence must be called");