Packages > @fluidframework/sequence

@fluidframework/sequence Package

Supports distributed data structures which are list-like.

This library’s main export is SharedString , a DDS for storing and simultaneously editing a sequence of text.

See the package’s README for a high-level introduction to SharedString’s feature set.

Remarks

Note that SharedString is a sequence DDS but it has additional specialized features and behaviors for working with text.

Interfaces

Interface Alerts Description
IInterval ALPHA Basic interval abstraction
IIntervalCollection ALPHA Collection of intervals that supports addition, modification, removal, and efficient spatial querying. Changes to this collection will be incur updates on collaborating clients (i.e. they are not local-only).
IIntervalCollectionEvent ALPHA Change events emitted by IntervalCollections
InteriorSequencePlace ALPHA

A sequence place that does not refer to the special endpoint segments.

See SequencePlace for additional context.

IntervalIndex ALPHA

Collection of intervals.

Implementers of this interface will typically implement additional APIs to support efficiently querying a collection of intervals in some manner, for example: - "find all intervals with start endpoint between these two points" - "find all intervals which overlap this range" etc.

ISequenceDeltaRange ALPHA A range that has changed corresponding to a segment modification.
ISerializableInterval ALPHA
ISerializedInterval ALPHA Serialized object representation of an interval. This representation is used for ops that create or change intervals.
ISharedIntervalCollection ALPHA
ISharedSegmentSequenceEvents ALPHA Events emitted in response to changes to the sequence data.
ISharedString ALPHA Fluid object interface describing access methods on a SharedString

Classes

Class Alerts Description
SequenceDeltaEvent ALPHA

The event object returned on sequenceDelta events.

The properties of this object and its sub-objects represent the state of the sequence at the point in time at which the operation was applied. They will not take into consideration any future modifications performed to the underlying sequence and merge tree.

For group ops, each op will get its own event, and the group op property will be set on the op args.

Ops may get multiple events. For instance, an insert-replace will get a remove then an insert event.

SequenceEvent ALPHA

Base class for SequenceDeltaEvent and SequenceMaintenanceEvent.

The properties of this object and its sub-objects represent the state of the sequence at the point in time at which the operation was applied. They will not take into any future modifications performed to the underlying sequence and merge tree.

SequenceInterval ALPHA Interval implementation whose ends are associated with positions in a mutatable sequence. As such, when content is inserted into the middle of the interval, the interval expands to include that content.
SequenceMaintenanceEvent ALPHA

The event object returned on maintenance events.

The properties of this object and its sub-objects represent the state of the sequence at the point in time at which the operation was applied. They will not take into consideration any future modifications performed to the underlying sequence and merge tree.

SharedSegmentSequence ALPHA
SharedString ALPHA

The Shared String is a specialized data structure for handling collaborative text. It is based on a more general Sequence data structure but has additional features that make working with text easier.

In addition to text, a Shared String can also contain markers. Markers can be used to store metadata at positions within the text, like the details of an image or Fluid object that should be rendered with the text.

SharedStringFactory ALPHA

Enumerations

Enum Alerts Description
IntervalType ALPHA
Side ALPHA Defines a side relative to a character in a sequence.

Types

TypeAlias Alerts Description
DeserializeCallback ALPHA
IntervalStickiness ALPHA

Determines how an interval should expand when segments are inserted adjacent to the range it spans

Note that interval stickiness is currently an experimental feature and must be explicitly enabled with the intervalStickinessEnabled flag

SequencePlace ALPHA

Defines a position and side relative to a character in a sequence.

For this purpose, sequences look like:

{start} - {character 0} - {character 1} - ... - {character N} - {end}

Each {value} in the diagram is a character within a sequence. Each - in the above diagram is a position where text could be inserted. Each position between a {value} and a - is a SequencePlace.

The special endpoints {start} and {end} refer to positions outside the contents of the string.

This gives us 2N + 2 possible positions to refer to within a string, where N is the number of characters.

If the position is specified with a bare number, the side defaults to Side.Before.

If a SequencePlace is the endpoint of a range (e.g. start/end of an interval or search range), the Side value means it is exclusive if it is nearer to the other position and inclusive if it is farther. E.g. the start of a range with Side.After is exclusive of the character at the position.

SharedStringSegment ALPHA

Variables

Variable Alerts Modifiers Description
IntervalStickiness ALPHA readonly

Determines how an interval should expand when segments are inserted adjacent to the range it spans

Note that interval stickiness is currently an experimental feature and must be explicitly enabled with the intervalStickinessEnabled flag

Type Details

DeserializeCallback (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type DeserializeCallback = (properties: PropertySet) => void;

IntervalStickiness (ALPHA)

Determines how an interval should expand when segments are inserted adjacent to the range it spans

Note that interval stickiness is currently an experimental feature and must be explicitly enabled with the intervalStickinessEnabled flag

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type IntervalStickiness = (typeof IntervalStickiness)[keyof typeof IntervalStickiness];

SequencePlace (ALPHA)

Defines a position and side relative to a character in a sequence.

For this purpose, sequences look like:

{start} - {character 0} - {character 1} - ... - {character N} - {end}

Each {value} in the diagram is a character within a sequence. Each - in the above diagram is a position where text could be inserted. Each position between a {value} and a - is a SequencePlace.

The special endpoints {start} and {end} refer to positions outside the contents of the string.

This gives us 2N + 2 possible positions to refer to within a string, where N is the number of characters.

If the position is specified with a bare number, the side defaults to Side.Before.

If a SequencePlace is the endpoint of a range (e.g. start/end of an interval or search range), the Side value means it is exclusive if it is nearer to the other position and inclusive if it is farther. E.g. the start of a range with Side.After is exclusive of the character at the position.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SequencePlace = number | "start" | "end" | InteriorSequencePlace;

SharedStringSegment (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type SharedStringSegment = TextSegment | Marker;

Variable Details

IntervalStickiness (ALPHA)

Determines how an interval should expand when segments are inserted adjacent to the range it spans

Note that interval stickiness is currently an experimental feature and must be explicitly enabled with the intervalStickinessEnabled flag

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

IntervalStickiness: {
    readonly NONE: 0;
    readonly START: 1;
    readonly END: 2;
    readonly FULL: 3;
}