@fluidframework/merge-tree 2.1.0-274160 → 2.1.0-276985

package/src/mergeTree.ts

@@ -76,6 +76,7 @@ import {
 	ReferenceType,
 } from "./ops.js";
 import { PartialSequenceLengths } from "./partialLengths.js";
+import { PerspectiveImpl, isSegmentPresent } from "./perspective.js";
 // eslint-disable-next-line import/no-deprecated
 import { PropertySet, createMap, extend, extendIfUndefined } from "./properties.js";
 import {
@@ -143,6 +144,7 @@ const LRUSegmentComparer: IComparer<LRUSegment> = {
 };
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeOptions {
@@ -192,6 +194,7 @@ export interface IMergeTreeOptions {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeAttributionOptions {
@@ -218,6 +221,7 @@ export interface IMergeTreeAttributionOptions {
 /**
  * Implements policy dictating which kinds of operations should be attributed and how.
  * @sealed
+ * @legacy
  * @alpha
  */
 export interface AttributionPolicy {
@@ -1026,27 +1030,55 @@ export class MergeTree {
 		}
 	}
 
+	/**
+	 * Returns the count of elements before the given reference position from the given perspective.
+	 *
+	 * @param refPos - The reference position to resolve.
+	 * @param refSeq - The number of the latest sequenced change to consider.
+	 * Defaults to including all edits which have been applied.
+	 * @param clientId - The ID of the client from whose perspective to resolve this reference. Defaults to the current client.
+	 * @param localSeq - The local sequence number to consider. Defaults to including all local edits.
+	 * @returns the count of elements before the given reference position in the given perspective.
+	 */
 	public referencePositionToLocalPosition(
 		refPos: ReferencePosition,
-		refSeq = this.collabWindow.currentSeq,
+		refSeq = Number.MAX_SAFE_INTEGER,
 		clientId = this.collabWindow.clientId,
+		localSeq: number | undefined = this.collabWindow.localSeq,
 	): number {
 		const seg: ISegmentLeaf | undefined = refPos.getSegment();
 		if (seg?.parent === undefined) {
+			// We have no idea where this reference is, because it refers to a segment which is not in the tree.
 			return DetachedReferencePosition;
 		}
 		if (refPos.isLeaf()) {
-			return this.getPosition(refPos, refSeq, clientId);
+			return this.getPosition(refPos, refSeq, clientId, localSeq);
 		}
 		if (refTypeIncludesFlag(refPos, ReferenceType.Transient) || seg.localRefs?.has(refPos)) {
-			const offset = isRemovedOrMoved(seg) ? 0 : refPos.getOffset();
-			const pos = this.getPosition(seg, refSeq, clientId);
-
-			if (isRemovedOrMoved(seg) && refPos.slidingPreference === SlidingPreference.BACKWARD) {
-				return pos === 0 ? 0 : pos - 1;
+			if (
+				seg !== this.startOfTree &&
+				seg !== this.endOfTree &&
+				!isSegmentPresent(seg, { refSeq, localSeq })
+			) {
+				const forward = refPos.slidingPreference === SlidingPreference.FORWARD;
+				const slideSeq =
+					seg.movedSeq !== UnassignedSequenceNumber && seg.movedSeq !== undefined
+						? seg.movedSeq
+						: seg.removedSeq !== UnassignedSequenceNumber && seg.removedSeq !== undefined
+							? seg.removedSeq
+							: refSeq;
+				const slideLocalSeq = seg.localMovedSeq ?? seg.localRemovedSeq;
+				const perspective = new PerspectiveImpl(this, {
+					refSeq: slideSeq,
+					localSeq: slideLocalSeq,
+				});
+				const slidSegment = perspective.nextSegment(seg, forward);
+				return (
+					this.getPosition(slidSegment, refSeq, clientId, localSeq) +
+					(forward ? 0 : slidSegment.cachedLength === 0 ? 0 : slidSegment.cachedLength - 1)
+				);
 			}
-
-			return offset + pos;
+			return this.getPosition(seg, refSeq, clientId, localSeq) + refPos.getOffset();
 		}
 		return DetachedReferencePosition;
 	}

package/src/mergeTreeDeltaCallback.ts

@@ -11,6 +11,7 @@ import { IMergeTreeGroupMsg, IMergeTreeOp, MergeTreeDeltaType } from "./ops.js";
 import { PropertySet } from "./properties.js";
 
 /**
+ * @legacy
  * @alpha
  */
 export type MergeTreeDeltaOperationType =
@@ -24,6 +25,7 @@ export type MergeTreeDeltaOperationType =
  * Maintenance events correspond to structural segment changes or acks of pending segments.
  *
  * Note: these values are assigned negative integers to avoid clashing with `MergeTreeDeltaType`.
+ * @legacy
  * @alpha
  */
 export const MergeTreeMaintenanceType = {
@@ -54,12 +56,14 @@ export const MergeTreeMaintenanceType = {
 	ACKNOWLEDGED: -4,
 } as const;
 /**
+ * @legacy
  * @alpha
  */
 export type MergeTreeMaintenanceType =
 	(typeof MergeTreeMaintenanceType)[keyof typeof MergeTreeMaintenanceType];
 
 /**
+ * @legacy
  * @alpha
  */
 export type MergeTreeDeltaOperationTypes =
@@ -67,6 +71,7 @@ export type MergeTreeDeltaOperationTypes =
 	| MergeTreeMaintenanceType;
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeDeltaCallbackArgs<
@@ -89,6 +94,7 @@ export interface IMergeTreeDeltaCallbackArgs<
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeSegmentDelta {
@@ -110,6 +116,7 @@ export interface IMergeTreeSegmentDelta {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeDeltaOpArgs {
@@ -153,6 +160,7 @@ export type MergeTreeDeltaCallback = (
 ) => void;
 
 /**
+ * @legacy
  * @alpha
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface

package/src/mergeTreeNodes.ts

@@ -32,6 +32,7 @@ import { PropertiesManager, PropertiesRollback } from "./segmentPropertiesManage
 
 /**
  * Common properties for a node in a merge tree.
+ * @legacy
  * @alpha
  */
 export interface IMergeNodeCommon {
@@ -55,6 +56,7 @@ export type IMergeNode = MergeBlock | ISegmentLeaf;
 
 /**
  * Contains removal information associated to an {@link ISegment}.
+ * @legacy
  * @alpha
  */
 export interface IRemovalInfo {
@@ -96,6 +98,7 @@ export function toRemovalInfo(
  * Note that merge-tree does not currently support moving and only supports
  * obliterate. The fields below include "move" in their names to avoid renaming
  * in the future, when moves _are_ supported.
+ * @legacy
  * @alpha
  */
 export interface IMoveInfo {
@@ -172,6 +175,7 @@ export function toMoveInfo(maybe: Partial<IMoveInfo> | undefined): IMoveInfo | u
 /**
  * A segment representing a portion of the merge tree.
  * Segments are leaf nodes of the merge tree and contain data.
+ * @legacy
  * @alpha
  */
 export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Partial<IMoveInfo> {
@@ -290,6 +294,7 @@ export interface IMarkerModifiedAction {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface ISegmentAction<TClientData> {
@@ -365,6 +370,7 @@ export interface SegmentActions<TClientData> {
 
 /**
  * @deprecated This functionality was not meant to be exported and will be removed in a future release
+ * @legacy
  * @alpha
  */
 export interface SegmentGroup {
@@ -375,6 +381,7 @@ export interface SegmentGroup {
 }
 
 /**
+ * @legacy
  * @alpha
  * @deprecated - unused and will be removed
  */
@@ -471,6 +478,7 @@ export function seqLTE(seq: number, minOrRefSeq: number) {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export abstract class BaseSegment implements ISegment {
@@ -697,6 +705,7 @@ export abstract class BaseSegment implements ISegment {
  *
  * @remarks In general, marker ids should be accessed using the inherent method
  * {@link Marker.getId}. Marker ids should not be updated after creation.
+ * @legacy
  * @alpha
  */
 export const reservedMarkerIdKey = "markerId";
@@ -707,6 +716,7 @@ export const reservedMarkerIdKey = "markerId";
 export const reservedMarkerSimpleTypeKey = "markerSimpleType";
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IJSONMarkerSegment extends IJSONSegment {
@@ -722,6 +732,7 @@ export interface IJSONMarkerSegment extends IJSONSegment {
  * start of a paragraph to the end, assuming a paragraph is bound by markers at
  * the start and end.
  *
+ * @legacy
  * @alpha
  */
 export class Marker extends BaseSegment implements ReferencePosition, ISegment {
@@ -798,6 +809,7 @@ export class Marker extends BaseSegment implements ReferencePosition, ISegment {
 
 /**
  * @deprecated This functionality was not meant to be exported and will be removed in a future release
+ * @legacy
  * @alpha
  */
 export class CollaborationWindow {

package/src/mergeTreeTracking.ts

@@ -9,11 +9,13 @@ import { ISegment } from "./mergeTreeNodes.js";
 import { SortedSegmentSet } from "./sortedSegmentSet.js";
 
 /**
+ * @legacy
  * @alpha
  */
 export type Trackable = ISegment | LocalReferencePosition;
 
 /**
+ * @legacy
  * @alpha
  */
 export interface ITrackingGroup {
@@ -25,6 +27,7 @@ export interface ITrackingGroup {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export class TrackingGroup implements ITrackingGroup {
@@ -104,6 +107,7 @@ export class UnorderedTrackingGroup implements ITrackingGroup {
 
 /**
  * A collection of {@link ITrackingGroup}.
+ * @legacy
  * @alpha
  */
 export class TrackingGroupCollection {

package/src/ops.ts

@@ -5,6 +5,7 @@
 
 /**
  * Flags enum that dictates behavior of a {@link ReferencePosition}
+ * @legacy
  * @alpha
  */
 export enum ReferenceType {
@@ -48,6 +49,7 @@ export enum ReferenceType {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMarkerDef {
@@ -56,6 +58,7 @@ export interface IMarkerDef {
 
 // Note: Assigned positive integers to avoid clashing with MergeTreeMaintenanceType
 /**
+ * @legacy
  * @alpha
  */
 export const MergeTreeDeltaType = {
@@ -70,11 +73,13 @@ export const MergeTreeDeltaType = {
 } as const;
 
 /**
+ * @legacy
  * @alpha
  */
 export type MergeTreeDeltaType = (typeof MergeTreeDeltaType)[keyof typeof MergeTreeDeltaType];
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeDelta {
@@ -86,6 +91,7 @@ export interface IMergeTreeDelta {
 
 /**
  * A position specified relative to a segment.
+ * @legacy
  * @alpha
  */
 export interface IRelativePosition {
@@ -106,6 +112,7 @@ export interface IRelativePosition {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeInsertMsg extends IMergeTreeDelta {
@@ -118,6 +125,7 @@ export interface IMergeTreeInsertMsg extends IMergeTreeDelta {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeRemoveMsg extends IMergeTreeDelta {
@@ -132,6 +140,7 @@ export interface IMergeTreeRemoveMsg extends IMergeTreeDelta {
  * @deprecated We no longer intend to support this functionality and it will
  * be removed in a future release. There is no replacement for this
  * functionality.
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeObliterateMsg extends IMergeTreeDelta {
@@ -151,6 +160,7 @@ export interface IMergeTreeObliterateMsg extends IMergeTreeDelta {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeAnnotateMsg extends IMergeTreeDelta {
@@ -167,6 +177,7 @@ export interface IMergeTreeAnnotateMsg extends IMergeTreeDelta {
  * release, as group ops are redundant with the native batching capabilities
  * of the runtime
  *
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeGroupMsg extends IMergeTreeDelta {
@@ -175,6 +186,7 @@ export interface IMergeTreeGroupMsg extends IMergeTreeDelta {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IJSONSegment {
@@ -182,6 +194,7 @@ export interface IJSONSegment {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export type IMergeTreeDeltaOp =
@@ -191,6 +204,7 @@ export type IMergeTreeDeltaOp =
 	| IMergeTreeObliterateMsg;
 
 /**
+ * @legacy
  * @alpha
  */
 export type IMergeTreeOp = IMergeTreeDeltaOp | IMergeTreeGroupMsg;

package/src/perspective.ts

@@ -0,0 +1,142 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UnassignedSequenceNumber } from "./constants.js";
+import { type MergeTree } from "./mergeTree.js";
+import { LeafAction, backwardExcursion, forwardExcursion } from "./mergeTreeNodeWalk.js";
+import { seqLTE, type ISegment } from "./mergeTreeNodes.js";
+
+/**
+ * Provides a view of a MergeTree from the perspective of a specific client at a specific sequence number.
+ */
+export interface Perspective {
+	nextSegment(segment: ISegment, forward?: boolean): ISegment;
+	previousSegment(segment: ISegment): ISegment;
+}
+
+/**
+ * Represents a point in time inside the collaboration window.
+ */
+export interface SeqTime {
+	refSeq: number;
+	localSeq?: number;
+}
+
+/**
+ * Implementation of {@link Perspective}.
+ * See {@link Client.createPerspective}.
+ */
+export class PerspectiveImpl implements Perspective {
+	/**
+	 * @param _mergeTree - The {@link MergeTree} to view.
+	 * @param _seqTime - The latest sequence number and local sequence number to consider.
+	 */
+	public constructor(
+		private readonly _mergeTree: MergeTree,
+		private readonly _seqTime: SeqTime,
+	) {}
+
+	/**
+	 * 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.
+	 *
+	 * @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.
+	 */
+	public nextSegment(segment: ISegment, forward: boolean = true): ISegment {
+		let next: ISegment | undefined;
+		const action = (seg: ISegment) => {
+			if (isSegmentPresent(seg, this._seqTime)) {
+				next = seg;
+				return LeafAction.Exit;
+			}
+		};
+		(forward ? forwardExcursion : backwardExcursion)(segment, action);
+		return next ?? (forward ? this._mergeTree.endOfTree : this._mergeTree.startOfTree);
+	}
+
+	/**
+	 * @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)`.
+	 */
+	public previousSegment(segment: ISegment): ISegment {
+		return this.nextSegment(segment, false);
+	}
+}
+
+/**
+ * @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.
+ */
+export function wasRemovedBefore(seg: ISegment, { refSeq, localSeq }: SeqTime): boolean {
+	if (
+		seg.removedSeq === UnassignedSequenceNumber &&
+		localSeq !== undefined &&
+		seg.localRemovedSeq !== undefined
+	) {
+		return seg.localRemovedSeq <= localSeq;
+	}
+	return seg.removedSeq !== undefined && seqLTE(seg.removedSeq, refSeq);
+}
+
+/**
+ * @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.
+ */
+export function wasMovedBefore(seg: ISegment, { refSeq, localSeq }: SeqTime): boolean {
+	if (
+		seg.movedSeq === UnassignedSequenceNumber &&
+		localSeq !== undefined &&
+		seg.localMovedSeq !== undefined
+	) {
+		return seg.localMovedSeq <= localSeq;
+	}
+	return seg.movedSeq !== undefined && seqLTE(seg.movedSeq, refSeq);
+}
+
+/**
+ * See {@link wasRemovedBefore} and {@link wasMovedBefore}.
+ */
+export function wasRemovedOrMovedBefore(seg: ISegment, seqTime: SeqTime): boolean {
+	return wasRemovedBefore(seg, seqTime) || wasMovedBefore(seg, seqTime);
+}
+
+/**
+ *
+ * @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.
+ */
+export function isSegmentPresent(seg: ISegment, seqTime: SeqTime): boolean {
+	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 (seg.seq !== undefined) {
+		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.
+			if (localSeq === undefined || seg.localSeq > localSeq) {
+				return false;
+			}
+		}
+	}
+	if (wasRemovedOrMovedBefore(seg, seqTime)) {
+		return false;
+	}
+	return true;
+}

package/src/properties.ts

@@ -5,6 +5,7 @@
 
 /**
  * Any mapping from a string to values of type `T`
+ * @legacy
  * @alpha
  */
 export interface MapLike<T> {
@@ -19,6 +20,7 @@ export interface MapLike<T> {
  * @privateRemarks PropertySet is typed using `any` because when you include
  * custom methods such as toJSON(), JSON.stringify accepts most types other than
  * functions
+ * @legacy
  * @alpha
  */
 export type PropertySet = MapLike<any>;

package/src/referencePositions.ts

@@ -30,6 +30,7 @@ export function refTypeIncludesFlag(
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export const refGetTileLabels = (refPos: ReferencePosition): string[] | undefined =>
@@ -38,6 +39,7 @@ export const refGetTileLabels = (refPos: ReferencePosition): string[] | undefine
 		: undefined;
 
 /**
+ * @legacy
  * @alpha
  */
 export function refHasTileLabel(refPos: ReferencePosition, label: string): boolean {
@@ -56,6 +58,7 @@ export function refHasTileLabels(refPos: ReferencePosition): boolean {
  * Represents a reference to a place within a merge tree. This place conceptually remains stable over time
  * by referring to a particular segment and offset within that segment.
  * Thus, this reference's character position changes as the tree is edited.
+ * @legacy
  * @alpha
  */
 export interface ReferencePosition {

package/src/revertibles.ts

@@ -19,6 +19,7 @@ import { PropertySet, matchProperties } from "./properties.js";
 import { DetachedReferencePosition } from "./referencePositions.js";
 
 /**
+ * @legacy
  * @alpha
  */
 export type MergeTreeDeltaRevertible =
@@ -61,6 +62,7 @@ interface RemoveSegmentRefProperties {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export interface MergeTreeRevertibleDriver {
@@ -189,6 +191,7 @@ function appendLocalAnnotateToRevertibles(
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export function appendToMergeTreeDeltaRevertibles(
@@ -219,6 +222,7 @@ export function appendToMergeTreeDeltaRevertibles(
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export function discardMergeTreeDeltaRevertible(revertibles: MergeTreeDeltaRevertible[]) {
@@ -381,6 +385,7 @@ function getPosition(mergeTreeWithRevert: MergeTreeWithRevert, segment: ISegment
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export function revertMergeTreeDeltaRevertibles(

package/src/segmentGroupCollection.ts

@@ -8,6 +8,7 @@ import { DoublyLinkedList, walkList } from "./collections/index.js";
 import { ISegment, SegmentGroup } from "./mergeTreeNodes.js";
 
 /**
+ * @legacy
  * @alpha
  */
 export class SegmentGroupCollection {

package/src/segmentPropertiesManager.ts

@@ -13,6 +13,7 @@ import { IMergeTreeAnnotateMsg } from "./ops.js";
 import { MapLike, PropertySet, createMap } from "./properties.js";
 
 /**
+ * @legacy
  * @alpha
  */
 export enum PropertiesRollback {
@@ -24,6 +25,7 @@ export enum PropertiesRollback {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export class PropertiesManager {

package/src/snapshotLoader.ts

@@ -280,8 +280,6 @@ export class SnapshotLoader {
 	}
 
 	private extractAttribution(segments: ISegment[], chunk: MergeTreeChunkV1): void {
-		this.mergeTree.options ??= {};
-		this.mergeTree.options.attribution ??= {};
 		if (chunk.attribution) {
 			const { attributionPolicy } = this.mergeTree;
 			if (attributionPolicy === undefined) {

package/src/textSegment.ts

@@ -21,6 +21,7 @@ import { PropertySet } from "./properties.js";
 export const TextSegmentGranularity = 256;
 
 /**
+ * @legacy
  * @alpha
  */
 export interface IJSONTextSegment extends IJSONSegment {
@@ -28,6 +29,7 @@ export interface IJSONTextSegment extends IJSONSegment {
 }
 
 /**
+ * @legacy
  * @alpha
  */
 export class TextSegment extends BaseSegment {
@@ -106,6 +108,7 @@ export class TextSegment extends BaseSegment {
 
 /**
  * @deprecated This functionality was not meant to be exported and will be removed in a future release
+ * @legacy
  * @alpha
  */
 export interface IMergeTreeTextHelper {