Skip to main content

ISharedSegmentSequence Interface

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

To use, import via fluid-framework/legacy.

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

Signature​

export interface ISharedSegmentSequence<T extends ISegment> extends ISharedObject<ISharedSegmentSequenceEvents>, ISharedIntervalCollection<SequenceInterval>, MergeTreeRevertibleDriver

Extends: ISharedObject<ISharedSegmentSequenceEvents>, ISharedIntervalCollection<SequenceInterval>, MergeTreeRevertibleDriver

Type Parameters​

Parameter Constraint Description
T ISegment

Methods​

Method Alerts Return Type Description
annotateAdjustRange(start, end, adjust) Alpha void Annotates a specified range within the sequence by applying the provided adjustments.
annotateRange(start, end, props) Alpha void Annotates the range with the provided properties
createLocalReferencePosition(segment, offset, refType, properties, slidingPreference, canSlideToEndpoint) Alpha LocalReferencePosition Creates a LocalReferencePosition on this SharedString. If the refType does not include ReferenceType.Transient, the returned reference will be added to the localRefs on the provided segment.
getContainingSegment(pos) Alpha { segment: T | undefined; offset: number | undefined; } Finds the segment information (i.e. segment + offset) corresponding to a character position in the SharedString. If the position is past the end of the string, segment and offset on the returned object may be undefined.
getCurrentSeq() Alpha number
getIntervalCollection(label) Alpha IIntervalCollection<SequenceInterval> Retrieves the interval collection keyed on label. If no such interval collection exists, creates one.
getIntervalCollectionLabels() Alpha IterableIterator<string>
getLength() Alpha number Returns the length of the current sequence for the client
getPosition(segment) Alpha number Returns the current position of a segment, and -1 if the segment does not exist in this sequence
getPropertiesAtPosition(pos) Alpha PropertySet | undefined
getRangeExtentsOfPosition(pos) Alpha { posStart: number | undefined; posAfterEnd: number | undefined; }
groupOperation(groupOp) Deprecated, Alpha void
initializeLocal() Alpha void Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.
insertAtReferencePosition(pos, segment) Alpha void Inserts a segment directly before a ReferencePosition.
insertFromSpec(pos, spec) Alpha void Inserts a segment
localReferencePositionToPosition(lref) Alpha number

Resolves a ReferencePosition into a character position using this client's perspective.

Reference positions that point to a character that has been removed will always return the position of the nearest non-removed character, regardless of ReferenceType. To handle this case specifically, one may wish to look at the segment returned by ReferencePosition.getSegment.
obliterateRange(start, end) Alpha void

Obliterate is similar to remove, but differs in that segments concurrently inserted into an obliterated range will also be removed. Inserts are considered concurrent to an obliterate iff the insert op's seq is after the obliterate op's refSeq and the insert's refSeq is before the obliterates seq. Inserts made by the client which most recently obliterated a range containing the insert position are not considered concurrent to any obliteration (the last client to obliterate gets the right to insert).

The endpoints can either be inclusive or exclusive. Exclusive endpoints allow the obliterated range to "grow" to include adjacent concurrently inserted segments on that side.
posFromRelativePos(relativePos) Alpha number Given a position specified relative to a marker id, lookup the marker and convert the position to a character position.
removeLocalReferencePosition(lref) Alpha LocalReferencePosition | undefined Removes a LocalReferencePosition from this SharedString.
removeRange(start, end) Alpha void
resolveRemoteClientPosition(remoteClientPosition, remoteClientRefSeq, remoteClientId) Alpha number | undefined Resolves a remote client's position against the local sequence and returns the remote client's position relative to the local sequence. The client ref seq must be above the minimum sequence number or the return value will be undefined. Generally this method is used in conjunction with signals which provide point in time values for the below parameters, and is useful for things like displaying user position. It should not be used with persisted values as persisted values will quickly become invalid as the remoteClientRefSeq moves below the minimum sequence number
walkSegments(handler, start, end, accum, splitRange) Alpha void

Walk the underlying segments of the sequence. The walked segments may extend beyond the range if the segments cross the ranges start or end boundaries.

Set split range to true to ensure only segments within the range are walked.

Method Details​

annotateAdjustRange​

