Skip to main content
Version: v1

Client Class

Signature​

export declare class Client

Constructors​

Constructor Description
(constructor)(specToSegment, logger, options) Constructs a new instance of the Client class

Properties​

Property Type Description
accumOps number
accumTime number
accumWindow number
accumWindowTime number
localOps number
localTime number
logger ITelemetryLogger
longClientId string | undefined
maxWindowTime number
measureOps boolean
mergeTree MergeTree
mergeTreeDeltaCallback MergeTreeDeltaCallback | undefined
mergeTreeMaintenanceCallback MergeTreeMaintenanceCallback | undefined
specToSegment (spec: IJSONSegment) => ISegment

Methods​

Method Alerts Return Type Description
addLocalReference(lref) Deprecated void
addLongClientId(longClientId) void
annotateMarker(marker, props, combiningOp) IMergeTreeAnnotateMsg | undefined Annotates the markers with the provided properties
annotateMarkerNotifyConsensus(marker, props, consensusCallback) IMergeTreeAnnotateMsg | undefined Annotate a marker and call the callback on consensus.
annotateRangeLocal(start, end, props, combiningOp) IMergeTreeAnnotateMsg | undefined Annotates the range with the provided properties
applyMsg(msg, local) void
applyStashedOp(op) SegmentGroup
applyStashedOp(op) SegmentGroup[]
applyStashedOp(op) SegmentGroup | SegmentGroup[]
cloneFromSegments() Client
createLocalReferencePosition(segment, offset, refType, properties) LocalReferencePosition
createTextHelper() MergeTreeTextHelper
findReconnectionPosition(segment, localSeq) number During reconnect, we must find the positions to pending segments relative to other pending segments. This methods computes that position relative to a localSeq. Pending segments above the localSeq will be ignored.
findTile(startPos, tileLabel, preceding) { tile: ReferencePosition; pos: number; } | undefined
getClientId() number
getCollabWindow() CollaborationWindow
getContainingSegment(pos, op) { segment: T | undefined; offset: number | undefined; }
getCurrentSeq() number
getLength() number
getLongClientId(shortClientId) string
getMarkerFromId(id) ISegment | undefined
getOrAddShortClientId(longClientId) number
getPosition(segment) number Returns the current position of a segment, and -1 if the segment does not exist in this merge tree
getPropertiesAtPosition(pos) PropertySet | undefined
getRangeExtentsOfPosition(pos) { posStart: number | undefined; posAfterEnd: number | undefined; }
getShortClientId(longClientId) number
getSlideToSegment(segoff) { segment: ISegment | undefined; offset: number | undefined; } Returns the position to slide a reference to if a slide is required.
getStackContext(startPos, rangeLabels) RangeStackMap
insertAtReferencePositionLocal(refPos, segment) IMergeTreeInsertMsg | undefined
insertSegmentLocal(pos, segment) IMergeTreeInsertMsg | undefined
load(runtime, storage, serializer) Promise<{ catchupOpsP: Promise<ISequencedDocumentMessage[]>; }>
localReferencePositionToPosition(lref) number
localTransaction(groupOp) void
peekPendingSegmentGroups(count) SegmentGroup | SegmentGroup[] | undefined The merge tree maintains a queue of segment groups for each local operation. These segment groups track segments modified by an operation. This method peeks the tail of that queue, and returns the segments groups there. It is used to get the segment group(s) for the previous operations.
posFromRelativePos(relativePos) number Given a position specified relative to a marker id, lookup the marker and convert the position to a character position.
rebasePosition(pos, seqNumberFrom, localSeq) number

Rebases a (local) position from the perspective { seq: seqNumberFrom, localSeq } to the perspective of the current sequence number. This is desirable when rebasing operations for reconnection.

