Constructs a CRuntime.
See DocOptions.
A unique ID for this replica (copy of a Collabs document).
Delivers remotes updates (receive/load calls) in a batch, so that only a single "Change" event is emitted for the entire batch.
f()
is called immediately, then if it delivered any remote updates,
a single "Change" event is emitted.
That way, "Change" listeners know that they only need
to refresh the display once at the end, instead of once per receive/load
call.
Notes:
See also: transact, a similar method for local operations.
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.
Emits an event, which triggers all the registered event handlers.
Event handlers are called in the order they are added. Errors in
event handlers are captured and logged (with console.error
),
not propagated to the caller.
Name of the event to emit.
Event object to pass to the event handlers.
Inverse of idOf.
Returns a CollabID for the given Collab.
The CollabID may be passed to fromID on any replica of this
runtime to obtain that replica's copy of collab
.
Loads saved state. The saved state must be from a call to save on a CRuntime that is a replica of this one (i.e., it has the same "schema").
The local Collabs merge in the saved state, change the local state accordingly, and emit events describing the local changes.
Calling load is roughly equivalent to calling receive on every message that influenced the saved state (skipping already-received messages), but it is typically much more efficient.
Saved state from another replica's save call.
Optionally, a value to use as the "Update" event's SavedStateEvent.caller field. A caller can use that field to distinguish its own updates from updates delivered by other sources.
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.
Receives a message from another replica's DocEventsRecord.Send event. The message's sender must be a CRuntime that is a replica of this one (i.e., it has the same "schema").
The local Collabs process the message, change the local state accordingly, and emit events describing the local changes.
Messages from other replicas should be received eventually and at-least-once. Arbitrary delays, duplicates, reordering, and delivery of (redundant) messages from this replica are acceptable. Two replicas will be in the same state once they have the same set of received (or sent) messages.
Optionally, a value to use as the "Update" event's MessageEvent.caller field. A caller can use that field to distinguish its own updates from updates delivered by other sources.
Registers a Collab as part of this document. See Documents - Using CRuntime.
Typically, you will call this method right after creating this CRuntime, with the style:
const foo = runtime.registerCollab("foo", (init) => new FooClass(init, constructor args...));
where const foo: FooClass;
is a top-level variable.
Registrations must be identical across all replicas, i.e., all CRuntime instances that share messages and saved states.
A name for the registered Collab, unique among
this document's registerCollab
calls.
We recommend using the same name as the variable where you store the Collab,
but you can also use short strings to reduce
network usage ("", "0", "1", ...).
The registered Collab.
Returns saved state describing the current state of this runtime, including its Collabs.
The saved state may later be passed to load on a replica of this CRuntime, possibly in a different collaboration session. That is equivalent to delivering all messages that this document has already sent or received.
Wraps f
's operations in a
transaction.
f()
is called immediately, then if it performed any local Collab operations,
their transaction is ended (emitting "Send", "Update", and "Change" events).
Notes:
transact
call use the constructor's
DocOptions.autoTransactions option.transact
calls (possibly due to
DocOptions.autoTransactions), only the outermost one matters.See also: batchRemoteUpdates, a similar method for remote updates.
The vector clock for our current state, mapping each senderID to the number of applied transactions from that senderID.
Our current state includes precisely the transactions
with ID (senderID, senderCounter)
where
senderCounter <= (vectorClock.get(senderID) ?? 0)
.
Generated using TypeDoc
A runtime for a Collabs document, responsible for managing the document's Collabs.
To get started with CRuntime, see Documents.
CRuntime is network- and storage-agnostic. By itself, it does not connect to remote collaborators or persistent storage. To easily set up networking and storage, configure Providers. Or, manually manage updates using the methods in this class; see Updates and Sync.
See also: AbstractDoc, which lets you encapsulate a CRuntime and its registered Collabs in a single object.