The key type.
The value type, which is a Collab.
The type of arguments to set.
Constructs a CMap with the given valueConstructor.
Callback used to construct a value Collab with the given [[InitToken]], key, and arguments to set. See collections of Collabs for example usage.
If provided, used to aggregate concurrently-set values at the same key, instead of picking one arbitrarily.
A serializer for SetArgs as an array.
Defaults to [[DefaultSerializer]].
A serializer for keys. 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]].
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]].
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.
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 the unique key associated to a value in this map, in O(1) time.
This method will succeed if value is the current value or a conflicting concurrently-set value (see getConflicts). Otherwise, it returns undefined.
The value to locate in this map.
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.
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.
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.
Sets the value at key using args.
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 set value.
Generated using TypeDoc
A collaborative map with keys of type K and 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.
Unlike a normal
Map<K, C>, you do not set values directly. Instead, you use the pattern described in collections of Collabs: one user calls set withSetArgs; each replica passes thoseSetArgsto itsvalueConstructor; andvalueConstructorreturns the local copy of the new value Collab.If multiple users set the value at a key concurrently, one of the value Collabs is picked arbitrarily; operations on the others are ignored. To instead "merge" concurrently-created values - applying all of their operations to the same underlying Collab - use [[CLazyMap]].
See also: CValueMap, a simpler map for immutable values.