Time queries
when() searches a date range and returns every interval during which a
compound sky condition remains true, formatted as [startJd, endJd] pairs in
UT Julian Days.
import {
Engine, julianDay, when, allOf, anyOf, notOf,
inSign, aspect, retrograde, notRetrograde,
} from "caelus";
import { embeddedData } from "caelus/data-embedded";
const engine = new Engine(embeddedData);
// Reads an interval of Julian Days as two UTC timestamps.
const utc = ([from, to]) => [from, to].map((jd) => new Date((jd - 2440587.5) * 86400000).toISOString());
when(
engine,
allOf(inSign("jupiter", "Cancer"), retrograde("mercury")),
julianDay(2025, 1, 1), julianDay(2027, 1, 1),
).map(utc);Over those two years, Jupiter occupies Cancer while Mercury is retrograde across four separate intervals:
| From | To |
|---|---|
| 18 July 2025 | 11 August 2025 |
| 9 November 2025 | 29 November 2025 |
| 26 February 2026 | 20 March 2026 |
| 29 June 2026 | 30 June 2026 |
The final interval lasts only a single day because Jupiter exits Cancer on 30 June 2026 shortly after Mercury turns retrograde.
Predicates
| Predicate | Matches while |
|---|---|
inSign(body, sign) | The body is inside the sign (name or index 0–11) |
aspect(body, kind, target, orb) | The body is within orb degrees of aspect to target |
retrograde(body) | The body's longitudinal motion is retrograde |
notRetrograde(body) | The body's longitudinal motion is direct |
In aspect(), target accepts either another body ID or a fixed ecliptic
longitude in degrees, supporting both sky-to-sky aspects and transits to natal
points. Supported aspects are conjunction, semisextile, sextile, square,
trine, quincunx, and opposition, with orb defaulting to 1°.
// Mars within 1° of Saturn, 2024 to 2030
when(engine, aspect("mars", "conjunction", "saturn", 1),
julianDay(2024, 1, 1), julianDay(2030, 1, 1)).map(utc);
// three intervals: 9 to 12 April 2024, 18 to 21 April 2026, 29 April to 2 May 2028Combining predicates
Compose and nest predicates to any depth with allOf, anyOf, and notOf:
when(
engine,
allOf(
aspect("venus", "trine", "jupiter", 2),
notRetrograde("venus"),
notOf(inSign("moon", "Scorpio")),
),
julianDay(2026, 1, 1), julianDay(2026, 7, 1),
).map(utc);
// one interval: 21 February 2026 07:14 UT to 24 February 2026 08:58 UTSearch mechanics and limits
Internally, every predicate evaluates as a continuous signed margin that stays
positive while satisfied. allOf takes the minimum of its parts, anyOf
takes the maximum, and notOf negates the margin, reducing any nested query
to a single function of time. when() samples this function across the date
range and applies bisection wherever the sign crosses zero.
By default, when() steps by one day, tightening to three hours whenever the
Moon or a lunar node appears in the query; pass { step } in options to set a
custom interval in days. Very short intervals that begin and end inside a
single step can be skipped unless you specify a smaller step (important when
testing tight orbs with fast planets). Returned intervals default to a cap of
500 via maxIntervals.
Because when() evaluates the entire range at uniform time steps, it works
best over spans of months, years, or decades. To search across millennia based
on planetary positions, use dateSky, which prunes candidate
windows from the slowest planet to the fastest.