swisseph-wasm 0.0.1

package/LICENSE

@@ -0,0 +1,41 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2024 prolaxu
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+ADDITIONAL TERMS FOR SWISS EPHEMERIS
+
+This software is a JavaScript wrapper around the Swiss Ephemeris library.
+The Swiss Ephemeris is subject to the following license terms:
+
+Swiss Ephemeris License:
+- For non-commercial use: Free under GNU General Public License
+- For commercial use: Requires a commercial license from Astrodienst AG
+
+For commercial licensing of the Swiss Ephemeris, please contact:
+Astrodienst AG
+Dammstrasse 23
+CH-8702 Zollikon
+Switzerland
+Email: swisseph@astro.com
+Website: https://www.astro.com/swisseph/
+
+The Swiss Ephemeris source code and documentation can be found at:
+https://www.astro.com/swisseph/
+
+This wrapper library (swisseph-wasm) is provided under GPL-3.0-or-later,
+but commercial use may require additional licensing for the underlying
+Swiss Ephemeris calculations.

package/QUICK_REFERENCE.md

@@ -0,0 +1,263 @@
+# SwissEph Quick Reference Guide
+
+## Basic Setup
+
+```javascript
+import SwissEph from './src/swisseph.js';
+
+const swe = new SwissEph();
+await swe.initSwissEph();
+
+// Your calculations here
+
+swe.close(); // Always clean up
+```
+
+## Essential Functions
+
+### Date & Time
+```javascript
+// Julian Day calculation
+const jd = swe.julday(2023, 6, 15, 12.5);
+
+// UTC to Julian Day
+const result = swe.utc_to_jd(2023, 6, 15, 12, 30, 0, swe.SE_GREG_CAL);
+
+// Julian Day to calendar date
+const date = swe.revjul(jd, swe.SE_GREG_CAL);
+
+// Sidereal time
+const sidTime = swe.sidtime(jd);
+
+// Delta T
+const deltaT = swe.deltat(jd);
+```
+
+### Planet Positions
+```javascript
+// Basic calculation
+const pos = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+// Returns: [longitude, latitude, distance, speed]
+
+// Detailed calculation
+const detailed = swe.calc(jd, swe.SE_MOON, swe.SEFLG_SWIEPH);
+// Returns: {longitude, latitude, distance, longitudeSpeed, latitudeSpeed, distanceSpeed}
+```
+
+### Sidereal Calculations
+```javascript
+// Set sidereal mode
+swe.set_sid_mode(swe.SE_SIDM_LAHIRI, 0, 0);
+
+// Calculate sidereal position
+const sidereal = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH | swe.SEFLG_SIDEREAL);
+
+// Get ayanamsa
+const ayanamsa = swe.get_ayanamsa(jd);
+```
+
+## Planet Constants
+
+```javascript
+// Major planets
+swe.SE_SUN = 0        swe.SE_JUPITER = 5
+swe.SE_MOON = 1       swe.SE_SATURN = 6
+swe.SE_MERCURY = 2    swe.SE_URANUS = 7
+swe.SE_VENUS = 3      swe.SE_NEPTUNE = 8
+swe.SE_MARS = 4       swe.SE_PLUTO = 9
+
+// Lunar nodes
+swe.SE_MEAN_NODE = 10
+swe.SE_TRUE_NODE = 11
+
+// Asteroids
+swe.SE_CHIRON = 15    swe.SE_CERES = 17
+swe.SE_PHOLUS = 16    swe.SE_PALLAS = 18
+```
+
+## Calculation Flags
+
+```javascript
+// Ephemeris types
+swe.SEFLG_SWIEPH = 2      // Swiss Ephemeris (default)
+swe.SEFLG_JPLEPH = 1      // JPL Ephemeris
+swe.SEFLG_MOSEPH = 4      // Moshier Ephemeris
+
+// Coordinate systems
+swe.SEFLG_HELCTR = 8      // Heliocentric
+swe.SEFLG_BARYCTR = 16384 // Barycentric
+swe.SEFLG_TOPOCTR = 32768 // Topocentric
+swe.SEFLG_EQUATORIAL = 2048 // Equatorial coordinates
+
+// Special flags
+swe.SEFLG_SPEED = 256     // Include speed
+swe.SEFLG_SIDEREAL = 65536 // Sidereal positions
+swe.SEFLG_RADIANS = 8192  // Results in radians
+swe.SEFLG_J2000 = 32      // J2000 coordinates
+```
+
+## Sidereal Modes
+
+```javascript
+swe.SE_SIDM_FAGAN_BRADLEY = 0
+swe.SE_SIDM_LAHIRI = 1
+swe.SE_SIDM_DELUCE = 2
+swe.SE_SIDM_RAMAN = 3
+swe.SE_SIDM_KRISHNAMURTI = 5
+swe.SE_SIDM_USER = 255
+```
+
+## Common Patterns
+
+### Birth Chart Calculation
+```javascript
+async function birthChart(year, month, day, hour, minute, timezone) {
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  const utcHour = hour + minute / 60 - timezone;
+  const jd = swe.julday(year, month, day, utcHour);
+  
+  const planets = [swe.SE_SUN, swe.SE_MOON, swe.SE_MERCURY, swe.SE_VENUS, 
+                   swe.SE_MARS, swe.SE_JUPITER, swe.SE_SATURN];
+  
+  const chart = {};
+  for (const planet of planets) {
+    const pos = swe.calc_ut(jd, planet, swe.SEFLG_SWIEPH);
+    chart[swe.get_planet_name(planet)] = pos[0];
+  }
+  
+  swe.close();
+  return chart;
+}
+```
+
+### Current Planetary Positions
+```javascript
+async function currentPositions() {
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  const now = new Date();
+  const jd = swe.julday(
+    now.getUTCFullYear(),
+    now.getUTCMonth() + 1,
+    now.getUTCDate(),
+    now.getUTCHours() + now.getUTCMinutes() / 60
+  );
+  
+  const sunPos = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+  const moonPos = swe.calc_ut(jd, swe.SE_MOON, swe.SEFLG_SWIEPH);
+  
+  swe.close();
+  
+  return {
+    sun: sunPos[0],
+    moon: moonPos[0],
+    julianDay: jd
+  };
+}
+```
+
+### Sidereal vs Tropical
+```javascript
+async function comparePositions(year, month, day, hour) {
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  const jd = swe.julday(year, month, day, hour);
+  
+  // Tropical
+  const tropical = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+  
+  // Sidereal (Lahiri)
+  swe.set_sid_mode(swe.SE_SIDM_LAHIRI, 0, 0);
+  const sidereal = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH | swe.SEFLG_SIDEREAL);
+  
+  swe.close();
+  
+  return {
+    tropical: tropical[0],
+    sidereal: sidereal[0],
+    difference: tropical[0] - sidereal[0]
+  };
+}
+```
+
+## Utility Functions
+
+```javascript
+// Normalize degrees (0-360)
+const normalized = swe.degnorm(370); // Returns 10
+
+// Split degrees into D°M'S"
+const split = swe.split_deg(123.456, swe.SE_SPLIT_DEG_ROUND_SEC);
+// Returns: {degree: 123, min: 27, second: 24, sign: 4}
+
+// Day of week (0=Monday, 6=Sunday)
+const dayOfWeek = swe.day_of_week(jd);
+
+// Planet name
+const name = swe.get_planet_name(swe.SE_SUN); // Returns "Sun"
+
+// Version info
+const version = swe.version();
+```
+
+## Error Handling Template
+
+```javascript
+async function safeCalculation() {
+  let swe = null;
+  
+  try {
+    swe = new SwissEph();
+    await swe.initSwissEph();
+    
+    // Your calculations here
+    const jd = swe.julday(2023, 6, 15, 12);
+    const result = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+    
+    return { success: true, data: result };
+    
+  } catch (error) {
+    return { success: false, error: error.message };
+  } finally {
+    if (swe) swe.close();
+  }
+}
+```
+
+## Performance Tips
+
+1. **Reuse instances** for multiple calculations
+2. **Batch calculations** in single session
+3. **Always call close()** to prevent memory leaks
+4. **Validate inputs** before calculation
+5. **Use appropriate flags** for your needs
+
+## Common Gotchas
+
+- **Time zones**: Convert to UTC before calculation
+- **Month numbering**: Use 1-12, not 0-11
+- **Memory management**: Always call `close()`
+- **Async initialization**: Always `await initSwissEph()`
+- **Flag combinations**: Use bitwise OR (`|`) to combine flags
+
+## Browser Requirements
+
+- WebAssembly support
+- ES6 modules
+- Modern JavaScript (async/await)
+
+## File Structure
+
+```
+your-project/
+├── src/
+│   └── swisseph.js          # Main library
+├── wsam/
+│   ├── swisseph.js          # WASM module
+│   └── swisseph.wasm        # WASM binary
+└── your-app.js              # Your application
+```