If the position refers to a segment/offset that was removed by some operation between seqNumberFrom and the current sequence number, the returned position will align with the position of a reference given SlideOnRemove semantics.
regeneratePendingOp(resetOp, segmentGroup) IMergeTreeOp Given an pending operation and segment group, regenerate the op, so it can be resubmitted
removeLocalReference(lref) Deprecated LocalReferencePosition | undefined
removeLocalReferencePosition(lref) LocalReferencePosition | undefined
removeRangeLocal(start, end) IMergeTreeRemoveMsg | undefined Removes the range
resolveRemoteClientPosition(remoteClientPosition, remoteClientRefSeq, remoteClientId) number | undefined Resolves a remote client's position against the local sequence and returns the remote client's position relative to the local sequence
serializeGCData(handle, handleCollectingSerializer) void Serializes the data required for garbage collection. The IFluidHandles stored in all segments that haven't been removed represent routes to other objects. We serialize the data in these segments using the passed in serializer which keeps track of all serialized handles.
startOrUpdateCollaboration(longClientId, minSeq, currentSeq) void
summarize(runtime, handle, serializer, catchUpMsgs) ISummaryTreeWithStats
updateConsensusProperty(op, msg) void
updateMinSeq(minSeq) void
updateSeqNumbers(min, seq) void
walkSegments(handler, start, end, accum, splitRange) void
walkSegments(handler, start, end, accum, splitRange) void

Constructor Details​

(constructor)​

Constructs a new instance of the Client class

Signature​

constructor(specToSegment: (spec: IJSONSegment) => ISegment, logger: ITelemetryLogger, options?: PropertySet);

Parameters​

Parameter Modifiers Type Description
specToSegment (spec: IJSONSegment) => ISegment
logger ITelemetryLogger
options optional PropertySet

Property Details​

accumOps​

Signature​

accumOps: number;

Type: number

accumTime​

Signature​

accumTime: number;

Type: number

accumWindow​

Signature​

accumWindow: number;

Type: number

accumWindowTime​

Signature​

accumWindowTime: number;

Type: number

localOps​

Signature​

localOps: number;

Type: number

localTime​

Signature​

localTime: number;

Type: number

logger​

Signature​

readonly logger: ITelemetryLogger;

Type: ITelemetryLogger

longClientId​

Signature​

longClientId: string | undefined;

Type: string | undefined

maxWindowTime​

Signature​

maxWindowTime: number;

Type: number

measureOps​

Signature​

measureOps: boolean;

Type: boolean

mergeTree​

Signature​

protected readonly mergeTree: MergeTree;

Type: MergeTree

mergeTreeDeltaCallback​

Signature​

get mergeTreeDeltaCallback(): MergeTreeDeltaCallback | undefined;
set mergeTreeDeltaCallback(callback: MergeTreeDeltaCallback | undefined);

Type: MergeTreeDeltaCallback | undefined

mergeTreeMaintenanceCallback​

Signature​

get mergeTreeMaintenanceCallback(): MergeTreeMaintenanceCallback | undefined;
set mergeTreeMaintenanceCallback(callback: MergeTreeMaintenanceCallback | undefined);

Type: MergeTreeMaintenanceCallback | undefined

specToSegment​

Signature​

readonly specToSegment: (spec: IJSONSegment) => ISegment;

Type: (spec: IJSONSegment) => ISegment

Method Details​

addLocalReference​

This API is deprecated and will be removed in a future release.
  • use createReferencePosition instead

Signature​

addLocalReference(lref: LocalReference): void;

Parameters​

Parameter Type Description
lref LocalReference

addLongClientId​

Signature​

addLongClientId(longClientId: string): void;

Parameters​

Parameter Type Description
longClientId string

annotateMarker​

Annotates the markers with the provided properties

Signature​

annotateMarker(marker: Marker, props: PropertySet, combiningOp?: ICombiningOp): IMergeTreeAnnotateMsg | undefined;

Parameters​

Parameter Modifiers Type Description
marker Marker The marker to annotate
props PropertySet The properties to annotate the marker with
combiningOp optional ICombiningOp Optional. Specifies how to combine values for the property, such as "incr" for increment.

Returns​

The annotate op if valid, otherwise undefined

Return type: IMergeTreeAnnotateMsg | undefined

annotateMarkerNotifyConsensus​

Annotate a marker and call the callback on consensus.

Signature​

annotateMarkerNotifyConsensus(marker: Marker, props: PropertySet, consensusCallback: (m: Marker) => void): IMergeTreeAnnotateMsg | undefined;

Parameters​

Parameter Type Description
marker Marker The marker to annotate
props PropertySet The properties to annotate the marker with
consensusCallback (m: Marker) => void The callback called when consensus is reached

Returns​

The annotate op if valid, otherwise undefined

Return type: IMergeTreeAnnotateMsg | undefined

annotateRangeLocal​

Annotates the range with the provided properties

Signature​

annotateRangeLocal(start: number, end: number, props: PropertySet, combiningOp: ICombiningOp | undefined): IMergeTreeAnnotateMsg | undefined;

