astrology-chart

A framework-neutral TypeScript renderer that converts an already calculated western astrology chart into accessible SVG.

The package intentionally does not calculate planetary positions or interpret a chart. It accepts deterministic chart data containing points, houses, angles, and aspects, then renders that data consistently in browsers or other SVG-capable environments.

Install

npm install astrology-chart

Usage

import { renderNatalChart } from "astrology-chart";

const svg = renderNatalChart(chart, {
  size: 760,
  orientation: "ascendant-left",
  zodiacStyle: "glyph",
  showPointDegrees: true,
});

document.querySelector("#chart")!.innerHTML = svg;

For an existing DOM element, the package also exports mountNatalChart:

import { mountNatalChart } from "astrology-chart";

mountNatalChart(document.querySelector("#chart")!, chart);

Input boundary

The renderer accepts already calculated chart facts. It does not infer missing positions or calculate houses and aspects.

Root chart object

| Field | Required | Contract | | --- | --- | --- | | points | yes | Array of planets, lunar nodes, and any explicitly supplied angle points. | | houses | yes | Exactly 12 unique cusps ordered from house 1 through house 12. | | aspects | yes | Precomputed relationships referencing IDs present in points or angles. | | angles | no | Named angle objects such as ascendant and midheaven. Missing ASC/MC produces warnings. | | input | no | Original UTC date-time and geographic latitude/longitude for traceability. | | julianDayUt | no | Finite Julian day value supplied by the calculation layer. | | warnings | no | Calculation-layer warning strings preserved by validation diagnostics. |

Points and angles

Each point requires:

• a unique, non-empty id;
• a non-empty kind;
• longitude in [0, 360) degrees.

Optional point fields include body, name, sign, degreeInSign, house, model, axis, and retrograde. When supplied, degreeInSign must be in [0, 30) and house must be an integer from 1 to 12.

Houses

Every house cusp requires house and longitude. The array must contain houses 1–12 in that order, without duplicate house numbers or cusp longitudes. Unequal cusps are accepted; house-system calculation remains outside this package.

Aspects

Every aspect requires:

• point1 and point2 IDs;
• a non-empty type;
• exactAngle, separation, and non-negative orb values;
• optional non-negative maxOrb.

An aspect referencing an unknown point is invalid and causes strict rendering to fail instead of silently omitting the line.

Out of scope

Ephemeris adapters, local-time conversion, timezone and DST rules, zodiac selection, house calculation, aspect discovery, and interpretation belong outside this package.

Validation

Use validateChartData before storing or rendering untrusted chart JSON:

import { validateChartData } from "astrology-chart";

const validation = validateChartData(chartJson);

if (!validation.valid) {
  console.error(validation.errors);
}

console.warn(validation.warnings);

Each issue contains a stable code, a JSON-like path, and a human-readable message.

renderNatalChart validates strictly. Invalid input throws ChartDataValidationError, whose validation property contains the complete structured result.

Render diagnostics

Use renderNatalChartDetailed when aspect filters or validation warnings need to be audited:

import { renderNatalChartDetailed } from "astrology-chart";

const result = renderNatalChartDetailed(chart, {
  aspectTypes: ["square", "opposition"],
});

console.log(result.diagnostics);
// {
//   suppliedAspectCount,
//   renderedAspectCount,
//   skippedAspects,
//   warnings
// }

Every valid supplied aspect is counted as rendered or returned in skippedAspects with an explicit reason. Invalid aspect references fail validation and are never silently dropped.

Renderer behavior

• outputs a standalone SVG string;
• draws every supplied aspect by default;
• gives conjunctions a curved marker so close points remain visible;
• renders deterministic vector zodiac glyphs without emoji-font differences;
• shows exact degree/minute labels beside each plotted point;
• spreads crowded planetary labels across radial and angular lanes;
• supports aspect filtering and theme overrides;
• uses the Ascendant as the left-hand chart anchor by default;
• supports vector zodiac glyphs or compact abbreviations without platform-dependent emoji.

Development

npm install
npm run dev

Run the full verification suite:

npm run check

License

MIT