package/README.md

@@ -0,0 +1,305 @@
+# SwissEph WebAssembly Library
+
+A high-precision JavaScript wrapper for the Swiss Ephemeris WebAssembly module, providing professional-grade astronomical calculations for astrology, astronomy, and related applications.
+
+## 🌟 Features
+
+- **High Precision**: Based on the renowned Swiss Ephemeris
+- **WebAssembly Performance**: Fast calculations in the browser and Node.js
+- **Comprehensive API**: Full access to Swiss Ephemeris functions
+- **Modern JavaScript**: ES6+ with async/await support
+- **Well Tested**: 106 tests with 86% coverage
+- **Complete Documentation**: Extensive guides and examples
+- **Professional Grade**: Suitable for commercial applications
+
+## 📦 Installation
+
+### npm
+```bash
+npm install swisseph-wasm
+```
+
+### yarn
+```bash
+yarn add swisseph-wasm
+```
+
+### pnpm
+```bash
+pnpm add swisseph-wasm
+```
+
+## 📦 What's Included
+
+- **Core Library** (`src/swisseph.js`) - Main JavaScript wrapper
+- **WebAssembly Module** (`wsam/`) - Compiled Swiss Ephemeris
+- **Comprehensive Tests** (`tests/`) - 106 tests covering all functionality
+- **Documentation** - Complete API reference and guides
+- **Examples** - Practical usage examples and patterns
+- **Quick Reference** - Handy developer reference
+- **TypeScript Definitions** - Full type support
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```javascript
+import SwissEph from 'swisseph-wasm';
+
+// Create and initialize
+const swe = new SwissEph();
+await swe.initSwissEph();
+
+// Calculate planetary position
+const jd = swe.julday(2023, 6, 15, 12.0); // June 15, 2023, 12:00 UTC
+const sunPos = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+
+console.log(`Sun longitude: ${sunPos[0]}°`);
+
+// Clean up
+swe.close();
+```
+
+### Birth Chart Example
+
+```javascript
+import SwissEph from 'swisseph-wasm';
+
+// You can also import the example calculator
+// import { BirthChartCalculator } from 'swisseph-wasm/examples/birth-chart.js';
+
+const calculator = new BirthChartCalculator();
+
+const chart = await calculator.calculateBirthChart({
+  year: 1990, month: 5, day: 15,
+  hour: 14, minute: 30, timezone: -5,
+  latitude: 40.7128, longitude: -74.0060
+});
+
+console.log('Planetary Positions:');
+Object.entries(chart.planets).forEach(([name, planet]) => {
+  console.log(`${planet.symbol} ${name}: ${planet.zodiacSign.formatted}`);
+});
+
+calculator.destroy();
+```
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [**DOCUMENTATION.md**](DOCUMENTATION.md) | Complete API reference and usage guide |
+| [**QUICK_REFERENCE.md**](QUICK_REFERENCE.md) | Quick developer reference |
+| [**examples/README.md**](examples/README.md) | Example usage patterns |
+| [**tests/README.md**](tests/README.md) | Test suite documentation |
+
+## 🎯 Core Capabilities
+
+### Planetary Calculations
+- All major planets (Sun through Pluto)
+- Lunar nodes and apogee
+- Major asteroids (Chiron, Ceres, Pallas, etc.)
+- Uranian planets
+- Fixed stars
+
+### Coordinate Systems
+- Tropical and sidereal positions
+- Geocentric, heliocentric, topocentric
+- Ecliptic and equatorial coordinates
+- Multiple ayanamsa systems
+
+### Time Functions
+- Julian Day calculations
+- Time zone conversions
+- Sidereal time
+- Delta T calculations
+- Calendar conversions
+
+### Advanced Features
+- Eclipse calculations
+- Rise/set/transit times
+- House systems
+- Aspect calculations
+- Atmospheric refraction
+- Coordinate transformations
+
+## 🧪 Testing
+
+The library includes a comprehensive test suite with 106 tests:
+
+```bash
+npm install
+npm test                 # Run all tests
+npm run test:coverage   # Run with coverage report
+npm run test:watch      # Watch mode
+```
+
+**Test Coverage:**
+- ✅ 106 tests passing
+- ✅ 86.1% statement coverage
+- ✅ 66.66% function coverage
+- ✅ All major functionality covered
+
+## 📁 Project Structure
+
+```
+swiss-wasm/
+├── src/
+│   └── swisseph.js              # Main library file
+├── wsam/
+│   ├── swisseph.js              # WebAssembly module
+│   └── swisseph.wasm            # WebAssembly binary
+├── tests/
+│   ├── swisseph.test.js         # Core functionality tests
+│   ├── swisseph-advanced.test.js # Advanced features tests
+│   ├── swisseph-integration.test.js # Integration tests
+│   ├── swisseph-constants.test.js # Constants validation
+│   ├── __mocks__/               # Mock implementations
+│   └── README.md                # Test documentation
+├── examples/
+│   ├── basic-usage.js           # Basic usage examples
+│   ├── birth-chart.js           # Birth chart calculator
+│   └── README.md                # Examples documentation
+├── DOCUMENTATION.md             # Complete API reference
+├── QUICK_REFERENCE.md           # Quick developer guide
+└── README.md                    # This file
+```
+
+## 🌐 Browser Support
+
+**Modern Browsers:**
+- Chrome 61+
+- Firefox 60+
+- Safari 11+
+- Edge 16+
+
+**Requirements:**
+- WebAssembly support
+- ES6 modules support
+- Async/await support
+
+## 💡 Examples
+
+### Current Planetary Positions
+```javascript
+async function getCurrentPositions() {
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+
+  const now = new Date();
+  const jd = swe.julday(
+    now.getUTCFullYear(),
+    now.getUTCMonth() + 1,
+    now.getUTCDate(),
+    now.getUTCHours() + now.getUTCMinutes() / 60
+  );
+
+  const planets = [swe.SE_SUN, swe.SE_MOON, swe.SE_MERCURY];
+  const positions = {};
+
+  for (const planet of planets) {
+    const pos = swe.calc_ut(jd, planet, swe.SEFLG_SWIEPH);
+    positions[swe.get_planet_name(planet)] = pos[0];
+  }
+
+  swe.close();
+  return positions;
+}
+```
+
+### Sidereal vs Tropical
+```javascript
+async function compareSystems(year, month, day) {
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+
+  const jd = swe.julday(year, month, day, 12);
+
+  // Tropical
+  const tropical = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+
+  // Sidereal (Lahiri)
+  swe.set_sid_mode(swe.SE_SIDM_LAHIRI, 0, 0);
+  const sidereal = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH | swe.SEFLG_SIDEREAL);
+
+  swe.close();
+
+  return {
+    tropical: tropical[0],
+    sidereal: sidereal[0],
+    difference: tropical[0] - sidereal[0]
+  };
+}
+```
+
+## 🔧 Development
+
+### Running Examples
+```bash
+# Basic usage examples
+node examples/basic-usage.js
+
+# Birth chart calculation
+node examples/birth-chart.js
+```
+
+### Performance Tips
+1. **Reuse instances** for multiple calculations
+2. **Batch operations** in single sessions
+3. **Always clean up** with `swe.close()`
+4. **Validate inputs** before calculations
+5. **Use appropriate flags** for your needs
+
+### Error Handling
+```javascript
+async function safeCalculation() {
+  let swe = null;
+  try {
+    swe = new SwissEph();
+    await swe.initSwissEph();
+    // calculations here
+    return result;
+  } catch (error) {
+    console.error('Calculation failed:', error);
+    return null;
+  } finally {
+    if (swe) swe.close();
+  }
+}
+```
+
+## 📄 License
+
+This library is a wrapper around the Swiss Ephemeris, which is licensed under the GNU General Public License (GPL) for non-commercial use. For commercial use, a license from Astrodienst is required.
+
+**Swiss Ephemeris License:**
+- Non-commercial use: Free under GPL
+- Commercial use: Requires license from [Astrodienst](https://www.astro.com/swisseph/)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Update documentation
+6. Submit a pull request
+
+## 📞 Support
+
+- **Documentation**: Check the comprehensive docs in this repository
+- **Examples**: Review the examples directory for usage patterns
+- **Tests**: Look at test files for detailed usage examples
+- **Issues**: File issues on the project repository
+
+## 🏆 Credits
+
+- **Swiss Ephemeris**: Created by Astrodienst AG
+- **WebAssembly Port**: Compiled for web use
+- **JavaScript Wrapper**: Modern ES6+ interface
+- **Test Suite**: Comprehensive validation
+- **Documentation**: Complete developer guides
+
+---
+
+**Ready to calculate the cosmos? Start with the [Quick Reference](QUICK_REFERENCE.md) or dive into the [Complete Documentation](DOCUMENTATION.md)!** 🌟