Options
All
  • Public
  • Public/Protected
  • All
Menu

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.

Hierarchy

Implements

Index

Constructors

Properties

isCRDTRuntime: true = true
isRuntime: true
replicaID: string

A unique ID for this replica (copy of a Collabs document).

Methods

  • batchRemoteUpdates(f: (() => void)): void
  • 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:

    • Each delivered update still emits its own "Update" event immediately, as usual.
    • If there are nested batchRemoteUpdates calls, only the outermost one matters.

    See also: transact, a similar method for local operations.

    Parameters

    • f: (() => void)

      A callback that delivers the remote updates by calling receive/load.

        • (): void
        • Returns void

    Returns void

  • 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.

    Type Parameters

    Parameters

    • eventName: K

      Name of the event to emit.

    • event: DocEventsRecord[K]

      Event object to pass to the event handlers.

    Returns void

  • fromID<C>(id: CollabID<C>): undefined | C
  • Inverse of idOf.

    Specifically, given a CollabID returned by idOf on some replica of this runtime, returns this replica's copy of the original collab. If that Collab does not exist (e.g., it was deleted or it is not present in this program version), returns undefined.

    Type Parameters

    Parameters

    Returns undefined | C

  • load(savedState: Uint8Array, caller?: unknown): void
  • 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.

    Parameters

    • savedState: Uint8Array

      Saved state from another replica's save call.

    • Optional caller: unknown

      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.

    Returns void

  • on<K>(eventName: K, handler: ((event: DocEventsRecord[K], caller: CRuntime) => void), options?: { once?: boolean }): (() => void)
  • Registers an event handler that is triggered when the event happens.

    Type Parameters

    Parameters

    • eventName: K

      Name of the event to listen on.

    • handler: ((event: DocEventsRecord[K], caller: CRuntime) => void)

      Callback that handles the event.

    • Optional options: { once?: boolean }
      • Optional once?: boolean

        If true, the event handler is triggered at most once (the next time the event happens), then unsubscribed.

    Returns (() => void)

    An "off" function that removes the event handler when called.

      • (): void
      • Registers an event handler that is triggered when the event happens.

        Returns void

        An "off" function that removes the event handler when called.

  • receive(message: Uint8Array, caller?: unknown): void
  • 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.

    Parameters

    • message: Uint8Array
    • Optional caller: unknown

      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.

    Returns void

  • registerCollab<C>(name: string, collabCallback: ((init: InitToken) => C)): C
  • 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.

    Type Parameters

    Parameters

    • name: string

      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", ...).

    • collabCallback: ((init: InitToken) => C)

      A callback that uses the given InitToken to construct the registered Collab.

    Returns C

    The registered Collab.

  • save(): Uint8Array
  • 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.

    Returns Uint8Array

  • setRootCollab<C>(rootCallback: ((init: InitToken) => C)): C
  • transact(f: (() => void)): void
  • 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:

    • Operations not wrapped in a transact call use the constructor's DocOptions.autoTransactions option.
    • If there are nested transact calls (possibly due to DocOptions.autoTransactions), only the outermost one matters.

    See also: batchRemoteUpdates, a similar method for remote updates.

    Parameters

    • f: (() => void)
        • (): void
        • Returns void

    Returns void

  • vectorClock(): Map<string, number>
  • 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).

    Returns Map<string, number>

Generated using TypeDoc