Reference

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

1
import { Actor, ActorContext, Operation } from '@orcher/sdk';
2
3
export interface CartItem {
4
sku: string;
5
price: number;
6
}
7
8
@Actor({ name: 'shoppingCart' })
9
export 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
}
17
18
@Operation()
19
async clear(ctx: ActorContext): Promise<void> {
20
await ctx.state.delete('items');
21
}
22
23
@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; without name, the class name is used.
  • Each @Operation() method takes an ActorContext first and at most one input.
  • ctx.state reads and writes the actor's state in the engine: get<T>(key), set(key, value), delete(key) and listKeys(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

ModeBehavior
'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.
2
const cart = client.actorRef(ShoppingCart, 'user-123');
3
4
const items = await cart.addItem({ sku: 'book-42', price: 2999 });
5
const total = await cart.total(); // operations without input take no argument
6
await cart.clear();

There is no create step: the first operation on a key finds its state empty.


ActorContext Reference

MemberDescription
ctx.stateThe actor's state in the engine: get, set, delete, listKeys
ctx.actorName / ctx.keyThe actor type and key
ctx.operationName / ctx.operationIdThe operation being run
ctx.mode'exclusive' or 'shared'
ctx.metadataMetadata sent with the operation

Next Steps

  • Client: connecting a client
  • Tasks: injection into task and actor classes
  • Worker: actor pollers and concurrency