Skip to main content

@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 Legacy, Alpha Basic interval abstraction
IIntervalCollection Legacy, 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 Legacy, Alpha Change events emitted by IntervalCollections
IntervalIndex Legacy, 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.
IOverlappingIntervalsIndex Legacy, Alpha
ISequenceDeltaRange Legacy, Alpha A range that has changed corresponding to a segment modification.
ISerializableInterval Legacy, Alpha
ISerializedInterval Legacy, Alpha Serialized object representation of an interval. This representation is used for ops that create or change intervals.
ISharedIntervalCollection Legacy, Alpha
ISharedSegmentSequence Legacy, Alpha
ISharedSegmentSequenceEvents Legacy, Alpha Events emitted in response to changes to the sequence data.
ISharedString Legacy, Alpha Fluid object interface describing access methods on a SharedString
SequenceDeltaEvent Legacy, 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 Legacy, 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 Legacy, 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 Legacy, 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.

Enumerations​

Enum Alerts Description
IntervalType Legacy, Alpha

Types​

TypeAlias Alerts Description
DeserializeCallback Legacy, Alpha
IntervalOpType Legacy, Alpha
IntervalRevertible Legacy, Alpha Data for undoing edits affecting Intervals.
IntervalStickiness Legacy, 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
SharedString Legacy, Alpha Alias for ISharedString for compatibility.
SharedStringRevertible Legacy, Alpha Data for undoing edits on SharedStrings and Intervals.
SharedStringSegment Legacy, Alpha

Functions​

Function Alerts Return Type Description
appendAddIntervalToRevertibles(interval, revertibles) Legacy, Alpha SharedStringRevertible[] Create revertibles for adding an interval
appendChangeIntervalToRevertibles(string, newInterval, previousInterval, revertibles) Legacy, Alpha SharedStringRevertible[] Create revertibles for moving endpoints of an interval
appendDeleteIntervalToRevertibles(string, interval, revertibles) Legacy, Alpha SharedStringRevertible[] Create revertibles for deleting an interval
appendIntervalPropertyChangedToRevertibles(interval, deltas, revertibles) Legacy, Alpha SharedStringRevertible[] Create revertibles for changing properties of an interval
appendSharedStringDeltaToRevertibles(string, delta, revertibles) Legacy, Alpha void Create revertibles for SharedStringDeltas, handling indirectly modified intervals (e.g. reverting remove of a range that contains an interval will move the interval back)
createOverlappingIntervalsIndex(sharedString) Legacy, Alpha IOverlappingIntervalsIndex<SequenceInterval>
discardSharedStringRevertibles(sharedString, revertibles) Legacy, Alpha void Clean up resources held by revertibles that are no longer needed.
revertSharedStringRevertibles(sharedString, revertibles) Legacy, Alpha void Invoke revertibles to reverse prior edits

Variables​

Variable Alerts Modifiers Type Description
IntervalOpType Legacy, Alpha readonly { readonly PROPERTY_CHANGED: "propertyChanged"; readonly POSITION_REMOVE: "positionRemove"; readonly ADD: "add"; readonly DELETE: "delete"; readonly CHANGE: "change"; } Values are used in revertibles.
IntervalStickiness Legacy, Alpha readonly { readonly NONE: 0; readonly START: 1; readonly END: 2; readonly FULL: 3; }

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
SharedString Legacy, Alpha readonly import("@fluidframework/shared-object-base/internal").ISharedObjectKind<ISharedString> & import("@fluidframework/shared-object-base/internal").SharedObjectKind<ISharedString> Entrypoint for ISharedString creation.

Function Details​

appendAddIntervalToRevertibles​

Create revertibles for adding an interval

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function appendAddIntervalToRevertibles(interval: SequenceInterval, revertibles: SharedStringRevertible[]): SharedStringRevertible[];

Parameters​

Parameter Type Description
interval SequenceInterval
revertibles SharedStringRevertible[]

Returns​