Annotates a specified range within the sequence by applying the provided adjustments.

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

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

Signature​

annotateAdjustRange(start: number, end: number, adjust: MapLike<AdjustParams>): void;

Remarks​

The range is defined by the start and end positions, where the start position is inclusive and the end position is exclusive. The properties provided in the adjust parameter will be applied to the specified range. Each adjustment modifies the current value of the property by adding the specified value. If the current value is not a number, the delta will be summed with 0 to compute the new value. The optional min and max constraints are applied after the adjustment to ensure the final value falls within the specified bounds.

Parameters​

Parameter Type Description
start number The inclusive start position of the range to annotate. This is a zero-based index.
end number The exclusive end position of the range to annotate. This is a zero-based index.
adjust MapLike<AdjustParams> A map-like object specifying the properties to adjust. Each key-value pair represents a property and its corresponding adjustment to be applied over the range. An adjustment is defined by an object containing a delta to be added to the current property value, and optional min and max constraints to limit the adjusted value.

annotateRange​

Annotates the range with the provided properties

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

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

Signature​

annotateRange(start: number, end: number, props: PropertySet): void;

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

createLocalReferencePosition​

Creates a LocalReferencePosition on this SharedString. If the refType does not include ReferenceType.Transient, the returned reference will be added to the localRefs on the provided segment.

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

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

Signature​

createLocalReferencePosition(segment: T, offset: number, refType: ReferenceType, properties: PropertySet | undefined, slidingPreference?: SlidingPreference, canSlideToEndpoint?: boolean): LocalReferencePosition;

Parameters​

Parameter Modifiers Type Description
segment T Segment to add the local reference on
offset number Offset on the segment at which to place the local reference
refType ReferenceType ReferenceType for the created local reference
properties PropertySet | undefined PropertySet to place on the created local reference
slidingPreference optional SlidingPreference
canSlideToEndpoint optional boolean

Returns​

Return type: LocalReferencePosition

getContainingSegment​

Finds the segment information (i.e. segment + offset) corresponding to a character position in the SharedString. If the position is past the end of the string, segment and offset on the returned object may be undefined.

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

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

Signature​

getContainingSegment(pos: number): {
        segment: T | undefined;
        offset: number | undefined;
    };

Parameters​

Parameter Type Description
pos number Character position (index) into the current local view of the SharedString.

Returns​

Return type: { segment: T | undefined; offset: number | undefined; }

getCurrentSeq​

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

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

Signature​

getCurrentSeq(): number;

Returns​

The most recent sequence number which has been acked by the server and processed by this SharedSegmentSequence.

Return type: number

getIntervalCollection​

Retrieves the interval collection keyed on label. If no such interval collection exists, creates one.

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

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

Signature​

getIntervalCollection(label: string): IIntervalCollection<SequenceInterval>;

Parameters​

Parameter Type Description
label string

Returns​

Return type: IIntervalCollection<SequenceInterval>

getIntervalCollectionLabels​

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

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

Signature​

getIntervalCollectionLabels(): IterableIterator<string>;

Example​

const iter = this.getIntervalCollectionKeys();
for (key of iter)
    const collection = this.getIntervalCollection(key);
    ...

Returns​

An iterable object that enumerates the IntervalCollection labels.

Return type: IterableIterator<string>

getLength​

Returns the length of the current sequence for the client

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

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

Signature​

getLength(): number;

Returns​

Return type: number

getPosition​

Returns the current position of a segment, and -1 if the segment does not exist in this sequence

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

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

Signature​

getPosition(segment: ISegment): number;

Parameters​

Parameter Type Description
segment ISegment The segment to get the position of

Returns​

Return type: number

getPropertiesAtPosition​

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

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

Signature​

getPropertiesAtPosition(pos: number): PropertySet | undefined;

Parameters​

Parameter Type Description
pos number

Returns​

Return type: PropertySet | undefined

getRangeExtentsOfPosition​

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

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

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; }

groupOperation​

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

The ability to create group ops will be removed in an upcoming release, as group ops are redundant with the native batching capabilities of the runtime

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

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

Signature​

groupOperation(groupOp: IMergeTreeGroupMsg): void;

Parameters​

Parameter Type Description
groupOp IMergeTreeGroupMsg

initializeLocal​

Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.

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

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

