Packages > @fluidframework/merge-tree > ISegment

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. 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 Alpha optional PropertiesManager Manages pending local state for properties on this segment.
segmentGroups 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) Alpha boolean Acks the current segment against the segment group, op, and merge tree.
addProperties(newProps, seq, collaborating, rollback) 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:

  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. 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 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 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

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 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 Description
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