Lifecycle

Lifecycle Hooks

_onInitialize

_onInitialize(): State | Promise<State>

Called when the actor is first created. This method should return the initial state of the actor.

_onStart

_onStart(): void | Promise<void>

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.

_onStateChange

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

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

_onBeforeConnect

_onBeforeConnect?(opts: OnBeforeConnectOptions<this>): ConnState | Promise<ConnState>

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. This can be used for authentication - see Authentication for details.

_onConnect

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

_onDisconnect

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

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

Destroying actors

Actors can be shut down gracefully with this._shutdown(). Clients will be gracefully disconnected.

This action is permanent and cannot be reverted.

Actors can also be destroyed externally via the platform API with actors.destroy.

Full Example

interface State {
  count: number;
}

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
}

class CounterActor extends Actor<State, ConnParams, ConnState> {
  async _onInitialize(): Promise<State> {
    // Initialize with a count of 0
    return {
      count: 0
    };
  }

  async _onStart(): Promise<void> {
    // Upgrade state if needed
    console.log('Started');
  }

  async _onStateChange(newState: State): Promise<void> {
    // Broadcast the new count to all connected clients
    this.broadcast('countUpdated', {
      count: newState.count
    });
  }

  async _onBeforeConnect(opts: OnBeforeConnectOptions<CounterActor>): Promise<ConnState> {
    // Validate auth token with your API and determine the user
    const auth = await myValidateAuthToken(opts.parameters.authToken);
    if (!auth) {
      throw new Error('Invalid auth token');
    }

    // Return connection state that will be available as connection.state
    return {
      userId: auth.userId
    };
  }

  async _onConnect(connection: Connection<this>): Promise<void> {
    console.log(`User ${connection.state.userId} connected`);
  }

  async _onDisconnect(connection: Connection<this>): Promise<void> {
    console.log(`User ${connection.state.userId} disconnected`);
  }

  // Example RPC method
  async increment(rpc: Rpc<this>) {
    this.state.count++;
  }
}