The value type: a plain object that contains presence info about a single replica.
Constructs a CPresence.
The time-to-live for users who we have not heard from, after which their entry is deleted. Heartbeats sent twice as often keep present users alive. Default: TTL_MS_DEFAULT.
Serializer for updates (setOurs and updateOurs), which change a subset of V's keys. Defaults to [[DefaultSerializer]].
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 default time-to-live: 10 seconds.
Whether we are connected.
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 value.
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.Connects to the group, marking us as present. This method must only be called after setting our value with setOurs.
Disconnects from the group, marking us as not present.
If you know the local user is about to go offline, try to call this method to let others know; otherwise, they will infer it from a timeout (default 10 seconds).
Disconnection affects others' view of us, not our view of them. When disconnected, you may wish to treat others as offline even though CPresence still has their state.
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 for entries in the map.
The iteration order is NOT eventually consistent: it may differ on replicas with the same value.
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.
Executes a provided function once for each (key, value) pair in the map, in the same order as entries.
Function to execute for each value. Its arguments are the value, key, and this map.
Value to use as this when executing callbackfn.
Returns the value associated to key replicaID, or undefined if
replicaID is not present.
Returns our value, i.e., the value at key [[IRuntime.replicaID]].
Returns whether key replicaID is present in the map.
Returns an iterator for keys (replicaIDs) in the map.
The iteration order is NOT eventually consistent: it may differ on replicas with the same state.
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.
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 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]].
Do not override; override receiveCRDT instead.
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.
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.
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.
Sets our value, overwriting the current value.
To become present, call this method followed by connect.
Updates a single property in our value, leaving the other properties unchanged.
Use this method for frequently-changed properties like cursor positions.
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
A map for sharing presence info between present (simultaneously online) replicas, e.g., usernames or shared cursors.
Each replica controls a fixed key: its [[IRuntime.replicaID]]. Its value should be a plain object that contains presence info about itself, such as its user's latest [[Cursor]] location in a collaborative text editor.
To make yourself present and start listening to others, call setOurs followed by connect. To update your value, call updateOurs or setOurs again. If you know you are about to go offline, try to call disconnect to let others know; otherwise, they will infer it from a timeout (default 10 seconds).
CPresence attempts to detect presence accurately on a variety of networks (centralized, peer-to-peer, op-based, state-based). You may prefer a custom solution if you can detect presence more accurately, e.g., by asking a central server who is connected.
Values must be internally immutable; mutating a value internally will not change it on other replicas. Instead, use updateOurs.
See also: