@fluidframework/sequence 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

package/lib/intervalCollection.mjs

@@ -0,0 +1,1144 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import { assert } from "@fluidframework/core-utils";
+import { addProperties, createMap, getSlideToSegoff, MergeTreeDeltaType, ReferenceType, refTypeIncludesFlag, reservedRangeLabelsKey, UnassignedSequenceNumber, DetachedReferencePosition, UniversalSequenceNumber, SlidingPreference, } from "@fluidframework/merge-tree";
+import { LoggingError, UsageError } from "@fluidframework/telemetry-utils";
+import { v4 as uuid } from "uuid";
+import { IntervalOpType, IntervalStickiness, IntervalType, SequenceInterval, createPositionReferenceFromSegoff, endReferenceSlidingPreference, startReferenceSlidingPreference, sequenceIntervalHelpers, createInterval, } from "./intervals/index.mjs";
+import { EndpointIndex, OverlappingIntervalsIndex, createIdIntervalIndex, } from "./intervalIndex/index.mjs";
+/**
+ * Defines a side relative to a character in a sequence.
+ *
+ * @remarks See {@link SequencePlace} for additional context on usage.
+ * @alpha
+ */
+export var Side;
+(function (Side) {
+    Side[Side["Before"] = 0] = "Before";
+    Side[Side["After"] = 1] = "After";
+})(Side || (Side = {}));
+const reservedIntervalIdKey = "intervalId";
+export function sidesFromStickiness(stickiness) {
+    const startSide = (stickiness & IntervalStickiness.START) !== 0 ? Side.After : Side.Before;
+    const endSide = (stickiness & IntervalStickiness.END) !== 0 ? Side.Before : Side.After;
+    return { startSide, endSide };
+}
+/**
+ * Decompress an interval after loading a summary from JSON. The exact format
+ * of this compression is unspecified and subject to change
+ */
+function decompressInterval(interval, label) {
+    const stickiness = interval[5] ?? IntervalStickiness.END;
+    const { startSide, endSide } = sidesFromStickiness(stickiness);
+    return {
+        start: interval[0],
+        end: interval[1],
+        sequenceNumber: interval[2],
+        intervalType: interval[3],
+        properties: { ...interval[4], [reservedRangeLabelsKey]: [label] },
+        stickiness,
+        startSide,
+        endSide,
+    };
+}
+/**
+ * Compress an interval prior to serialization as JSON. The exact format of this
+ * compression is unspecified and subject to change
+ */
+function compressInterval(interval) {
+    const { start, end, sequenceNumber, intervalType, properties } = interval;
+    let base = [
+        start,
+        end,
+        sequenceNumber,
+        intervalType,
+        // remove the `referenceRangeLabels` property as it is already stored
+        // in the `label` field of the summary
+        { ...properties, [reservedRangeLabelsKey]: undefined },
+    ];
+    if (interval.stickiness !== undefined && interval.stickiness !== IntervalStickiness.END) {
+        // reassignment to make it easier for typescript to reason about types
+        base = [...base, interval.stickiness];
+    }
+    return base;
+}
+export function endpointPosAndSide(start, end) {
+    const startIsPlainEndpoint = typeof start === "number" || start === "start" || start === "end";
+    const endIsPlainEndpoint = typeof end === "number" || end === "start" || end === "end";
+    const startSide = startIsPlainEndpoint ? Side.Before : start?.side;
+    const endSide = endIsPlainEndpoint ? Side.Before : end?.side;
+    const startPos = startIsPlainEndpoint ? start : start?.pos;
+    const endPos = endIsPlainEndpoint ? end : end?.pos;
+    return {
+        startSide,
+        endSide,
+        startPos,
+        endPos,
+    };
+}
+function toSequencePlace(pos, side) {
+    return typeof pos === "number" ? { pos, side } : pos;
+}
+function toOptionalSequencePlace(pos, side = Side.Before) {
+    return typeof pos === "number" ? { pos, side } : pos;
+}
+export function computeStickinessFromSide(startPos = -1, startSide = Side.Before, endPos = -1, endSide = Side.Before) {
+    let stickiness = IntervalStickiness.NONE;
+    if (startSide === Side.After || startPos === "start") {
+        stickiness |= IntervalStickiness.START;
+    }
+    if (endSide === Side.Before || endPos === "end") {
+        stickiness |= IntervalStickiness.END;
+    }
+    return stickiness;
+}
+export function createIntervalIndex() {
+    const helpers = {
+        create: createInterval,
+    };
+    const lc = new LocalIntervalCollection(undefined, "", helpers, {});
+    return lc;
+}
+export class LocalIntervalCollection {
+    constructor(client, label, helpers, options, 
+    /** Callback invoked each time one of the endpoints of an interval slides. */
+    onPositionChange) {
+        this.client = client;
+        this.label = label;
+        this.helpers = helpers;
+        this.options = options;
+        this.onPositionChange = onPositionChange;
+        this.overlappingIntervalsIndex = new OverlappingIntervalsIndex(client, helpers);
+        this.idIntervalIndex = createIdIntervalIndex();
+        this.endIntervalIndex = new EndpointIndex(client, helpers);
+        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
+        // 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) {
+        let id = serializedInterval.properties?.[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 = 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);
+        }
+    }
+    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, undefined, this.options.mergeTreeReferencesCanSlideToEndpoint);
+    }
+    addInterval(start, end, intervalType, props, op) {
+        var _a;
+        const interval = this.createInterval(start, end, intervalType, op);
+        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 = interval.properties)[reservedIntervalIdKey] ?? (_a[reservedIntervalIdKey] = uuid());
+            this.add(interval);
+        }
+        return interval;
+    }
+    linkEndpointsToInterval(interval) {
+        if (interval instanceof SequenceInterval) {
+            interval.start.addProperties({ interval });
+            interval.end.addProperties({ interval });
+        }
+    }
+    addIntervalToIndexes(interval) {
+        for (const index of this.indexes) {
+            index.add(interval);
+        }
+    }
+    add(interval) {
+        this.linkEndpointsToInterval(interval);
+        this.addIntervalToIndexes(interval);
+        this.addIntervalListeners(interval);
+    }
+    changeInterval(interval, start, end, op, localSeq) {
+        const newInterval = interval.modify(this.label, start, end, op, localSeq, this.options.mergeTreeReferencesCanSlideToEndpoint);
+        if (newInterval) {
+            this.removeExistingInterval(interval);
+            this.add(newInterval);
+        }
+        return newInterval;
+    }
+    serialize() {
+        return {
+            label: this.label,
+            intervals: Array.from(this.idIntervalIndex, (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(), ReferenceType.Transient, ref.properties, ref.slidingPreference, ref.canSlideToEndpoint);
+        };
+        if (interval instanceof SequenceInterval) {
+            let previousInterval;
+            let pendingChanges = 0;
+            interval.addPositionChangeListeners(() => {
+                pendingChanges++;
+                // Note: both start and end can change and invoke beforeSlide on each endpoint before afterSlide.
+                if (!previousInterval) {
+                    previousInterval = interval.clone();
+                    previousInterval.start = cloneRef(previousInterval.start);
+                    previousInterval.end = cloneRef(previousInterval.end);
+                    this.removeIntervalFromIndexes(interval);
+                }
+            }, () => {
+                assert(previousInterval !== undefined, 0x3fa /* Invalid interleaving of before/after slide */);
+                pendingChanges--;
+                if (pendingChanges === 0) {
+                    this.addIntervalToIndexes(interval);
+                    this.onPositionChange?.(interval, previousInterval);
+                    previousInterval = undefined;
+                }
+            });
+        }
+    }
+    removeIntervalListeners(interval) {
+        if (interval instanceof SequenceInterval) {
+            interval.removePositionChangeListeners();
+        }
+    }
+}
+LocalIntervalCollection.legacyIdPrefix = "legacy";
+class SequenceIntervalCollectionFactory {
+    load(emitter, raw = [], options) {
+        return new IntervalCollection(sequenceIntervalHelpers, true, emitter, raw, options);
+    }
+    store(value) {
+        return value.serializeInternal();
+    }
+}
+export class SequenceIntervalCollectionValueType {
+    get name() {
+        return SequenceIntervalCollectionValueType.Name;
+    }
+    get factory() {
+        return SequenceIntervalCollectionValueType._factory;
+    }
+    get ops() {
+        return SequenceIntervalCollectionValueType._ops;
+    }
+}
+SequenceIntervalCollectionValueType.Name = "sharedStringIntervalCollection";
+SequenceIntervalCollectionValueType._factory = new SequenceIntervalCollectionFactory();
+SequenceIntervalCollectionValueType._ops = makeOpsMap();
+class IntervalCollectionFactory {
+    load(emitter, raw = [], options) {
+        const helpers = {
+            create: createInterval,
+        };
+        const collection = new IntervalCollection(helpers, false, emitter, raw, options);
+        collection.attachGraph(undefined, "");
+        return collection;
+    }
+    store(value) {
+        return value.serializeInternal();
+    }
+}
+export class IntervalCollectionValueType {
+    get name() {
+        return IntervalCollectionValueType.Name;
+    }
+    get factory() {
+        return IntervalCollectionValueType._factory;
+    }
+    get ops() {
+        return IntervalCollectionValueType._ops;
+    }
+}
+IntervalCollectionValueType.Name = "sharedIntervalCollection";
+IntervalCollectionValueType._factory = new IntervalCollectionFactory();
+IntervalCollectionValueType._ops = makeOpsMap();
+export function makeOpsMap() {
+    const rebase = (collection, op, localOpMetadata) => {
+        const { localSeq } = localOpMetadata;
+        const rebasedValue = collection.rebaseLocalInterval(op.opName, op.value, localSeq);
+        if (rebasedValue === undefined) {
+            return undefined;
+        }
+        const rebasedOp = { ...op, value: rebasedValue };
+        return { rebasedOp, rebasedLocalOpMetadata: localOpMetadata };
+    };
+    return new Map([
+        [
+            IntervalOpType.ADD,
+            {
+                process: (collection, params, local, op, localOpMetadata) => {
+                    // if params is undefined, the interval was deleted during
+                    // rebasing
+                    if (!params) {
+                        return;
+                    }
+                    assert(op !== undefined, 0x3fb /* op should exist here */);
+                    collection.ackAdd(params, local, op, localOpMetadata);
+                },
+                rebase,
+            },
+        ],
+        [
+            IntervalOpType.DELETE,
+            {
+                process: (collection, params, local, op) => {
+                    assert(op !== undefined, 0x3fc /* op should exist here */);
+                    collection.ackDelete(params, local, op);
+                },
+                rebase: (collection, op, localOpMetadata) => {
+                    // Deletion of intervals is based on id, so requires no rebasing.
+                    return { rebasedOp: op, rebasedLocalOpMetadata: localOpMetadata };
+                },
+            },
+        ],
+        [
+            IntervalOpType.CHANGE,
+            {
+                process: (collection, params, local, op, localOpMetadata) => {
+                    // if params is undefined, the interval was deleted during
+                    // rebasing
+                    if (!params) {
+                        return;
+                    }
+                    assert(op !== undefined, 0x3fd /* op should exist here */);
+                    collection.ackChange(params, local, op, localOpMetadata);
+                },
+                rebase,
+            },
+        ],
+    ]);
+}
+class IntervalCollectionIterator {
+    constructor(collection, iteratesForward = true, start, end) {
+        this.results = [];
+        this.index = 0;
+        collection.gatherIterationResults(this.results, iteratesForward, start, end);
+    }
+    next() {
+        if (this.index < this.results.length) {
+            return {
+                value: this.results[this.index++],
+                done: false,
+            };
+        }
+        return {
+            value: undefined,
+            done: true,
+        };
+    }
+}
+// solely for type checking in the implementation of add - will be removed once
+// deprecated signatures are removed
+const isSequencePlace = (place) => {
+    return typeof place === "number" || typeof place === "string" || place.pos !== undefined;
+};
+/**
+ * {@inheritdoc IIntervalCollection}
+ */
+export class IntervalCollection extends TypedEventEmitter {
+    get attached() {
+        return !!this.localCollection;
+    }
+    /** @internal */
+    constructor(helpers, requiresClient, emitter, serializedIntervals, options = {}) {
+        super();
+        this.helpers = helpers;
+        this.requiresClient = requiresClient;
+        this.emitter = emitter;
+        this.options = options;
+        this.localSeqToSerializedInterval = new Map();
+        this.localSeqToRebasedInterval = new Map();
+        this.pendingChangesStart = new Map();
+        this.pendingChangesEnd = new Map();
+        this.savedSerializedIntervals = Array.isArray(serializedIntervals)
+            ? serializedIntervals
+            : serializedIntervals.intervals.map((i) => decompressInterval(i, serializedIntervals.label));
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.attachIndex}
+     */
+    attachIndex(index) {
+        if (!this.attached) {
+            throw new LoggingError("The local interval collection must exist");
+        }
+        for (const interval of this) {
+            index.add(interval);
+        }
+        this.localCollection?.appendIndex(index);
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.detachIndex}
+     */
+    detachIndex(index) {
+        if (!this.attached) {
+            throw new LoggingError("The local interval collection must exist");
+        }
+        // Avoid removing intervals if the index does not exist
+        if (!this.localCollection?.removeIndex(index)) {
+            return false;
+        }
+        for (const interval of this) {
+            index.remove(interval);
+        }
+        return true;
+    }
+    rebasePositionWithSegmentSlide(pos, seqNumberFrom, localSeq) {
+        if (!this.client) {
+            throw new LoggingError("mergeTree client must exist");
+        }
+        if (pos === "start" || pos === "end") {
+            return pos;
+        }
+        const { clientId } = this.client.getCollabWindow();
+        const { segment, offset } = this.client.getContainingSegment(pos, {
+            referenceSequenceNumber: seqNumberFrom,
+            clientId: this.client.getLongClientId(clientId),
+        }, localSeq);
+        // if segment is undefined, it slid off the string
+        assert(segment !== undefined, 0x54e /* No segment found */);
+        const segoff = getSlideToSegoff({ segment, offset }, undefined, this.options.mergeTreeReferencesCanSlideToEndpoint) ?? segment;
+        // case happens when rebasing op, but concurrently entire string has been deleted
+        if (segoff.segment === undefined || segoff.offset === undefined) {
+            return DetachedReferencePosition;
+        }
+        assert(offset !== undefined && 0 <= offset && offset < segment.cachedLength, 0x54f /* Invalid offset */);
+        return this.client.findReconnectionPosition(segoff.segment, localSeq) + segoff.offset;
+    }
+    computeRebasedPositions(localSeq) {
+        assert(this.client !== undefined, 0x550 /* Client should be defined when computing rebased position */);
+        const original = this.localSeqToSerializedInterval.get(localSeq);
+        assert(original !== undefined, 0x551 /* Failed to store pending serialized interval info for this localSeq. */);
+        const rebased = { ...original };
+        const { start, end, sequenceNumber } = original;
+        if (start !== undefined) {
+            rebased.start = this.rebasePositionWithSegmentSlide(start, sequenceNumber, localSeq);
+        }
+        if (end !== undefined) {
+            rebased.end = this.rebasePositionWithSegmentSlide(end, sequenceNumber, localSeq);
+        }
+        return rebased;
+    }
+    /** @internal */
+    attachGraph(client, label) {
+        if (this.attached) {
+            throw new LoggingError("Only supports one Sequence attach");
+        }
+        if (client === undefined && this.requiresClient) {
+            throw new LoggingError("Client required for this collection");
+        }
+        // Instantiate the local interval collection based on the saved intervals
+        this.client = client;
+        if (client) {
+            client.on("normalize", () => {
+                for (const localSeq of this.localSeqToSerializedInterval.keys()) {
+                    this.localSeqToRebasedInterval.set(localSeq, this.computeRebasedPositions(localSeq));
+                }
+            });
+        }
+        this.localCollection = new LocalIntervalCollection(client, label, this.helpers, this.options, (interval, previousInterval) => this.emitChange(interval, previousInterval, true, true));
+        if (this.savedSerializedIntervals) {
+            for (const serializedInterval of this.savedSerializedIntervals) {
+                this.localCollection.ensureSerializedId(serializedInterval);
+                const { start: startPos, end: endPos, intervalType, properties, startSide, endSide, } = serializedInterval;
+                const start = typeof startPos === "number" && startSide !== undefined
+                    ? { pos: startPos, side: startSide }
+                    : startPos;
+                const end = typeof endPos === "number" && endSide !== undefined
+                    ? { pos: endPos, side: endSide }
+                    : endPos;
+                const interval = this.helpers.create(label, start, end, client, intervalType, undefined, true, this.options.mergeTreeReferencesCanSlideToEndpoint);
+                if (properties) {
+                    interval.addProperties(properties);
+                }
+                this.localCollection.add(interval);
+            }
+        }
+        this.savedSerializedIntervals = undefined;
+    }
+    /**
+     * Gets the next local sequence number, modifying this client's collab window in doing so.
+     */
+    getNextLocalSeq() {
+        if (this.client) {
+            return ++this.client.getCollabWindow().localSeq;
+        }
+        return 0;
+    }
+    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.
+        let startRefType;
+        let endRefType;
+        if (previousInterval instanceof SequenceInterval) {
+            startRefType = previousInterval.start.refType;
+            endRefType = previousInterval.end.refType;
+            previousInterval.start.refType = ReferenceType.Transient;
+            previousInterval.end.refType = ReferenceType.Transient;
+            this.emit("changeInterval", interval, previousInterval, local, op, slide);
+            previousInterval.start.refType = startRefType;
+            previousInterval.end.refType = endRefType;
+        }
+        else {
+            this.emit("changeInterval", interval, previousInterval, local, op, slide);
+        }
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.getIntervalById}
+     */
+    getIntervalById(id) {
+        if (!this.localCollection) {
+            throw new LoggingError("attach must be called before accessing intervals");
+        }
+        return this.localCollection.idIntervalIndex.getIntervalById(id);
+    }
+    assertStickinessEnabled(start, end) {
+        if (!(typeof start === "number" && typeof end === "number") &&
+            !this.options.intervalStickinessEnabled) {
+            throw new UsageError("attempted to set interval stickiness without enabling `intervalStickinessEnabled` feature flag");
+        }
+    }
+    add(start, end, intervalType, props) {
+        let intStart;
+        let intEnd;
+        let type;
+        let properties;
+        if (isSequencePlace(start)) {
+            intStart = start;
+            assert(end !== undefined, 0x7c0 /* end must be defined */);
+            intEnd = end;
+            assert(intervalType !== undefined, 0x7c1 /* intervalType must be defined */);
+            type = intervalType;
+            properties = props;
+        }
+        else {
+            intStart = start.start;
+            intEnd = start.end;
+            type = IntervalType.SlideOnRemove;
+            properties = start.props;
+        }
+        if (!this.localCollection) {
+            throw new LoggingError("attach must be called prior to adding intervals");
+        }
+        if (type & IntervalType.Transient) {
+            throw new LoggingError("Can not add transient intervals");
+        }
+        const { startSide, endSide, startPos, endPos } = endpointPosAndSide(intStart, intEnd);
+        assert(startPos !== undefined &&
+            endPos !== undefined &&
+            startSide !== undefined &&
+            endSide !== undefined, 0x793 /* start and end cannot be undefined because they were not passed in as undefined */);
+        const stickiness = computeStickinessFromSide(startPos, startSide, endPos, endSide);
+        this.assertStickinessEnabled(intStart, intEnd);
+        const interval = this.localCollection.addInterval(toSequencePlace(startPos, startSide), toSequencePlace(endPos, endSide), type, properties);
+        if (interval) {
+            if (!this.isCollaborating && interval instanceof SequenceInterval) {
+                setSlideOnRemove(interval.start);
+                setSlideOnRemove(interval.end);
+            }
+            const serializedInterval = {
+                start: startPos,
+                end: endPos,
+                intervalType: type,
+                properties: interval.properties,
+                sequenceNumber: this.client?.getCurrentSeq() ?? 0,
+                stickiness,
+                startSide,
+                endSide,
+            };
+            const localSeq = this.getNextLocalSeq();
+            this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
+            // Local ops get submitted to the server. Remote ops have the deserializer run.
+            this.emitter.emit("add", undefined, serializedInterval, { localSeq });
+        }
+        this.emit("addInterval", interval, true, undefined);
+        return interval;
+    }
+    deleteExistingInterval(interval, local, op) {
+        if (!this.localCollection) {
+            throw new 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(), {
+                    localSeq: this.getNextLocalSeq(),
+                });
+            }
+            else {
+                if (this.onDeserialize) {
+                    this.onDeserialize(interval);
+                }
+            }
+        }
+        this.emit("deleteInterval", interval, local, op);
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.removeIntervalById}
+     */
+    removeIntervalById(id) {
+        if (!this.localCollection) {
+            throw new LoggingError("Attach must be called before accessing intervals");
+        }
+        const interval = this.localCollection.idIntervalIndex.getIntervalById(id);
+        if (interval) {
+            this.deleteExistingInterval(interval, true, undefined);
+        }
+        return interval;
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.changeProperties}
+     * @deprecated - call change with the id and an object containing the new props values
+     */
+    changeProperties(id, props) {
+        this.change(id, { props });
+    }
+    change(arg1, arg2, arg3) {
+        const id = arg1;
+        let start;
+        let end;
+        let props;
+        if (isSequencePlace(arg2)) {
+            start = arg2;
+            end = arg3;
+        }
+        else {
+            start = arg2.start;
+            end = arg2.end;
+            props = arg2.props;
+        }
+        if (!this.localCollection) {
+            throw new LoggingError("Attach must be called before accessing intervals");
+        }
+        // Force id to be a string.
+        if (typeof id !== "string") {
+            throw new UsageError("Change API requires an ID that is a string");
+        }
+        // Ensure that both start and end are defined or both are undefined.
+        if ((start === undefined) !== (end === undefined)) {
+            throw new UsageError("Change API requires both start and end to be defined or undefined");
+        }
+        // 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 UsageError("The label property should not be modified once inserted to the collection");
+        }
+        const interval = this.getIntervalById(id);
+        if (interval) {
+            let deltaProps;
+            let newInterval;
+            if (props !== undefined) {
+                deltaProps = interval.addProperties(props, true, this.isCollaborating ? UnassignedSequenceNumber : UniversalSequenceNumber);
+            }
+            if (start !== undefined && end !== undefined) {
+                newInterval = this.localCollection.changeInterval(interval, start, end);
+                if (!this.isCollaborating && newInterval instanceof SequenceInterval) {
+                    setSlideOnRemove(newInterval.start);
+                    setSlideOnRemove(newInterval.end);
+                }
+            }
+            const serializedInterval = interval.serialize();
+            const { startPos, startSide, endPos, endSide } = endpointPosAndSide(start, end);
+            const stickiness = computeStickinessFromSide(startPos, startSide, endPos, endSide);
+            serializedInterval.start = startPos;
+            serializedInterval.end = endPos;
+            serializedInterval.startSide = startSide;
+            serializedInterval.endSide = endSide;
+            serializedInterval.stickiness = stickiness;
+            // Emit a property bag containing the ID and the other (if any) properties changed
+            serializedInterval.properties = {
+                [reservedIntervalIdKey]: interval.getIntervalId(),
+                ...props,
+            };
+            const localSeq = this.getNextLocalSeq();
+            this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
+            this.emitter.emit("change", undefined, serializedInterval, { localSeq });
+            if (deltaProps !== undefined) {
+                this.emit("propertyChanged", interval, deltaProps, true, undefined);
+            }
+            if (newInterval) {
+                this.addPendingChange(id, serializedInterval);
+                this.emitChange(newInterval, interval, true, false);
+            }
+            return newInterval;
+        }
+        // No interval to change
+        return undefined;
+    }
+    get isCollaborating() {
+        return this.client?.getCollabWindow().collaborating ?? false;
+    }
+    addPendingChange(id, serializedInterval) {
+        if (!this.isCollaborating) {
+            return;
+        }
+        if (serializedInterval.start !== undefined) {
+            this.addPendingChangeHelper(id, this.pendingChangesStart, serializedInterval);
+        }
+        if (serializedInterval.end !== undefined) {
+            this.addPendingChangeHelper(id, this.pendingChangesEnd, serializedInterval);
+        }
+    }
+    addPendingChangeHelper(id, pendingChanges, serializedInterval) {
+        let entries = pendingChanges.get(id);
+        if (!entries) {
+            entries = [];
+            pendingChanges.set(id, entries);
+        }
+        entries.push(serializedInterval);
+    }
+    removePendingChange(serializedInterval) {
+        // Change ops always have an ID.
+        const id = serializedInterval.properties?.[reservedIntervalIdKey];
+        if (serializedInterval.start !== undefined) {
+            this.removePendingChangeHelper(id, this.pendingChangesStart, serializedInterval);
+        }
+        if (serializedInterval.end !== undefined) {
+            this.removePendingChangeHelper(id, this.pendingChangesEnd, serializedInterval);
+        }
+    }
+    removePendingChangeHelper(id, pendingChanges, serializedInterval) {
+        const entries = pendingChanges.get(id);
+        if (entries) {
+            const pendingChange = entries.shift();
+            if (entries.length === 0) {
+                pendingChanges.delete(id);
+            }
+            if (pendingChange?.start !== serializedInterval.start ||
+                pendingChange?.end !== serializedInterval.end) {
+                throw new LoggingError("Mismatch in pending changes");
+            }
+        }
+    }
+    hasPendingChangeStart(id) {
+        const entries = this.pendingChangesStart.get(id);
+        return entries && entries.length !== 0;
+    }
+    hasPendingChangeEnd(id) {
+        const entries = this.pendingChangesEnd.get(id);
+        return entries && entries.length !== 0;
+    }
+    /** @internal */
+    ackChange(serializedInterval, local, op, localOpMetadata) {
+        if (!this.localCollection) {
+            throw new LoggingError("Attach must be called before accessing intervals");
+        }
+        if (local) {
+            assert(localOpMetadata !== undefined, 0x552 /* op metadata should be defined for local op */);
+            this.localSeqToSerializedInterval.delete(localOpMetadata?.localSeq);
+            // This is an ack from the server. Remove the pending change.
+            this.removePendingChange(serializedInterval);
+        }
+        // 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 { [reservedIntervalIdKey]: id, ...newProps } = serializedInterval.properties ?? {};
+        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.
+            interval.propertyManager?.ackPendingProperties({
+                type: MergeTreeDeltaType.ANNOTATE,
+                props: serializedInterval.properties ?? {},
+            });
+            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.
+            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 =
+                    this.localCollection.changeInterval(interval, toOptionalSequencePlace(start, serializedInterval.startSide), toOptionalSequencePlace(end, serializedInterval.endSide), op) ?? interval;
+            }
+            const deltaProps = newInterval.addProperties(newProps, true, op.sequenceNumber);
+            if (this.onDeserialize) {
+                this.onDeserialize(newInterval);
+            }
+            if (newInterval !== interval) {
+                this.emitChange(newInterval, interval, local, false, op);
+            }
+            const changedProperties = Object.keys(newProps).length > 0;
+            if (changedProperties) {
+                this.emit("propertyChanged", interval, deltaProps, local, op);
+            }
+        }
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.attachDeserializer}
+     */
+    attachDeserializer(onDeserialize) {
+        // If no deserializer is specified can skip all processing work
+        if (!onDeserialize) {
+            return;
+        }
+        // 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
+        if (this.attached) {
+            this.map(onDeserialize);
+        }
+    }
+    /**
+     * Returns new interval after rebasing. If undefined, the interval was
+     * deleted as a result of rebasing. This can occur if the interval applies
+     * to a range that no longer exists, and the interval was unable to slide.
+     *
+     * @internal
+     */
+    rebaseLocalInterval(opName, serializedInterval, localSeq) {
+        if (!this.client) {
+            // If there's no associated mergeTree client, the originally submitted op is still correct.
+            return serializedInterval;
+        }
+        if (!this.attached) {
+            throw new LoggingError("attachSequence must be called");
+        }
+        const { intervalType, properties, stickiness, startSide, endSide } = serializedInterval;
+        const { start: startRebased, end: endRebased } = this.localSeqToRebasedInterval.get(localSeq) ?? this.computeRebasedPositions(localSeq);
+        const intervalId = properties?.[reservedIntervalIdKey];
+        const localInterval = this.localCollection?.idIntervalIndex.getIntervalById(intervalId);
+        const rebased = {
+            start: startRebased,
+            end: endRebased,
+            intervalType,
+            sequenceNumber: this.client?.getCurrentSeq() ?? 0,
+            properties,
+            stickiness,
+            startSide,
+            endSide,
+        };
+        if (opName === "change" &&
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- ?? is not logically equivalent when .hasPendingChangeStart returns false.
+            (this.hasPendingChangeStart(intervalId) || this.hasPendingChangeEnd(intervalId))) {
+            this.removePendingChange(serializedInterval);
+            this.addPendingChange(intervalId, rebased);
+        }
+        // if the interval slid off the string, rebase the op to be a noop and delete the interval.
+        if (startRebased === DetachedReferencePosition ||
+            endRebased === DetachedReferencePosition) {
+            if (localInterval) {
+                this.localCollection?.removeExistingInterval(localInterval);
+            }
+            return undefined;
+        }
+        if (localInterval !== undefined) {
+            // we know we must be using `SequenceInterval` because `this.client` exists
+            assert(localInterval instanceof SequenceInterval, 0x3a0 /* localInterval must be `SequenceInterval` when used with client */);
+            // The rebased op may place this interval's endpoints on different segments. Calling `changeInterval` here
+            // updates the local client's state to be consistent with the emitted op.
+            this.localCollection?.changeInterval(localInterval, toOptionalSequencePlace(startRebased, startSide), toOptionalSequencePlace(endRebased, endSide), undefined, localSeq);
+        }
+        return rebased;
+    }
+    getSlideToSegment(lref) {
+        if (!this.client) {
+            throw new LoggingError("client does not exist");
+        }
+        const segoff = { segment: lref.getSegment(), offset: lref.getOffset() };
+        if (segoff.segment?.localRefs?.has(lref) !== true) {
+            return undefined;
+        }
+        const newSegoff = getSlideToSegoff(segoff, undefined, this.options.mergeTreeReferencesCanSlideToEndpoint);
+        const value = segoff.segment === newSegoff.segment && segoff.offset === newSegoff.offset
+            ? undefined
+            : newSegoff;
+        return value;
+    }
+    ackInterval(interval, op) {
+        // Only SequenceIntervals need potential sliding
+        if (!(interval instanceof SequenceInterval)) {
+            return;
+        }
+        if (!refTypeIncludesFlag(interval.start, ReferenceType.StayOnRemove) &&
+            !refTypeIncludesFlag(interval.end, ReferenceType.StayOnRemove)) {
+            return;
+        }
+        const newStart = this.getSlideToSegment(interval.start);
+        const newEnd = this.getSlideToSegment(interval.end);
+        const id = interval.properties[reservedIntervalIdKey];
+        const hasPendingStartChange = this.hasPendingChangeStart(id);
+        const hasPendingEndChange = this.hasPendingChangeEnd(id);
+        if (!hasPendingStartChange) {
+            setSlideOnRemove(interval.start);
+        }
+        if (!hasPendingEndChange) {
+            setSlideOnRemove(interval.end);
+        }
+        const needsStartUpdate = newStart !== undefined && !hasPendingStartChange;
+        const needsEndUpdate = newEnd !== undefined && !hasPendingEndChange;
+        if (needsStartUpdate || needsEndUpdate) {
+            if (!this.localCollection) {
+                throw new 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 LoggingError("client does not exist");
+            }
+            if (needsStartUpdate) {
+                const props = interval.start.properties;
+                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op, undefined, undefined, startReferenceSlidingPreference(interval.stickiness), startReferenceSlidingPreference(interval.stickiness) ===
+                    SlidingPreference.BACKWARD);
+                if (props) {
+                    interval.start.addProperties(props);
+                }
+                const oldSeg = oldInterval.start.getSegment();
+                // remove and rebuild start interval as transient for event
+                this.client.removeLocalReferencePosition(oldInterval.start);
+                oldInterval.start.refType = ReferenceType.Transient;
+                oldSeg?.localRefs?.addLocalRef(oldInterval.start, oldInterval.start.getOffset());
+            }
+            if (needsEndUpdate) {
+                const props = interval.end.properties;
+                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op, undefined, undefined, endReferenceSlidingPreference(interval.stickiness), endReferenceSlidingPreference(interval.stickiness) ===
+                    SlidingPreference.FORWARD);
+                if (props) {
+                    interval.end.addProperties(props);
+                }
+                // remove and rebuild end interval as transient for event
+                const oldSeg = oldInterval.end.getSegment();
+                this.client.removeLocalReferencePosition(oldInterval.end);
+                oldInterval.end.refType = ReferenceType.Transient;
+                oldSeg?.localRefs?.addLocalRef(oldInterval.end, oldInterval.end.getOffset());
+            }
+            this.localCollection.add(interval);
+            this.emitChange(interval, oldInterval, true, true, op);
+        }
+    }
+    /** @internal */
+    ackAdd(serializedInterval, local, op, localOpMetadata) {
+        if (local) {
+            assert(localOpMetadata !== undefined, 0x553 /* op metadata should be defined for local op */);
+            this.localSeqToSerializedInterval.delete(localOpMetadata.localSeq);
+            const id = serializedInterval.properties?.[reservedIntervalIdKey];
+            const localInterval = this.getIntervalById(id);
+            if (localInterval) {
+                this.ackInterval(localInterval, op);
+            }
+            return;
+        }
+        if (!this.localCollection) {
+            throw new LoggingError("attachSequence must be called");
+        }
+        this.localCollection.ensureSerializedId(serializedInterval);
+        const interval = this.localCollection.addInterval(toSequencePlace(serializedInterval.start, serializedInterval.startSide ?? Side.Before), toSequencePlace(serializedInterval.end, serializedInterval.endSide ?? Side.Before), serializedInterval.intervalType, serializedInterval.properties, op);
+        if (interval) {
+            if (this.onDeserialize) {
+                this.onDeserialize(interval);
+            }
+        }
+        this.emit("addInterval", interval, local, op);
+        return interval;
+    }
+    /** @internal */
+    ackDelete(serializedInterval, local, op) {
+        if (local) {
+            // Local ops were applied when the message was created and there's no "pending delete"
+            // state to book keep: remote operation application takes into account possibility of
+            // locally deleted interval whenever a lookup happens.
+            return;
+        }
+        if (!this.localCollection) {
+            throw new LoggingError("attach must be called prior to deleting intervals");
+        }
+        const id = this.localCollection.ensureSerializedId(serializedInterval);
+        const interval = this.localCollection.idIntervalIndex.getIntervalById(id);
+        if (interval) {
+            this.deleteExistingInterval(interval, local, op);
+        }
+    }
+    /**
+     * @internal
+     */
+    serializeInternal() {
+        if (!this.localCollection) {
+            throw new 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;
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.CreateForwardIteratorWithStartPosition}
+     */
+    CreateForwardIteratorWithStartPosition(startPosition) {
+        const iterator = new IntervalCollectionIterator(this, true, startPosition);
+        return iterator;
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.CreateBackwardIteratorWithStartPosition}
+     */
+    CreateBackwardIteratorWithStartPosition(startPosition) {
+        const iterator = new IntervalCollectionIterator(this, false, startPosition);
+        return iterator;
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.CreateForwardIteratorWithEndPosition}
+     */
+    CreateForwardIteratorWithEndPosition(endPosition) {
+        const iterator = new IntervalCollectionIterator(this, true, undefined, endPosition);
+        return iterator;
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.CreateBackwardIteratorWithEndPosition}
+     */
+    CreateBackwardIteratorWithEndPosition(endPosition) {
+        const iterator = new IntervalCollectionIterator(this, false, undefined, endPosition);
+        return iterator;
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.gatherIterationResults}
+     */
+    gatherIterationResults(results, iteratesForward, start, end) {
+        if (!this.localCollection) {
+            return;
+        }
+        this.localCollection.overlappingIntervalsIndex.gatherIterationResults(results, iteratesForward, start, end);
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.findOverlappingIntervals}
+     */
+    findOverlappingIntervals(startPosition, endPosition) {
+        if (!this.localCollection) {
+            throw new LoggingError("attachSequence must be called");
+        }
+        return this.localCollection.overlappingIntervalsIndex.findOverlappingIntervals(startPosition, endPosition);
+    }
+    /**
+     * {@inheritdoc IIntervalCollection.map}
+     */
+    map(fn) {
+        if (!this.localCollection) {
+            throw new LoggingError("attachSequence must be called");
+        }
+        for (const interval of this.localCollection.idIntervalIndex) {
+            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");
+        }
+        return this.localCollection.endIntervalIndex.nextInterval(pos);
+    }
+}
+function setSlideOnRemove(lref) {
+    let refType = lref.refType;
+    refType = refType & ~ReferenceType.StayOnRemove;
+    refType = refType | ReferenceType.SlideOnRemove;
+    lref.refType = refType;
+}
+/**
+ * Returns an object that can be used to find the interval a given LocalReferencePosition belongs to.
+ * @returns undefined if the reference position is not the endpoint of any interval (e.g. it was created
+ * on the merge tree directly by app code), otherwise an {@link IntervalLocator} for the interval this
+ * endpoint is a part of.
+ * @internal
+ */
+export function intervalLocatorFromEndpoint(potentialEndpoint) {
+    const { interval, [reservedRangeLabelsKey]: collectionNameArray } = potentialEndpoint.properties ?? {};
+    return interval && collectionNameArray?.length === 1
+        ? { label: collectionNameArray[0], interval }
+        : undefined;
+}
+//# sourceMappingURL=intervalCollection.mjs.map