Waitfor Expressions
A WAITFOR expression pauses a query until something happens, then resumes and produces a value. It has two modes: waiting for a condition to become true, and waiting for an event to arrive.
Waiting for a condition
In its condition (predicate) mode, WAITFOR re-checks an ordinary expression until it is satisfied or a timeout is reached. This mode is a pure language construct — it needs no special capability.
There are four forms:
| Form | Waits until | Returns |
|---|---|---|
WAITFOR <expr> |
the expression is true | true, or false on timeout |
WAITFOR EXISTS <expr> |
the expression is non-empty according to EXISTS semantics |
true, or false on timeout |
WAITFOR NOT EXISTS <expr> |
the expression is empty or absent | true, or false on timeout |
WAITFOR VALUE <expr> |
the expression yields anything other than NONE |
that value, or NONE on timeout |
WAITFOR VALUE treats empty strings, arrays, and objects as valid values and returns them immediately. When you need the candidate itself but also require it to be non-empty, add a WHEN condition:
The expression is re-evaluated on each attempt, so it can reflect state that changes over time. When the wait runs out, the result reports the timeout rather than raising an error:
Tuning the wait
Several clauses control how the wait behaves:
TIMEOUT <duration>— the maximum time to wait, provided as a value coercible to Duration.EVERY <interval>— how often to re-check. A second coercible Duration,EVERY <interval>, <cap>, caps how large the interval can grow. Without this clause, polling defaults to100ms.BACKOFF LINEAR | EXPONENTIAL | NONE— how the interval between checks grows over time.JITTER <0..1>— randomizes the interval to avoid synchronized retries.WHEN <condition>— an additional condition that must also hold; the candidate value is available as..
TIMEOUT, EVERY, and its cap accept ordinary expressions, so values can be stored or computed:
TIMEOUT, EVERY, and its cap use the canonical Duration conversion rules. Numbers are milliseconds, duration strings may be compound, and singleton lists are converted recursively:
All scheduling results must be non-negative. Conversion failures, overflow, and negative values raise runtime errors.
Recovering from a timeout
By default a timed-out wait returns false (or NONE for the VALUE form). A recovery clause lets you choose a different result.
Use ON ERROR to handle a failure raised while evaluating the condition.
Waiting for an event
In event mode, WAITFOR subscribes to an event source and waits for a matching event, which it returns as a value.
Event timeouts use the same Duration conversion and non-negative scheduling policy as condition waits.
A WHEN filter accepts only events that match a condition. Inside the filter, the incoming event is available as .. Multiple WHEN clauses must all pass.
Triggering the event
A TRIGGER clause runs statements after the subscription is set up but before waiting begins. This is how you cause the event you are waiting for without risking a race where it fires before you start listening.
The trigger body can dispatch events and run other statements. See Dispatch Expressions.
A host capability
Event mode only works when the source is an observable value — one that produces a stream of events, provided by a module or the host application, such as a browser page. Condition mode has no such requirement. See Value Capabilities and Host Values.