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.
Authentication modes
This module is available to use with a client in anonymous or user authentication mode. Access it throughbase44.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. Callconnect() 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(Creates or returns the connection for this session. Callingoptions?):Connection<N>
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
Properties
Properties
Returns
Connection
The connection for this actor session.
Example
Connection methods
Represents a client’s WebSocket connection to an actor session, returned after callingconnect(). The WebSocket queues messages you send before it opens.
Learn more about
connections.
subscribe()
subscribe(Registers a listener for messages from the actor. You can register multiple listeners on the same connection.callback):ActorSubscription
Parameters
Returns
ActorSubscription
A subscription handle. Call unsubscribe() on it to remove this listener without closing the socket.
Example
send()
send(Sends a message to the actor. The WebSocket queues messages until it opens. When you calldata):void
close(),
the WebSocket drops any messages you send afterward.
Parameters
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 withsubscribe().
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 inActorRegistry. 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.
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 withtypes generate.
The generated names provide autocomplete for deployed actors. To define
incoming and outgoing message types manually, augment ActorRegistry.
ServiceRoleActorRef
ServiceRoleActorRef<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 theN> =ActorMethods<N>
service identity.