Return type: SharedStringRevertible[]

appendChangeIntervalToRevertibles​

Create revertibles for moving endpoints of an interval

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function appendChangeIntervalToRevertibles(string: ISharedString, newInterval: SequenceInterval, previousInterval: SequenceInterval, revertibles: SharedStringRevertible[]): SharedStringRevertible[];

Parameters​

Parameter Type Description
string ISharedString
newInterval SequenceInterval
previousInterval SequenceInterval
revertibles SharedStringRevertible[]

Returns​

Return type: SharedStringRevertible[]

appendDeleteIntervalToRevertibles​

Create revertibles for deleting an interval

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function appendDeleteIntervalToRevertibles(string: ISharedString, interval: SequenceInterval, revertibles: SharedStringRevertible[]): SharedStringRevertible[];

Parameters​

Parameter Type Description
string ISharedString
interval SequenceInterval
revertibles SharedStringRevertible[]

Returns​

Return type: SharedStringRevertible[]

appendIntervalPropertyChangedToRevertibles​

Create revertibles for changing properties of an interval

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function appendIntervalPropertyChangedToRevertibles(interval: SequenceInterval, deltas: PropertySet, revertibles: SharedStringRevertible[]): SharedStringRevertible[];

Parameters​

Parameter Type Description
interval SequenceInterval
deltas PropertySet
revertibles SharedStringRevertible[]

Returns​

Return type: SharedStringRevertible[]

appendSharedStringDeltaToRevertibles​

Create revertibles for SharedStringDeltas, handling indirectly modified intervals (e.g. reverting remove of a range that contains an interval will move the interval back)

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function appendSharedStringDeltaToRevertibles(string: ISharedString, delta: SequenceDeltaEvent, revertibles: SharedStringRevertible[]): void;

Parameters​

Parameter Type Description
string ISharedString
delta SequenceDeltaEvent
revertibles SharedStringRevertible[]

createOverlappingIntervalsIndex​

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function createOverlappingIntervalsIndex(sharedString: ISharedString): IOverlappingIntervalsIndex<SequenceInterval>;

Parameters​

Parameter Type Description
sharedString ISharedString

Returns​

Return type: IOverlappingIntervalsIndex<SequenceInterval>

discardSharedStringRevertibles​

Clean up resources held by revertibles that are no longer needed.

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function discardSharedStringRevertibles(sharedString: ISharedString, revertibles: SharedStringRevertible[]): void;

Parameters​

Parameter Type Description
sharedString ISharedString
revertibles SharedStringRevertible[]

revertSharedStringRevertibles​

Invoke revertibles to reverse prior edits

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

export declare function revertSharedStringRevertibles(sharedString: ISharedString, revertibles: SharedStringRevertible[]): void;

Parameters​

Parameter Type Description
sharedString ISharedString
revertibles SharedStringRevertible[]

Variable Details​

IntervalOpType​

Values are used in revertibles.

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

IntervalOpType: {
    readonly PROPERTY_CHANGED: "propertyChanged";
    readonly POSITION_REMOVE: "positionRemove";
    readonly ADD: "add";
    readonly DELETE: "delete";
    readonly CHANGE: "change";
}

Type: { readonly PROPERTY_CHANGED: "propertyChanged"; readonly POSITION_REMOVE: "positionRemove"; readonly ADD: "add"; readonly DELETE: "delete"; readonly CHANGE: "change"; }

IntervalStickiness​

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

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

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

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

SharedString​

Entrypoint for ISharedString creation.

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

To use, import via @fluidframework/sequence/legacy.

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

Signature​

SharedString: import("@fluidframework/shared-object-base/internal").ISharedObjectKind<ISharedString> & import("@fluidframework/shared-object-base/internal").SharedObjectKind<ISharedString>

Type: import("@fluidframework/shared-object-base/internal").ISharedObjectKind<ISharedString> & import("@fluidframework/shared-object-base/internal").SharedObjectKind<ISharedString>