Aller au contenu
Français

Behaviors

Ce contenu n’est pas encore disponible dans votre langue.

const Behaviors: object

Defined in: src/typed/Behaviors.ts:166

Factory for building Behaviors — the functional facade over the OO Actor API. Use these combinators to compose an actor’s logic as a tree of values rather than as an imperative class.

get empty(): EmptyBehavior

Sentinel: accept messages but do nothing — useful as a placeholder.

EmptyBehavior

get ignore(): IgnoreBehavior

Sentinel: drop every incoming message silently.

IgnoreBehavior

get same(): SameBehavior

Sentinel: keep the current behavior.

SameBehavior

get stopped(): StoppedBehavior

Sentinel: stop the actor.

StoppedBehavior

get unhandled(): UnhandledBehavior

Sentinel: mark the message as unhandled (goes to dead letters).

UnhandledBehavior

intercept<T>(inner, interceptor): Behavior<T>

Wrap inner so interceptor runs first on every message. The interceptor observes, transforms, or drops — it decides whether inner runs at all:

const b = Behaviors.intercept(inner, (context, message, next) => {
if (isNoise(message)) return Behaviors.same; // drop, inner never sees it
return next(context, transform(message)); // transform + delegate
});

The wrapper survives the inner behavior’s transitions: whatever the interceptor returns becomes the new inner behavior and is re-wrapped, so an inner Behaviors.receive that swaps itself out stays intercepted. The only way out is Behaviors.stopped, where there is nothing left to intercept.

Nesting runs outermost-first — in intercept(intercept(leaf, first), second) it is second that sees the message first, and first only runs if second delegates.

Errors thrown by the interceptor are treated exactly like errors from the inner handler: they reach an enclosing supervise.

User messages only; lifecycle signals go straight to receiveWithSignal’s handler and are not intercepted.

T

Behavior<T>

BehaviorInterceptor<T>

Behavior<T>

logMessages<T>(inner, options?): Behavior<T>

Log every message before inner handles it — debug by default:

const traced = Behaviors.logMessages(inner);
const audited = Behaviors.logMessages(inner, {
level: 'info',
formatter: (message) => `order ${message.orderId}`,
});

The built-in line is received <kind> for the project’s tagged messages, falling back to the class name and then to typeof — a bare object literal has a constructor.name of Object, which would say nothing.

The line is only built when the actor’s logger would actually emit it, so leaving this in place on a system logging at warn costs one comparison per message rather than a formatted string.

T

Behavior<T>

LogMessagesOptions<T> = {}

Behavior<T>

monitor<T>(observer, inner): Behavior<T>

Forward every message to observer before inner handles it — a tap for test probes and audit trails:

const probe = kit.createTestProbe();
const monitored = Behaviors.monitor(probe, inner);

Forward-then-deliver is the deliberate order: the monitor sees a message even if handling it crashes the actor, which is the case you most want a trace of. Delivery to the monitor is fire-and-forget and its failures are swallowed — a broken tap must not take the actor down with it.

T

ActorRef<T>

Behavior<T>

Behavior<T>

receive<T>(handler): ReceiveBehavior<T>

Standard receive — gets both context and message.

T

(context, message) => Behavior<T>

ReceiveBehavior<T>

receiveMessage<T>(handler): ReceiveBehavior<T>

Receive when you don’t need the context — message-only shortcut.

T

(message) => Behavior<T>

ReceiveBehavior<T>

receiveWithSignal<T>(handler, onSignal): ReceiveBehavior<T>

Receive with an additional signal handler.

The handler belongs to this behavior, not to the actor: transitioning to a receive that declares none unregisters it, so a state machine that needs post-stop cleanup — or wants a watched actor’s death as a signal rather than as a message — declares onSignal in every state that needs it. The sentinels are the exception: Behaviors.stopped leaves the handler in place, because a post-stop handler that stopped working the moment the actor stopped itself would be useless.

T

(context, message) => Behavior<T>

(context, signal) => Behavior<T>

ReceiveBehavior<T>

setup<T>(factory): Behavior<T>

Run factory once with the actor’s context; the returned Behavior is the first one the actor adopts. Use this to capture context.self or spawn children in the “constructor”.

T

(context) => Behavior<T>

Behavior<T>

supervise<T>(child): SuperviseBuilder<T>

Wrap a behavior with a supervisor strategy. Any error thrown from the wrapped handler is routed through strategy — the behavior is restarted (reset to its initial form), stopped, resumed, or escalated.

The wrapper installs a scope that outlives the subtree it wraps, the same way intercept survives its inner behavior’s transitions: it contributes its side effect once and the framework remembers the strategy for the actor’s lifetime, so a behavior the wrapped one transitions to is still supervised. Behaviors.stopped is the way out of a scope; a transition is not.

Nesting layers rather than replaces. In supervise(supervise(leaf).onFailure(inner)).onFailure(outer) the innermost strategy decides; Directive.Escalate — and a restart budget it has spent — hand the same error to the next scope out, and only falling off the outermost one reaches the actor’s cell, where the parent’s strategy applies. A scope a running behavior installs (returning a fresh supervise(...) from a handler) nests inside the ones already active rather than displacing them.

A restart decided by an outer scope re-resolves that scope’s own child, which rebuilds the wrappers below it — so the inner scopes come back with a full restart allowance.

T

Behavior<T>

SuperviseBuilder<T>

withStash<T>(capacity, factory): Behavior<T>

Expose a capacity-bounded stash buffer. The inner behavior can stash user messages (e.g. during init) and call stash.unstashAll() later.

capacity must be an integer in [1, 2 ** 32 - 1]; 0, a negative, a fractional value, NaN, Infinity and anything past the array ceiling throw OptionsError — see assertStashCapacity for why a bound that never compares true is worse than no bound at all, and why an astronomically large integer is the same defect wearing an integer’s clothes. The rejection lands here, on the caller’s stack while the behavior is still a value, rather than later inside the actor that adopts it.

T

number

(stash) => Behavior<T>

Behavior<T>

withTimers<T>(factory): Behavior<T>

Expose the per-actor TimerScheduler to the behavior.

T

(timers) => Behavior<T>

Behavior<T>