@fluidframework/merge-tree 0.59.2001 → 0.59.3000

package/src/localReference.ts

@@ -5,91 +5,121 @@
 
 import { assert } from "@fluidframework/common-utils";
 import { Client } from "./client";
+import { List, ListMakeHead, ListRemoveEntry } from "./collections";
 import {
     ISegment,
+} from "./mergeTree";
+import { ICombiningOp, ReferenceType } from "./ops";
+import { addProperties, PropertySet } from "./properties";
+import {
+    minReferencePosition,
+    maxReferencePosition,
+    compareReferencePositions,
+    refHasTileLabels,
+    refHasRangeLabels,
     ReferencePosition,
     refGetRangeLabels,
     refGetTileLabels,
     refHasRangeLabel,
     refHasTileLabel,
-} from "./mergeTree";
-import { ICombiningOp, ReferenceType } from "./ops";
-import { addProperties, PropertySet } from "./properties";
+    refTypeIncludesFlag,
+} from "./referencePositions";
 
+/**
+ * @deprecated - Use ReferencePosition
+ */
 export class LocalReference implements ReferencePosition {
+    /**
+     * @deprecated - use DetachedReferencePosition
+     */
     public static readonly DetachedPosition: number = -1;
 
     public properties: PropertySet | undefined;
+    /**
+     * @deprecated - use properties to store pair
+     */
     public pairedRef?: LocalReference;
+    /**
+     * @deprecated - use getSegment
+     */
     public segment: ISegment | undefined;
 
+    /**
+     * @deprecated - use createReferencePosition
+     */
     constructor(
         private readonly client: Client,
         initSegment: ISegment,
-        public offset = 0,
+        /**
+         * @deprecated - use getOffset
+         */
+        public offset: number = 0,
         public refType = ReferenceType.Simple,
+        properties?: PropertySet,
     ) {
         this.segment = initSegment;
+        this.properties = properties;
     }
 
+    /**
+     * @deprecated - use minReferencePosition
+     */
     public min(b: LocalReference) {
-        if (this.compare(b) < 0) {
-            return this;
-        } else {
-            return b;
-        }
+        return minReferencePosition(this, b);
     }
-
+    /**
+     * @deprecated - use maxReferencePosition
+     */
     public max(b: LocalReference) {
-        if (this.compare(b) > 0) {
-            return this;
-        } else {
-            return b;
-        }
+        return maxReferencePosition(this, b);
     }
-
+    /**
+     * @deprecated - use compareReferencePositions
+     */
     public compare(b: LocalReference) {
-        if (this.segment === b.segment) {
-            return this.offset - b.offset;
-        } else {
-            if (this.segment === undefined
-                || (b.segment !== undefined &&
-                    this.segment.ordinal < b.segment.ordinal)) {
-                return -1;
-            } else {
-                return 1;
-            }
-        }
+        return compareReferencePositions(this, b);
     }
 
+    /**
+     * @deprecated - use getLocalReferencePosition
+     */
     public toPosition() {
-        if (this.segment && this.segment.parent) {
-            return this.getOffset() + this.client.getPosition(this.segment);
-        } else {
-            return LocalReference.DetachedPosition;
-        }
+        return this.getClient().localReferencePositionToPosition(this);
     }
 
-    public hasTileLabels() {
-        return !!this.getTileLabels();
+    /**
+     * @deprecated - use refHasTileLabels
+     */
+    public hasTileLabels(): boolean {
+        return refHasTileLabels(this);
     }
-
-    public hasRangeLabels() {
-        return !!this.getRangeLabels();
+    /**
+     * @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);
     }
@@ -102,6 +132,9 @@ export class LocalReference implements ReferencePosition {
         this.properties = addProperties(this.properties, newProps, op);
     }
 
+    /**
+     * @deprecated - no longer supported
+     */
     public getClient() {
         return this.client;
     }
@@ -123,13 +156,17 @@ export class LocalReference implements ReferencePosition {
 }
 
 interface IRefsAtOffset {
-    before?: LocalReference[];
-    at?: LocalReference[];
-    after?: LocalReference[];
+    before?: List<LocalReference>;
+    at?: List<LocalReference>;
+    after?: List<LocalReference>;
+}
+
+function assertLocalReferences(lref: ReferencePosition | LocalReference): asserts lref is LocalReference {
+    assert(lref instanceof LocalReference, 0x2e0 /* "lref not a Local Reference" */);
 }
 
 /**
- * Represents a collection of {@link LocalReference}s associated with one segment in a merge-tree.
+ * Represents a collection of {@link ReferencePosition}s associated with one segment in a merge-tree.
  */
 export class LocalReferenceCollection {
     public static append(seg1: ISegment, seg2: ISegment) {
@@ -140,18 +177,25 @@ export class LocalReferenceCollection {
             assert(seg1.localRefs.refsByOffset.length === seg1.cachedLength,
                 0x2be /* "LocalReferences array contains a gap" */);
             seg1.localRefs.append(seg2.localRefs);
-        }
-        else if (seg1.localRefs) {
+        } else if (seg1.localRefs) {
             // Since creating the LocalReferenceCollection, we may have appended
             // segments that had no local references. Account for them now by padding the array.
             seg1.localRefs.refsByOffset.length += seg2.cachedLength;
         }
     }
 
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
     public hierRefCount: number = 0;
     private readonly refsByOffset: (IRefsAtOffset | undefined)[];
     private refCount: number = 0;
 
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
     constructor(
         /** Segment this `LocalReferenceCollection` is associated to. */
         private readonly segment: ISegment,
@@ -162,6 +206,10 @@ export class LocalReferenceCollection {
         this.refsByOffset = initialRefsByfOffset;
     }
 
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
     public [Symbol.iterator]() {
         const subiterators: IterableIterator<LocalReference>[] = [];
         for (const refs of this.refsByOffset) {
@@ -198,16 +246,20 @@ export class LocalReferenceCollection {
         return iterator;
     }
 
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
     public clear() {
         this.refCount = 0;
         this.hierRefCount = 0;
-        const detachSegments = (refs: LocalReference[] | undefined) => {
+        const detachSegments = (refs: List<LocalReference> | undefined) => {
             if (refs) {
-                refs.forEach((r) => {
+                for (const r of refs) {
                     if (r.segment === this.segment) {
                         r.segment = undefined;
                     }
-                });
+                }
             }
         };
         for (let i = 0; i < this.refsByOffset.length; i++) {
@@ -221,41 +273,80 @@ export class LocalReferenceCollection {
         }
     }
 
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
     public get empty() {
         return this.refCount === 0;
     }
 
-    public addLocalRef(lref: LocalReference) {
-        const refsAtOffset = this.refsByOffset[lref.offset];
-        if (refsAtOffset === undefined) {
-            this.refsByOffset[lref.offset] = {
-                at: [lref],
-            };
-        } else if (refsAtOffset.at === undefined) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            this.refsByOffset[lref.offset]!.at = [lref];
-        } else {
-            refsAtOffset.at.push(lref);
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
+    public createLocalRef(
+        offset: number,
+        refType: ReferenceType,
+        properties: PropertySet | undefined,
+        client: Client): ReferencePosition {
+        const ref = new LocalReference(
+            client,
+            this.segment,
+            offset,
+            refType,
+            properties,
+        );
+        if (!refTypeIncludesFlag(ref, ReferenceType.Transient)) {
+            this.addLocalRef(ref);
         }
+        return ref;
+    }
 
-        if (lref.hasRangeLabels() || lref.hasTileLabels()) {
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
+    public addLocalRef(lref: LocalReference | ReferencePosition) {
+        assert(
+            !refTypeIncludesFlag(lref, ReferenceType.Transient),
+            0x2df /* "transient references cannot be bound to segments" */);
+        assertLocalReferences(lref);
+        const refsAtOffset = this.refsByOffset[lref.getOffset()] =
+            this.refsByOffset[lref.getOffset()]
+            ?? { at: ListMakeHead() };
+        const atRefs = refsAtOffset.at =
+            refsAtOffset.at
+            ?? ListMakeHead();
+
+        atRefs.enqueue(lref);
+
+        if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
             this.hierRefCount++;
         }
         this.refCount++;
     }
 
-    public removeLocalRef(lref: LocalReference) {
-        const tryRemoveRef = (refs: LocalReference[] | undefined) => {
+    /**
+     *
+     * @internal - this method should only be called by mergeTree
+     */
+    public removeLocalRef(lref: LocalReference | ReferencePosition) {
+        assertLocalReferences(lref);
+        const tryRemoveRef = (refs: List<LocalReference> | undefined) => {
             if (refs) {
-                const index = refs.indexOf(lref);
-                if (index >= 0) {
-                    refs.splice(index, 1);
-                    if (lref.hasRangeLabels() || lref.hasTileLabels()) {
-                        this.hierRefCount--;
+                let node = refs;
+                do {
+                    node = node.next;
+                    if (node.data === lref) {
+                        ListRemoveEntry(node);
+                        if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
+                            this.hierRefCount--;
+                        }
+                        this.refCount--;
+                        return lref;
                     }
-                    this.refCount--;
-                    return lref;
-                }
+                } while (!node.isHead);
             }
         };
         const refAtOffset = this.refsByOffset[lref.offset];
@@ -278,6 +369,8 @@ export class LocalReferenceCollection {
     }
 
     /**
+     * @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.
      *
@@ -301,6 +394,8 @@ export class LocalReferenceCollection {
     }
 
     /**
+     * @internal - this method should only be called by mergeTree
+     *
      * 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`,
@@ -320,7 +415,7 @@ export class LocalReferenceCollection {
             for (const lref of localRefs) {
                 lref.segment = splitSeg;
                 lref.offset -= offset;
-                if (lref.hasRangeLabels() || lref.hasTileLabels()) {
+                if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
                     this.hierRefCount--;
                     localRefs.hierRefCount++;
                 }
@@ -333,17 +428,17 @@ export class LocalReferenceCollection {
         }
     }
 
-    public addBeforeTombstones(...refs: Iterable<LocalReference>[]) {
-        const beforeRefs: LocalReference[] = [];
+    public addBeforeTombstones(...refs: Iterable<LocalReference | ReferencePosition>[]) {
+        const beforeRefs = this.refsByOffset[0]?.before ?? ListMakeHead();
 
         for (const iterable of refs) {
             for (const lref of iterable) {
-                // eslint-disable-next-line no-bitwise
-                if (lref.refType & ReferenceType.SlideOnRemove) {
+                assertLocalReferences(lref);
+                if (refTypeIncludesFlag(lref, ReferenceType.SlideOnRemove)) {
                     beforeRefs.push(lref);
                     lref.segment = this.segment;
                     lref.offset = 0;
-                    if (lref.hasRangeLabels() || lref.hasTileLabels()) {
+                    if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
                         this.hierRefCount++;
                     }
                     this.refCount++;
@@ -352,28 +447,27 @@ export class LocalReferenceCollection {
                 }
             }
         }
-        if (beforeRefs.length > 0) {
-            if (this.refsByOffset[0] === undefined) {
-                this.refsByOffset[0] = { before: beforeRefs };
-            } else if (this.refsByOffset[0].before === undefined) {
-                this.refsByOffset[0].before = beforeRefs;
-            } else {
-                this.refsByOffset[0].before.unshift(...beforeRefs);
-            }
+        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>[]) {
-        const afterRefs: LocalReference[] = [];
+    public addAfterTombstones(...refs: Iterable<LocalReference | ReferencePosition>[]) {
+        const lastOffset = this.refsByOffset.length - 1;
+        const afterRefs =
+            this.refsByOffset[lastOffset]?.after ?? ListMakeHead();
 
         for (const iterable of refs) {
             for (const lref of iterable) {
-                // eslint-disable-next-line no-bitwise
-                if (lref.refType & ReferenceType.SlideOnRemove) {
+                assertLocalReferences(lref);
+                if (refTypeIncludesFlag(lref, ReferenceType.SlideOnRemove)) {
                     afterRefs.push(lref);
                     lref.segment = this.segment;
                     lref.offset = this.segment.cachedLength - 1;
-                    if (lref.hasRangeLabels() || lref.hasTileLabels()) {
+                    if (refHasRangeLabels(lref) || refHasTileLabels(lref)) {
                         this.hierRefCount++;
                     }
                     this.refCount++;
@@ -382,15 +476,11 @@ export class LocalReferenceCollection {
                 }
             }
         }
-        if (afterRefs.length > 0) {
-            const refsAtOffset = this.refsByOffset[this.segment.cachedLength - 1];
-            if (refsAtOffset === undefined) {
-                this.refsByOffset[this.segment.cachedLength - 1] = { after: afterRefs };
-            } else if (refsAtOffset.after === undefined) {
-                refsAtOffset.after = afterRefs;
-            } else {
-                refsAtOffset.after.push(...afterRefs);
-            }
+        if (!afterRefs.empty() && this.refsByOffset[lastOffset]?.after === undefined) {
+            const refsAtOffset = this.refsByOffset[lastOffset] =
+                this.refsByOffset[lastOffset]
+                ?? { after: afterRefs };
+            refsAtOffset.after = refsAtOffset.after ?? afterRefs;
         }
     }
 }