ISegment Interface

A segment representing a portion of the merge tree. Segments are leaf nodes of the merge tree and contain data.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/merge-tree/legacy.

For more information about our API support guarantees, see here.

Signature

export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Partial<IMoveInfo>

Extends: IMergeNodeCommon, Partial<IRemovalInfo>, Partial<IMoveInfo>

Properties

Property	Alerts	Modifiers	Type	Description
attribution	Alpha	optional	IAttributionCollection<AttributionKey>	Stores attribution keys associated with offsets of this segment. This data is only persisted if MergeTree's attributions.track flag is set to true. Pending segments (i.e. ones that only exist locally and haven't been acked by the server) also have attribution === undefined until ack. Keys can be used opaquely with an IAttributor or a container runtime that provides attribution.
cachedLength	Alpha		number	The length of the contents of the node.
clientId	Alpha		number	Short clientId for the client that inserted this segment.
endpointType	Alpha	optional, readonly	"start" | "end"	Whether or not this segment is a special segment denoting the start or end of the tree Endpoint segments are imaginary segments positioned immediately before or after the tree. These segments cannot be referenced by regular operations and exist primarily as a bucket for local references to slide onto during deletion of regular segments.
localRefs	Alpha	optional	LocalReferenceCollection	Local references added to this segment.
localRemovedSeq	Alpha	optional	number	Local seq at which this segment was removed. If this is defined, removedSeq will initially be set to UnassignedSequenceNumber. However, if another client concurrently removes the same segment, removedSeq will be updated to the seq at which that client removed this segment. Like localSeq, this field is cleared once the local removal of the segment is acked.
localSeq	Alpha	optional	number	Local seq at which this segment was inserted. This is defined if and only if the insertion of the segment is pending ack, i.e. seq is UnassignedSequenceNumber. Once the segment is acked, this field is cleared.
properties	Alpha	optional	PropertySet	Properties that have been added to this segment via annotation.
seq	Alpha	optional	number	Seq at which this segment was inserted. If undefined, it is assumed the segment was inserted prior to the collab window's minimum sequence number.
trackingCollection	Alpha	readonly	TrackingGroupCollection
type	Alpha	readonly	string

Methods

Method	Alerts	Return Type	Description
append(segment)	Alpha	void
canAppend(segment)	Alpha	boolean
clone()	Alpha	ISegment
splitAt(pos)	Alpha	ISegment | undefined
toJSONObject()	Alpha	any

Property Details

attribution

Stores attribution keys associated with offsets of this segment. This data is only persisted if MergeTree's attributions.track flag is set to true. Pending segments (i.e. ones that only exist locally and haven't been acked by the server) also have attribution === undefined until ack.

Keys can be used opaquely with an IAttributor or a container runtime that provides attribution.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

attribution?: IAttributionCollection<AttributionKey>;

Type: IAttributionCollection<AttributionKey>

Remarks

There are plans to make the shape of the data stored extensible in a couple ways:

1. Injection of custom attribution information associated with the segment (ex: copy-paste of content but keeping the old attribution information).

2. Storage of multiple "channels" of information (ex: track property changes separately from insertion, or only attribute certain property modifications, etc.)

cachedLength

The length of the contents of the node.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

cachedLength: number;

Type: number

clientId

Short clientId for the client that inserted this segment.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

clientId: number;

Type: number

endpointType

Whether or not this segment is a special segment denoting the start or end of the tree

Endpoint segments are imaginary segments positioned immediately before or after the tree. These segments cannot be referenced by regular operations and exist primarily as a bucket for local references to slide onto during deletion of regular segments.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

readonly endpointType?: "start" | "end";

Type: "start" | "end"

localRefs

Local references added to this segment.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

localRefs?: LocalReferenceCollection;

Type: LocalReferenceCollection

localRemovedSeq

Local seq at which this segment was removed. If this is defined, removedSeq will initially be set to UnassignedSequenceNumber. However, if another client concurrently removes the same segment, removedSeq will be updated to the seq at which that client removed this segment.

Like localSeq, this field is cleared once the local removal of the segment is acked.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

localRemovedSeq?: number;

Type: number

localSeq

Local seq at which this segment was inserted. This is defined if and only if the insertion of the segment is pending ack, i.e. seq is UnassignedSequenceNumber. Once the segment is acked, this field is cleared.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

localSeq?: number;

Type: number

properties

Properties that have been added to this segment via annotation.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

properties?: PropertySet;

Type: PropertySet

seq

Seq at which this segment was inserted. If undefined, it is assumed the segment was inserted prior to the collab window's minimum sequence number.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

seq?: number;

Type: number

trackingCollection

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

readonly trackingCollection: TrackingGroupCollection;

Type: TrackingGroupCollection

type

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

readonly type: string;

Type: string

Method Details

append

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

append(segment: ISegment): void;

Parameters

Parameter	Type	Description
segment	ISegment

canAppend

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

canAppend(segment: ISegment): boolean;

Parameters

Parameter	Type	Description
segment	ISegment

Returns

Return type: boolean

clone

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

clone(): ISegment;

Returns

Return type: ISegment

splitAt

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

splitAt(pos: number): ISegment | undefined;

Parameters

Parameter	Type	Description
pos	number

Returns

Return type: ISegment | undefined

toJSONObject

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/merge-tree/alpha.

For more information about our API support guarantees, see here.

Signature

toJSONObject(): any;

Returns

Return type: any