Ask pattern
此内容尚不支持你的语言。
tell is fire-and-forget — it returns immediately and you never see
the actor’s response. Most actor-to-actor communication is fine like
that. But sometimes you need a reply: an HTTP handler that asks
an actor for state and serializes it as a response, a saga that needs
the result of step N before issuing step N+1, a test that wants to
assert on a return value.
ask is the helper for those cases. It sends a message to an actor,
attaches a temporary “reply-to” ref under the hood, and returns a
Promise that resolves with the first reply or rejects on timeout.
A minimal example
Section titled “A minimal example”import { match } from 'ts-pattern';import { Actor, ActorSystem, type ActorRef } from 'actor-ts';
type IncrementCommand = { readonly kind: 'increment' };type GetCommand = { readonly kind: 'get'; readonly replyTo: ActorRef<number> };type Command = IncrementCommand | GetCommand;
class Counter extends Actor<Command> { private count = 0; override onReceive(command: Command): void { match(command) .with({ kind: 'increment' }, () => this.onIncrement()) .with({ kind: 'get' }, (c) => this.onGet(c)) .exhaustive(); }
private onIncrement(): void { this.count++; } private onGet(command: GetCommand): void { command.replyTo.tell(this.count); }}
const system = ActorSystem.create('demo');const counter = system.spawnAnonymous(Counter);
counter.tell({ kind: 'increment' });counter.tell({ kind: 'increment' });
// Method-on-ref form — terse, infers the reply type:const current = await counter.ask<number>({ kind: 'get' }, 5_000);console.log(current); // 2
await system.terminate();ask is a method on every ActorRef:
// Method on every ActorRef — infers Reply from the type argument:ref.ask<Reply>(message, timeoutMs?): Promise<Reply>The OmitReplyTo<TMessage> parameter type subtracts replyTo from
every variant of the message union that declares it — callers never
write the field themselves. The framework allocates a one-shot
reply ref, attaches it both as context.sender and (when the
message shape expects it) as message.replyTo, and resolves the
promise with the first reply.
The replyTo field convention
Section titled “The replyTo field convention”ask works by sending your message with a temporary reply-to ref
attached. The receiver replies by tellling that ref.
By convention, the framework uses replyTo as the field name in
the request message, and the recipient pattern-matches on it the
same as any other field. Look at the Command type above: the 'get'
variant has replyTo: ActorRef<number>.
For the recipient, it’s just a regular tell on a regular ref:
private onGet(command: GetCommand): void { command.replyTo.tell(this.count);}Inside the recipient, you can also reach the same ref via
this.sender — it’s an Option<ActorRef>, and ask attaches the
temporary ref through that channel too:
private onGet(command: GetCommand): void { this.sender.forEach((replyTo) => replyTo.tell(this.count));}Either works. Using an explicit replyTo field makes the type
contract more obvious (the request shape declares it expects a
reply of type ActorRef<number>); using this.sender is more
implicit but works for actors that handle both ask-style and
fire-and-forget messages.
Timeouts + the AskTimeoutError
Section titled “Timeouts + the AskTimeoutError”import { AskTimeoutError } from 'actor-ts';
try { const result = await counter.ask({ kind: 'get' }, 1_000); console.log(result);} catch (e) { if (e instanceof AskTimeoutError) { console.log('counter did not reply in time'); } else { throw e; }}The timeout is mandatory in spirit — defaulting to 5 seconds catches
the case where you forgot to think about it. That default is settable
system-wide with actor-ts.actor.ask-timeout; a per-call argument
always wins over it. Tune per call site:
- Cheap in-process replies: 100-500 ms.
- Cross-cluster lookups: 1-5 s depending on network expectations.
- Anything that might hit a slow downstream (DB query, HTTP call inside the actor): match the underlying-call’s timeout + a small buffer.
When the timeout fires, the AskTimeoutError rejects the Promise.
The temporary reply-to ref is a one-shot: once it has settled — on
the timeout or on the first reply — any later reply is silently
discarded in place (it does not go to dead letters). The actor
itself isn’t affected — it has no idea the asker gave up.
There is no “no deadline” mode
Section titled “There is no “no deadline” mode”timeoutMs must be a positive finite number. 0, a negative
value, NaN and Infinity all throw OptionsError at the call
site, synchronously — before the message is sent, and as a thrown
error rather than a rejected Promise, because an argument outside
its domain is a bug in the caller rather than a failed request.
import { OptionsError } from 'actor-ts';
const budget = deadline - Date.now(); // negative once the deadline passedtry { await counter.ask({ kind: 'get' }, budget);} catch (e) { if (e instanceof OptionsError) { // budget was <= 0 — the deadline is already gone, don't ask at all }}That is stricter than it looks at first, and deliberately so. The
timeout is what arms the reply ref’s only self-settling path: a ref
with no timer can be settled by a reply and by nothing else, so an
unanswered ask would leave the await pending for the life of the
process — and, across the cluster, leave one entry in the per-path
handler map that every inbound envelope is matched against. Neither
value needs a typo to arrive: a computed budget goes negative the
moment its deadline passes, and an untyped configuration value
arrives as whatever it parsed to.
To get the default deadline, omit the argument (or pass
undefined):
const value = await counter.ask<number>({ kind: 'get' });Changing the default for the whole system
Section titled “Changing the default for the whole system”actor-ts.actor.ask-timeout is what that omitted argument resolves
to. It ships as 5s:
actor-ts { actor { ask-timeout = 2s }}Three things are worth knowing before you set it.
It reaches most refs, not all of them. A ref applies the
configured value only if it can reach the ActorSystem that read it —
which the ordinary local ref, TestProbe, RemoteActorRef,
ClusterSingletonProxy, the two shard refs and EntityRef all can.
The dead-letter ref, Nobody, an unresolved-path ref and the one-shot
reply ref cannot, and keep the built-in 5 s — as do two
framework-internal handles nothing can reply to. Every ref in that
group is one you hold where no live actor is behind it, so an ask on it
is waiting for a reply that is never coming either way.
A value that arms no deadline is refused, not clamped.
ask-timeout = 0 (or a negative one) throws at ActorSystem.create,
naming the key — the same rule as the positional argument, applied at
the moment the configuration is read rather than at every ask site.
Watch the interaction with scatter-gather routing. A router from
Router.scatterGatherFirstCompleted(…) defaults to 4.5 s so it can
name the failing routees before the caller’s ask gives up. An ask
default under 4.6 s inverts that, and you get AskTimeoutError instead
of the diagnosis; the system logs a warn at startup when it happens.
Give the router its own ScatterGatherOptions.withTimeoutMs() if the
shorter ask deadline is what you want.
Replying with an Error
Section titled “Replying with an Error”A recipient can reject an ask by replying with an Error
instance. The ask Promise rejects with that error rather than
resolving with the message.
class Service extends Actor<Command> { override onReceive(command: Command): void { match(command) .with({ kind: 'fetch' }, (c) => this.onFetch(c)) .exhaustive(); }
private onFetch(command: FetchCommand): void { if (this.unavailable) { command.replyTo.tell(new Error('service unavailable')); return; } command.replyTo.tell(this.data); }}
try { const data = await service.ask({ kind: 'fetch' });} catch (e) { // e is the actor's "service unavailable" Error.}This is a deliberate convention — the framework recognizes
Error-typed replies and rejects the Promise. Carry domain errors
the normal way (typed via the reply union) for everything else;
reserve the Error-reply path for genuine failure states.
When NOT to use ask
Section titled “When NOT to use ask”ask is convenient but it has overhead — it allocates a temporary
ref, registers it with the system, and tears it down on
resolution/timeout. Three situations where plain tell is the
right call instead:
Where to next
Section titled “Where to next”- Messages — the
replyTo: ActorRef<T>field convention covered in detail. - Actor —
this.senderand how the framework wires it. - ActorSystem — where temporary ask refs are registered and torn down.
- CircuitBreaker — when the ask’s downstream call is flakey and you want to fail fast rather than time out.
- Future patterns —
pipeTo,after, sequence — composing async results back into the actor world withoutawait-blocking.
The ActorRef class API reference
documents the ask method’s full signature and error types.
