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

package/lib/partialLengths.js

@@ -5,7 +5,7 @@
 import { assert } from "@fluidframework/common-utils";
 import { RedBlackTree } from "./collections";
 import { UnassignedSequenceNumber } from "./constants";
-import { compareNumbers, toRemovalInfo, } from "./mergeTree";
+import { compareNumbers, toRemovalInfo, } from "./mergeTreeNodes";
 /**
  * Returns the partial length whose sequence number is
  * the greatest sequence number within a that is
@@ -32,141 +32,137 @@ function latestLEQ(a, key) {
     return best;
 }
 /**
- * Keep track of partial sums of segment lengths for all sequence numbers
- * in the current collaboration window (if any).  Only used during active
- * collaboration.
+ * Keeps track of partial sums of segment lengths for all sequence numbers in the current collaboration window.
+ * Only used during active collaboration.
+ *
+ * This class is associated with an internal node (block) of a MergeTree. It efficiently answers queries of the form
+ * "What is the length of `block` from the perspective of some particular seq and clientId?".
+ *
+ * It also supports incremental updating of state for newly-sequenced ops that don't affect the structure of the
+ * MergeTree.
+ *
+ * To answer these queries, it pre-builds several lists which track the length of the block at a per-sequence-number
+ * level. These lists are:
+ *
+ * 1. (`partialLengths`): Stores the total length of the block.
+ * 2. (`clientSeqNumbers[clientId]`): Stores only the total lengths of segments submitted by `clientId`. [see footnote]
+ *
+ * The reason both lists are necessary is that resolving the length of the block from the perspective of
+ * (clientId, refSeq) requires including both of the following types of segments:
+ * 1. Segments sequenced before `refSeq`
+ * 2. Segments submitted by `clientId`
+ *
+ * This is possible with the above bookkeeping, using:
+ *
+ * (length of the block at the minimum sequence number)
+ * + (partialLengths total length at refSeq)
+ * + (clientSeqNumbers total length at most recent op)
+ * - (clientSeqNumbers total length at refSeq)
+ *
+ * where the subtraction avoids double-counting segments submitted by clientId sequenced within the collab window.
+ *
+ * This algorithm scales roughly linearly with number of editing clients and the size of the collab window.
+ * (certain unlikely sequences of operations may introduce log factors on those variables)
+ *
+ * Note: there is some slight complication with clientSeqNumbers resulting from the possibility of different clients
+ * concurrently removing the same segment. See the field's documentation for more details.
  */
 export class PartialSequenceLengths {
-    constructor(minSeq) {
+    constructor(
+    /**
+     * The minimumSequenceNumber as defined by the collab window used in the last call to `update`,
+     * or if no such calls have been made, the one used on construction.
+    */
+    minSeq) {
         this.minSeq = minSeq;
+        /**
+         * Length of the block this PartialSequenceLength corresponds to when viewed at `minSeq`.
+         */
         this.minLength = 0;
+        /**
+         * Total number of segments in the subtree rooted at the block this PartialSequenceLength corresponds to.
+         */
         this.segmentCount = 0;
+        /**
+         * List of PartialSequenceLength objects--ordered by increasing seq--giving length information about
+         * the block associated with this PartialSequenceLengths object.
+         *
+         * `partialLengths[i].len` contains the length of this block considering only sequenced segments with
+         * `sequenceNumber <= partialLengths[i].seq`.
+         */
         this.partialLengths = [];
+        /**
+         * clientSeqNumbers[clientId] is a list of partial lengths for sequenced ops which either:
+         * - were submitted by `clientId`.
+         * - deleted a range containing segments that were concurrently deleted by `clientId`
+         *
+         * The second case is referred to as the "overlapping delete" case. It is necessary to avoid double-counting
+         * the removal of those segments in queries including clientId.
+         */
         this.clientSeqNumbers = [];
     }
-    static combine(mergeTree, block, collabWindow, recur = false) {
-        return PartialSequenceLengths.combineBranch(mergeTree, block, collabWindow, recur);
-    }
     /**
      * Combine the partial lengths of block's children
-     * @param block - an interior node; it is assumed that each interior node child of this block
-     * has its partials up to date
-     * @param collabWindow - segment window of the segment tree containing textSegmentBlock
+     * @param block - an interior node. If `recur` is false, it is assumed that each interior node child of this block
+     * has its partials up to date.
+     * @param collabWindow - segment window of the segment tree containing `block`.
+     * @param recur - whether to recursively compute partial lengths for internal children of `block`.
+     * This incurs more work, but gives correct bookkeeping in the case that a descendant in the merge tree has been
+     * modified without bubbling up the resulting partial length change to this block's partials.
      */
-    static combineBranch(mergeTree, block, collabWindow, recur = false) {
-        let combinedPartialLengths = new PartialSequenceLengths(collabWindow.minSeq);
-        PartialSequenceLengths.fromLeaves(combinedPartialLengths, block, collabWindow);
-        let prevPartial;
-        function cloneOverlapRemoveClients(oldTree) {
-            if (!oldTree) {
-                return undefined;
-            }
-            const newTree = new RedBlackTree(compareNumbers);
-            oldTree.map((bProp) => {
-                newTree.put(bProp.data.clientId, Object.assign({}, bProp.data));
-                return true;
-            });
-            return newTree;
-        }
-        function combineOverlapClients(a, b) {
-            const overlapRemoveClientsA = a.overlapRemoveClients;
-            if (overlapRemoveClientsA) {
-                if (b.overlapRemoveClients) {
-                    b.overlapRemoveClients.map((bProp) => {
-                        const aProp = overlapRemoveClientsA.get(bProp.key);
-                        if (aProp) {
-                            aProp.data.seglen += bProp.data.seglen;
-                        }
-                        else {
-                            overlapRemoveClientsA.put(bProp.data.clientId, Object.assign({}, bProp.data));
-                        }
-                        return true;
-                    });
-                }
-            }
-            else {
-                a.overlapRemoveClients = cloneOverlapRemoveClients(b.overlapRemoveClients);
-            }
-        }
-        function addNext(partialLength) {
-            const seq = partialLength.seq;
-            let pLen = 0;
-            if (prevPartial) {
-                if (prevPartial.seq === partialLength.seq) {
-                    prevPartial.seglen += partialLength.seglen;
-                    prevPartial.len += partialLength.seglen;
-                    combineOverlapClients(prevPartial, partialLength);
-                    return;
-                }
-                else {
-                    pLen = prevPartial.len;
-                    // Previous sequence number is finished
-                    combinedPartialLengths.addClientSeqNumberFromPartial(prevPartial);
-                }
-            }
-            prevPartial = {
-                clientId: partialLength.clientId,
-                len: pLen + partialLength.seglen,
-                overlapRemoveClients: cloneOverlapRemoveClients(partialLength.overlapRemoveClients),
-                seglen: partialLength.seglen,
-                seq,
-            };
-            combinedPartialLengths.partialLengths.push(prevPartial);
-        }
+    static combine(block, collabWindow, recur = false) {
+        var _a;
+        const leafPartialLengths = PartialSequenceLengths.fromLeaves(block, collabWindow);
+        let hasInternalChild = false;
         const childPartials = [];
         for (let i = 0; i < block.childCount; i++) {
             const child = block.children[i];
             if (!child.isLeaf()) {
-                const childBlock = child;
+                hasInternalChild = true;
                 if (recur) {
-                    childBlock.partialLengths =
-                        PartialSequenceLengths.combine(mergeTree, childBlock, collabWindow, true);
+                    child.partialLengths =
+                        PartialSequenceLengths.combine(child, collabWindow, true);
                 }
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                childPartials.push(childBlock.partialLengths);
+                childPartials.push(child.partialLengths);
             }
         }
-        let childPartialsLen = childPartials.length;
-        if (childPartialsLen !== 0) {
-            // Some children are interior nodes
-            if (combinedPartialLengths.partialLengths.length > 0) {
+        // If there are no internal children, the PartialSequenceLengths returns from `fromLeaves` is exactly correct.
+        // Otherwise, we must additively combine all of the children partial lengths to get this block's totals.
+        const combinedPartialLengths = hasInternalChild ? new PartialSequenceLengths(collabWindow.minSeq) : leafPartialLengths;
+        if (hasInternalChild) {
+            if (leafPartialLengths.partialLengths.length > 0) {
                 // Some children were leaves; add combined partials from these segments
-                childPartials.push(combinedPartialLengths);
-                childPartialsLen++;
-                combinedPartialLengths = new PartialSequenceLengths(collabWindow.minSeq);
+                childPartials.push(leafPartialLengths);
             }
-            const indices = new Array(childPartialsLen);
-            const childPartialsCounts = new Array(childPartialsLen);
+            const childPartialsLen = childPartials.length;
+            const childPartialLengths = [];
             for (let i = 0; i < childPartialsLen; i++) {
-                indices[i] = 0;
-                childPartialsCounts[i] = childPartials[i].partialLengths.length;
-                combinedPartialLengths.minLength += childPartials[i].minLength;
-                combinedPartialLengths.segmentCount += childPartials[i].segmentCount;
-            }
-            let outerIndexOfEarliest = 0;
-            let earliestPartialLength;
-            while (outerIndexOfEarliest >= 0) {
-                outerIndexOfEarliest = -1;
-                for (let k = 0; k < childPartialsLen; k++) {
-                    // Find next earliest sequence number
-                    if (indices[k] < childPartialsCounts[k]) {
-                        const cpLen = childPartials[k].partialLengths[indices[k]];
-                        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                        if ((outerIndexOfEarliest < 0) || (cpLen.seq < earliestPartialLength.seq)) {
-                            outerIndexOfEarliest = k;
-                            earliestPartialLength = cpLen;
-                        }
-                    }
+                const { segmentCount, minLength, partialLengths } = childPartials[i];
+                combinedPartialLengths.segmentCount += segmentCount;
+                combinedPartialLengths.minLength += minLength;
+                childPartialLengths.push(partialLengths);
+            }
+            // All child PartialSequenceLengths are now sorted temporally (i.e. by seq). Since
+            // a given MergeTree operation can affect multiple segments, there may be multiple entries
+            // for a given seq. We run through them in order, coalescing all length information for a given
+            // seq together into `combinedPartialLengths`.
+            let currentPartial;
+            for (const partialLength of mergeSortedListsBySeq(childPartialLengths)) {
+                if (!currentPartial || currentPartial.seq !== partialLength.seq) {
+                    // Start a new seq entry.
+                    currentPartial = Object.assign(Object.assign({}, partialLength), { len: ((_a = currentPartial === null || currentPartial === void 0 ? void 0 : currentPartial.len) !== null && _a !== void 0 ? _a : 0) + partialLength.seglen, overlapRemoveClients: cloneOverlapRemoveClients(partialLength.overlapRemoveClients) });
+                    combinedPartialLengths.partialLengths.push(currentPartial);
                 }
-                if (outerIndexOfEarliest >= 0) {
-                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                    addNext(earliestPartialLength);
-                    indices[outerIndexOfEarliest]++;
+                else {
+                    // Update existing entry
+                    currentPartial.seglen += partialLength.seglen;
+                    currentPartial.len += partialLength.seglen;
+                    combineOverlapClients(currentPartial, partialLength);
                 }
             }
-            // Add client entry for last partial, if any
-            if (prevPartial) {
-                combinedPartialLengths.addClientSeqNumberFromPartial(prevPartial);
+            for (const partial of combinedPartialLengths.partialLengths) {
+                combinedPartialLengths.addClientSeqNumberFromPartial(partial);
             }
         }
         // TODO: incremental zamboni during build
@@ -178,8 +174,12 @@ export class PartialSequenceLengths {
         }
         return combinedPartialLengths;
     }
-    static fromLeaves(combinedPartialLengths, block, collabWindow) {
-        combinedPartialLengths.minLength = 0;
+    /**
+     * @returns a PartialSequenceLengths structure which tracks only lengths of leaf children of the provided
+     * IMergeBlock.
+     */
+    static fromLeaves(block, collabWindow) {
+        const combinedPartialLengths = new PartialSequenceLengths(collabWindow.minSeq);
         combinedPartialLengths.segmentCount = block.childCount;
         function seqLTE(seq, minSeq) {
             return seq !== undefined && seq !== UnassignedSequenceNumber && seq <= minSeq;
@@ -222,6 +222,7 @@ export class PartialSequenceLengths {
         if (PartialSequenceLengths.options.verify) {
             combinedPartialLengths.verify();
         }
+        return combinedPartialLengths;
     }
     static getOverlapClients(overlapClientIds, seglen) {
         const bst = new RedBlackTree(compareNumbers);
@@ -247,7 +248,14 @@ export class PartialSequenceLengths {
                 PartialSequenceLengths.getOverlapClients(overlapRemoveClientIds, seglen);
         }
     }
+    /**
+     * Inserts length information about the insertion of `segment` into `combinedPartialLengths.partialLengths`.
+     * Does not update the clientSeqNumbers field to account for this segment.
+     * If `removalInfo` is defined, this operation updates the bookkeeping to account for the removal of this
+     * segment at the removedSeq instead.
+     */
     static insertSegment(combinedPartialLengths, segment, removalInfo) {
+        var _a;
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         let seq = segment.seq;
         let segmentLen = segment.cachedLength;
@@ -273,31 +281,34 @@ export class PartialSequenceLengths {
                 break;
             }
         }
-        if ((indexFirstGTE < seqPartialsLen) && (seqPartials[indexFirstGTE].seq === seq)) {
-            seqPartials[indexFirstGTE].seglen += segmentLen;
+        let partialLengthEntry = ((_a = seqPartials[indexFirstGTE]) === null || _a === void 0 ? void 0 : _a.seq) === seq ? seqPartials[indexFirstGTE] : undefined;
+        if (partialLengthEntry !== undefined) {
+            // Existing entry at this seq--this occurs for ops that insert/delete more than one segment.
+            partialLengthEntry.seglen += segmentLen;
             if (removeClientOverlap) {
                 PartialSequenceLengths.accumulateRemoveClientOverlap(seqPartials[indexFirstGTE], removeClientOverlap, segmentLen);
             }
         }
         else {
-            let pLen;
-            if (removeClientOverlap) {
-                const overlapClients = PartialSequenceLengths.getOverlapClients(removeClientOverlap, segmentLen);
-                pLen = { seq, clientId, len: 0, seglen: segmentLen, overlapRemoveClients: overlapClients };
-            }
-            else {
-                pLen = { seq, clientId, len: 0, seglen: segmentLen };
-            }
+            partialLengthEntry = {
+                seq,
+                clientId,
+                len: 0,
+                seglen: segmentLen,
+                overlapRemoveClients: removeClientOverlap
+                    ? PartialSequenceLengths.getOverlapClients(removeClientOverlap, segmentLen)
+                    : undefined,
+            };
             if (indexFirstGTE < seqPartialsLen) {
                 // Shift entries with greater sequence numbers
                 // TODO: investigate performance improvement using BST
                 for (let k = seqPartialsLen; k > indexFirstGTE; k--) {
                     seqPartials[k] = seqPartials[k - 1];
                 }
-                seqPartials[indexFirstGTE] = pLen;
+                seqPartials[indexFirstGTE] = partialLengthEntry;
             }
             else {
-                seqPartials.push(pLen);
+                seqPartials.push(partialLengthEntry);
             }
         }
     }
@@ -318,11 +329,11 @@ export class PartialSequenceLengths {
                 penultPartialLen = pLen;
             }
         }
+        const len = penultPartialLen !== undefined ? penultPartialLen.len + seqSeglen : seqSeglen;
         if (seqPartialLen === undefined) {
-            // len will be assigned below, making this assertion true.
-            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
             seqPartialLen = {
                 clientId,
+                len,
                 seglen: seqSeglen,
                 seq,
             };
@@ -330,19 +341,15 @@ export class PartialSequenceLengths {
         }
         else {
             seqPartialLen.seglen = seqSeglen;
+            seqPartialLen.len = len;
             // Assert client id matches
         }
-        if (penultPartialLen !== undefined) {
-            seqPartialLen.len = seqPartialLen.seglen + penultPartialLen.len;
-        }
-        else {
-            seqPartialLen.len = seqPartialLen.seglen;
-        }
     }
     // Assume: seq is latest sequence number; no structural change to sub-tree, but a segment
-    // with sequence number seq has been added within the sub-tree
+    // with sequence number seq has been added within the sub-tree (and `update` has been called
+    // on all descendant PartialSequenceLengths)
     // TODO: assert client id matches
-    update(mergeTree, node, seq, clientId, collabWindow) {
+    update(node, seq, clientId, collabWindow) {
         let seqSeglen = 0;
         let segCount = 0;
         // Compute length for seq across children
@@ -406,6 +413,8 @@ export class PartialSequenceLengths {
                     pLen += cliLatest.len;
                     const precedingCliIndex = this.cliLatestLEQ(clientId, refSeq);
                     if (precedingCliIndex >= 0) {
+                        // Subtract out double-counted lengths: segments still in the collab window but before
+                        // the refSeq submitted by the client we're querying for were counted in each addition above.
                         pLen -= cliSeq[precedingCliIndex].len;
                     }
                 }
@@ -468,6 +477,7 @@ export class PartialSequenceLengths {
             return minLength;
         }
         this.minLength += copyDown(this.partialLengths);
+        this.minSeq = segmentWindow.minSeq;
         // eslint-disable-next-line @typescript-eslint/no-for-in-array, guard-for-in, no-restricted-syntax
         for (const clientId in this.clientSeqNumbers) {
             const cliPartials = this.clientSeqNumbers[clientId];
@@ -487,7 +497,7 @@ export class PartialSequenceLengths {
         }
         cli.push({ seq, len: pLen, seglen });
     }
-    // Assumes sequence number already coalesced
+    // Assumes sequence number already coalesced and that this is called in increasing `seq` order.
     addClientSeqNumberFromPartial(partialLength) {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         this.addClientSeqNumber(partialLength.clientId, partialLength.seq, partialLength.seglen);
@@ -588,4 +598,86 @@ PartialSequenceLengths.options = {
     verify: false,
     zamboni: true,
 };
+/**
+ * Clones an `overlapRemoveClients` red-black tree.
+ */
+function cloneOverlapRemoveClients(oldTree) {
+    if (!oldTree) {
+        return undefined;
+    }
+    const newTree = new RedBlackTree(compareNumbers);
+    oldTree.map((bProp) => {
+        newTree.put(bProp.data.clientId, Object.assign({}, bProp.data));
+        return true;
+    });
+    return newTree;
+}
+/**
+ * Combines the `overlapRemoveClients` field of two `PartialSequenceLength` objects,
+ * modifying the first PartialSequenceLength's bookkeeping in-place.
+ *
+ * Combination is performed additively on `seglen` on a per-client basis.
+ */
+function combineOverlapClients(a, b) {
+    const overlapRemoveClientsA = a.overlapRemoveClients;
+    if (overlapRemoveClientsA) {
+        if (b.overlapRemoveClients) {
+            b.overlapRemoveClients.map((bProp) => {
+                const aProp = overlapRemoveClientsA.get(bProp.key);
+                if (aProp) {
+                    aProp.data.seglen += bProp.data.seglen;
+                }
+                else {
+                    overlapRemoveClientsA.put(bProp.data.clientId, Object.assign({}, bProp.data));
+                }
+                return true;
+            });
+        }
+    }
+    else {
+        a.overlapRemoveClients = cloneOverlapRemoveClients(b.overlapRemoveClients);
+    }
+}
+/**
+ * Given a collection of PartialSequenceLength lists--each sorted by sequence number--returns an iterable that yields
+ * each PartialSequenceLength in sequence order.
+ *
+ * This is equivalent to flattening the input list and sorting it by sequence number. If the number of lists to merge is
+ * a constant, however, this approach is advantageous asymptotically.
+ */
+function mergeSortedListsBySeq(lists) {
+    class PartialSequenceLengthIterator {
+        constructor(sublists) {
+            this.sublists = sublists;
+            this.nextSmallestIndex = new Array(sublists.length);
+            for (let i = 0; i < sublists.length; i++) {
+                this.nextSmallestIndex[i] = 0;
+            }
+        }
+        next() {
+            const len = this.sublists.length;
+            let currentMin;
+            let currentMinIndex;
+            for (let i = 0; i < len; i++) {
+                const candidateIndex = this.nextSmallestIndex[i];
+                if (candidateIndex < this.sublists[i].length) {
+                    const candidate = this.sublists[i][candidateIndex];
+                    if (!currentMin || candidate.seq < currentMin.seq) {
+                        currentMin = candidate;
+                        currentMinIndex = i;
+                    }
+                }
+            }
+            if (currentMin) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                this.nextSmallestIndex[currentMinIndex]++;
+                return { value: currentMin, done: false };
+            }
+            else {
+                return { value: undefined, done: true };
+            }
+        }
+    }
+    return { [Symbol.iterator]: () => new PartialSequenceLengthIterator(lists) };
+}
 //# sourceMappingURL=partialLengths.js.map