Skip to main content
This release is 1 version behind 24.6.2 — the latest version of @rivet-gg/actor. Jump to latest

🔩 Rivet Actors have built-in RPC, state, and events — the easiest way to build modern applications.

This package works with Deno
This package works with Deno
JSR Score
88%
Published
a month ago (24.6.1-rc.2)
class Actor

Abstract class representing a Rivet Actor. Extend this class to implement logic for your actor.

Constructors

new
Actor(config?: Partial<ActorConfig>)

This constructor should never be used directly.

Constructed in Actor.start.

Type Parameters

State = undefined

Represents the actor's state, which is stored in-memory and persisted automatically. This allows you to work with data without added latency while still being able to survive crashes & upgrades. Must define _onInitialize to create the initial state. For more details, see the State Documentation.

ConnParams = undefined

Represents the parameters passed when a client connects to the actor. These parameters can be used for authentication or other connection-specific logic. For more details, see the Connections Documentation.

ConnState = undefined

Represents the state of a connection, which is initialized from the data returned by _onBeforeConnect. This state can be accessed in any actor method using connection.state. For more details, see the Connections Documentation.

Properties

protected
writeonly
_state: State

Sets the current state.

This property will automatically be persisted.

protected
readonly
_connections: Map<ConnectionId, Connection<this>>

Gets the map of connections.

protected
readonly
_kv: Kv

Gets the KV state API. This KV storage is local to this actor.

protected
readonly
_log: Logger

Gets the logger instance.

protected
readonly
_metadata: Metadata

Gets metadata associated with this actor.

protected
readonly
_state: State

Gets the current state.

Changing properties of this value will automatically be persisted.

Methods

protected
_broadcast<Args extends Array<unknown>>(
name: string,
...args: Args,
): void

Broadcasts an event to all connected clients.

Called whenever a new client connects to the actor. Clients can pass parameters when connecting, accessible via opts.parameters.

The returned value becomes the connection's initial state and can be accessed later via connection.state.

Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection.

protected
optional
_onConnect(connection: Connection<this>): void | Promise<void>

Executed after the client has successfully connected.

Messages will not be processed for this actor until this method succeeds.

Errors thrown from this method will cause the client to disconnect.

protected
optional
_onDisconnect(connection: Connection<this>): void | Promise<void>

Called when a client disconnects from the actor. Use this to clean up any connection-specific resources.

protected
optional
_onInitialize(): State | Promise<State>

Hook called when the actor is first created. This method should return the initial state of the actor. The state can be access with this._state.

protected
optional
_onStart(): void | Promise<void>

Hook called after the actor has been initialized but before any connections are accepted. If the actor crashes or is upgraded, this method will be called before startup. If you need to upgrade your state, use this method.

Use this to set up any resources or start any background tasks.

protected
optional
_onStateChange(newState: State): void | Promise<void>

Hook called whenever the actor's state changes. This is often used to broadcast state updates.

protected
_runInBackground(promise: Promise<void>): void

Runs a promise in the background.

This allows the actor runtime to ensure that a promise completes while returning from an RPC request early.

protected
_saveState(opts: SaveStateOptions): Promise<void>

Forces the state to get saved.

This is helpful if running a long task that may fail later or when running a background job that updates the state.

protected
_shutdown(): Promise<void>

Shuts down the actor, closing all connections and stopping the server.

Static Methods

Called by Rivet runtime to start a new actor. This class must use export default in order to be called automatically.

This should never be used directly.

See

Add Package

deno add jsr:@rivet-gg/actor

Import symbol

import { Actor } from "@rivet-gg/actor";

---- OR ----

Import directly with a jsr specifier

import { Actor } from "jsr:@rivet-gg/actor";