@fluidframework/sequence 2.0.0-internal.1.4.2 → 2.0.0-internal.2.0.0

package/src/intervalTree.ts

@@ -0,0 +1,166 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    IIntegerRange,
+    RBNode,
+    IRBAugmentation,
+    IRBMatcher,
+    RedBlackTree,
+    ConflictAction,
+    RBNodeActions,
+} from "@fluidframework/merge-tree";
+import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+
+export interface AugmentedIntervalNode {
+    minmax: IInterval;
+}
+
+export const integerRangeToString = (range: IIntegerRange) => `[${range.start},${range.end})`;
+
+/**
+ * Basic interval abstraction
+ */
+export interface IInterval {
+    /**
+     * @returns a new interval object with identical semantics.
+     */
+    clone(): IInterval;
+    /**
+     * Compares this interval to `b` with standard comparator semantics:
+     * - returns -1 if this is less than `b`
+     * - returns 1 if this is greater than `b`
+     * - returns 0 if this is equivalent to `b`
+     * @param b - Interval to compare against
+     */
+    compare(b: IInterval): number;
+    /**
+     * Compares the start endpoint of this interval to `b`'s start endpoint.
+     * Standard comparator semantics apply.
+     * @param b - Interval to compare against
+     */
+    compareStart(b: IInterval): number;
+    /**
+     * Compares the end endpoint of this interval to `b`'s end endpoint.
+     * Standard comparator semantics apply.
+     * @param b - Interval to compare against
+     */
+    compareEnd(b: IInterval): number;
+    /**
+     * Modifies one or more of the endpoints of this interval, returning a new interval representing the result.
+     * @internal
+     */
+    modify(
+        label: string,
+        start: number | undefined,
+        end: number | undefined,
+        op?: ISequencedDocumentMessage,
+        localSeq?: number
+    ): IInterval | undefined;
+    /**
+     * @returns whether this interval overlaps with `b`.
+     * Since intervals are inclusive, this includes cases where endpoints are equal.
+     */
+    overlaps(b: IInterval): boolean;
+    /**
+     * Unions this interval with `b`, returning a new interval.
+     * The union operates as a convex hull, i.e. if the two intervals are disjoint, the return value includes
+     * intermediate values between the two intervals.
+     * @internal
+     */
+    union(b: IInterval): IInterval;
+}
+
+const intervalComparer = (a: IInterval, b: IInterval) => a.compare(b);
+
+export type IntervalNode<T extends IInterval> = RBNode<T, AugmentedIntervalNode>;
+
+export type IntervalConflictResolver<TInterval> = (a: TInterval, b: TInterval) => TInterval;
+
+export class IntervalTree<T extends IInterval> implements IRBAugmentation<T, AugmentedIntervalNode>,
+    IRBMatcher<T, AugmentedIntervalNode> {
+    public intervals = new RedBlackTree<T, AugmentedIntervalNode>(intervalComparer, this);
+
+    public remove(x: T) {
+        this.intervals.remove(x);
+    }
+
+    public removeExisting(x: T) {
+        this.intervals.removeExisting(x);
+    }
+
+    public put(x: T, conflict?: IntervalConflictResolver<T>) {
+        let rbConflict: ConflictAction<T, AugmentedIntervalNode> | undefined;
+        if (conflict) {
+            rbConflict = (key: T, currentKey: T) => {
+                const ival = conflict(key, currentKey);
+                return {
+                    key: ival,
+                };
+            };
+        }
+        this.intervals.put(x, { minmax: x.clone() }, rbConflict);
+    }
+
+    public map(fn: (x: T) => void) {
+        const actions: RBNodeActions<T, AugmentedIntervalNode> = {
+            infix: (node) => {
+                fn(node.key);
+                return true;
+            },
+            showStructure: true,
+        };
+        this.intervals.walk(actions);
+    }
+
+    public mapUntil(fn: (X: T) => boolean) {
+        const actions: RBNodeActions<T, AugmentedIntervalNode> = {
+            infix: (node) => {
+                return fn(node.key);
+            },
+            showStructure: true,
+        };
+        this.intervals.walk(actions);
+    }
+
+    public mapBackward(fn: (x: T) => void) {
+        const actions: RBNodeActions<T, AugmentedIntervalNode> = {
+            infix: (node) => {
+                fn(node.key);
+                return true;
+            },
+            showStructure: true,
+        };
+        this.intervals.walkBackward(actions);
+    }
+
+    // TODO: toString()
+    public match(x: T) {
+        return this.intervals.gather(x, this);
+    }
+
+    public matchNode(node: IntervalNode<T> | undefined, key: T) {
+        return !!node && node.key.overlaps(key);
+    }
+
+    public continueSubtree(node: IntervalNode<T> | undefined, key: T) {
+        return !!node && node.data.minmax.overlaps(key);
+    }
+
+    public update(node: IntervalNode<T>) {
+        if (node.left && node.right) {
+            node.data.minmax = node.key.union(
+                node.left.data.minmax.union(node.right.data.minmax));
+        } else {
+            if (node.left) {
+                node.data.minmax = node.key.union(node.left.data.minmax);
+            } else if (node.right) {
+                node.data.minmax = node.key.union(node.right.data.minmax);
+            } else {
+                node.data.minmax = node.key.clone();
+            }
+        }
+    }
+}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/sequence";
-export const pkgVersion = "2.0.0-internal.1.4.2";
+export const pkgVersion = "2.0.0-internal.2.0.0";