Signature​

initializeLocal(): void;

insertAtReferencePosition​

Inserts a segment directly before a ReferencePosition.

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

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

Signature​

insertAtReferencePosition(pos: ReferencePosition, segment: T): void;

Parameters​

Parameter Type Description
pos ReferencePosition
segment T The segment to insert

insertFromSpec​

Inserts a segment

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

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

Signature​

insertFromSpec(pos: number, spec: IJSONSegment): void;

Parameters​

Parameter Type Description
pos number
spec IJSONSegment The segment to inserts spec

localReferencePositionToPosition​

Resolves a ReferencePosition into a character position using this client's perspective.

Reference positions that point to a character that has been removed will always return the position of the nearest non-removed character, regardless of ReferenceType. To handle this case specifically, one may wish to look at the segment returned by ReferencePosition.getSegment.

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

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

Signature​

localReferencePositionToPosition(lref: ReferencePosition): number;

Parameters​

Parameter Type Description
lref ReferencePosition

Returns​

Return type: number

obliterateRange​

Obliterate is similar to remove, but differs in that segments concurrently inserted into an obliterated range will also be removed. Inserts are considered concurrent to an obliterate iff the insert op's seq is after the obliterate op's refSeq and the insert's refSeq is before the obliterates seq. Inserts made by the client which most recently obliterated a range containing the insert position are not considered concurrent to any obliteration (the last client to obliterate gets the right to insert).

The endpoints can either be inclusive or exclusive. Exclusive endpoints allow the obliterated range to "grow" to include adjacent concurrently inserted segments on that side.

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

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

Signature​

obliterateRange(start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): void;

Example​

Given the initial state "|ABC>", obliterateRange({ pos: 0, side: Side.After }, { pos: 4, side: Side.Before }) obliterates "ABC", leaving only "|>". insertFromSpec(1, { text: "AAA"}) would insert "AAA" before |, resulting in "|AAA>". If another client does the same thing but inserts "BBB" and gets sequenced later, all clients will eventually see |BBB>.

Parameters​

Parameter Type Description
start number | InteriorSequencePlace The start of the range to obliterate. Inclusive if side is Before or a number is provided.
end number | InteriorSequencePlace The end of the range to obliterate. Inclusive if side is After. If a number is provided it is treated as exclusive, but the endpoint does not expand in order to preserve existing behavior.

posFromRelativePos​

Given a position specified relative to a marker id, lookup the marker and convert the position to a character position.

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

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

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

removeLocalReferencePosition​

Removes a LocalReferencePosition from this SharedString.

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

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

Signature​

removeLocalReferencePosition(lref: LocalReferencePosition): LocalReferencePosition | undefined;

Parameters​

Parameter Type Description
lref LocalReferencePosition

Returns​

Return type: LocalReferencePosition | undefined

removeRange​

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

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

Signature​

removeRange(start: number, end: number): void;

Parameters​

Parameter Type Description
start number The inclusive start of the range to remove
end number The exclusive end of the range to remove

resolveRemoteClientPosition​

Resolves a remote client's position against the local sequence and returns the remote client's position relative to the local sequence. The client ref seq must be above the minimum sequence number or the return value will be undefined. Generally this method is used in conjunction with signals which provide point in time values for the below parameters, and is useful for things like displaying user position. It should not be used with persisted values as persisted values will quickly become invalid as the remoteClientRefSeq moves below the minimum sequence number

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

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

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

walkSegments​

Walk the underlying segments of the sequence. The walked segments may extend beyond the range if the segments cross the ranges start or end boundaries.

Set split range to true to ensure only segments within the range are walked.

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

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

Signature​

walkSegments<TClientData>(handler: ISegmentAction<TClientData>, start?: number, end?: number, accum?: TClientData, splitRange?: boolean): void;
Type Parameters​
Parameter Description
TClientData

Parameters​

Parameter Modifiers Type Description
handler ISegmentAction<TClientData> The function to handle each segment. Traversal ends if this function returns true.
start optional number Optional. The start of range walk.
end optional number Optional. The end of range walk
accum optional TClientData Optional. An object that will be passed to the handler for accumulation
splitRange optional boolean Optional. Splits boundary segments on the range boundaries. Defaults to false.