@fluidframework/merge-tree 2.23.0 → 2.30.0

package/lib/perspective.d.ts

@@ -4,86 +4,124 @@
  */
 import { type MergeTree } from "./mergeTree.js";
 import { type ISegmentLeaf } from "./mergeTreeNodes.js";
-import { type IInsertionInfo, type IMoveInfo, type IRemovalInfo, type SegmentWithInfo } from "./segmentInfos.js";
+import type { OperationStamp, InsertOperationStamp, RemoveOperationStamp } from "./stamps.js";
 /**
- * Provides a view of a MergeTree from the perspective of a specific client at a specific sequence number.
+ * A perspective which includes some subset of operations known to the local client.
+ *
+ * This helps the local client reason about the state of other clients when they issued an operation.
  */
 export interface Perspective {
-    nextSegment(segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;
-    previousSegment(segment: ISegmentLeaf): ISegmentLeaf;
-}
-/**
- * Represents a point in time inside the collaboration window.
- */
-export interface SeqTime {
-    refSeq: number;
-    localSeq?: number;
-}
-/**
- * Implementation of {@link Perspective}.
- * @privateRemarks
- * TODO:AB#29765: This class does not support non-local-client perspectives, but should.
- */
-export declare class PerspectiveImpl implements Perspective {
-    private readonly _mergeTree;
-    private readonly _seqTime;
     /**
-     * @param _mergeTree - The {@link MergeTree} to view.
-     * @param _seqTime - The latest sequence number and local sequence number to consider.
+     * The sequence number last seen from this perspective. Same concept as `ISequencedDocumentMessage.referenceSequenceNumber`.
+     * @privateRemarks
+     * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends
+     * on the (refSeq, clientId, localSeq?) representation of perspectives.
+     */
+    readonly refSeq: number;
+    /**
+     * The client id for this perspective.
+     * @privateRemarks
+     * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends
+     * on the (refSeq, clientId, localSeq?) representation of perspectives.
+     */
+    readonly clientId: number;
+    /**
+     * When this is a local perspective, the local sequence number last seen from this perspective.
+     *
+     * Perspectives with defined `localSeq` values are useful in reconnection flows, where the local client may need to resend some
+     * of its ops after rederiving their new equivalents.
+     * @privateRemarks
+     * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends
+     * on the (refSeq, clientId, localSeq?) representation of perspectives.
+     */
+    readonly localSeq?: number;
+    /**
+     * @returns Whether the segment is present (visible) from this perspective
+     */
+    isSegmentPresent(segment: ISegmentLeaf): boolean;
+    /**
+     * @returns Whether this perspective has seen the given operation.
      */
-    constructor(_mergeTree: MergeTree, _seqTime: SeqTime);
+    hasOccurred(stamp: RemoveOperationStamp | InsertOperationStamp): boolean;
+    nextSegment(mergeTree: MergeTree, segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;
+    previousSegment(mergeTree: MergeTree, segment: ISegmentLeaf): ISegmentLeaf;
+}
+declare abstract class PerspectiveBase {
+    abstract hasOccurred(stamp: RemoveOperationStamp | InsertOperationStamp): boolean;
     /**
      * Returns the immediately adjacent segment in the specified direction from this perspective.
      * There may actually be multiple segments between the given segment and the returned segment,
-     * but they were either inserted after this perspective, or have been removed or moved before this perspective.
+     * but they were either inserted after this perspective, or have been removed before this perspective.
      *
      * @param segment - The segment to start from.
      * @param forward - The direction to search.
      * @returns the next segment in the specified direction, or the start or end of the tree if there is no next segment.
      */
-    nextSegment(segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;
+    nextSegment(mergeTree: MergeTree, segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;
     /**
      * Finds the segment prior to the given segment.
      * @param segment - The segment to start from.
      * @returns the previous segment, or the start of the tree if there is no previous segment.
      * @remarks This is a convenient equivalent to calling `nextSegment(segment, false)`.
      */
-    previousSegment(segment: ISegmentLeaf): ISegmentLeaf;
+    previousSegment(mergeTree: MergeTree, segment: ISegmentLeaf): ISegmentLeaf;
+    isSegmentPresent(seg: ISegmentLeaf): boolean;
 }
 /**
- * Determines if the given segment was removed before the given perspective.
- * @param seg - The segment to check.
- * @param seq - The latest sequence number to consider.
- * @param localSeq - The latest local sequence number to consider.
- * @returns true iff this segment was removed in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes edits at or before some reference sequence number alongside all edits from some particular client.
+ *
+ * @remarks
+ * This works for both the local client as well as remote clients since refSeq-based checks disallow unacked edits, but the clientId check
+ * catches unacked edits from the local client.
  */
-export declare function wasRemovedBefore(seg: SegmentWithInfo<IInsertionInfo & IRemovalInfo>, { refSeq, localSeq }: SeqTime): boolean;
+export declare class PriorPerspective extends PerspectiveBase implements Perspective {
+    readonly refSeq: number;
+    readonly clientId: number;
+    constructor(refSeq: number, clientId: number);
+    hasOccurred(stamp: OperationStamp): boolean;
+}
 /**
- * Determines if the given segment was moved before the given perspective.
- * @param seg - The segment to check.
- * @param refSeq - The latest sequence number to consider.
- * @param localSeq - The latest local sequence number to consider.
- * @returns true iff this segment was moved (aka obliterated) in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes edits which were either:
+ * - acked and at or before some reference sequence number
+ * - unacked, but at or before some local sequence number
+ *
+ * This is a useful perspective when the local client is in the process of reconnecting, since it must
+ * rederive positions for unacked ops while only considering a portion of its own edits as having been applied.
  */
-export declare function wasMovedBefore(seg: SegmentWithInfo<IInsertionInfo & IMoveInfo>, { refSeq, localSeq }: SeqTime): boolean;
+export declare class LocalReconnectingPerspective extends PerspectiveBase implements Perspective {
+    readonly refSeq: number;
+    readonly clientId: number;
+    readonly localSeq: number;
+    constructor(refSeq: number, clientId: number, localSeq: number);
+    hasOccurred(stamp: OperationStamp): boolean;
+}
 /**
- * See {@link wasRemovedBefore} and {@link wasMovedBefore}.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes all known edits.
+ *
+ * This is the perspective that the application sees.
+ * @remarks
+ * This can be represented using {@link PriorPerspective} with a refSeq of `Number.MAX_SAFE_INTEGER`, but having an explicit
+ * variant of this perspective renders extra refSeq checks unnecessary and is a bit easier to read.
  */
-export declare function wasRemovedOrMovedBefore(seg: ISegmentLeaf, seqTime: SeqTime): boolean;
+export declare class LocalDefaultPerspective extends PerspectiveBase implements Perspective {
+    readonly clientId: number;
+    readonly refSeq: number;
+    constructor(clientId: number);
+    hasOccurred(_stamp: OperationStamp): boolean;
+}
 /**
- * Determines if the given segment is present in the given perspective.
- * @param seg - The segment to check.
- * @param seqTime - The latest sequence number and local sequence number to consider.
- * @returns true iff this segment was inserted before the given perspective,
- * and it was not removed or moved in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective dictating whether segments are 'visible' to a remote obliterate operation.
+ *
+ * NOTE: Beware that partial lengths doesn't support this perspective, in the sense that consulting partial lengths' for the length of a block
+ * can give different results than summing the lengths of present segments in that block.
+ * This ends up not affecting the current obliterate implementation (which has some special casing in the mapRange calls it uses),
+ * but use with caution.
  */
-export declare function isSegmentPresent(seg: ISegmentLeaf, seqTime: SeqTime): boolean;
+export declare class RemoteObliteratePerspective extends PerspectiveBase implements Perspective {
+    readonly clientId: number;
+    readonly refSeq: number;
+    constructor(clientId: number);
+    hasOccurred(stamp: InsertOperationStamp | RemoveOperationStamp): boolean;
+}
+export {};
 //# sourceMappingURL=perspective.d.ts.map

package/lib/perspective.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perspective.d.ts","sourceRoot":"","sources":["../src/perspective.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAIN,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACpE,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAMjD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAN1B;;;OAGG;gBAEe,UAAU,EAAE,SAAS,EACrB,QAAQ,EAAE,OAAO;IAGnC;;;;;;;;OAQG;IACI,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,OAAc,GAAG,YAAY;IAYhF;;;;;OAKG;IACI,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY;CAG3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,eAAe,CAAC,cAAc,GAAG,YAAY,CAAC,EACnD,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,OAAO,GAC3B,OAAO,CAST;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,eAAe,CAAC,cAAc,GAAG,SAAS,CAAC,EAChD,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,OAAO,GAC3B,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAMpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAsB7E"}
+{"version":3,"file":"perspective.d.ts","sourceRoot":"","sources":["../src/perspective.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE9F;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;IAEjD;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,GAAG,OAAO,CAAC;IAEzE,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IAC1F,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;CAC3E;AAED,uBAAe,eAAe;IAC7B,QAAQ,CAAC,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,GAAG,OAAO;IAEjF;;;;;;;;OAQG;IACI,WAAW,CACjB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,OAAc,GACrB,YAAY;IAYf;;;;;OAKG;IACI,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAI1E,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO;CAsDnD;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,eAAgB,YAAW,WAAW;aAE1D,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;gBADhB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM;IAK1B,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;CAKlD;AAED;;;;;;;GAOG;AACH,qBAAa,4BAA6B,SAAQ,eAAgB,YAAW,WAAW;aAEtE,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,MAAM;gBAFhB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM;IAK1B,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;CAMlD;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,eAAgB,YAAW,WAAW;aAG/C,QAAQ,EAAE,MAAM;IAFnD,SAAgB,MAAM,SAA2B;gBAEd,QAAQ,EAAE,MAAM;IAI5C,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO;CAGnD;AAED;;;;;;;GAOG;AACH,qBAAa,2BAA4B,SAAQ,eAAgB,YAAW,WAAW;aAG1D,QAAQ,EAAE,MAAM;IAF5C,SAAgB,MAAM,SAA2B;gBAErB,QAAQ,EAAE,MAAM;IAIrC,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,GAAG,OAAO;CAY/E"}

package/lib/perspective.js

@@ -2,43 +2,31 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { UnassignedSequenceNumber } from "./constants.js";
+import { LocalClientId, UnassignedSequenceNumber } from "./constants.js";
 import { LeafAction, backwardExcursion, forwardExcursion } from "./mergeTreeNodeWalk.js";
 import { seqLTE } from "./mergeTreeNodes.js";
-import { isInserted, isMoved, isRemoved, } from "./segmentInfos.js";
-/**
- * Implementation of {@link Perspective}.
- * @privateRemarks
- * TODO:AB#29765: This class does not support non-local-client perspectives, but should.
- */
-export class PerspectiveImpl {
-    /**
-     * @param _mergeTree - The {@link MergeTree} to view.
-     * @param _seqTime - The latest sequence number and local sequence number to consider.
-     */
-    constructor(_mergeTree, _seqTime) {
-        this._mergeTree = _mergeTree;
-        this._seqTime = _seqTime;
-    }
+import { isInserted, toMoveInfo, toRemovalInfo } from "./segmentInfos.js";
+import * as opstampUtils from "./stamps.js";
+class PerspectiveBase {
     /**
      * Returns the immediately adjacent segment in the specified direction from this perspective.
      * There may actually be multiple segments between the given segment and the returned segment,
-     * but they were either inserted after this perspective, or have been removed or moved before this perspective.
+     * but they were either inserted after this perspective, or have been removed before this perspective.
      *
      * @param segment - The segment to start from.
      * @param forward - The direction to search.
      * @returns the next segment in the specified direction, or the start or end of the tree if there is no next segment.
      */
-    nextSegment(segment, forward = true) {
+    nextSegment(mergeTree, segment, forward = true) {
         let next;
         const action = (seg) => {
-            if (isSegmentPresent(seg, this._seqTime)) {
+            if (this.isSegmentPresent(seg)) {
                 next = seg;
                 return LeafAction.Exit;
             }
         };
         (forward ? forwardExcursion : backwardExcursion)(segment, action);
-        return next ?? (forward ? this._mergeTree.endOfTree : this._mergeTree.startOfTree);
+        return next ?? (forward ? mergeTree.endOfTree : mergeTree.startOfTree);
     }
     /**
      * Finds the segment prior to the given segment.
@@ -46,83 +34,134 @@ export class PerspectiveImpl {
      * @returns the previous segment, or the start of the tree if there is no previous segment.
      * @remarks This is a convenient equivalent to calling `nextSegment(segment, false)`.
      */
-    previousSegment(segment) {
-        return this.nextSegment(segment, false);
+    previousSegment(mergeTree, segment) {
+        return this.nextSegment(mergeTree, segment, false);
+    }
+    isSegmentPresent(seg) {
+        const insert = {
+            type: "insert",
+            clientId: seg.clientId,
+            seq: seg.seq,
+            localSeq: seg.localSeq,
+        };
+        if (isInserted(seg) && !this.hasOccurred(insert)) {
+            return false;
+        }
+        const removes = [];
+        const removalInfo = toRemovalInfo(seg);
+        if (removalInfo !== undefined) {
+            removes.push(...removalInfo.removedClientIds.map((clientId) => (clientId === LocalClientId || clientId === 0) &&
+                removalInfo.localRemovedSeq !== undefined
+                ? {
+                    type: "setRemove",
+                    seq: UnassignedSequenceNumber,
+                    clientId,
+                    localSeq: removalInfo.localRemovedSeq,
+                }
+                : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    { type: "setRemove", seq: removalInfo.removedSeq, clientId }));
+        }
+        const moveInfo = toMoveInfo(seg);
+        if (moveInfo !== undefined) {
+            removes.push(...moveInfo.movedClientIds.map((clientId, index) => (clientId === LocalClientId || clientId === 0) &&
+                moveInfo.localMovedSeq !== undefined
+                ? {
+                    type: "sliceRemove",
+                    seq: UnassignedSequenceNumber,
+                    clientId,
+                    localSeq: moveInfo.localMovedSeq,
+                }
+                : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    { type: "setRemove", seq: moveInfo.movedSeqs[index], clientId }));
+        }
+        if (removes.some((remove) => this.hasOccurred(remove))) {
+            return false;
+        }
+        return true;
     }
 }
 /**
- * Determines if the given segment was removed before the given perspective.
- * @param seg - The segment to check.
- * @param seq - The latest sequence number to consider.
- * @param localSeq - The latest local sequence number to consider.
- * @returns true iff this segment was removed in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes edits at or before some reference sequence number alongside all edits from some particular client.
+ *
+ * @remarks
+ * This works for both the local client as well as remote clients since refSeq-based checks disallow unacked edits, but the clientId check
+ * catches unacked edits from the local client.
  */
-export function wasRemovedBefore(seg, { refSeq, localSeq }) {
-    if (seg.removedSeq === UnassignedSequenceNumber &&
-        localSeq !== undefined &&
-        seg.localRemovedSeq !== undefined) {
-        return seg.localRemovedSeq <= localSeq;
+export class PriorPerspective extends PerspectiveBase {
+    constructor(refSeq, clientId) {
+        super();
+        this.refSeq = refSeq;
+        this.clientId = clientId;
+    }
+    hasOccurred(stamp) {
+        const predatesViaRefSeq = seqLTE(stamp.seq, this.refSeq);
+        const predatesViaSameClient = stamp.clientId === this.clientId;
+        return predatesViaRefSeq || predatesViaSameClient;
     }
-    return seg.removedSeq !== undefined && seqLTE(seg.removedSeq, refSeq);
 }
 /**
- * Determines if the given segment was moved before the given perspective.
- * @param seg - The segment to check.
- * @param refSeq - The latest sequence number to consider.
- * @param localSeq - The latest local sequence number to consider.
- * @returns true iff this segment was moved (aka obliterated) in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes edits which were either:
+ * - acked and at or before some reference sequence number
+ * - unacked, but at or before some local sequence number
+ *
+ * This is a useful perspective when the local client is in the process of reconnecting, since it must
+ * rederive positions for unacked ops while only considering a portion of its own edits as having been applied.
  */
-export function wasMovedBefore(seg, { refSeq, localSeq }) {
-    if (seg.movedSeq === UnassignedSequenceNumber &&
-        localSeq !== undefined &&
-        seg.localMovedSeq !== undefined) {
-        return seg.localMovedSeq <= localSeq;
+export class LocalReconnectingPerspective extends PerspectiveBase {
+    constructor(refSeq, clientId, localSeq) {
+        super();
+        this.refSeq = refSeq;
+        this.clientId = clientId;
+        this.localSeq = localSeq;
+    }
+    hasOccurred(stamp) {
+        const predatesViaRefSeq = seqLTE(stamp.seq, this.refSeq);
+        const predatesViaLocalSeq = stamp.localSeq !== undefined && stamp.localSeq <= this.localSeq;
+        return predatesViaRefSeq || predatesViaLocalSeq;
     }
-    return seg.movedSeq !== undefined && seqLTE(seg.movedSeq, refSeq);
 }
 /**
- * See {@link wasRemovedBefore} and {@link wasMovedBefore}.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes all known edits.
+ *
+ * This is the perspective that the application sees.
+ * @remarks
+ * This can be represented using {@link PriorPerspective} with a refSeq of `Number.MAX_SAFE_INTEGER`, but having an explicit
+ * variant of this perspective renders extra refSeq checks unnecessary and is a bit easier to read.
  */
-export function wasRemovedOrMovedBefore(seg, seqTime) {
-    return (isInserted(seg) &&
-        ((isRemoved(seg) && wasRemovedBefore(seg, seqTime)) ||
-            (isMoved(seg) && wasMovedBefore(seg, seqTime))));
+export class LocalDefaultPerspective extends PerspectiveBase {
+    constructor(clientId) {
+        super();
+        this.clientId = clientId;
+        this.refSeq = Number.MAX_SAFE_INTEGER;
+    }
+    hasOccurred(_stamp) {
+        return true;
+    }
 }
 /**
- * Determines if the given segment is present in the given perspective.
- * @param seg - The segment to check.
- * @param seqTime - The latest sequence number and local sequence number to consider.
- * @returns true iff this segment was inserted before the given perspective,
- * and it was not removed or moved in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective dictating whether segments are 'visible' to a remote obliterate operation.
+ *
+ * NOTE: Beware that partial lengths doesn't support this perspective, in the sense that consulting partial lengths' for the length of a block
+ * can give different results than summing the lengths of present segments in that block.
+ * This ends up not affecting the current obliterate implementation (which has some special casing in the mapRange calls it uses),
+ * but use with caution.
  */
-export function isSegmentPresent(seg, seqTime) {
-    const { refSeq, localSeq } = seqTime;
-    // If seg.seq is undefined, then this segment has existed since minSeq.
-    // It may have been moved or removed since.
-    if (isInserted(seg)) {
-        if (seg.seq !== UnassignedSequenceNumber) {
-            if (!seqLTE(seg.seq, refSeq)) {
-                return false;
-            }
-        }
-        else if (seg.localSeq !== undefined && // seg.seq === UnassignedSequenceNumber
-            // If the current perspective does not include local sequence numbers,
-            // then this segment does not exist yet.
-            (localSeq === undefined || seg.localSeq > localSeq)) {
+export class RemoteObliteratePerspective extends PerspectiveBase {
+    constructor(clientId) {
+        super();
+        this.clientId = clientId;
+        this.refSeq = Number.MAX_SAFE_INTEGER;
+    }
+    hasOccurred(stamp) {
+        // Local-only removals are not visible to an obliterate operation, since this means the local removal was concurrent
+        // to a remote obliterate and we may need to mark the segment appropriately to reflect this overlapping remove.
+        // Every other type of operation is visible: obliterates do not affect segments that have already been removed and acked,
+        // and they always affect segments within their range that have not been removed, even if those segments were inserted
+        // after the obliterate's refSeq.
+        if (stamp.type !== "insert" && opstampUtils.isLocal(stamp)) {
             return false;
         }
+        return true;
     }
-    if (wasRemovedOrMovedBefore(seg, seqTime)) {
-        return false;
-    }
-    return true;
 }
 //# sourceMappingURL=perspective.js.map

package/lib/perspective.js.map

@@ -1 +1 @@
-{"version":3,"file":"perspective.js","sourceRoot":"","sources":["../src/perspective.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { UnassignedSequenceNumber } from \"./constants.js\";\nimport { type MergeTree } from \"./mergeTree.js\";\nimport { LeafAction, backwardExcursion, forwardExcursion } from \"./mergeTreeNodeWalk.js\";\nimport { seqLTE, type ISegmentLeaf } from \"./mergeTreeNodes.js\";\nimport {\n\tisInserted,\n\tisMoved,\n\tisRemoved,\n\ttype IInsertionInfo,\n\ttype IMoveInfo,\n\ttype IRemovalInfo,\n\ttype SegmentWithInfo,\n} from \"./segmentInfos.js\";\n\n/**\n * Provides a view of a MergeTree from the perspective of a specific client at a specific sequence number.\n */\nexport interface Perspective {\n\tnextSegment(segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;\n\tpreviousSegment(segment: ISegmentLeaf): ISegmentLeaf;\n}\n\n/**\n * Represents a point in time inside the collaboration window.\n */\nexport interface SeqTime {\n\trefSeq: number;\n\tlocalSeq?: number;\n}\n\n/**\n * Implementation of {@link Perspective}.\n * @privateRemarks\n * TODO:AB#29765: This class does not support non-local-client perspectives, but should.\n */\nexport class PerspectiveImpl implements Perspective {\n\t/**\n\t * @param _mergeTree - The {@link MergeTree} to view.\n\t * @param _seqTime - The latest sequence number and local sequence number to consider.\n\t */\n\tpublic constructor(\n\t\tprivate readonly _mergeTree: MergeTree,\n\t\tprivate readonly _seqTime: SeqTime,\n\t) {}\n\n\t/**\n\t * Returns the immediately adjacent segment in the specified direction from this perspective.\n\t * There may actually be multiple segments between the given segment and the returned segment,\n\t * but they were either inserted after this perspective, or have been removed or moved before this perspective.\n\t *\n\t * @param segment - The segment to start from.\n\t * @param forward - The direction to search.\n\t * @returns the next segment in the specified direction, or the start or end of the tree if there is no next segment.\n\t */\n\tpublic nextSegment(segment: ISegmentLeaf, forward: boolean = true): ISegmentLeaf {\n\t\tlet next: ISegmentLeaf | undefined;\n\t\tconst action = (seg: ISegmentLeaf): boolean | undefined => {\n\t\t\tif (isSegmentPresent(seg, this._seqTime)) {\n\t\t\t\tnext = seg;\n\t\t\t\treturn LeafAction.Exit;\n\t\t\t}\n\t\t};\n\t\t(forward ? forwardExcursion : backwardExcursion)(segment, action);\n\t\treturn next ?? (forward ? this._mergeTree.endOfTree : this._mergeTree.startOfTree);\n\t}\n\n\t/**\n\t * Finds the segment prior to the given segment.\n\t * @param segment - The segment to start from.\n\t * @returns the previous segment, or the start of the tree if there is no previous segment.\n\t * @remarks This is a convenient equivalent to calling `nextSegment(segment, false)`.\n\t */\n\tpublic previousSegment(segment: ISegmentLeaf): ISegmentLeaf {\n\t\treturn this.nextSegment(segment, false);\n\t}\n}\n\n/**\n * Determines if the given segment was removed before the given perspective.\n * @param seg - The segment to check.\n * @param seq - The latest sequence number to consider.\n * @param localSeq - The latest local sequence number to consider.\n * @returns true iff this segment was removed in the given perspective.\n * @privateRemarks\n * TODO:AB#29765: This function does not support non-local-client perspectives, but should.\n */\nexport function wasRemovedBefore(\n\tseg: SegmentWithInfo<IInsertionInfo & IRemovalInfo>,\n\t{ refSeq, localSeq }: SeqTime,\n): boolean {\n\tif (\n\t\tseg.removedSeq === UnassignedSequenceNumber &&\n\t\tlocalSeq !== undefined &&\n\t\tseg.localRemovedSeq !== undefined\n\t) {\n\t\treturn seg.localRemovedSeq <= localSeq;\n\t}\n\treturn seg.removedSeq !== undefined && seqLTE(seg.removedSeq, refSeq);\n}\n\n/**\n * Determines if the given segment was moved before the given perspective.\n * @param seg - The segment to check.\n * @param refSeq - The latest sequence number to consider.\n * @param localSeq - The latest local sequence number to consider.\n * @returns true iff this segment was moved (aka obliterated) in the given perspective.\n * @privateRemarks\n * TODO:AB#29765: This function does not support non-local-client perspectives, but should.\n */\nexport function wasMovedBefore(\n\tseg: SegmentWithInfo<IInsertionInfo & IMoveInfo>,\n\t{ refSeq, localSeq }: SeqTime,\n): boolean {\n\tif (\n\t\tseg.movedSeq === UnassignedSequenceNumber &&\n\t\tlocalSeq !== undefined &&\n\t\tseg.localMovedSeq !== undefined\n\t) {\n\t\treturn seg.localMovedSeq <= localSeq;\n\t}\n\treturn seg.movedSeq !== undefined && seqLTE(seg.movedSeq, refSeq);\n}\n\n/**\n * See {@link wasRemovedBefore} and {@link wasMovedBefore}.\n * @privateRemarks\n * TODO:AB#29765: This function does not support non-local-client perspectives, but should.\n */\nexport function wasRemovedOrMovedBefore(seg: ISegmentLeaf, seqTime: SeqTime): boolean {\n\treturn (\n\t\tisInserted(seg) &&\n\t\t((isRemoved(seg) && wasRemovedBefore(seg, seqTime)) ||\n\t\t\t(isMoved(seg) && wasMovedBefore(seg, seqTime)))\n\t);\n}\n\n/**\n * Determines if the given segment is present in the given perspective.\n * @param seg - The segment to check.\n * @param seqTime - The latest sequence number and local sequence number to consider.\n * @returns true iff this segment was inserted before the given perspective,\n * and it was not removed or moved in the given perspective.\n * @privateRemarks\n * TODO:AB#29765: This function does not support non-local-client perspectives, but should.\n */\nexport function isSegmentPresent(seg: ISegmentLeaf, seqTime: SeqTime): boolean {\n\tconst { refSeq, localSeq } = seqTime;\n\t// If seg.seq is undefined, then this segment has existed since minSeq.\n\t// It may have been moved or removed since.\n\tif (isInserted(seg)) {\n\t\tif (seg.seq !== UnassignedSequenceNumber) {\n\t\t\tif (!seqLTE(seg.seq, refSeq)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else if (\n\t\t\tseg.localSeq !== undefined && // seg.seq === UnassignedSequenceNumber\n\t\t\t// If the current perspective does not include local sequence numbers,\n\t\t\t// then this segment does not exist yet.\n\t\t\t(localSeq === undefined || seg.localSeq > localSeq)\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t}\n\tif (wasRemovedOrMovedBefore(seg, seqTime)) {\n\t\treturn false;\n\t}\n\treturn true;\n}\n"]}
+{"version":3,"file":"perspective.js","sourceRoot":"","sources":["../src/perspective.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { LocalClientId, UnassignedSequenceNumber } from \"./constants.js\";\nimport { type MergeTree } from \"./mergeTree.js\";\nimport { LeafAction, backwardExcursion, forwardExcursion } from \"./mergeTreeNodeWalk.js\";\nimport { seqLTE, type ISegmentLeaf } from \"./mergeTreeNodes.js\";\nimport { isInserted, toMoveInfo, toRemovalInfo } from \"./segmentInfos.js\";\nimport * as opstampUtils from \"./stamps.js\";\nimport type { OperationStamp, InsertOperationStamp, RemoveOperationStamp } from \"./stamps.js\";\n\n/**\n * A perspective which includes some subset of operations known to the local client.\n *\n * This helps the local client reason about the state of other clients when they issued an operation.\n */\nexport interface Perspective {\n\t/**\n\t * The sequence number last seen from this perspective. Same concept as `ISequencedDocumentMessage.referenceSequenceNumber`.\n\t * @privateRemarks\n\t * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends\n\t * on the (refSeq, clientId, localSeq?) representation of perspectives.\n\t */\n\treadonly refSeq: number;\n\n\t/**\n\t * The client id for this perspective.\n\t * @privateRemarks\n\t * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends\n\t * on the (refSeq, clientId, localSeq?) representation of perspectives.\n\t */\n\treadonly clientId: number;\n\n\t/**\n\t * When this is a local perspective, the local sequence number last seen from this perspective.\n\t *\n\t * Perspectives with defined `localSeq` values are useful in reconnection flows, where the local client may need to resend some\n\t * of its ops after rederiving their new equivalents.\n\t * @privateRemarks\n\t * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends\n\t * on the (refSeq, clientId, localSeq?) representation of perspectives.\n\t */\n\treadonly localSeq?: number;\n\n\t/**\n\t * @returns Whether the segment is present (visible) from this perspective\n\t */\n\tisSegmentPresent(segment: ISegmentLeaf): boolean;\n\n\t/**\n\t * @returns Whether this perspective has seen the given operation.\n\t */\n\thasOccurred(stamp: RemoveOperationStamp | InsertOperationStamp): boolean;\n\n\tnextSegment(mergeTree: MergeTree, segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;\n\tpreviousSegment(mergeTree: MergeTree, segment: ISegmentLeaf): ISegmentLeaf;\n}\n\nabstract class PerspectiveBase {\n\tabstract hasOccurred(stamp: RemoveOperationStamp | InsertOperationStamp): boolean;\n\n\t/**\n\t * Returns the immediately adjacent segment in the specified direction from this perspective.\n\t * There may actually be multiple segments between the given segment and the returned segment,\n\t * but they were either inserted after this perspective, or have been removed before this perspective.\n\t *\n\t * @param segment - The segment to start from.\n\t * @param forward - The direction to search.\n\t * @returns the next segment in the specified direction, or the start or end of the tree if there is no next segment.\n\t */\n\tpublic nextSegment(\n\t\tmergeTree: MergeTree,\n\t\tsegment: ISegmentLeaf,\n\t\tforward: boolean = true,\n\t): ISegmentLeaf {\n\t\tlet next: ISegmentLeaf | undefined;\n\t\tconst action = (seg: ISegmentLeaf): boolean | undefined => {\n\t\t\tif (this.isSegmentPresent(seg)) {\n\t\t\t\tnext = seg;\n\t\t\t\treturn LeafAction.Exit;\n\t\t\t}\n\t\t};\n\t\t(forward ? forwardExcursion : backwardExcursion)(segment, action);\n\t\treturn next ?? (forward ? mergeTree.endOfTree : mergeTree.startOfTree);\n\t}\n\n\t/**\n\t * Finds the segment prior to the given segment.\n\t * @param segment - The segment to start from.\n\t * @returns the previous segment, or the start of the tree if there is no previous segment.\n\t * @remarks This is a convenient equivalent to calling `nextSegment(segment, false)`.\n\t */\n\tpublic previousSegment(mergeTree: MergeTree, segment: ISegmentLeaf): ISegmentLeaf {\n\t\treturn this.nextSegment(mergeTree, segment, false);\n\t}\n\n\tpublic isSegmentPresent(seg: ISegmentLeaf): boolean {\n\t\tconst insert: InsertOperationStamp = {\n\t\t\ttype: \"insert\",\n\t\t\tclientId: seg.clientId,\n\t\t\tseq: seg.seq,\n\t\t\tlocalSeq: seg.localSeq,\n\t\t};\n\t\tif (isInserted(seg) && !this.hasOccurred(insert)) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst removes: RemoveOperationStamp[] = [];\n\t\tconst removalInfo = toRemovalInfo(seg);\n\t\tif (removalInfo !== undefined) {\n\t\t\tremoves.push(\n\t\t\t\t...removalInfo.removedClientIds.map((clientId) =>\n\t\t\t\t\t(clientId === LocalClientId || clientId === 0) &&\n\t\t\t\t\tremovalInfo.localRemovedSeq !== undefined\n\t\t\t\t\t\t? ({\n\t\t\t\t\t\t\t\ttype: \"setRemove\",\n\t\t\t\t\t\t\t\tseq: UnassignedSequenceNumber,\n\t\t\t\t\t\t\t\tclientId,\n\t\t\t\t\t\t\t\tlocalSeq: removalInfo.localRemovedSeq,\n\t\t\t\t\t\t\t} as const)\n\t\t\t\t\t\t: // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\t\t\t\t\t({ type: \"setRemove\", seq: removalInfo.removedSeq, clientId } as const),\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\tconst moveInfo = toMoveInfo(seg);\n\t\tif (moveInfo !== undefined) {\n\t\t\tremoves.push(\n\t\t\t\t...moveInfo.movedClientIds.map((clientId, index) =>\n\t\t\t\t\t(clientId === LocalClientId || clientId === 0) &&\n\t\t\t\t\tmoveInfo.localMovedSeq !== undefined\n\t\t\t\t\t\t? ({\n\t\t\t\t\t\t\t\ttype: \"sliceRemove\",\n\t\t\t\t\t\t\t\tseq: UnassignedSequenceNumber,\n\t\t\t\t\t\t\t\tclientId,\n\t\t\t\t\t\t\t\tlocalSeq: moveInfo.localMovedSeq,\n\t\t\t\t\t\t\t} as const)\n\t\t\t\t\t\t: // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\t\t\t\t\t({ type: \"setRemove\", seq: moveInfo.movedSeqs[index]!, clientId } as const),\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\tif (removes.some((remove) => this.hasOccurred(remove))) {\n\t\t\treturn false;\n\t\t}\n\n\t\treturn true;\n\t}\n}\n\n/**\n * A perspective which includes edits at or before some reference sequence number alongside all edits from some particular client.\n *\n * @remarks\n * This works for both the local client as well as remote clients since refSeq-based checks disallow unacked edits, but the clientId check\n * catches unacked edits from the local client.\n */\nexport class PriorPerspective extends PerspectiveBase implements Perspective {\n\tpublic constructor(\n\t\tpublic readonly refSeq: number,\n\t\tpublic readonly clientId: number,\n\t) {\n\t\tsuper();\n\t}\n\n\tpublic hasOccurred(stamp: OperationStamp): boolean {\n\t\tconst predatesViaRefSeq = seqLTE(stamp.seq, this.refSeq);\n\t\tconst predatesViaSameClient = stamp.clientId === this.clientId;\n\t\treturn predatesViaRefSeq || predatesViaSameClient;\n\t}\n}\n\n/**\n * A perspective which includes edits which were either:\n * - acked and at or before some reference sequence number\n * - unacked, but at or before some local sequence number\n *\n * This is a useful perspective when the local client is in the process of reconnecting, since it must\n * rederive positions for unacked ops while only considering a portion of its own edits as having been applied.\n */\nexport class LocalReconnectingPerspective extends PerspectiveBase implements Perspective {\n\tpublic constructor(\n\t\tpublic readonly refSeq: number,\n\t\tpublic readonly clientId: number,\n\t\tpublic readonly localSeq: number,\n\t) {\n\t\tsuper();\n\t}\n\n\tpublic hasOccurred(stamp: OperationStamp): boolean {\n\t\tconst predatesViaRefSeq = seqLTE(stamp.seq, this.refSeq);\n\t\tconst predatesViaLocalSeq =\n\t\t\tstamp.localSeq !== undefined && stamp.localSeq <= this.localSeq;\n\t\treturn predatesViaRefSeq || predatesViaLocalSeq;\n\t}\n}\n\n/**\n * A perspective which includes all known edits.\n *\n * This is the perspective that the application sees.\n * @remarks\n * This can be represented using {@link PriorPerspective} with a refSeq of `Number.MAX_SAFE_INTEGER`, but having an explicit\n * variant of this perspective renders extra refSeq checks unnecessary and is a bit easier to read.\n */\nexport class LocalDefaultPerspective extends PerspectiveBase implements Perspective {\n\tpublic readonly refSeq = Number.MAX_SAFE_INTEGER;\n\n\tpublic constructor(public readonly clientId: number) {\n\t\tsuper();\n\t}\n\n\tpublic hasOccurred(_stamp: OperationStamp): boolean {\n\t\treturn true;\n\t}\n}\n\n/**\n * A perspective dictating whether segments are 'visible' to a remote obliterate operation.\n *\n * NOTE: Beware that partial lengths doesn't support this perspective, in the sense that consulting partial lengths' for the length of a block\n * can give different results than summing the lengths of present segments in that block.\n * This ends up not affecting the current obliterate implementation (which has some special casing in the mapRange calls it uses),\n * but use with caution.\n */\nexport class RemoteObliteratePerspective extends PerspectiveBase implements Perspective {\n\tpublic readonly refSeq = Number.MAX_SAFE_INTEGER;\n\n\tconstructor(public readonly clientId: number) {\n\t\tsuper();\n\t}\n\n\tpublic hasOccurred(stamp: InsertOperationStamp | RemoveOperationStamp): boolean {\n\t\t// Local-only removals are not visible to an obliterate operation, since this means the local removal was concurrent\n\t\t// to a remote obliterate and we may need to mark the segment appropriately to reflect this overlapping remove.\n\t\t// Every other type of operation is visible: obliterates do not affect segments that have already been removed and acked,\n\t\t// and they always affect segments within their range that have not been removed, even if those segments were inserted\n\t\t// after the obliterate's refSeq.\n\t\tif (stamp.type !== \"insert\" && opstampUtils.isLocal(stamp)) {\n\t\t\treturn false;\n\t\t}\n\n\t\treturn true;\n\t}\n}\n"]}

package/lib/stamps.d.ts

@@ -0,0 +1,90 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * A stamp that identifies provenance of an operation performed on the MergeTree.
+ *
+ * Stamps identify a point in time (`seq`/`localSeq`) as well as the source (`clientId`) for the operation.
+ * This provides enough information to linearize all known applied operations: acked operations happen before
+ * local+unacked ones, with acked operations ordered by their sequence numbers and local+unacked operations
+ * ordered by their localSeq.
+ *
+ * By including `clientId`, it also provides enough information to resolve whether segments are visible
+ * from alternative perspectives: a remote client will have seen all of its own previous operations as well as
+ * those at or below the op's reference sequence number.
+ *
+ * @remarks - As the `readonly` identifies suggest, these stamps should be treated as immutable.
+ * New operations applied to a merge-tree should create new stamps rather than modify existing ones (e.g. when
+ * a change's ack happens).
+ * @internal
+ */
+export interface OperationStamp {
+    /**
+     * The sequence number at which this operation was applied.
+     */
+    readonly seq: number;
+    /**
+     * Short clientId for the client that performed this operation.
+     */
+    readonly clientId: number;
+    /**
+     * Local seq at which this operation was applied.
+     * This is defined if and only if the operation is pending an ack, i.e. `seq` is UnassignedSequenceNumber.
+     *
+     * @privateRemarks
+     * See {@link CollaborationWindow.localSeq} for more information on the semantics of localSeq.
+     */
+    readonly localSeq?: number;
+}
+/**
+ * {@link OperationStamp} for an 'insert' operation.
+ */
+export interface InsertOperationStamp extends OperationStamp {
+    readonly type: "insert";
+}
+/**
+ * {@link OperationStamp} for a 'set remove' operation. This aligns with the `markRangeRemoved` API in MergeTree.
+ *
+ * @remarks The terminology here comes from the fact that the removal should affect only the *set* of nodes that were
+ * specified at the time the local client issued the remove, and not any nodes that were inserted concurrently.
+ *
+ * Not using "remove" and "obliterate" here allows us to unambiguously use the term "remove" elsewhere in code to mean
+ * "removed from the tree, either by MergeTree.obliterateRange or MergeTree.removeRange". This is convenient as the vast majority
+ * of merge-tree code only cares about segment visibility and not the specific operation that caused a segment to be removed.
+ */
+export interface SetRemoveOperationStamp extends OperationStamp {
+    readonly type: "setRemove";
+}
+/**
+ * {@link OperationStamp} for a 'set remove' operation. This aligns with the `obliterateRange` API in MergeTree.
+ *
+ * @remarks The terminology here comes from the fact that the removal should affect the *slice* of nodes between the
+ * start and end point specified by the local client, which includes any nodes that were inserted concurrently.
+ *
+ * Not using "remove" and "obliterate" here allows us to unambiguously use the term "remove" elsewhere in code to mean
+ * "removed from the tree, either by MergeTree.obliterateRange or MergeTree.removeRange". This is convenient as the vast majority
+ * of merge-tree code only cares about segment visibility and not the specific operation that caused a segment to be removed.
+ */
+export interface SliceRemoveOperationStamp extends OperationStamp {
+    readonly type: "sliceRemove";
+}
+export type RemoveOperationStamp = SetRemoveOperationStamp | SliceRemoveOperationStamp;
+export declare function lessThan(a: OperationStamp, b: OperationStamp): boolean;
+export declare function gte(a: OperationStamp, b: OperationStamp): boolean;
+export declare function greaterThan(a: OperationStamp, b: OperationStamp): boolean;
+export declare function lte(a: OperationStamp, b: OperationStamp): boolean;
+export declare function equal(a: OperationStamp, b: OperationStamp): boolean;
+export declare function isLocal(a: OperationStamp): boolean;
+export declare function isAcked(a: OperationStamp): boolean;
+/**
+ * Inserts a stamp into a sorted list of stamps in the correct (sorted) position.
+ *
+ * Beware that this uses Array.splice, thus requires asymptotics considerations.
+ * If inserting a variable number of timestamp, consider just pushing them and sorting the list
+ * after using {@link compare} instead.
+ */
+export declare function spliceIntoList(list: OperationStamp[], stamp: OperationStamp): void;
+export declare function hasAnyAckedOperation(list: OperationStamp[]): boolean;
+export declare function compare(a: OperationStamp, b: OperationStamp): number;
+//# sourceMappingURL=stamps.d.ts.map

package/lib/stamps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamps.d.ts","sourceRoot":"","sources":["../src/stamps.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC3D,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC9D,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAChE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,GAAG,yBAAyB,CAAC;AAEvF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAWtE;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAEjE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAWzE;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAEjE;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAEnE;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAElD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAclF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,OAAO,CAEpE;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,CAQpE"}