Initializes this Collab with the given InitToken.
The InitToken must have provided by our parent explicitly for this constructor call.
Typically, a Collab subclass takes init
as its first constructor
argument and calls super(init)
.
The length of the list.
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 ambient IRuntime.
Use this to access utilities like IRuntime.replicaID.
Returns an iterator for values in the list, in list order.
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.Deletes every value in the list.
Delete count
values starting at index
, i.e., values
[index, index + count - 1)
.
All later values shift to the left,
decreasing their indices by count
.
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 an iterator of [index, value, position] tuples for every value in the list, in list order.
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.
Performs the specified action for each element in this list.
Returns the value currently at index.
Returns the value at position, or undefined if it is not currently present (hasPosition returns false).
Returns the position currently at index.
Returns whether position is currently present in the list, i.e., its value is present.
Returns the index of the first occurrence of a value in this list, or -1 if it is not present.
Returns the current index of position.
If position is not currently present in the list (hasPosition returns false), then the result depends on searchDir:
To find the index where a position would be if
present, use searchDir = "right"
.
Inserts a value at the given index using args.
All values currently at or after index
shift
to the right, incrementing their indices.
Typically, args are broadcast to all replicas in serialized form. Every replica then uses them to contruct the actual value of type T.
The inserted value, or undefined if it is not constructed immediately.
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 saveCRDT 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.
The saved state to load,
or null
as described above.
Generic metadata attached to this message by the CRuntime.
Note that meta.updateType
is always "savedState"
.
CRDT-specific metadata attached to this message by the CRuntime. It contains all fields and vector clock entries.
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.
Calls a defined callback function on each element of this list, and returns an array that contains the results.
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.
Returns the position of the first occurrence of searchElement, or undefined if there are no occurrences.
Compare to indexOf.
Returns an iterator for present positions, in list order.
Inserts a value at the end of the list using args. Equivalent to
this.insert(this.length, ...args)
.
The inserted value, or undefined if it is not constructed immediately.
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 sendCRDT on a local or remote replica of this PrimitiveCRDT.
This method processes the message, changes the local state accordingly, and emits events describing the local changes.
This method may assume eventual, exactly-once, causal-order message delivery, and it must ensure strong eventual consistency.
See Collab.receive.
The message sent by sendCRDT.
Generic metadata attached to this message by the CRuntime.
Note that meta.updateType
is always "message"
.
Do not override; override receiveCRDT instead.
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 loadCRDT 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.
saveCRDT
may be called at any time, possibly many times while an app
is running. Calling saveCRDT
should not affect this Collab's
user-visible state.
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 CRDT. The message will be delivered to all replicas' receiveCRDT, including locally.
Call this method instead of Collab.send or CPrimitive.sendPrimitive.
By default, receiveCRDT's crdtMeta
will contain all fields that are accessed
during the sender's local call to receiveCRDT.
You can request additional fields with metaRequest
.
The message to send.
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.
Returns a copy of a section of this list, as an array. For both start and end, a negative index can be used to indicate an offset from the end of the list. For example, -2 refers to the second to last element of the list.
Inserts a value at the start of the list using args. Equivalent to
this.insert(0, ...args)
.
The inserted value, or undefined if it is not constructed immediately.
Returns an iterator for values in the list, in list order.
Generated using TypeDoc
Skeletal implementation of the IList interface, as a subclass of PrimitiveCRDT.
This class is a convenience for Collab implementers. It provides some default method implementations and leaves the others abstract.