The value type, which is a Collab.
The type of arguments to insert.
Constructs a CList with the given valueConstructor.
Callback used to construct a value Collab with the given [[InitToken]] and arguments to insert. See collections of Collabs for example usage.
A serializer for InsertArgs as an array.
Defaults to [[DefaultSerializer]].
The children (registered Collab properties), keyed by name.
This map should only be read, not mutated. It is exposed to subclasses as a convenience for methods that loop over all children.
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]].
The abstract total order underlying this list CRDT.
Access this to construct separate LocalList views on top of the same total order, e.g., a view of all archived values.
Archives count values starting at index, i.e., values
[index, index + count - 1).
The number of values to archive.
Defaults to 1 (archive the value at index only).
Internal (parent) use only.
By default, this method returns true if canGC returns true
on every child. Override to change this behavior.
See [[Collab.canGC]].
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 values are deleted permanently and can no longer be used; future and concurrent operations on those values are ignored. Local operations will succeed but will not affect remote replicas. The values can perform cleanup in their [[Collab.finalize]] methods.
See also: archive, CSet.delete.
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.
Note: If you move list elements, you should not use position
as a React key, since a value's position changes when it moves.
Instead, use the object itself as the key.
Internal (parent) use only.
By default, this methods calls finalize on every child.
Override to change this behavior,
e.g., to add your own finalization steps
(but consider calling super.finalize()).
Returns whether position is currently present in the list, i.e., its value is present (neither deleted nor archived).
Inserts a value at the given index using args.
All values currently at or after index shift
to the right, incrementing their indices.
The args are broadcast to all replicas in serialized form.
Every replica then passes them to valueConstructor to construct the actual
value of type C, a new Collab that is collaborative as usual.
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. See [[Collab.load]].
A CObject subclass may override this method to load additional state from [[Collab.save]] or to perform extra setup - e.g., refreshing functional views that were not automatically updated by children's load events. It is recommended to do so as follows:
load(savedStateTree: SavedStateTree | null, meta: SavedStateMeta) {
super.load(savedStateTree, meta);
// Process your extra saved state from savedStateTree.self.
const savedState = savedStateTree === null? null: savedStateTree.self!;
...
// Perform extra setup as needed.
...
}
Moves count values from index to insertionIndex.
That is, the range of values at [index, index + count - 1) is moved to the position
currently at insertionIndex.
Other values shift to accommodate the move.
Collaborative operations on the values continue to work normally, even if concurrent to the move.
The number of values to move.
Defaults to 1 (move the value at index only).
The new index of the first moved value.
This will be less then insertionIndex if index < insertionIndex.
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 value's position, or undefined if it is deleted or never an element of this list.
For an archived (but not deleted) value, returns the position
that it would have when restored. You can use
list.indexOfPosition(list.positionOf(value), "right") to find
the index that it would have when restored.
Inserts a value at the end of the list using args. Equivalent to
this.insert(this.length, ...args).
The inserted value.
Registers a [[Collab]] property of this CObject with the given name, making it one of our children.
Typically, you will call this method during the constructor in the style:
this.foo = this.registerCollab("foo", (init) => new FooClass(init, constructor args...));
where readonly foo: FooClass; is a Collab property. See
Data Modeling
for examples.
Registrations must be identical across all replicas.
See also: CRuntime.registerCollab.
A name for this property, unique among
this class's registerCollab calls.
We recommend using the same name as the property,
but you can also use short strings to reduce
network usage ("", "0", "1", ...).
A callback that uses the given [[InitToken]] to construct the registered [[Collab]].
The registered Collab.
Restores the given value, marking it as present in the list.
The value re-appears at its previous position, unless moved by move. All values after that position shift to the right, incrementing their indices.
In case of concurrent restore and archive operations, the restore wins. If the value is deleted (not just archived), this method has no effect.
One usage pattern is to call restore on a value each time you mutate that value. That way, if one user archives a value while it is still in use by another user, the archive will be canceled (update-wins semantics).
Internal (parent) use only.
Returns saved state describing the current state of this CObject. See [[Collab.save]].
A CObject subclass may override this method to save additional state. It is recommended to do so as follows:
save() {
const ans = super.save();
// Put your extra saved state in ans.self, which is otherwise unused.
ans.self = <subclass's saved state>;
return ans;
}
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.
Inserts a value at the start of the list using args. Equivalent to
this.insert(0, ...args).
The inserted value.
Generated using TypeDoc
A collaborative list with mutable values of type C.
Values are internally mutable. Specifically, each value is its own [[Collab]], and operations on that Collab are collaborative as usual.
CList<C>has a similar API toArray<C>, 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.To insert values, you use the pattern described in collections of Collabs: one user calls insert with
InsertArgs; each replica passes thoseInsertArgsto itsvalueConstructor; andvalueConstructorreturns the local copy of the new value Collab.When a value is deleted with delete, it is deleted permanently and can no longer be used; future and concurrent operations on that value are ignored. Alternately, use archive and restore.
It is not safe to modify a CList while iterating over it. The iterator will attempt to throw an exception if it detects such modification, but this is not guaranteed.
See also: CValueList, CText, CRichText.