Documentation

Installation

npm install natalengine

Quick Start

import {
  calculateAstrology,
  calculateVedic,
  calculateHumanDesign,
  calculateGeneKeys
} from 'natalengine';

// Western Astrology
const astro = calculateAstrology(
  '1990-06-15',  // birth date (YYYY-MM-DD)
  14.5,          // birth hour (decimal, 14.5 = 2:30 PM)
  -5,            // timezone (UTC offset)
  40.7128,       // latitude
  -74.0060       // longitude
);

console.log(astro.bigThree);
// "♊ Gemini Sun, ♓ Pisces Moon, ♎ Libra Rising"

// Human Design
const hd = calculateHumanDesign('1990-06-15', 14.5, -5);
console.log(hd.type.name);  // "Generator"

// Vedic (Jyotish)
const vedic = calculateVedic('1990-06-15', 14.5, -5, 40.7128, -74.0060);
console.log(vedic.moonSign.summary);
// "Moon in Simha (Leo), Purva Phalguni Nakshatra"

// Gene Keys
const gk = calculateGeneKeys(hd);
console.log(gk.activationSequence.lifeWork.gift);  // "Discrimination"

calculateAstrology()

Calculate Western natal chart with planetary positions, aspects, and analysis.

Parameters

• birthDate (string) - Date in YYYY-MM-DD format
• birthHour (number) - Decimal hours (14.5 = 2:30 PM)
• timezone (number) - UTC offset (-5 for EST)
• latitude (number, optional) - Required for accurate Rising
• longitude (number, optional) - Required for accurate Rising

Returns

{
  sun: { sign, degree, longitude },
  moon: { sign, degree, longitude },
  rising: { sign, degree, longitude, accurate },
  planets: {
    mercury, venus, mars, jupiter,
    saturn, uranus, neptune, pluto
  },
  nodes: { north, south },
  midheaven: { sign, degree, longitude },
  aspects: [
    { planet1, planet2, aspect, symbol, orb, nature }
  ],
  balance: {
    elements: { fire, earth, air, water },
    modalities: { cardinal, fixed, mutable },
    dominantElement,
    dominantModality
  },
  bigThree: "♊ Gemini Sun, ♓ Pisces Moon, ♎ Libra Rising"
}

calculateVedic()

Calculate Vedic (Jyotish) astrology chart using sidereal zodiac with Lahiri ayanamsa.

Parameters

• birthDate (string) - Date in YYYY-MM-DD format
• birthHour (number) - Decimal hours (14.5 = 2:30 PM)
• timezone (number) - UTC offset (-5 for EST)
• latitude (number, optional) - Required for accurate Lagna
• longitude (number, optional) - Required for accurate Lagna

Returns

{
  ayanamsa: {
    system: "Lahiri",
    degrees: 24.123,
    formatted: "24° 7' 23\""
  },
  moonSign: {
    rashi: { name: "Simha", westernName: "Leo", symbol: "♌" },
    nakshatra: { name: "Purva Phalguni", pada: 2 },
    summary: "Moon in Simha (Leo), Purva Phalguni Nakshatra"
  },
  positions: {
    sun: { rashi, nakshatra, degree },
    moon: { rashi, nakshatra, degree },
    // ... all planets, rahu, ketu
  },
  dasha: {
    birthLord: "Venus",
    current: {
      maha: "Venus", mahaRemaining: "5y 3m",
      antar: "Saturn", antarRemaining: "1y 2m"
    },
    dashas: [...]
  },
  houses: { 1: { sign, planets }, ... }
}

calculateHumanDesign()

Calculate Human Design chart with Type, Strategy, Authority, and gate activations.

Parameters

• birthDate (string) - Date in YYYY-MM-DD format
• birthHour (number) - Decimal hours
• timezone (number) - UTC offset

Returns

{
  type: {
    name: "Generator",
    strategy: "Wait to respond",
    signature: "Satisfaction",
    notSelf: "Frustration"
  },
  authority: {
    name: "Emotional Authority",
    description: "Wait through emotional wave"
  },
  profile: {
    numbers: "3/5",
    name: "Martyr/Heretic",
    theme: "Trial and error, universalizing"
  },
  incarnationCross: {
    name: "Right Angle Cross of Planning",
    gates: [40, 37, 9, 16]
  },
  centers: {
    defined: [{ name, theme, biological }],
    undefined: [{ name, theme, biological }]
  },
  gates: {
    personality: {
      sun, earth, moon, northNode, southNode,
      mercury, venus, mars, jupiter, saturn,
      uranus, neptune, pluto
    },
    design: { ... },
    all: [1, 2, 3, ...]
  },
  channels: [
    { gates: [41, 30], name: "Recognition", centers: [...] }
  ]
}

calculateGeneKeys()

Calculate Gene Keys profile from Human Design data.

Parameters

• humanDesignData (object) - Result from calculateHumanDesign()

Returns

{
  activationSequence: {
    lifeWork: { key, line, sphere, shadow, gift, siddhi },
    evolution: { ... },
    radiance: { ... },
    purpose: { ... }
  },
  venusSequence: {
    attraction: { ... },
    iq: { ... },
    eq: { ... },
    sq: { ... }
  },
  pearlSequence: {
    vocation: { ... },
    culture: { ... },
    pearl: { ... }
  }
}

Accuracy

• Planetary positions: VSOP87 via astronomy-engine (±1 arcminute)
• Ascendant: Calculated from local sidereal time
• Human Design: 88° solar arc for design calculation
• Aspects: Includes major (±8°) and minor (±2-3°) aspects