TypeScript

Install

npm install terse-sdk zod

Define actors in src/actor.ts. Use standard TypeScript decorators; leave experimentalDecorators disabled. Keep the configuration from terse init.

import { Actor, Emittable, Persisted, type ActorSocket } from "terse-sdk/actor"

type Member = { userId: string }
type Change = { by: number }
type Update = { count: number }

export class Counter extends Actor<Member, Change, Update> {
    @Persisted
    @Emittable
    count = 0

    async increment(by: number): Promise<number> {
        this.count += by
        return this.count
    }

    async onMessage(socket: ActorSocket<Member, Update>, message: Change): Promise<void> {
        await this.increment(message.by)
        this.broadcast({ count: this.count })
    }
}

Actor definitions

Import actor classes, decorators, and socket types from terse-sdk/actor. Extend Actor directly. Give fields defaults. Keep constructors free of external work. Make application methods async. Use concrete JSON-compatible argument and return types.

API	Purpose
`Actor<Metadata, Incoming, Outgoing, Tag>`	Type connection metadata, messages, and optional tags.
`@Persisted`	Save a field after successful calls.
`@Ephemeral`	Keep a field in memory only.
`@Emittable`	Send saved field snapshots and updates. Requires public `@Persisted`.
`@Reentrant`	Allow other calls to enter during this method.
`this.id`	Read the bound actor ID during a call.

Every instance field needs @Persisted or @Ephemeral. Private persisted fields stay outside emitted state. Use TypeScript private; JavaScript #private fields cannot use @Persisted.

Backend calls

Generate the client from your application project:

terse actor generate --language typescript

import { actors } from "./terse.actors/index.js"

const counter = actors.Counter.get("visits")
const count = await counter.increment(1)

get() returns a reference. The first call activates the actor as needed. Use the same ID to reach the same state. Use the generated client for Terse connection settings. Set TERSE_ACTOR_URL and TERSE_API_KEY on the calling backend for hosted actors.

Browser access

Authenticate the user. Check access to the actor ID. Derive metadata on your backend. Issue a grant:

const grant = await actors.Counter.prepareWebsocket({
    actorId: "visits",
    metadata: { userId: "authorized-user" },
})

Return the grant with Cache-Control: no-store. The browser opens new WebSocket(grant.websocketUrl). It sends JSON.stringify({ by: 1 }). ActorProxy.handle({ actorName, actorId, metadata }) provides the same grant flow through the generated ActorProxy export.

Socket handlers

API	Purpose
`onConnect(socket)`	Accept a connection or reject it.
`onMessage(socket, message)`	Handle a parsed application message.
`onDisconnect(socket, code, reason, wasClean)`	Handle disconnection. A process failure can skip this hook.
`socket.metadata`	Read backend-supplied metadata. Assign the whole value to update it.
`socket.send(message)`	Send to one connection.
`socket.reject(4003, "Forbidden")`	Reject during `onConnect`.
`socket.close(1000, "Done")`	Close the connection.
`socket.setTags(...tags)`	Set connection tags.
`this.getConnections()`	List connections during a call. Returns a promise.
`this.broadcast(message, options?)`	Send to matching connections. Includes the sender by default.

Broadcast options accept except, tags, and tagMatch: "all" | "any". Socket metadata and tags last for that connection.

Streaming and state

Broadcast inside the model’s streaming loop. Accumulate output locally. Assign the completed result to a persisted field before returning. Emitted fields use two wire messages:

{"type":"state","state":{"count":0}}
{"type":"state_update","changes":{"count":1},"removed":[],"version":1}

Replace local state on state. Merge changes on state_update. Delete fields in removed. Keep application message types distinct from those two names. Broadcasts have no replay. Obtain a fresh grant on reconnect. Restore the saved snapshot. See the browser example.

Failures and concurrency

Ordinary calls serialize. Failed calls roll back persisted fields. Broadcasts and external writes can already have happened. ActorInvocationError with code outcome_unknown means the call may have executed. Reconcile saved state and external effects before retrying. @Reentrant permits overlap. It disables failure rollback across the actor class. See Concepts.

Get started

Reference

Install

Actor definitions

Backend calls

Browser access

Socket handlers

Streaming and state

Failures and concurrency

​Install

​Actor definitions

​Backend calls

​Browser access

​Socket handlers

​Streaming and state

​Failures and concurrency

Install

Actor definitions

Backend calls

Browser access

Socket handlers

Streaming and state

Failures and concurrency