Behaviors

此内容尚不支持你的语言。

const Behaviors: object

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.

Type Declaration

empty

Get Signature

get empty(): EmptyBehavior

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

Returns

EmptyBehavior

ignore

Get Signature

get ignore(): IgnoreBehavior

Sentinel: drop every incoming message silently.

Returns

IgnoreBehavior

same

Get Signature

get same(): SameBehavior

Sentinel: keep the current behavior.

Returns

SameBehavior

stopped

Get Signature

get stopped(): StoppedBehavior

Sentinel: stop the actor.

Returns

StoppedBehavior

unhandled

Get Signature

get unhandled(): UnhandledBehavior

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

Returns

UnhandledBehavior

intercept()

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.

Type Parameters

T

T

Parameters

logMessages()

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.

Type Parameters

T

T

Parameters

inner

Behavior<T>

options?

LogMessagesOptions<T> = {}

Returns

Behavior<T>

monitor()

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.

Type Parameters

T

T

Parameters

observer

ActorRef<T>

inner

Behavior<T>

Returns

Behavior<T>

receive()

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

Standard receive — gets both context and message.

Type Parameters

T

T

Parameters

handler

(context, message) => Behavior<T>

Returns

ReceiveBehavior<T>

receiveMessage()

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

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

Type Parameters

T

T

Parameters

handler

(message) => Behavior<T>

Returns

ReceiveBehavior<T>

receiveWithSignal()

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.

Type Parameters

T

T

Parameters

handler

(context, message) => Behavior<T>

onSignal

(context, signal) => Behavior<T>

Returns

ReceiveBehavior<T>

setup()

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”.

Type Parameters

T

T

Parameters

factory

(context) => Behavior<T>

Returns

Behavior<T>

supervise()

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.

Type Parameters

T

T

Parameters

child

Behavior<T>

Returns

SuperviseBuilder<T>

withStash()

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.

Type Parameters

T

T

Parameters

capacity

number

factory

(stash) => Behavior<T>

Returns

Behavior<T>

withTimers()

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

Expose the per-actor TimerScheduler to the behavior.

Type Parameters

T

T

Parameters

factory

(timers) => Behavior<T>

Returns

Behavior<T>