kerykeion-ts

TypeScript core port of kerykeion, with a source-built Swiss Ephemeris WASM runtime compiled from the vendored upstream C sources. The package is designed to run in browser and serverless JavaScript environments without Python or native addons.

The repository keeps vendored upstream snapshots under vendor/ for auditability and parity work. The published npm package ships only the built core runtime plus the public Swiss Ephemeris data files.

Requirements

• Bun >= 1.3
• macOS / Linux / Windows environment that can load the bundled Swiss Ephemeris data in assets/sweph

Install

bun add kerykeion-ts

If you are working from this repository instead of the published package, use bun install.

The packaged runtime does not require Python at runtime. Python is only used by the parity test suite that compares the Bun/TypeScript implementation against the upstream Python project.

Repository commands

# lint
bun run lint

# type check
bun run typecheck

# check for unused files and dependencies
bun run check:unused

# run the parity and regression test suite
bun run test

# run the publish-facing checks
bun run verify

# build the npm-ready dist/ output and regenerate generated assets
bun run build

# run the browser demo
bun run demo:web

Build output

bun run build does five things:

1. regenerates chart assets
2. regenerates Swiss Ephemeris constants from vendored libswe headers
3. rebuilds the Swiss Ephemeris WASM runtime from vendored C sources
4. bundles the publishable dist/ package contents with Vite
5. emits TypeScript declarations for the published package

The published package ships ESM JavaScript plus .d.ts declarations from dist/. Bun remains the task runner for the repository, but package bundling now happens through Vite.

TypeScript usage

Create a subject and natal chart data

import {
  AstrologicalSubjectFactory,
  ChartDataFactory,
  ReportGenerator,
} from "kerykeion-ts";

const subject = await AstrologicalSubjectFactory.fromBirthData({
  name: "Ada Lovelace",
  year: 1815,
  month: 12,
  day: 10,
  hour: 13,
  minute: 45,
  city: "London",
  nation: "GB",
  lng: -0.1276,
  lat: 51.5072,
  tz_str: "Europe/London",
  online: false,
  zodiac_type: "Tropical",
  houses_system_identifier: "P",
  perspective_type: "Apparent Geocentric",
  suppress_geonames_warning: true,
});

const chartData = ChartDataFactory.createNatalChartData(subject);

console.log(chartData.chart_type);
console.log(chartData.subject.sun.sign);
console.log(new ReportGenerator(chartData).generate_report());

Generate an SVG chart

import {
  AstrologicalSubjectFactory,
  ChartDataFactory,
  ChartDrawer,
} from "kerykeion-ts";

const subject = await AstrologicalSubjectFactory.fromBirthData({
  name: "Alan Turing",
  year: 1912,
  month: 6,
  day: 23,
  hour: 14,
  minute: 0,
  city: "London",
  nation: "GB",
  lng: -0.1276,
  lat: 51.5072,
  tz_str: "Europe/London",
  online: false,
  suppress_geonames_warning: true,
});

const chartData = ChartDataFactory.createNatalChartData(subject);
const drawer = new ChartDrawer(chartData, {
  theme: "classic",
  chart_language: "EN",
  style: "modern",
  show_zodiac_background_ring: true,
});

const svg = drawer.generate_svg_string(false, false, {
  custom_title: "Alan Turing",
  style: "modern",
});

await Bun.write("./alan-turing-chart.svg", svg);

Browser or serverless usage

The published package ships the Swiss Ephemeris loader as ESM plus a standalone .wasm asset. That means:

• no python, pip, or native sweph package is required at runtime
• the ephemeris core can be loaded in browser/serverless deployments through normal bundler asset handling
• Node/Bun-only features such as writing SVG files or shelling out to scour stay behind runtime checks

import { AstrologicalSubjectFactory } from "kerykeion-ts";

const subject = await AstrologicalSubjectFactory.fromBirthData({
  name: "Browser Example",
  year: 1990,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  city: "Rome",
  nation: "IT",
  lng: 12.4964,
  lat: 41.9028,
  tz_str: "Europe/Rome",
  online: false,
  suppress_geonames_warning: true,
});

console.log(subject.sun.abs_pos);

For serverless handlers, import the core factories directly and build your own handler around them.

Upstream sync

The repository keeps a parity map and sync checklist in CLAUDE.md. That file records:

• the exact upstream SHAs last audited
• the mapping between local TypeScript modules and upstream Python/C files
• the difference between "keep parity with kerykeion" updates and "intentionally upgrade Swiss Ephemeris" updates
• the release checklist that must pass before publishing

The vendor/ directories are committed source snapshots, not nested git repositories. That is intentional: it keeps the main repository self-contained, reviewable, and publishable without submodules or embedded .git metadata.

To refresh the vendored snapshots from upstream:

# refresh all vendored upstream snapshots using the refs recorded in vendor/upstream-sources.json
bun run sync:vendors

# preview what would be synced without touching the working tree
bun run sync:vendors -- --dry-run

# update only one vendor
bun run sync:vendors -- --vendor=kerykeion

# override a specific ref during sync
bun run sync:vendors -- --vendor=pyswisseph-source --pyswisseph-ref=v2.10.03.2

After any sync, run:

bun run build
bun run verify:full

Notes

• For deterministic results, prefer explicit coordinates and timezone over GeoNames lookups.
• The test suite compares TypeScript results against the Python reference implementation and should stay green before publishing.

License

This project is distributed under AGPL-3.0-only, matching the upstream licensing constraints of kerykeion and the AGPL distribution path of Swiss Ephemeris used here. The top-level LICENSE file applies to this repository; vendored upstream source trees keep their original notices as well.