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