API Reference / when · function
Function: when()
function when(
engine,
predicate,
jdStart,
jdEnd,
opts?): Interval[];
Solve for the time intervals within [jdStart, jdEnd] (UT Julian Days) where
a Predicate holds. Predicates compose from aspect,
inSign, retrograde, notRetrograde, and the
allOf/anyOf combinators, so one call answers questions like
"when is Venus in Taurus while Mercury is direct?".
Returned intervals are sorted and disjoint; endpoints touching the range
bounds are clamped. The scan step defaults to 0.125 d when a fast body (Moon,
nodes, Lilith) is involved and 1 d otherwise — override it with opts.step.
Parameters
| Parameter | Type | Description |
|---|---|---|
engine | Engine | The engine used to evaluate positions. |
predicate | Predicate | A celestial predicate (see aspect, inSign). |
jdStart | number | Start of the search window, Julian Day (UT). |
jdEnd | number | End of the search window, Julian Day (UT). |
opts | WhenOptions | step (scan resolution in days) and maxIntervals. |
Returns
Interval[]
Sorted, disjoint [startUt, endUt] intervals where the predicate is
true.
Example
const windows = when(
engine,
allOf(inSign("venus", "Taurus"), notRetrograde("mercury")),
julianDay(2025, 1, 1), julianDay(2026, 1, 1),
);