Ugrás a fő tartalomhoz

Overview

Actors module for interacting with actors from your app. An actor is a long-running backend process that multiple clients connect to simultaneously. A session is a running instance of an actor, identified by the actor name and a session ID. Each session manages its own state, storage, and client connections independently. The actors module provides the functionality to:
  • Manage connections: Open and close a WebSocket connection to a session.
  • Exchange messages: Send and listen for messages to and from an actor.
  • Manage subscriptions: Subscribe and unsubscribe from actor messages without closing the connection.
  • Call methods: run one of an actor’s callable methods on a session, without connecting.
For a sample flow, see connect a client to a session.

Authentication modes

This module is available to use with a client in anonymous or user authentication mode. Access it through base44.actors. In service role authentication mode, base44.asServiceRole.actors only calls methods. The actor receives each client’s identity when the client connects or calls a method. A client that hasn’t logged in is anonymous, a client that has logged in is authenticated, and server code calling with the service role is service.

Actor methods

Represents a reference to an actor session, identified by actor name and session ID. Call connect() to open the WebSocket and get a connection, or call one of the actor’s callable methods by name, such as ref.kick({ userId }): it runs the actor’s method with your identity, even when no client is connected, and resolves to its return value. A refusal rejects with a Base44Error carrying the actor’s status (404 for a method the actor doesn’t list in static callable). A call takes one argument, any JSON value: pass several values as an object, such as ref.videoReady({ id, url }), or an array. Further arguments are dropped, so ref.m(a, b) sends only a. Arguments and the reply are JSON-encoded: a Date arrives as a string, undefined is dropped (null inside an array), and functions, Map and Set values don’t survive. A request is at most 64 KB and calls are rate-limited per caller.

Example

connect()

connect(options?): Connection<N>
Creates or returns the connection for this session. Calling connect() again on the same session reference returns the same connection until it closes. For a sample flow, see connect a client to a session.

Parameters

ActorConnectOptions
Optional connection settings, such as a stable connection ID.
string
Connection ID that the actor receives as conn.id.To let the actor recognize a client when it reconnects, use a stable value, such as an ID stored per browser tab. If you omit this property, the SDK generates a new connection ID.

Returns

Connection The connection for this actor session.
string
kötelező
Connection ID that the actor receives as conn.id.

Example

Connection methods

Represents a client’s WebSocket connection to an actor session, returned after calling connect(). The WebSocket queues messages you send before it opens. Learn more about connections.

subscribe()

subscribe(callback): ActorSubscription
Registers a listener for messages from the actor. You can register multiple listeners on the same connection.

Parameters

(data) => void
kötelező
Callback that runs for each message the actor sends to this connection.

Returns

ActorSubscription A subscription handle. Call unsubscribe() on it to remove this listener without closing the socket.

Example


send()

send(data): void
Sends a message to the actor. The WebSocket queues messages until it opens. When you call close(), the WebSocket drops any messages you send afterward.

Parameters

ToServerFor<N>
kötelező
Message to send to the actor. The type comes from ActorRegistry when you register the actor there.

Returns

void

Example


close()

close(): void
Closes the connection and removes all listeners. You can call this method more than once. A connection also closes itself when it fails permanently.

Returns

void

Example

Subscription methods

Represents a listener for messages from the actor, registered with subscribe().

unsubscribe()

unsubscribe(): void
Removes this listener. Other listeners and the socket stay open.

Returns

void

Example

Type Definitions

ActorClient

Selects a session for a named actor. TypeScript infers message types when you register the actor in ActorRegistry. ActorNameRegistry provides autocomplete for actor names only.

Parameters

instanceId

string Session ID that identifies which session to connect to.

Returns

ActorRef<N> A reference to the actor session.

Example

ActorRegistry

Maps actor names to their incoming and outgoing message types. Extend this interface when you want typed actor messages without generating types with the CLI:
  • toServer: Defines incoming messages that a client sends to the actor.
  • toClient: Defines outgoing messages that the actor sends to connected clients.
To generate types from deployed actors, use the types generate CLI command. To learn how incoming and outgoing messages work, see message types.

Example

ActorNameRegistry

Lists actor names when your project includes types generated by the CLI with types generate. The generated names provide autocomplete for deployed actors. To define incoming and outgoing message types manually, augment ActorRegistry.

ServiceRoleActorRef

ServiceRoleActorRef<N> = ActorMethods<N>
Represents a reference to an actor session for server code running with the service role. Server code can’t hold a connection, so it only calls methods; the actor sees the service identity.

Example