ISegment Interface

Packages > @fluidframework/merge-tree > ISegment

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. See localSeq for more information on the semantics of localSeq.
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. See localSeq for more information on the semantics of localSeq.
properties	`Alpha`	`optional`	PropertySet	Properties that have been added to this segment via annotation.
propertyManager	`Deprecated`, `Alpha`	`optional`	PropertiesManager	Manages pending local state for properties on this segment.
segmentGroups	`Deprecated`, `Alpha`	`readonly`	SegmentGroupCollection
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
ack(segmentGroup, opArgs)	`Deprecated`, `Alpha`	boolean
addProperties(newProps, seq, collaborating, rollback)	`Deprecated`, `Alpha`	PropertySet	Add properties to this segment via annotation.
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:

Injection of custom attribution information associated with the segment (ex: copy-paste of content but keeping the old attribution information).
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. See localSeq for more information on the semantics of localSeq.

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.

See localSeq for more information on the semantics of localSeq.

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

propertyManager

Manages pending local state for properties on this segment.

This API is deprecated and will be removed in a future release.

This property should not be used externally and will be removed in a subsequent release.

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

propertyManager?: PropertiesManager;

Type: PropertiesManager

segmentGroups

This API is deprecated and will be removed in a future release.

This property should not be used externally and will be removed in a subsequent release.

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 segmentGroups: SegmentGroupCollection;

Type: SegmentGroupCollection

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

ack

This API is deprecated and will be removed in a future release.

This function should not be used externally and will be removed in a subsequent release. Acks the current segment against the segment group, op, and merge tree.

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

ack(segmentGroup: SegmentGroup, opArgs: IMergeTreeDeltaOpArgs): boolean;

Parameters

Parameter	Type	Description
segmentGroup	SegmentGroup	Pending segment group associated with this op.
opArgs	IMergeTreeDeltaOpArgs	Information about the op that was acked

Returns

true if the op modifies the segment, otherwise false. The only current false case is overlapping remove, where a segment is removed by a previously sequenced operation before the current operation is acked.

Return type: boolean

Error Handling

error if the segment state doesn’t match segment group or op. E.g. if the segment group is not first in the pending queue, or an inserted segment does not have unassigned sequence number.

addProperties

Add properties to this segment via annotation.

This API is deprecated and will be removed in a future release.

This function should not be used externally and will be removed in a subsequent release.

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

addProperties(newProps: PropertySet, seq?: number, collaborating?: boolean, rollback?: PropertiesRollback): PropertySet;

Remarks

This function should not be called directly. Properties should be added through the annotateRange functions.

Parameters

Parameter	Modifiers	Type
newProps		PropertySet
seq	optional	number
collaborating	optional	boolean
rollback	optional	PropertiesRollback

Returns

Return type: PropertySet

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