Constructs a CTotalOrder.
Internal (this/parent) use only.
This Collab's name, which distinguishes it among its siblings in the tree of Collabs.
Internal (this/parent) use only.
This Collab's parent in the tree of Collabs.
The root waypoint.
The special position (rootWaypoint, 0) is the root of the tree of positions. It technically appears first in the total order but is usually not used.
The ambient [[IRuntime]].
Use this to access utilities like [[IRuntime.replicaID]].
Internal (parent) use only.
If this Collab is in its initial, post-constructor state, then this method may (but is not required to) return true; otherwise, it returns false.
By default, this method always returns false; override to change.
If this method returns true:
load(null, meta).
load should process this as if called with the output of save
from a garbage-collectable state. For a nontrivial example,
see CMultiValueMap.load's implementation.Creates count new positions between prevPosition and nextPosition.
The positions are created collaboratively
(replicated on all devices).
If !(prevPosition < nextPosition), behavior is undefined.
Note that this might not actually send a message.
The previous position, or null to create positions at the beginning of the list.
The next position, or null to create positions at the end of the list.
The number of positions to create.
The created [[Position]]s, in list order. Internally, they use the same waypoint with contiguously increasing valueIndex.
Emits an event, which triggers all the registered event handlers.
See [[CollabEventsRecord]] for advice on what events to emit.
This is a wrapper around [[EventEmitter.emit]] that forces events to extend [[CollabEvent]] and also emits an "Any" event.
Set to true to skip emitting an "Any" event.
Returns the positions representing (waypoint, valueIndex + i) for i in range [0, count).
Internal (parent) use only.
Called by this Collab's parent when it has been deleted from a collection on the local replica and can no longer be used (e.g., due to CSet.delete on this or an ancestor). A Collab implementation can implement this method to clean up external resources, e.g., associated DOM elements.
finalize has no relation to the JavaScript garbage collector or
canGC.
By default, this method does nothing.
Returns the waypoint with the given senderID and counter, throwing an error if it does not exist.
Registers an event handler that is triggered when the event happens.
Name of the event to listen on.
Callback that handles the event.
If true, the event handler is triggered at most once (the next time the event happens), then unsubscribed.
An "off" function that removes the event handler when called.
Registers an event handler that is triggered when the event happens.
An "off" function that removes the event handler when called.
Broadcasts a message to other replicas of this Collab. The message will be delivered to all replicas' receive, including locally.
For convenience, the message may be expressed as a stack of
(Uint8Array | string),
instead of just a single Uint8Array. This is
useful for parents sending messages on behalf of their children;
see the implementation of [[CObject]] for an example.
The message to send, in the form of a stack of Uint8Arrays. Note that this method may mutate it in-place.
Broadcasts a message to other replicas of this Collab. The message will be delivered to all replicas' receivePrimitive, including locally.
Call this method instead of [[Collab.send]].
The message to send.
A metadata request. The runtime will use this when creating the [[MessageMeta]] for receivePrimitive.
Generated using TypeDoc
A collaborative abstract total order on [[Position]]s.
This is a low-level API intended for internal use by list CRDT implementations. In most apps, you are better off using CValueList or CList.
A CTotalOrder represents the core of a list CRDT: a collaborative list of Positions that can be expanded over time, but without any associated values. Instead, you use a LocalList to map a subset of Positions to values, in list order with indexed access. Note that LocalList is a local (non-collaborative) data structure, i.e., its value assignments are not automatically replicated.
Waypoints
Internally, CTotalOrder stores an append-only log of Waypoints. The allowed [[Position]]s correspond to pairs (waypoint, valueIndex) where waypoint is an existing Waypoint and valueIndex is a nonnegative number. Methods decode, encode, and encodeAll convert between the two representations.
Note that waypoints and positions are only created, never destroyed. To create new positions (creating a new waypoint if needed), call createPositions.
List Order
The positions are ordered using a tree. Each waypoint's positions form a descending, left-to-right branch in the tree rooted at the position with valueIndex 0. The position with valueIndex 0 is a child of the waypoint's parent position, on the side given by Waypoint.isRight.
The position order is then an in-order traversal of this tree: we traverse a position's left children, then visit the position, then traverse its right children. Same-side siblings are ordered by the tiebreakers:
Note that positions belonging to the same waypoint are contiguous when first created. Later, (left-side) waypoint children may appear between them.