Actor API

Overall

When specifying an actor, you should return a class that implements the actor behavior you want. Example:

actor("userActor", () => {
   return class {
       // Your Actor Implementation
   }
});

Events

onMessage

The onMessage handler is called when a message is received.

actor("userActor", () => {
   return class {
       onMessage(message, context) {
           console.log(message);
       }
   }
});

onActivate

The onActivate handler is called when the actor is activated before the first message is processed.

actor("userActor", () => {
   return class {
       onActivate(context) {
           console.log("Activated");
       }
   }
});

onDeactivate

The onDeactivate handler is called before the actor is deactivated.

actor("userActor", () => {
   return class {
       onDeactivate(context) {
           console.log("Deactivated");
       }
   }
});

Return Types

Return Type Behavior

Events may return the following types:

• nothing/undefined: Message is immediately marked as complete.
• value: Message is immediately marked as complete and value is returned.
• Promise: Message is only marked as complete when the promise is resolved/rejected.

Exception Behavior

Exceptions are automatically caught by the framework and returned to the original caller, this includes promise rejections as well as traditional throws.

Context

A context is passed for every event on an actor.

Actor Type

onMessage(message, context) {
    console.log(context.actorType);
}

Actor ID

onMessage(message, context) {
    console.log(context.actorId);
}

Server API

onMessage(message, context) {
    return context.api.send("otherActor", "hello");
}

Timers

• Timers are subject to the same execution guarantees as messages and will run through the regular serialized execution.
• Timer delay is specified in milliseconds.
• Timers may return all return types that may be returned by other actor events such as promises and no other actor event may run during this chain.
• Timers are automatically deregistered during deactivation and will not cause activation or actor lifetime to be extended.
  • Combine with reminders for more persistent events.
• Timers may be one time or recurring events.
• Timers are typically accurate to within a few milliseconds.

Context#registerTimer(timerName: string, delayMs: number, recurring: boolean, callback)
Context#unregisterTimer(timerName: string)

onActivate(context) {
    context.registerTimer("myTimer", 1000, true, () => console.log("Hello"));
}

Reminders

• Reminders are subject to the same execution guarantees as messages and will run through the regular serialized execution.
• Reminder delay is specified in seconds.
• Reminders may return all return types that may be returned by other actor events such as promises and no other actor event may run during this chain.
• Reminders are persistent and will cause an actor to activate and extend the actor lifetime.
• Reminders are typically accurate to within a few seconds.
  • You can combine reminders with timers for more accurate timing.
• Reminders are one time events, register another reminder for recurrence.
• Reminders are at-least once delivery.
  • Although very rare, a node failure can result in a message being delivered more than once.
  • Your implementation must handle this case correctly.

Context#registerReminder(reminderName: string, delaySecs: number)
Context#unregisterReminder(reminderName: string)

onActivate(context) {
    context.registerReminder("myReminder", 60);
}

onReminder(reminderName, context) {
    if(reminderName === "myReminder") {
        // Do something
    }
}