Parameters​

Parameter Type Description
start number The inclusive start position of the range to annotate
end number The exclusive end position of the range to annotate
props PropertySet The properties to annotate the range with
combiningOp ICombiningOp | undefined Specifies how to combine values for the property, such as "incr" for increment.

Returns​

The annotate op if valid, otherwise undefined

Return type: IMergeTreeAnnotateMsg | undefined

applyMsg​

Signature​

applyMsg(msg: ISequencedDocumentMessage, local?: boolean): void;

Parameters​

Parameter Modifiers Type Description
msg ISequencedDocumentMessage
local optional boolean

applyStashedOp​

Signature​

applyStashedOp(op: IMergeTreeDeltaOp): SegmentGroup;

Parameters​

Parameter Type Description
op IMergeTreeDeltaOp

Returns​

Return type: SegmentGroup

applyStashedOp​

Signature​

applyStashedOp(op: IMergeTreeGroupMsg): SegmentGroup[];

Parameters​

Parameter Type Description
op IMergeTreeGroupMsg

Returns​

Return type: SegmentGroup[]

applyStashedOp​

Signature​

applyStashedOp(op: IMergeTreeOp): SegmentGroup | SegmentGroup[];

Parameters​

Parameter Type Description
op IMergeTreeOp

Returns​

Return type: SegmentGroup | SegmentGroup[]

cloneFromSegments​

Signature​

cloneFromSegments(): Client;

Returns​

Return type: Client

createLocalReferencePosition​

Signature​

createLocalReferencePosition(segment: ISegment, offset: number | undefined, refType: ReferenceType, properties: PropertySet | undefined): LocalReferencePosition;

Parameters​

Parameter Type Description
segment ISegment
offset number | undefined
refType ReferenceType
properties PropertySet | undefined

Returns​

Return type: LocalReferencePosition

createTextHelper​

Signature​

createTextHelper(): MergeTreeTextHelper;

Returns​

Return type: MergeTreeTextHelper

findReconnectionPosition​

During reconnect, we must find the positions to pending segments relative to other pending segments. This methods computes that position relative to a localSeq. Pending segments above the localSeq will be ignored.

Signature​

protected findReconnectionPosition(segment: ISegment, localSeq: number): number;

Parameters​

Parameter Type Description
segment ISegment The segment to find the position for
localSeq number The localSeq to find the position of the segment at

Returns​

Return type: number

findTile​

Signature​

findTile(startPos: number, tileLabel: string, preceding?: boolean): {
        tile: ReferencePosition;
        pos: number;
    } | undefined;

Parameters​

Parameter Modifiers Type Description
startPos number
tileLabel string
preceding optional boolean

Returns​

Return type: { tile: ReferencePosition; pos: number; } | undefined

getClientId​

Signature​

getClientId(): number;

Returns​

Return type: number

getCollabWindow​

Signature​

getCollabWindow(): CollaborationWindow;

Returns​

Return type: CollaborationWindow

getContainingSegment​

Signature​

getContainingSegment<T extends ISegment>(pos: number, op?: ISequencedDocumentMessage): {
        segment: T | undefined;
        offset: number | undefined;
    };
Type Parameters​
Parameter Constraint Description
T ISegment

Parameters​

Parameter Modifiers Type Description
pos number
op optional ISequencedDocumentMessage

Returns​

Return type: { segment: T | undefined; offset: number | undefined; }

getCurrentSeq​

Signature​

getCurrentSeq(): number;

Returns​

Return type: number

getLength​

Signature​

getLength(): number;

Returns​

Return type: number

getLongClientId​

Signature​

getLongClientId(shortClientId: number): string;

Parameters​

Parameter Type Description
shortClientId number

Returns​

Return type: string

getMarkerFromId​

Signature​

getMarkerFromId(id: string): ISegment | undefined;

Parameters​

Parameter Type Description
id string

Returns​

Return type: ISegment | undefined

getOrAddShortClientId​

Signature​

getOrAddShortClientId(longClientId: string): number;

Parameters​

Parameter Type Description
longClientId string

Returns​

Return type: number

getPosition​

Returns the current position of a segment, and -1 if the segment does not exist in this merge tree

Signature​

getPosition(segment: ISegment): number;

Parameters​

Parameter Type Description
segment ISegment The segment to get the position of

Returns​

Return type: number

getPropertiesAtPosition​

Signature​

