@swisseph/node 1.0.0

package/README.md

@@ -0,0 +1,261 @@
+# @swisseph/node
+
+High precision astronomical calculations for Node.js using native bindings to the Swiss Ephemeris C library.
+
+## Installation
+
+```bash
+npm install @swisseph/node
+```
+
+**Requirements:**
+- Node.js 14.0.0 or higher
+- C++ build tools for native compilation
+
+<details>
+<summary>Installing build tools</summary>
+
+**macOS:**
+```bash
+xcode-select --install
+```
+
+**Linux (Debian/Ubuntu):**
+```bash
+sudo apt-get install build-essential
+```
+
+**Windows:**
+```bash
+npm install --global windows-build-tools
+```
+</details>
+
+## Quick Start
+
+```typescript
+import {
+  julianDay,
+  calculatePosition,
+  calculateHouses,
+  Planet,
+  HouseSystem
+} from '@swisseph/node';
+
+// No setup required! Ephemeris files are bundled and auto-loaded.
+
+// Calculate planetary position
+const jd = julianDay(2007, 3, 3);
+const sun = calculatePosition(jd, Planet.Sun);
+console.log(`Sun: ${sun.longitude}°`);
+
+// Calculate houses
+const houses = calculateHouses(jd, 40.7128, -74.0060, HouseSystem.Placidus);
+console.log(`Ascendant: ${houses.ascendant}°`);
+console.log(`MC: ${houses.mc}°`);
+```
+
+## Core API
+
+### Date & Time
+
+```typescript
+julianDay(year, month, day, hour?, calendarType?)
+julianDayToDate(jd, calendarType?)
+```
+
+### Planetary Positions
+
+```typescript
+calculatePosition(jd, body, flags?)
+// Returns: { longitude, latitude, distance, longitudeSpeed, ... }
+```
+
+**Available bodies:** `Planet.Sun`, `Planet.Moon`, `Planet.Mercury`, `Planet.Venus`, `Planet.Mars`, `Planet.Jupiter`, `Planet.Saturn`, `Planet.Uranus`, `Planet.Neptune`, `Planet.Pluto`, `Asteroid.Chiron`, `LunarPoint.MeanNode`, etc.
+
+### Houses
+
+```typescript
+calculateHouses(jd, latitude, longitude, houseSystem?)
+// Returns: { cusps[], ascendant, mc, armc, vertex, ... }
+```
+
+**House systems:** `Placidus`, `Koch`, `Equal`, `WholeSign`, `Campanus`, `Regiomontanus`, etc.
+
+### Eclipses
+
+```typescript
+findNextLunarEclipse(startJd, flags?, eclipseType?, backward?)
+findNextSolarEclipse(startJd, flags?, eclipseType?, backward?)
+// Returns eclipse object with methods: isTotal(), isPartial(), getTotalityDuration(), etc.
+```
+
+### Utilities
+
+```typescript
+getCelestialBodyName(body)  // Get name string
+close()                      // Free resources when done
+```
+
+## Ephemeris Options
+
+**Default: Swiss Ephemeris (bundled, ~2MB)**
+- JPL precision, automatically loaded
+- Includes planets, moon, and main asteroids
+- No configuration needed
+
+**Optional: Moshier Ephemeris (built-in)**
+```typescript
+import { CalculationFlag } from '@swisseph/node';
+calculatePosition(jd, Planet.Sun, CalculationFlag.MoshierEphemeris);
+```
+- No files loaded, smaller footprint
+- Sub-arcsecond precision
+- Major planets only (no asteroids)
+
+**Optional: Custom Files**
+```typescript
+import { setEphemerisPath } from '@swisseph/node';
+setEphemerisPath('/path/to/custom/ephemeris');
+```
+
+Download additional files from [Swiss Ephemeris repository](https://raw.githubusercontent.com/aloistr/swisseph/master/ephe/).
+
+## TypeScript Support
+
+Full TypeScript types included. All enums and interfaces are exported:
+
+```typescript
+import {
+  Planet, Asteroid, LunarPoint,      // Celestial bodies
+  HouseSystem,                        // House systems
+  CalculationFlag,                    // Calculation options
+  CalendarType                        // Gregorian/Julian
+} from '@swisseph/node';
+```
+
+## Examples
+
+### Birth Chart Calculation
+
+```typescript
+import {
+  julianDay,
+  calculatePosition,
+  calculateHouses,
+  Planet,
+  HouseSystem,
+  close
+} from '@swisseph/node';
+
+// Birth: May 15, 1990, 14:30 UTC, New York (40.7128°N, 74.0060°W)
+const jd = julianDay(1990, 5, 15, 14.5);
+
+// Calculate all planet positions
+const planets = [
+  { name: 'Sun', position: calculatePosition(jd, Planet.Sun) },
+  { name: 'Moon', position: calculatePosition(jd, Planet.Moon) },
+  { name: 'Mercury', position: calculatePosition(jd, Planet.Mercury) },
+  { name: 'Venus', position: calculatePosition(jd, Planet.Venus) },
+  { name: 'Mars', position: calculatePosition(jd, Planet.Mars) },
+  { name: 'Jupiter', position: calculatePosition(jd, Planet.Jupiter) },
+  { name: 'Saturn', position: calculatePosition(jd, Planet.Saturn) },
+  { name: 'Uranus', position: calculatePosition(jd, Planet.Uranus) },
+  { name: 'Neptune', position: calculatePosition(jd, Planet.Neptune) },
+  { name: 'Pluto', position: calculatePosition(jd, Planet.Pluto) }
+];
+
+planets.forEach(({ name, position }) => {
+  console.log(`${name}: ${position.longitude.toFixed(4)}°`);
+});
+
+// Calculate houses
+const houses = calculateHouses(jd, 40.7128, -74.0060, HouseSystem.Placidus);
+console.log(`Ascendant: ${houses.ascendant.toFixed(4)}°`);
+console.log(`MC: ${houses.mc.toFixed(4)}°`);
+
+for (let i = 1; i <= 12; i++) {
+  console.log(`House ${i}: ${houses.cusps[i].toFixed(4)}°`);
+}
+
+close();
+```
+
+### Eclipse Search
+
+```typescript
+import {
+  julianDay,
+  julianDayToDate,
+  findNextLunarEclipse,
+  close
+} from '@swisseph/node';
+
+// Find next 5 lunar eclipses starting from Jan 1, 2025
+let searchDate = julianDay(2025, 1, 1);
+
+for (let i = 0; i < 5; i++) {
+  const eclipse = findNextLunarEclipse(searchDate);
+  const maxTime = julianDayToDate(eclipse.maximum);
+
+  console.log(`\nEclipse ${i + 1}:`);
+  console.log(`  Date: ${maxTime.toString()}`);
+  console.log(`  Type: ${eclipse.isTotal() ? 'Total' : eclipse.isPartial() ? 'Partial' : 'Penumbral'}`);
+  console.log(`  Totality duration: ${eclipse.getTotalityDuration().toFixed(2)} hours`);
+
+  // Search for next eclipse after this one
+  searchDate = eclipse.maximum + 1;
+}
+
+close();
+```
+
+### Planetary Aspects
+
+```typescript
+import { julianDay, calculatePosition, Planet, close } from '@swisseph/node';
+
+const jd = julianDay(2025, 6, 15);
+
+// Calculate positions
+const sun = calculatePosition(jd, Planet.Sun);
+const moon = calculatePosition(jd, Planet.Moon);
+
+// Calculate aspect (angular difference)
+let aspect = Math.abs(sun.longitude - moon.longitude);
+if (aspect > 180) aspect = 360 - aspect;
+
+console.log(`Sun-Moon aspect: ${aspect.toFixed(2)}°`);
+
+// Classify aspect
+if (Math.abs(aspect - 0) < 10) console.log('Conjunction');
+else if (Math.abs(aspect - 60) < 10) console.log('Sextile');
+else if (Math.abs(aspect - 90) < 10) console.log('Square');
+else if (Math.abs(aspect - 120) < 10) console.log('Trine');
+else if (Math.abs(aspect - 180) < 10) console.log('Opposition');
+
+close();
+```
+
+## Troubleshooting
+
+**Build fails with "node-gyp rebuild failed"**
+- Install C++ build tools (see installation section above)
+
+**"Cannot find ephemeris files"**
+- Files are bundled with the package. Check `node_modules/@swisseph/node/ephemeris/` exists
+- If using custom files, verify path in `setEphemerisPath()`
+
+**"Module did not self-register"**
+- Rebuild for your Node.js version: `npm rebuild @swisseph/node`
+
+## License
+
+AGPL-3.0 (same as Swiss Ephemeris)
+
+## Links
+
+- [GitHub Repository](https://github.com/swisseph-js/swisseph)
+- [Swiss Ephemeris Documentation](https://www.astro.com/swisseph/)
+- [@swisseph/browser](../browser/) - WebAssembly version for browsers
+- [@swisseph/core](../core/) - Shared TypeScript types

package/binding/swisseph_binding.cc

@@ -0,0 +1,266 @@
+#include <napi.h>
+#include "swephexp.h"
+#include <cstring>
+
+// Wrapper for swe_set_ephe_path
+Napi::Value SetEphePath(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1) {
+    // If no argument provided, set to NULL (use default path)
+    swe_set_ephe_path(NULL);
+    return env.Undefined();
+  }
+
+  if (!info[0].IsString()) {
+    Napi::TypeError::New(env, "String expected").ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  std::string path = info[0].As<Napi::String>().Utf8Value();
+  swe_set_ephe_path(path.c_str());
+
+  return env.Undefined();
+}
+
+// Wrapper for swe_julday
+Napi::Value Julday(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 4) {
+    Napi::TypeError::New(env, "Expected 4 or 5 arguments: year, month, day, hour, [gregflag]")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  int year = info[0].As<Napi::Number>().Int32Value();
+  int month = info[1].As<Napi::Number>().Int32Value();
+  int day = info[2].As<Napi::Number>().Int32Value();
+  double hour = info[3].As<Napi::Number>().DoubleValue();
+  int gregflag = info.Length() >= 5 ? info[4].As<Napi::Number>().Int32Value() : SE_GREG_CAL;
+
+  double jd = swe_julday(year, month, day, hour, gregflag);
+
+  return Napi::Number::New(env, jd);
+}
+
+// Wrapper for swe_revjul
+Napi::Value Revjul(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Expected Julian day number")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  double jd = info[0].As<Napi::Number>().DoubleValue();
+  int gregflag = info.Length() >= 2 ? info[1].As<Napi::Number>().Int32Value() : SE_GREG_CAL;
+
+  int year, month, day;
+  double hour;
+
+  swe_revjul(jd, gregflag, &year, &month, &day, &hour);
+
+  Napi::Array result = Napi::Array::New(env, 4);
+  result[0u] = Napi::Number::New(env, year);
+  result[1u] = Napi::Number::New(env, month);
+  result[2u] = Napi::Number::New(env, day);
+  result[3u] = Napi::Number::New(env, hour);
+
+  return result;
+}
+
+// Wrapper for swe_calc_ut
+Napi::Value CalcUt(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 2) {
+    Napi::TypeError::New(env, "Expected Julian day and planet number")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  double tjd_ut = info[0].As<Napi::Number>().DoubleValue();
+  int32 ipl = info[1].As<Napi::Number>().Int32Value();
+  int32 iflag = info.Length() >= 3 ? info[2].As<Napi::Number>().Int32Value() : SEFLG_SWIEPH | SEFLG_SPEED;
+
+  double xx[6];
+  char serr[256];
+
+  int32 ret = swe_calc_ut(tjd_ut, ipl, iflag, xx, serr);
+
+  if (ret < 0) {
+    Napi::Error::New(env, serr).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  Napi::Array xxArray = Napi::Array::New(env, 6);
+  for (int i = 0; i < 6; i++) {
+    xxArray[i] = Napi::Number::New(env, xx[i]);
+  }
+
+  Napi::Array result = Napi::Array::New(env, 2);
+  result[0u] = xxArray;
+  result[1u] = Napi::Number::New(env, ret);
+
+  return result;
+}
+
+// Wrapper for swe_close
+Napi::Value Close(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  swe_close();
+  return env.Undefined();
+}
+
+// Wrapper for swe_get_planet_name
+Napi::Value GetPlanetName(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Expected planet number")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  int ipl = info[0].As<Napi::Number>().Int32Value();
+  char name[256];
+
+  swe_get_planet_name(ipl, name);
+
+  return Napi::String::New(env, name);
+}
+
+// Wrapper for swe_lun_eclipse_when
+Napi::Value LunEclipseWhen(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Expected starting Julian day")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  double tjd_start = info[0].As<Napi::Number>().DoubleValue();
+  int32 ifl = info.Length() >= 2 ? info[1].As<Napi::Number>().Int32Value() : SEFLG_SWIEPH;
+  int32 ifltype = info.Length() >= 3 ? info[2].As<Napi::Number>().Int32Value() : 0;
+  int32 backward = info.Length() >= 4 ? info[3].As<Napi::Number>().Int32Value() : 0;
+
+  double tret[10];
+  char serr[256];
+
+  int32 ret = swe_lun_eclipse_when(tjd_start, ifl, ifltype, tret, backward, serr);
+
+  if (ret < 0) {
+    Napi::Error::New(env, serr).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  Napi::Array tretArray = Napi::Array::New(env, 10);
+  for (int i = 0; i < 10; i++) {
+    tretArray[i] = Napi::Number::New(env, tret[i]);
+  }
+
+  Napi::Array result = Napi::Array::New(env, 2);
+  result[0u] = Napi::Number::New(env, ret);
+  result[1u] = tretArray;
+
+  return result;
+}
+
+// Wrapper for swe_sol_eclipse_when_glob
+Napi::Value SolEclipseWhenGlob(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Expected starting Julian day")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  double tjd_start = info[0].As<Napi::Number>().DoubleValue();
+  int32 ifl = info.Length() >= 2 ? info[1].As<Napi::Number>().Int32Value() : SEFLG_SWIEPH;
+  int32 ifltype = info.Length() >= 3 ? info[2].As<Napi::Number>().Int32Value() : 0;
+  int32 backward = info.Length() >= 4 ? info[3].As<Napi::Number>().Int32Value() : 0;
+
+  double tret[10];
+  char serr[256];
+
+  int32 ret = swe_sol_eclipse_when_glob(tjd_start, ifl, ifltype, tret, backward, serr);
+
+  if (ret < 0) {
+    Napi::Error::New(env, serr).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  Napi::Array tretArray = Napi::Array::New(env, 10);
+  for (int i = 0; i < 10; i++) {
+    tretArray[i] = Napi::Number::New(env, tret[i]);
+  }
+
+  Napi::Array result = Napi::Array::New(env, 2);
+  result[0u] = Napi::Number::New(env, ret);
+  result[1u] = tretArray;
+
+  return result;
+}
+
+// Wrapper for swe_houses
+Napi::Value Houses(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 3) {
+    Napi::TypeError::New(env, "Expected tjd_ut, geolat, geolon, [hsys]")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  double tjd_ut = info[0].As<Napi::Number>().DoubleValue();
+  double geolat = info[1].As<Napi::Number>().DoubleValue();
+  double geolon = info[2].As<Napi::Number>().DoubleValue();
+  int hsys = info.Length() >= 4 ? info[3].As<Napi::String>().Utf8Value()[0] : 'P';
+
+  double cusps[13];
+  double ascmc[10];
+
+  int ret = swe_houses(tjd_ut, geolat, geolon, hsys, cusps, ascmc);
+
+  if (ret < 0) {
+    Napi::Error::New(env, "Failed to calculate houses").ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  Napi::Array cuspsArray = Napi::Array::New(env, 13);
+  for (int i = 0; i < 13; i++) {
+    cuspsArray[i] = Napi::Number::New(env, cusps[i]);
+  }
+
+  Napi::Array ascmcArray = Napi::Array::New(env, 10);
+  for (int i = 0; i < 10; i++) {
+    ascmcArray[i] = Napi::Number::New(env, ascmc[i]);
+  }
+
+  Napi::Array result = Napi::Array::New(env, 2);
+  result[0u] = cuspsArray;
+  result[1u] = ascmcArray;
+
+  return result;
+}
+
+// Initialize the addon
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("set_ephe_path", Napi::Function::New(env, SetEphePath));
+  exports.Set("julday", Napi::Function::New(env, Julday));
+  exports.Set("revjul", Napi::Function::New(env, Revjul));
+  exports.Set("calc_ut", Napi::Function::New(env, CalcUt));
+  exports.Set("close", Napi::Function::New(env, Close));
+  exports.Set("get_planet_name", Napi::Function::New(env, GetPlanetName));
+  exports.Set("lun_eclipse_when", Napi::Function::New(env, LunEclipseWhen));
+  exports.Set("sol_eclipse_when_glob", Napi::Function::New(env, SolEclipseWhenGlob));
+  exports.Set("houses", Napi::Function::New(env, Houses));
+
+  return exports;
+}
+
+NODE_API_MODULE(swisseph, Init)

package/binding.gyp

@@ -0,0 +1,52 @@
+{
+  "targets": [
+    {
+      "target_name": "swisseph",
+      "sources": [
+        "binding/swisseph_binding.cc",
+        "../../native/libswe/sweph.c",
+        "../../native/libswe/swephlib.c",
+        "../../native/libswe/swedate.c",
+        "../../native/libswe/swejpl.c",
+        "../../native/libswe/swemmoon.c",
+        "../../native/libswe/swemplan.c",
+        "../../native/libswe/swehouse.c",
+        "../../native/libswe/swecl.c",
+        "../../native/libswe/swehel.c"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "../../native/libswe",
+        "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/v1"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
+      "conditions": [
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "CLANG_CXX_LANGUAGE_STANDARD": "c++14",
+            "MACOSX_DEPLOYMENT_TARGET": "10.15",
+            "OTHER_CPLUSPLUSFLAGS": ["-std=c++14", "-stdlib=libc++"]
+          },
+          "cflags_cc": ["-std=c++14", "-stdlib=libc++"]
+        }],
+        ["OS=='linux'", {
+          "cflags_cc": ["-std=c++14"]
+        }],
+        ["OS=='win'", {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1
+            }
+          }
+        }]
+      ]
+    }
+  ]
+}