Skip to main content
You’re viewing developer documentation
This documentation is for developers working with the Base44 developer platform.
Complete reference for the Actor class that runs in your app’s backend. For the client SDK that connects to a session, see the actors SDK reference. For actor concepts and terminology, see the actors overview.

​
Required handlers

The Actor class is abstract. Implement the body of each of the following handlers. The handlers respond to events from clients and timers.

​
Optional handlers

When your actor needs them, implement these handlers. When the session ticks, set tickIntervalMs. If you omit shouldTick(), the session never ticks.

​
Methods to call

The actor class provides built-in functionality. The following are methods that you can use when implementing an actor’s handlers. Use this.client to read and write entities.

​
Class declaration

Import Actor from base44:runtime/actors and export a class that extends Actor as the default export from base44/actors/<actor-name>/entry.ts. The folder name becomes the actor name in the SDK. For setup details, see create an actor.
​
generic
Types the messages the actor receives from connected clients. Applies to the msg parameter of handleMessage().
​
generic
Types the messages the actor sends to connected clients. Applies to conn.send() and broadcast().

​
Runtime API

Actors import the Actor class from the base44:runtime/actors module:

​
Read secrets

Use secrets.get() to read your app’s environment variables from a handler. The method returns the value as a string, or undefined when the secret isn’t set. Import secrets from the base44:runtime module:
Configure secrets from the CLI with secrets set. We recommend calling a backend function for work that needs a secret. The function reads the secret and returns the result, so the actor never receives the secret. For a sample flow, see call a backend function for secret work.

​
Lifecycle handlers

Base44 calls these handlers in response to client activity in the session. You implement the body for each. Learn more about how actors and clients interact. For a sample flow, see manage client connections.
​
method
Runs anytime a session activates, such as:
  • When the session is first created.
  • When a client connects to an idle session.
  • When a message arrives on an idle session.
  • When a scheduled time arrives.
Returns void or a Promise<void>.
​
method
required
Runs when a client connects to the session. You can send the current session state with conn.send(), or refuse the connection with conn.reject(). Returns void or a Promise<void>.
​
method
required
Runs when a connected client sends a message. You can validate the message before changing session state or accessing app data. Returns void or a Promise<void>.
​
method
required
Runs when a client disconnects. Use this handler to remove any session state associated with the connection ID. A reconnect that reuses the same ID replaces the old socket without running handleClose(). Returns void or a Promise<void>.

​
Timer handlers and settings

These handlers and settings control timed work in the session. Base44 calls them when a scheduled time arrives, not in response to client activity. Learn more about scheduled work. For sample flows, see run ticks and schedule wakes.
​
method
required
Runs once per interval while shouldTick() returns true and the session has at least one client. Returns void or a Promise<void>.
​
number
Specifies the interval between ticks in milliseconds. Defaults to 100.
​
method
Returns a boolean. Return true to keep the session ticking, or false to stop it. This method is synchronous.Keep this method fast and free of side effects. Base44 calls this method after each connection, message, disconnection, and tick.
​
method
Runs once when a time set with schedule() arrives. Returns void or a Promise<void>.
​
method
Schedules one run of handleWake() at a specified time. Returns a Promise that settles after Base44 stores the schedule. The schedule survives an idle period and can start an idle session. Calling this method again with the same key replaces the scheduled time.
​
method
Cancels the scheduled wake associated with a key. Returns a Promise that settles after Base44 clears the schedule.

​
Connections

These properties and methods are available on the conn object passed to lifecycle handlers that involve a client. Use these properties and methods to read client identity, send messages, and manage the connection. For an overview of messaging, see realtime messages. For a sample flow, see manage client connections.
conn is the backend end of the WebSocket, and Connection in the client is the other end of the same socket. Use conn in the actor class. See the actors SDK reference for the client object.
​
string
Identifies this connection. Matches the ID the client passed when connecting, or an ID the SDK generated.
​
object
Identifies the client on this connection. Present on all connections.
​
method
Sends a message to this connection. Returns void.
​
method
Refuses a connection from handleConnect(). Returns void.
​
method
Sends a message to every live connection in the session. Returns void.
​
method
Returns an array of live conn objects in the session. Use this method in handleStart() to match restored data with clients that stayed connected through an idle period.
​
string
Session-level property. Contains the session ID that the client used to reach this session.

​
Storage

Use this.storage to read and write session data. Unlike class fields, storage survives idle periods. To choose between storage and class fields, see storage. For a sample flow, see persist session data.
​
method
Retrieves a value by key. Returns a Promise that resolves to the stored value, or undefined when the key doesn’t exist.
​
method
Saves a value by key. Replaces the value already stored under the key. Returns a Promise that settles when the write completes.
​
method
Removes a value by key. Returns a Promise that resolves to true when the key existed, and false otherwise.
​
method
Removes all saved data for the session. Returns a Promise that settles when the store is empty. A later connection starts with the same empty storage as a new session.

​
Entity access

Use this.client and this.client.asServiceRole to read and write app entities from inside an actor handler. For a sample flow, see write entity data from a session.
​
Base44Client
Provides an app client scoped to this session. This client uses anonymous authentication, so entity access follows the same rules as a logged-out client, and it reads production data.
​
Base44Client
Provides elevated access that bypasses row-level security. Validate messages before you use this client. Make writes safe to repeat, because the session can run a handler again after an error.

​
See also