Caelus3,462 checksGitHubv0.25.0MIT
Guides

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.

TypeScript
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:

FromTo
18 July 202511 August 2025
9 November 202529 November 2025
26 February 202620 March 2026
29 June 202630 June 2026

The final interval lasts only a single day because Jupiter exits Cancer on 30 June 2026 shortly after Mercury turns retrograde.

Predicates

PredicateMatches 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°.

TypeScript
// 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 2028

Combining predicates

Compose and nest predicates to any depth with allOf, anyOf, and notOf:

TypeScript
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 UT

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

Start building

Quickstart →