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 Positions, 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.
Internal (parent) use only.
Called by this Collab's parent to load saved state. You may assume that the saved state was generated by save on some replica of this Collab, possibly in a different collaboration session, with guarantees set by the runtime.
This method may also be called with savedStateTree = null;
you should ignore such calls (i.e., return immediately)
unless you override canGC. If you do override canGC,
see that method's docs for instructions.
Called by this Collab's parent to load some saved state. You may assume that the saved state was generated by savePrimitive on some replica of this Collab, possibly in a different collaboration session, with guarantees set by the runtime.
This method may also be called with savedState = null;
you should ignore such calls (i.e., return immediately)
unless you override canGC. If you do override canGC,
see that method's docs for instructions.
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.
Internal (parent) use only.
Receives a message sent by send on a local or remote replica of this Collab.
This method processes the message, changes the local state accordingly, and emits events describing the local changes.
This method should make assumptions and ensure consistency guarantees appropriate to its use case. For example, CRDTs may assume eventual, exactly-once, causal-order message delivery, and they must ensure strong eventual consistency.
Receives a message sent by sendPrimitive on a local or remote replica of this CPrimitive.
This method processes the message, changes the local state accordingly, and emits events describing the local changes.
This method should make assumptions and ensure consistency guarantees appropriate to its use case. For example, CRDTs may assume eventual, exactly-once, causal-order message delivery, and they must ensure strong eventual consistency.
See Collab.receive.
Internal (parent) use only.
Returns saved state describing the current state of this Collab.
The saved state may later be passed to load on a replica of this Collab, possibly in a different collaboration session, with rules set by the runtime. For example, CRuntime allows load at any time; it must then act as a merge operation (like a state-based CRDT), applying all updates that the saved replica had applied before saving, ignoring duplicates.
save may be called at any time, possibly many times while an app
is running. Calling save should not affect this Collab's
user-visible state.
For convenience, the saved state may be expressed as a tree of Uint8Arrays instead of just a single Uint8Array; see [[SaveStateTree]]'s docs.
The saved state.
Returns saved state describing the current state of this Collab.
The saved state may later be passed to loadPrimitive on a replica of this Collab, possibly in a different collaboration session, with rules set by the runtime. For example, CRuntime allows load to be called only at the beginning of a session, before sending or receiving any messages.
savePrimitive may be called at any time, possibly many times while an app
is running. Calling savePrimitive should not affect this Collab's
user-visible state.
The saved state.
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.
A stack of metadata requests. The runtime will use
the union of these when creating the MessageMeta for receive.
Note that the stack need not align with messageStack, and 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 Positions.
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 Positions 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.