getPropertiesAtPosition(pos: number): PropertySet | undefined;

Parameters​

Parameter Type Description
pos number

Returns​

Return type: PropertySet | undefined

getRangeExtentsOfPosition​

Signature​

getRangeExtentsOfPosition(pos: number): {
        posStart: number | undefined;
        posAfterEnd: number | undefined;
    };

Parameters​

Parameter Type Description
pos number

Returns​

Return type: { posStart: number | undefined; posAfterEnd: number | undefined; }

getShortClientId​

Signature​

getShortClientId(longClientId: string): number;

Parameters​

Parameter Type Description
longClientId string

Returns​

Return type: number

getSlideToSegment​

Returns the position to slide a reference to if a slide is required.

Signature​

getSlideToSegment(segoff: {
        segment: ISegment | undefined;
        offset: number | undefined;
    }): {
        segment: ISegment | undefined;
        offset: number | undefined;
    };

Parameters​

Parameter Type Description
segoff { segment: ISegment | undefined; offset: number | undefined; } The segment and offset to slide from

Returns​

  • segment and offset to slide the reference to

Return type: { segment: ISegment | undefined; offset: number | undefined; }

getStackContext​

Signature​

getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap;

Parameters​

Parameter Type Description
startPos number
rangeLabels string[]

Returns​

Return type: RangeStackMap

insertAtReferencePositionLocal​

Signature​

insertAtReferencePositionLocal(refPos: ReferencePosition, segment: ISegment): IMergeTreeInsertMsg | undefined;

Parameters​

Parameter Type Description
refPos ReferencePosition The reference position to insert the segment at
segment ISegment The segment to insert

Returns​

Return type: IMergeTreeInsertMsg | undefined

insertSegmentLocal​

Signature​

insertSegmentLocal(pos: number, segment: ISegment): IMergeTreeInsertMsg | undefined;

Parameters​

Parameter Type Description
pos number The position to insert the segment at
segment ISegment The segment to insert

Returns​

Return type: IMergeTreeInsertMsg | undefined

load​

Signature​

load(runtime: IFluidDataStoreRuntime, storage: IChannelStorageService, serializer: IFluidSerializer): Promise<{
        catchupOpsP: Promise<ISequencedDocumentMessage[]>;
    }>;

Parameters​

Parameter Type Description
runtime IFluidDataStoreRuntime
storage IChannelStorageService
serializer IFluidSerializer

Returns​

Return type: Promise<{ catchupOpsP: Promise<ISequencedDocumentMessage[]>; }>

localReferencePositionToPosition​

Signature​

localReferencePositionToPosition(lref: ReferencePosition): number;

Parameters​

Parameter Type Description
lref ReferencePosition

Returns​

Return type: number

localTransaction​

Signature​

localTransaction(groupOp: IMergeTreeGroupMsg): void;

Parameters​

Parameter Type Description
groupOp IMergeTreeGroupMsg

peekPendingSegmentGroups​

The merge tree maintains a queue of segment groups for each local operation. These segment groups track segments modified by an operation. This method peeks the tail of that queue, and returns the segments groups there. It is used to get the segment group(s) for the previous operations.

Signature​

peekPendingSegmentGroups(count?: number): SegmentGroup | SegmentGroup[] | undefined;

Parameters​

Parameter Modifiers Type Description
count optional number The number segment groups to get peek from the tail of the queue. Default 1.

Returns​

Return type: SegmentGroup | SegmentGroup[] | undefined

posFromRelativePos​

Given a position specified relative to a marker id, lookup the marker and convert the position to a character position.

Signature​

posFromRelativePos(relativePos: IRelativePosition): number;

Parameters​

Parameter Type Description
relativePos IRelativePosition Id of marker (may be indirect) and whether position is before or after marker.

Returns​

Return type: number

rebasePosition​

Rebases a (local) position from the perspective { seq: seqNumberFrom, localSeq } to the perspective of the current sequence number. This is desirable when rebasing operations for reconnection.

If the position refers to a segment/offset that was removed by some operation between seqNumberFrom and the current sequence number, the returned position will align with the position of a reference given SlideOnRemove semantics.

Signature​

rebasePosition(pos: number, seqNumberFrom: number, localSeq: number): number;

Parameters​

Parameter Type Description
pos number
seqNumberFrom number
localSeq number

Returns​

Return type: number

regeneratePendingOp​