package/src/sequence.ts

@@ -36,6 +36,7 @@ import {
     RangeStackMap,
     ReferencePosition,
     ReferenceType,
+    MergeTreeRevertibleDriver,
     SegmentGroup,
 } from "@fluidframework/merge-tree";
 import { ObjectStoragePartition, SummaryTreeBuilder } from "@fluidframework/runtime-utils";
@@ -50,13 +51,13 @@ import {
 import { IEventThisPlaceHolder } from "@fluidframework/common-definitions";
 import { ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
 
+import { DefaultMap } from "./defaultMap";
+import { IMapMessageLocalMetadata, IValueChanged } from "./defaultMapInterfaces";
 import {
     IntervalCollection,
     SequenceInterval,
     SequenceIntervalCollectionValueType,
 } from "./intervalCollection";
-import { DefaultMap } from "./defaultMap";
-import { IMapMessageLocalMetadata, IValueChanged } from "./defaultMapInterfaces";
 import { SequenceDeltaEvent, SequenceMaintenanceEvent } from "./sequenceDeltaEvent";
 import { ISharedIntervalCollection } from "./sharedIntervalCollection";
 
@@ -106,7 +107,7 @@ export interface ISharedSegmentSequenceEvents extends ISharedObjectEvents {
 
 export abstract class SharedSegmentSequence<T extends ISegment>
     extends SharedObject<ISharedSegmentSequenceEvents>
-    implements ISharedIntervalCollection<SequenceInterval> {
+    implements ISharedIntervalCollection<SequenceInterval>, MergeTreeRevertibleDriver {
     get loaded(): Promise<void> {
         return this.loadedDeferred.promise;
     }
@@ -143,6 +144,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
                 case MergeTreeDeltaType.REMOVE: {
                     const lastRem = ops[ops.length - 1] as IMergeTreeRemoveMsg;
                     if (lastRem?.pos1 === r.position) {
+                        assert(lastRem.pos2 !== undefined, 0x3ff /* pos2 should not be undefined here */);
                         lastRem.pos2 += r.segment.cachedLength;
                     } else {
                         ops.push(createRemoveRangeOp(
@@ -159,7 +161,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
     }
 
     protected client: Client;
-    // Deferred that triggers once the object is loaded
+    /** `Deferred` that triggers once the object is loaded */
     protected loadedDeferred = new Deferred<void>();
     // cache out going ops created when partial loading
     private readonly loadedDeferredOutgoingOps:
@@ -237,9 +239,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
      */
     public removeRange(start: number, end: number): IMergeTreeRemoveMsg {
         const removeOp = this.client.removeRangeLocal(start, end);
-        if (removeOp) {
-            this.submitSequenceMessage(removeOp);
-        }
+        this.submitSequenceMessage(removeOp);
         return removeOp;
     }
 
@@ -248,7 +248,12 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         this.submitSequenceMessage(groupOp);
     }
 
-    public getContainingSegment(pos: number) {
+    /**
+     * Finds the segment information (i.e. segment + offset) corresponding to a character position in the SharedString.
+     * If the position is past the end of the string, `segment` and `offset` on the returned object may be undefined.
+     * @param pos - Character position (index) into the current local view of the SharedString.
+     */
+    public getContainingSegment(pos: number): { segment: T | undefined; offset: number | undefined; } {
         return this.client.getContainingSegment<T>(pos);
     }
 
@@ -297,6 +302,14 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         return this.client.getRangeExtentsOfPosition(pos);
     }
 
+    /**
+     * Creates a `LocalReferencePosition` on this SharedString. If the refType does not include
+     * ReferenceType.Transient, the returned reference will be added to the localRefs on the provided segment.
+     * @param segment - Segment to add the local reference on
+     * @param offset - Offset on the segment at which to place the local reference
+     * @param refType - ReferenceType for the created local reference
+     * @param properties - PropertySet to place on the created local reference
+     */
     public createLocalReferencePosition(
         segment: T,
         offset: number,
@@ -309,10 +322,20 @@ export abstract class SharedSegmentSequence<T extends ISegment>
             properties);
     }
 
+    /**
+     * Resolves a `ReferencePosition` into a character position using this client's perspective.
+     */
     public localReferencePositionToPosition(lref: ReferencePosition): number {
         return this.client.localReferencePositionToPosition(lref);
     }
 
+    /**
+     * Removes a `LocalReferencePosition` from this SharedString.
+     */
+    public removeLocalReferencePosition(lref: LocalReferencePosition) {
+        return this.client.removeLocalReferencePosition(lref);
+    }
+
     /**
      * Resolves a remote client's position against the local sequence
      * and returns the remote client's position relative to the local
@@ -330,11 +353,12 @@ export abstract class SharedSegmentSequence<T extends ISegment>
     public resolveRemoteClientPosition(
         remoteClientPosition: number,
         remoteClientRefSeq: number,
-        remoteClientId: string): number {
+        remoteClientId: string): number | undefined {
         return this.client.resolveRemoteClientPosition(
             remoteClientPosition,
             remoteClientRefSeq,
-            remoteClientId);
+            remoteClientId,
+        );
     }
 
     public submitSequenceMessage(message: IMergeTreeOp) {
@@ -349,16 +373,12 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         // local ops until loading is complete, and then
         // they will be resent
         if (!this.loadedDeferred.isCompleted) {
-            this.loadedDeferredOutgoingOps.push([translated, metadata]);
+            this.loadedDeferredOutgoingOps.push(metadata ? [translated, metadata] : translated);
         } else {
             this.submitLocalMessage(translated, metadata);
         }
     }
 
-    public removeLocalReferencePosition(lref: LocalReferencePosition) {
-        return this.client.removeLocalReferencePosition(lref);
-    }
-
     /**
      * Given a position specified relative to a marker id, lookup the marker
      * and convert the position to a character position.
@@ -383,40 +403,54 @@ export abstract class SharedSegmentSequence<T extends ISegment>
      */
     public walkSegments<TClientData>(
         handler: ISegmentAction<TClientData>,
-        start?: number, end?: number, accum?: TClientData,
-        splitRange: boolean = false) {
-        return this.client.walkSegments<TClientData>(handler, start, end, accum, splitRange);
+        start?: number,
+        end?: number,
+        accum?: TClientData,
+        splitRange: boolean = false,
+    ): void {
+        this.client.walkSegments(handler, start, end, accum as TClientData, splitRange);
     }
 
-    /**
-     * @deprecated  for internal use only. public export will be removed.
-     * @internal
-     */
     public getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap {
         return this.client.getStackContext(startPos, rangeLabels);
     }
 
+    /**
+     * @returns - The most recent sequence number which has been acked by the server and processed by this
+     * SharedSegmentSequence.
+     */
     public getCurrentSeq() {
         return this.client.getCurrentSeq();
     }
 
+    /**
+     * Inserts a segment directly before a `ReferencePosition`.
+     * @param refPos - The reference position to insert the segment at
+     * @param segment - The segment to insert
+     */
     public insertAtReferencePosition(pos: ReferencePosition, segment: T) {
         const insertOp = this.client.insertAtReferencePositionLocal(pos, segment);
         if (insertOp) {
             this.submitSequenceMessage(insertOp);
         }
     }
-
     /**
-     * @deprecated `IntervalCollection`s are created on a first-write wins basis, and concurrent creates
-     * are supported. Use {@link SharedSegmentSequence.getIntervalCollection} instead.
+     * Inserts a segment
+     * @param start - The position to insert the segment at
+     * @param spec - The segment to inserts spec
      */
-    public async waitIntervalCollection(
-        label: string,
-    ): Promise<IntervalCollection<SequenceInterval>> {
-        return this.intervalCollections.get(label);
+    public insertFromSpec(pos: number, spec: IJSONSegment) {
+        const segment = this.segmentFromSpec(spec);
+        const insertOp = this.client.insertSegmentLocal(pos, segment);
+        if (insertOp) {
+            this.submitSequenceMessage(insertOp);
+        }
     }
 
+    /**
+     * Retrieves the interval collection keyed on `label`. If no such interval collection exists,
+     * creates one.
+     */
     public getIntervalCollection(label: string): IntervalCollection<SequenceInterval> {
         return this.intervalCollections.get(label);
     }
@@ -436,6 +470,9 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         return this.intervalCollections.keys();
     }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.summarizeCore}
+     */
     protected summarizeCore(
         serializer: IFluidSerializer,
         telemetryContext?: ITelemetryContext,
@@ -483,20 +520,30 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         if (insert) {
             if (start < end) {
                 const remove = this.client.removeRangeLocal(start, end);
-                this.submitSequenceMessage(createGroupOp(insert, remove));
+                const op = remove ? createGroupOp(insert, remove) : insert;
+                this.submitSequenceMessage(op);
             } else {
                 this.submitSequenceMessage(insert);
             }
         }
     }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.onConnect}
+     */
     protected onConnect() {
         // Update merge tree collaboration information with new client ID and then resend pending ops
         this.client.startOrUpdateCollaboration(this.runtime.clientId);
     }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
+     */
     protected onDisconnect() { }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}
+     */
     protected reSubmitCore(content: any, localOpMetadata: unknown) {
         if (!this.intervalCollections.tryResubmitMessage(content, localOpMetadata as IMapMessageLocalMetadata)) {
             this.submitSequenceMessage(
@@ -564,6 +611,9 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         }
     }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.processCore}
+     */
     protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown) {
         // if loading isn't complete, we need to cache all
         // incoming ops to be applied after loading is complete
@@ -586,6 +636,9 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         }
     }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.didAttach}
