@fluidframework/merge-tree 1.2.1 → 2.0.0-internal.1.0.0

package/src/localReference.ts

@@ -5,24 +5,16 @@
 
 import { assert } from "@fluidframework/common-utils";
 import { UsageError } from "@fluidframework/container-utils";
-import { Client } from "./client";
 import { List, ListMakeHead, ListRemoveEntry } from "./collections";
 import {
     ISegment,
-} from "./mergeTree";
+} from "./mergeTreeNodes";
 import { ICombiningOp, ReferenceType } from "./ops";
 import { addProperties, PropertySet } from "./properties";
 import {
-    minReferencePosition,
-    maxReferencePosition,
-    compareReferencePositions,
     refHasTileLabels,
     refHasRangeLabels,
     ReferencePosition,
-    refGetRangeLabels,
-    refGetTileLabels,
-    refHasRangeLabel,
-    refHasTileLabel,
     refTypeIncludesFlag,
 } from "./referencePositions";
 
@@ -51,105 +43,34 @@ export interface LocalReferencePosition extends ReferencePosition {
 }
 
 /**
- * @deprecated - Use LocalReferencePosition
+ * @privateRemarks This should not be exported outside merge tree.
+ * @internal
  */
-export class LocalReference implements LocalReferencePosition {
-    /**
-     * @deprecated - use DetachedReferencePosition
-     */
-    public static readonly DetachedPosition: number = -1;
-
+class LocalReference implements LocalReferencePosition {
     public properties: PropertySet | undefined;
-    /**
-     * @deprecated - use properties to store pair
-     */
-    public pairedRef?: LocalReference;
-    /**
-     * @deprecated - use getSegment
-     */
-    public segment: ISegment | undefined;
+
+    private segment: ISegment | undefined;
+    private offset: number = 0;
+    private listNode: List<LocalReference> | undefined;
 
     public callbacks?: Partial<Record<"beforeSlide" | "afterSlide", () => void>> | undefined;
 
-    /**
-     * @deprecated - use createReferencePosition
-     */
     constructor(
-        private readonly client: Client,
-        initSegment: ISegment,
-        /**
-         * @deprecated - use getOffset
-         */
-        public offset: number = 0,
         public refType = ReferenceType.Simple,
         properties?: PropertySet,
     ) {
         _validateReferenceType(refType);
-        this.segment = initSegment;
         this.properties = properties;
     }
 
-    /**
-     * @deprecated - use minReferencePosition
-     */
-    public min(b: LocalReference) {
-        return minReferencePosition(this, b);
-    }
-    /**
-     * @deprecated - use maxReferencePosition
-     */
-    public max(b: LocalReference) {
-        return maxReferencePosition(this, b);
-    }
-    /**
-     * @deprecated - use compareReferencePositions
-     */
-    public compare(b: LocalReference) {
-        return compareReferencePositions(this, b);
-    }
-
-    /**
-     * @deprecated - use getLocalReferencePosition
-     */
-    public toPosition() {
-        return this.getClient().localReferencePositionToPosition(this);
-    }
-
-    /**
-     * @deprecated - use refHasTileLabels
-     */
-    public hasTileLabels(): boolean {
-        return refHasTileLabels(this);
-    }
-    /**
-     * @deprecated - use refHasRangeLabels
-     */
-    public hasRangeLabels(): boolean {
-        return refHasRangeLabels(this);
-    }
-    /**
-     * @deprecated - use refHasTileLabel
-     */
-    public hasTileLabel(label: string): boolean {
-        return refHasTileLabel(this, label);
-    }
-    /**
-     * @deprecated - use refHasRangeLabel
-     */
-    public hasRangeLabel(label: string): boolean {
-        return refHasRangeLabel(this, label);
-    }
-    /**
-     * @deprecated - use refGetTileLabels
-     */
-    public getTileLabels(): string[] | undefined {
-        return refGetTileLabels(this);
-    }
-    /**
-     * @deprecated - use refGetRangeLabels
-     */
-    public getRangeLabels(): string[] | undefined {
-        return refGetRangeLabels(this);
+    public link(segment: ISegment | undefined, offset: number, listNode: List<LocalReference> | undefined) {
+        if (listNode !== this.listNode
+            && this.listNode !== undefined) {
+            this.segment?.localRefs?.removeLocalRef(this);
+        }
+        this.segment = segment;
+        this.offset = offset;
+        this.listNode = listNode;
     }
 
     public isLeaf() {
@@ -160,13 +81,6 @@ export class LocalReference implements LocalReferencePosition {
         this.properties = addProperties(this.properties, newProps, op);
     }
 
-    /**
-     * @deprecated - no longer supported
-     */
-    public getClient() {
-        return this.client;
-    }
-
     public getSegment() {
         return this.segment;
     }
@@ -175,23 +89,33 @@ export class LocalReference implements LocalReferencePosition {
         return this.offset;
     }
 
+    public getListNode() {
+        return this.listNode;
+    }
+
     public getProperties() {
         return this.properties;
     }
 }
 
+export function createDetachedLocalReferencePosition(refType?: ReferenceType): LocalReferencePosition {
+    return new LocalReference(refType, undefined);
+}
+
 interface IRefsAtOffset {
     before?: List<LocalReference>;
     at?: List<LocalReference>;
     after?: List<LocalReference>;
 }
 
-function assertLocalReferences(lref: ReferencePosition | LocalReference): asserts lref is LocalReference {
+export function assertLocalReferences(
+    lref: any,
+): asserts lref is LocalReference {
     assert(lref instanceof LocalReference, 0x2e0 /* "lref not a Local Reference" */);
 }
 
 /**
- * Represents a collection of {@link ReferencePosition}s associated with one segment in a merge-tree.
+ * Represents a collection of {@link LocalReferencePosition}s associated with one segment in a merge-tree.
  */
 export class LocalReferenceCollection {
     public static append(seg1: ISegment, seg2: ISegment) {
@@ -210,8 +134,8 @@ export class LocalReferenceCollection {
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public hierRefCount: number = 0;
     private readonly refsByOffset: (IRefsAtOffset | undefined)[];
@@ -219,7 +143,7 @@ export class LocalReferenceCollection {
 
     /**
      *
-     * @internal - this method should only be called by mergeTree
+     * @internal
      */
     constructor(
         /** Segment this `LocalReferenceCollection` is associated to. */
@@ -232,11 +156,11 @@ export class LocalReferenceCollection {
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public [Symbol.iterator]() {
-        const subiterators: IterableIterator<LocalReference>[] = [];
+        const subiterators: IterableIterator<LocalReferencePosition>[] = [];
         for (const refs of this.refsByOffset) {
             if (refs) {
                 if (refs.before) {
@@ -252,7 +176,7 @@ export class LocalReferenceCollection {
         }
 
         const iterator = {
-            next(): IteratorResult<LocalReference> {
+            next(): IteratorResult<LocalReferencePosition> {
                 while (subiterators.length > 0) {
                     const next = subiterators[0].next();
                     if (next.done === true) {
@@ -272,8 +196,8 @@ export class LocalReferenceCollection {
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public clear() {
         this.refCount = 0;
@@ -281,9 +205,7 @@ export class LocalReferenceCollection {
         const detachSegments = (refs: List<LocalReference> | undefined) => {
             if (refs) {
                 for (const r of refs) {
-                    if (r.segment === this.segment) {
-                        r.segment = undefined;
-                    }
+                    this.removeLocalRef(r);
                 }
             }
         };
@@ -292,59 +214,57 @@ export class LocalReferenceCollection {
             if (refsAtOffset) {
                 detachSegments(refsAtOffset.before);
                 detachSegments(refsAtOffset.at);
-                detachSegments(refsAtOffset.before);
+                detachSegments(refsAtOffset.after);
                 this.refsByOffset[i] = undefined;
             }
         }
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public get empty() {
         return this.refCount === 0;
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public createLocalRef(
-        offset: number | undefined,
+        offset: number,
         refType: ReferenceType,
-        properties: PropertySet | undefined,
-        client: Client): ReferencePosition {
+        properties: PropertySet | undefined): LocalReferencePosition {
         const ref = new LocalReference(
-            client,
-            this.segment,
-            offset,
             refType,
             properties,
         );
+        ref.link(this.segment, offset, undefined);
         if (!refTypeIncludesFlag(ref, ReferenceType.Transient)) {
-            this.addLocalRef(ref);
+            this.addLocalRef(ref, offset);
         }
         return ref;
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
-    public addLocalRef(lref: LocalReference | ReferencePosition) {
+    public addLocalRef(lref: LocalReferencePosition, offset: number) {
         assert(
             !refTypeIncludesFlag(lref, ReferenceType.Transient),
             0x2df /* "transient references cannot be bound to segments" */);
         assertLocalReferences(lref);
-        const refsAtOffset = this.refsByOffset[lref.offset] =
-            this.refsByOffset[lref.offset]
+        assert(offset < this.segment.cachedLength, 0x348 /* offset cannot be beyond segment length */);
+        const refsAtOffset = this.refsByOffset[offset] =
+            this.refsByOffset[offset]
             ?? { at: ListMakeHead() };
         const atRefs = refsAtOffset.at =
             refsAtOffset.at
             ?? ListMakeHead();
 
-        atRefs.enqueue(lref);
+        lref.link(this.segment, offset, atRefs.enqueue(lref));
 
         if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
             this.hierRefCount++;
@@ -353,55 +273,37 @@ export class LocalReferenceCollection {
     }
 
     /**
-     *
-     * @internal - this method should only be called by mergeTree
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
-    public removeLocalRef(lref: LocalReference | ReferencePosition) {
-        assertLocalReferences(lref);
-        const tryRemoveRef = (refs: List<LocalReference> | undefined) => {
-            if (refs) {
-                let node = refs;
-                do {
-                    node = node.next;
-                    if (node.data === lref) {
-                        ListRemoveEntry(node);
-                        if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
-                            this.hierRefCount--;
-                        }
-                        this.refCount--;
-                        return lref;
-                    }
-                } while (!node.isHead);
-            }
-        };
-        const refAtOffset = this.refsByOffset[lref.offset];
-        if (refAtOffset !== undefined) {
-            let ref = tryRemoveRef(refAtOffset.before);
-            if (ref) {
-                return ref;
-            }
-
-            ref = tryRemoveRef(refAtOffset.at);
-            if (ref) {
-                return ref;
-            }
-
-            ref = tryRemoveRef(refAtOffset.after);
-            if (ref) {
-                return ref;
+    public removeLocalRef(lref: LocalReferencePosition): LocalReferencePosition | undefined {
+        if (this.has(lref)) {
+            assertLocalReferences(lref);
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            ListRemoveEntry(lref.getListNode()!);
+            lref.link(
+                lref.getSegment(),
+                lref.getOffset(),
+                undefined);
+            if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
+                this.hierRefCount--;
             }
+            this.refCount--;
+            return lref;
         }
     }
 
     /**
-     * @internal - this method should only be called by mergeTree
      *
      * Called by 'append()' implementations to append local refs from the given 'other' segment to the
      * end of 'this' segment.
      *
      * Note: This method should be invoked after the caller has ensured that segments can be merged,
-     *       but before 'this' segment's cachedLength has changed, or the adjustment to the local refs
-     *       will be incorrect.
+     * but before 'this' segment's cachedLength has changed, or the adjustment to the local refs
+     * will be incorrect.
+     *
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public append(other: LocalReferenceCollection) {
         if (!other || other.empty) {
@@ -411,16 +313,58 @@ export class LocalReferenceCollection {
         this.refCount += other.refCount;
         other.hierRefCount = 0;
         for (const lref of other) {
-            lref.segment = this.segment;
-            lref.offset += this.refsByOffset.length;
+            assertLocalReferences(lref);
+            lref.link(
+                this.segment,
+                lref.getOffset() + this.refsByOffset.length,
+                lref.getListNode());
         }
 
         this.refsByOffset.push(...other.refsByOffset);
     }
-
     /**
-     * @internal - this method should only be called by mergeTree
+     * Returns true of the local reference is in the collection, otherwise false.
      *
+     * @remarks This method should only be called by mergeTree.
+     * @internal
+     */
+    public has(lref: ReferencePosition): boolean {
+        if (!(lref instanceof LocalReference)
+            || refTypeIncludesFlag(lref, ReferenceType.Transient)) {
+            return false;
+        }
+        const seg = lref.getSegment();
+        if (seg !== this.segment) {
+            return false;
+        }
+        // we should be able to optimize finding the
+        // list head
+        const listNode = lref.getListNode();
+        if (listNode === undefined) {
+            return false;
+        }
+        let prev = listNode;
+        let next = listNode;
+        while (prev?.isHead !== true && next?.isHead !== true) {
+            prev = prev?.prev;
+            next = next?.next;
+        }
+
+        const headNode = prev?.isHead === true ? prev : next;
+        if (headNode?.isHead !== true || headNode.empty()) {
+            return false;
+        }
+        const offset = lref.getOffset();
+        const refsAtOffset = this.refsByOffset[offset];
+        if (refsAtOffset?.before === headNode
+            || refsAtOffset?.at === headNode
+            || refsAtOffset?.after === headNode) {
+                return true;
+            }
+        return false;
+    }
+
+    /**
      * Splits this `LocalReferenceCollection` into the intervals [0, offset) and [offset, originalLength).
      * Local references in the former half of this split will remain associated with the segment used on construction.
      * Local references in the latter half of this split will be transferred to `splitSeg`,
@@ -428,6 +372,9 @@ export class LocalReferenceCollection {
      * @param offset - Offset into the original segment at which the collection should be split
      * @param splitSeg - Split segment which originally corresponded to the indices [offset, originalLength)
      * before splitting.
+     *
+     * @remarks This method should only be called by mergeTree.
+     * @internal
      */
     public split(offset: number, splitSeg: ISegment) {
         if (!this.empty) {
@@ -438,8 +385,11 @@ export class LocalReferenceCollection {
 
             splitSeg.localRefs = localRefs;
             for (const lref of localRefs) {
-                lref.segment = splitSeg;
-                lref.offset -= offset;
+                assertLocalReferences(lref);
+                lref.link(
+                    splitSeg,
+                    lref.getOffset() - offset,
+                    lref.getListNode());
                 if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
                     this.hierRefCount--;
                     localRefs.hierRefCount++;
@@ -453,59 +403,58 @@ export class LocalReferenceCollection {
         }
     }
 
-    public addBeforeTombstones(...refs: Iterable<LocalReference | ReferencePosition>[]) {
+    public addBeforeTombstones(...refs: Iterable<LocalReferencePosition>[]) {
         const beforeRefs = this.refsByOffset[0]?.before ?? ListMakeHead();
 
+        if (this.refsByOffset[0]?.before === undefined) {
+            const refsAtOffset = this.refsByOffset[0] ??= { before: beforeRefs };
+            refsAtOffset.before ??= beforeRefs;
+        }
+
         for (const iterable of refs) {
             for (const lref of iterable) {
                 assertLocalReferences(lref);
                 if (refTypeIncludesFlag(lref, ReferenceType.SlideOnRemove)) {
-                    beforeRefs.push(lref);
-                    lref.segment = this.segment;
-                    lref.offset = 0;
+                    lref.callbacks?.beforeSlide?.();
+                    beforeRefs.unshift(lref);
+                    lref.link(this.segment, 0, beforeRefs.next);
                     if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
                         this.hierRefCount++;
                     }
                     this.refCount++;
+                    lref.callbacks?.afterSlide?.();
                 } else {
-                    lref.segment = undefined;
+                    lref.link(undefined, 0, undefined);
                 }
             }
         }
-        if (!beforeRefs.empty() && this.refsByOffset[0]?.before === undefined) {
-            const refsAtOffset = this.refsByOffset[0] =
-                this.refsByOffset[0]
-                ?? { before: beforeRefs };
-            refsAtOffset.before = refsAtOffset.before ?? beforeRefs;
-        }
     }
 
-    public addAfterTombstones(...refs: Iterable<LocalReference | ReferencePosition>[]) {
-        const lastOffset = this.refsByOffset.length - 1;
-        const afterRefs =
-            this.refsByOffset[lastOffset]?.after ?? ListMakeHead();
+    public addAfterTombstones(...refs: Iterable<LocalReferencePosition>[]) {
+        const lastOffset = this.segment.cachedLength - 1;
+        const afterRefs = this.refsByOffset[lastOffset]?.after ?? ListMakeHead();
+
+        if (this.refsByOffset[lastOffset]?.after === undefined) {
+            const refsAtOffset = this.refsByOffset[lastOffset] ??= { after: afterRefs };
+            refsAtOffset.after ??= afterRefs;
+        }
 
         for (const iterable of refs) {
             for (const lref of iterable) {
                 assertLocalReferences(lref);
                 if (refTypeIncludesFlag(lref, ReferenceType.SlideOnRemove)) {
-                    afterRefs.push(lref);
-                    lref.segment = this.segment;
-                    lref.offset = this.segment.cachedLength - 1;
+                    lref.callbacks?.beforeSlide?.();
+                    afterRefs.enqueue(lref);
+                    lref.link(this.segment, lastOffset, afterRefs.prev);
                     if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
                         this.hierRefCount++;
                     }
                     this.refCount++;
+                    lref.callbacks?.afterSlide?.();
                 } else {
-                    lref.segment = undefined;
+                    lref.link(undefined, 0, undefined);
                 }
             }
         }
-        if (!afterRefs.empty() && this.refsByOffset[lastOffset]?.after === undefined) {
-            const refsAtOffset = this.refsByOffset[lastOffset] =
-                this.refsByOffset[lastOffset]
-                ?? { after: afterRefs };
-            refsAtOffset.after = refsAtOffset.after ?? afterRefs;
-        }
     }
 }