Actors
An actor is an addressable piece of state with operations on it. Each actor has a type and a key; its state lives in the engine as named values, so any worker can run its operations. Operations on one key are processed one at a time, unless they are declared read-only.
Defining an Actor
1import { Actor, ActorContext, Operation } from '@orcher/sdk';23export interface CartItem {4 sku: string;5 price: number;6}78@Actor({ name: 'shoppingCart' })9export class ShoppingCart {10 @Operation()11 async addItem(ctx: ActorContext, item: CartItem): Promise<CartItem[]> {12 const items = (await ctx.state.get<CartItem[]>('items')) ?? [];13 items.push(item);14 await ctx.state.set('items', items);15 return items;16 }1718 @Operation()19 async clear(ctx: ActorContext): Promise<void> {20 await ctx.state.delete('items');21 }2223 @Operation({ mode: 'shared' })24 async total(ctx: ActorContext): Promise<number> {25 const items = (await ctx.state.get<CartItem[]>('items')) ?? [];26 return items.reduce((sum, item) => sum + item.price, 0);27 }28}@Actor({ name })names the actor type; withoutname, the class name is used.- Each
@Operation()method takes anActorContextfirst and at most one input. ctx.statereads and writes the actor's state in the engine:get<T>(key),set(key, value),delete(key)andlistKeys(prefix?). Values are stored as JSON.- The actor class is built anew for each operation, by the worker's container, so constructor
parameters are injected as for task classes.
Keep state in
ctx.state, not in fields.
A worker polls for actor operations only when actors are registered in its process; register them by importing the module, as with workflows and tasks.
Operation Modes
| Mode | Behavior |
|---|---|
'exclusive' (default) | Runs alone: no other operation on the same key runs at the same time |
'shared' | May run alongside other shared operations on the same key; an exclusive operation waits for them |
Declare an operation shared only if it does not change state.
Calling an Actor
client.actorRef(ActorClass, key) returns a typed reference. Each operation becomes a method
that takes the operation's input, or nothing for an operation without one:
1// Addressed by actor type and key; a key never used before starts with empty state.2const cart = client.actorRef(ShoppingCart, 'user-123');34const items = await cart.addItem({ sku: 'book-42', price: 2999 });5const total = await cart.total(); // operations without input take no argument6await cart.clear();There is no create step: the first operation on a key finds its state empty.
ActorContext Reference
| Member | Description |
|---|---|
ctx.state | The actor's state in the engine: get, set, delete, listKeys |
ctx.actorName / ctx.key | The actor type and key |
ctx.operationName / ctx.operationId | The operation being run |
ctx.mode | 'exclusive' or 'shared' |
ctx.metadata | Metadata sent with the operation |