The value type.
The type of arguments to insert.
Defaults to [T], i.e., insert inputs the actual value.
Events record.
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.
The number of values to delete.
Defaults to 1 (delete the value at index only).
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.
A function that accepts up to three arguments. forEach calls the callbackfn function one time for each element in the list.
An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
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.
The value to locate in this list.
The index to start the search at. If the index is greater than or equal to the list's length, -1 is returned, which means the list will not be searched. If the provided index value is a negative number, it is taken as the offset from the end of the list. Note: if the provided index is negative, the list is still searched from front to back. If the provided index is 0, then the whole list will be searched. Default: 0 (entire list is searched).
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 insertion index in the range
[0, this.length]. If this.length, the value
is appended to the end of the list.
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.
The saved state to load, in the same format as in save,
or null as described above.
Metadata attached to this saved state by the runtime.
It incorporates all possible metadata requests. Note that
meta.updateType is always "savedState".
Calls a defined callback function on each element of this list, and returns an array that contains the results.
A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the list.
An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
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.
The message to receive, in the same format
as in send. This method may mutate messageStack
in-place (e.g., calling pop).
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.
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.
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.
The beginning index of the specified portion of the list. If start is undefined, then the slice begins at index 0.
The end index of the specified portion of the list. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end 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
Interface for a collaborative list with values of type T.
For implementations, see [[CList]] and [[CValueList]]. [[CText]] is similar but not an actual IList implementation.
IList<T>has a similar API toArray<T>, but it is mutated more like a linked list: instead of mutating existing values, you insert and delete list entries. Insertions and deletions shift later entries, changing their indices, like in collaborative text editing or Array.splice.This interface permits insert to accept arbitrary
InsertArgsinstead of just the value to insert. That is useful when the value is not serializable, e.g., a dynamically- created Collab.IList lets you address a list entry by its immutable position, in addition to its mutable index; see Position.