Data Tiers

The engine is given its ephemeris data explicitly. Two suppliers ship with the package: the embedded dataset for the browser and edge, and the Node loader for the extended packs. The hosted REST demo and MCP server build on these two.

What runs where

Embedded (browser, edge)

caelus/data-embedded bundles a compact dataset: the eight planets, the Moon, Pluto, Chiron, and the nodes, with the core house systems and aspects. This is what runs client-side and on edge runtimes, with no files on disk.

import { Engine } from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

Node loader (extended)

loadNodeData reads the larger JSON packs from disk: higher-precision VSOP tiers, the precise Moon pack, the asteroids and Uranian points, and the 318-star catalog. Use it when you need extended bodies, fixed stars, or event search.

import { Engine } from "caelus";
import { loadNodeData } from "caelus/node";

const engine = new Engine(loadNodeData());
const star = engine.fixedStar("Aldebaran", jd);

Turbo (bulk longitude scans)

For century-scale work that evaluates a longitude tens of thousands of times — a long transit scan, a returns sweep — the Turbo tier trades generality for speed. A turbo pack is a segmented Chebyshev representation of the engine's own apparent longitude, fit to the engine itself, so one evaluation is a couple of dozen multiply-adds. The pack is data you mint for your range and bodies; the runtime evaluator does no I/O and needs no engine.

import { Turbo } from "caelus";

// pack: a TurboPack you minted for your range/bodies (python/fit_turbo.py).
const turbo = new Turbo(pack);
turbo.has("mars");            // is this body in the pack?
turbo.longitude("mars", jd);  // apparent longitude (degrees), within [jd0, jd1]

Bundle sizes

The choice between client-side and server-side computation comes down to one number: the embedded dataset. The engine code tree-shakes small (a chart-only import drops event search, eclipses, the query and turbo tiers, and the derived and electional layers); the weight a browser pays is the coefficient data it bundles.

So: ship caelus + caelus/data-embedded for full charts in the browser (the data dominates, the code is a small addition on top of your app), or compute server-side through the REST endpoint or the MCP server and ship only caelus-wheel to render the result.