+     */
     protected didAttach() {
         // If we are not local, and we've attached we need to start generating and sending ops
         // so start collaboration and provide a default client id incase we are not connected
@@ -594,6 +647,9 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         }
     }
 
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.initializeLocalCore}
+     */
     protected initializeLocalCore() {
         super.initializeLocalCore();
         this.loadFinished();

package/src/sequenceDeltaEvent.ts

@@ -44,7 +44,7 @@ export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTy
                     const newRange: ISequenceDeltaRange<TOperation> = {
                         operation: this.deltaArgs.operation,
                         position: this.mergeTreeClient.getPosition(delta.segment),
-                        propertyDeltas: delta.propertyDeltas,
+                        propertyDeltas: delta.propertyDeltas ?? {},
                         segment: delta.segment,
                     };
                     set.addOrUpdate(newRange);
@@ -72,7 +72,7 @@ export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTy
     /**
      * The client id of the client that made the change which caused the delta event
      */
-    public get clientId(): string {
+    public get clientId(): string | undefined {
         return this.mergeTreeClient.longClientId;
     }
 
@@ -139,6 +139,11 @@ export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenance
  * A range that has changed corresponding to a segment modification.
  */
 export interface ISequenceDeltaRange<TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes> {
+    /**
+     * The type of operation that changed this range.
+     * @remarks - Consuming code should typically compare this to the enum values defined in
+     * `MergeTreeDeltaOperationTypes`.
+     */
     operation: TOperation;
     /**
      * The index of the start of the range.
@@ -148,11 +153,20 @@ export interface ISequenceDeltaRange<TOperation extends MergeTreeDeltaOperationT
      * The segment that corresponds to the range.
      */
     segment: ISegment;
+    /**
+     * Deltas object which contains all modified properties with their previous values.
+     * Since `undefined` doesn't survive a round-trip through JSON serialization, the old value being absent
+     * is instead encoded with `null`.
+     * @remarks - This object is motivated by undo/redo scenarios, and provides a convenient "inverse op" to apply to
+     * undo a property change.
+     * @example - If a segment initially had properties `{ foo: "1", bar: 2 }` and it was annotated with
+     * `{ foo: 3, baz: 5 }`, the corresponding event would have a `propertyDeltas` of `{ foo: "1", baz: null }`.
+     */
     propertyDeltas: PropertySet;
 }
 
 class Lazy<T> {
-    private pValue: T;
+    private pValue: T | undefined;
     private pEvaluated: boolean;
     constructor(private readonly valueGenerator: () => T) {
         this.pEvaluated = false;
@@ -167,6 +181,6 @@ class Lazy<T> {
             this.pEvaluated = true;
             this.pValue = this.valueGenerator();
         }
-        return this.pValue;
+        return this.pValue as T;
     }
 }