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