Given an pending operation and segment group, regenerate the op, so it can be resubmitted

Signature​

regeneratePendingOp(resetOp: IMergeTreeOp, segmentGroup: SegmentGroup | SegmentGroup[]): IMergeTreeOp;

Parameters​

Parameter Type Description
resetOp IMergeTreeOp The op to reset
segmentGroup SegmentGroup | SegmentGroup[] The segment group associated with the op

Returns​

Return type: IMergeTreeOp

removeLocalReference​

This API is deprecated and will be removed in a future release.
  • use removeReferencePosition instead

Signature​

removeLocalReference(lref: LocalReference): LocalReferencePosition | undefined;

Parameters​

Parameter Type Description
lref LocalReference

Returns​

Return type: LocalReferencePosition | undefined

removeLocalReferencePosition​

Signature​

removeLocalReferencePosition(lref: LocalReferencePosition): LocalReferencePosition | undefined;

Parameters​

Parameter Type Description
lref LocalReferencePosition

Returns​

Return type: LocalReferencePosition | undefined

removeRangeLocal​

Removes the range

Signature​

removeRangeLocal(start: number, end: number): IMergeTreeRemoveMsg | undefined;

Parameters​

Parameter Type Description
start number The inclusive start of the range to remove
end number The exclusive end of the range to remove

Returns​

Return type: IMergeTreeRemoveMsg | undefined

resolveRemoteClientPosition​

Resolves a remote client's position against the local sequence and returns the remote client's position relative to the local sequence

Signature​

resolveRemoteClientPosition(remoteClientPosition: number, remoteClientRefSeq: number, remoteClientId: string): number | undefined;

Parameters​

Parameter Type Description
remoteClientPosition number The remote client's position to resolve
remoteClientRefSeq number The reference sequence number of the remote client
remoteClientId string The client id of the remote client

Returns​

Return type: number | undefined

serializeGCData​

Serializes the data required for garbage collection. The IFluidHandles stored in all segments that haven't been removed represent routes to other objects. We serialize the data in these segments using the passed in serializer which keeps track of all serialized handles.

Signature​

serializeGCData(handle: IFluidHandle, handleCollectingSerializer: IFluidSerializer): void;

Parameters​

Parameter Type Description
handle IFluidHandle
handleCollectingSerializer IFluidSerializer

startOrUpdateCollaboration​

Signature​

startOrUpdateCollaboration(longClientId: string | undefined, minSeq?: number, currentSeq?: number): void;

Parameters​

Parameter Modifiers Type Description
longClientId string | undefined
minSeq optional number
currentSeq optional number

summarize​

Signature​

summarize(runtime: IFluidDataStoreRuntime, handle: IFluidHandle, serializer: IFluidSerializer, catchUpMsgs: ISequencedDocumentMessage[]): ISummaryTreeWithStats;

Parameters​

Parameter Type Description
runtime IFluidDataStoreRuntime
handle IFluidHandle
serializer IFluidSerializer
catchUpMsgs ISequencedDocumentMessage[]

Returns​

Return type: ISummaryTreeWithStats

updateConsensusProperty​

Signature​

updateConsensusProperty(op: IMergeTreeAnnotateMsg, msg: ISequencedDocumentMessage): void;

Parameters​

Parameter Type Description
op IMergeTreeAnnotateMsg
msg ISequencedDocumentMessage

updateMinSeq​

Signature​

updateMinSeq(minSeq: number): void;

Parameters​

Parameter Type Description
minSeq number

updateSeqNumbers​

Signature​

updateSeqNumbers(min: number, seq: number): void;

Parameters​

Parameter Type Description
min number
seq number

walkSegments​

Signature​

walkSegments<TClientData>(handler: ISegmentAction<TClientData>, start: number | undefined, end: number | undefined, accum: TClientData, splitRange?: boolean): void;
Type Parameters​
Parameter Description
TClientData

Parameters​

Parameter Modifiers Type Description
handler ISegmentAction<TClientData>
start number | undefined
end number | undefined
accum TClientData
splitRange optional boolean

walkSegments​

Signature​

walkSegments<undefined>(handler: ISegmentAction<undefined>, start?: number, end?: number, accum?: undefined, splitRange?: boolean): void;
Type Parameters​
Parameter Description
undefined

Parameters​

Parameter Modifiers Type Description
handler ISegmentAction<undefined>
start optional number
end optional number
accum optional undefined
splitRange optional boolean