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 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 number of present keys in the map.
Returns an iterator for entries in the map.
The iteration order is NOT eventually consistent: it may differ on replicas with the same state.
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.
Internal (Collab.send) use only.
Sends the given message on behalf of child. In general, this parent is then responsible for delivering the given message to Collab.receive on each replica of child, with guarantees set by the runtime.
Deletes every key in the map.
Deletes the given key, making it no longer present in this map.
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 key, value pairs for every entry in the map.
The iteration order is NOT eventually consistent: it may differ on replicas with the same state.
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()
).
Executes a provided function once for each (key, value) pair in the map, in the same order as entries.
Inverse of idOf.
Returns the value associated to key, or undefined if key is not present.
Returns whether key is present in the map.
Returns a CollabID for the given strict descendant of this parent.
The CollabID may be passed to fromID on any replica of this
parent (but not other parents) to obtain that replica's copy of
descendant
.
Returns the key for some occurrence of a value
searchElement
in
this map, or undefined if searchElement
is not
associated with any key.
Returns an iterator for keys in the map.
The iteration order is NOT eventually consistent: it may differ on replicas with the same state.
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.
...
}
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.
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", ...).
The registered Collab.
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.
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.
Sets the value at key using args.
Typically, args are broadcast to all replicas in serialized form. Every replica then uses them to contruct the actual value of type V.
The set value, or undefined if it is not constructed immediately.
Returns an iterator for values in the map.
The iteration order is NOT eventually consistent: it may differ on replicas with the same state.
Generated using TypeDoc
Skeletal implementation of the IMap interface, as a subclass of CObject.
This class is a convenience for Collab implementers. It provides some default method implementations and leaves the others abstract.