swisseph-wasm 0.0.1

package/examples/README.md

@@ -0,0 +1,239 @@
+# SwissEph Examples
+
+This directory contains practical examples demonstrating how to use the SwissEph WebAssembly library for various astronomical and astrological calculations.
+
+## Examples Overview
+
+### 1. `basic-usage.js`
+Fundamental operations and core functionality:
+- Basic planetary position calculations
+- Multiple planet calculations
+- Time zone handling
+- Sidereal vs tropical comparisons
+- Date conversion functions
+- Degree utilities
+- Library information
+
+**Run with:**
+```bash
+node examples/basic-usage.js
+```
+
+### 2. `birth-chart.js`
+Complete birth chart calculation system:
+- Full birth chart calculator class
+- Planetary positions with zodiac signs
+- House calculations
+- Additional astrological points (nodes, Lilith, Chiron)
+- Aspect calculations
+- Professional-grade chart interpretation
+
+**Run with:**
+```bash
+node examples/birth-chart.js
+```
+
+### 3. `advanced-features.js` *(Coming Soon)*
+Advanced astronomical calculations:
+- Eclipse predictions
+- Rise/set/transit times
+- Fixed star positions
+- Topocentric calculations
+- Atmospheric refraction
+- Coordinate transformations
+
+### 4. `web-integration.js` *(Coming Soon)*
+Browser integration examples:
+- HTML/JavaScript integration
+- Real-time calculations
+- Interactive charts
+- Performance optimization
+- Error handling in web environments
+
+## Quick Start
+
+### Basic Planetary Position
+```javascript
+import SwissEph from '../src/swisseph.js';
+
+const swe = new SwissEph();
+await swe.initSwissEph();
+
+const jd = swe.julday(2023, 6, 15, 12.0);
+const sunPos = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+
+console.log(`Sun longitude: ${sunPos[0]}°`);
+swe.close();
+```
+
+### Birth Chart Calculation
+```javascript
+import { BirthChartCalculator } from './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(chart.planets);
+calculator.destroy();
+```
+
+## Example Output
+
+### Basic Planetary Positions
+```
+=== Basic Planetary Position ===
+Julian Day: 2460110.0
+Sun Position:
+  Longitude: 84.123456°
+  Latitude: 0.000123°
+  Distance: 1.015678 AU
+  Speed: 0.958765°/day
+  Zodiac: 24.12° Gemini
+```
+
+### Birth Chart
+```
+PLANETARY POSITIONS:
+===================
+☉ Sun       : 24.12° Taurus (54.12°)
+☽ Moon      : 15.67° Scorpio (225.67°)
+☿ Mercury   : 8.45° Gemini (68.45°)
+♀ Venus     : 2.89° Cancer (92.89°)
+♂ Mars      : 18.34° Virgo (168.34°)
+♃ Jupiter   : 12.78° Pisces (342.78°)
+♄ Saturn    : 25.91° Capricorn (295.91°)
+♅ Uranus    : 7.23° Capricorn (277.23°)
+♆ Neptune   : 11.45° Capricorn (281.45°)
+♇ Pluto     : 16.78° Scorpio (226.78°)
+
+MAJOR ASPECTS:
+==============
+Sun ☌ Mercury: Conjunction (orb: 2.34°)
+Moon ☍ Venus: Opposition (orb: 3.21°)
+Mars △ Jupiter: Trine (orb: 1.87°)
+```
+
+## Common Patterns
+
+### 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();
+  }
+}
+```
+
+### Batch Processing
+```javascript
+async function calculateMultipleDates(dates) {
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  const results = [];
+  for (const date of dates) {
+    const jd = swe.julday(date.year, date.month, date.day, date.hour);
+    const pos = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+    results.push({ date, position: pos[0] });
+  }
+  
+  swe.close();
+  return results;
+}
+```
+
+### Reusable Calculator Class
+```javascript
+class AstrologyCalculator {
+  constructor() {
+    this.swe = null;
+    this.initialized = false;
+  }
+  
+  async init() {
+    if (!this.initialized) {
+      this.swe = new SwissEph();
+      await this.swe.initSwissEph();
+      this.initialized = true;
+    }
+  }
+  
+  async calculate(params) {
+    await this.init();
+    // calculations here
+  }
+  
+  destroy() {
+    if (this.swe) {
+      this.swe.close();
+      this.swe = null;
+      this.initialized = false;
+    }
+  }
+}
+```
+
+## Running Examples
+
+### Prerequisites
+- Node.js 14+ or modern browser
+- ES6 modules support
+
+### Command Line
+```bash
+# Run basic usage examples
+node examples/basic-usage.js
+
+# Run birth chart example
+node examples/birth-chart.js
+
+# Run specific function
+node -e "import('./examples/basic-usage.js').then(m => m.basicPlanetaryPosition())"
+```
+
+### Browser
+```html
+<script type="module">
+  import { runAllExamples } from './examples/basic-usage.js';
+  runAllExamples();
+</script>
+```
+
+## Tips for Development
+
+1. **Always initialize**: Call `await swe.initSwissEph()` before calculations
+2. **Clean up**: Always call `swe.close()` when done
+3. **Handle time zones**: Convert to UTC before calculations
+4. **Validate inputs**: Check date ranges and parameter validity
+5. **Use constants**: Use library constants instead of magic numbers
+6. **Batch operations**: Reuse SwissEph instance for multiple calculations
+7. **Error handling**: Wrap calculations in try-catch blocks
+
+## Performance Considerations
+
+- Initialize once, calculate many times
+- Use appropriate calculation flags
+- Clean up resources properly
+- Consider WebWorkers for heavy calculations
+- Cache results when appropriate
+
+## Further Reading
+
+- [Main Documentation](../DOCUMENTATION.md)
+- [Quick Reference](../QUICK_REFERENCE.md)
+- [Test Suite](../tests/README.md)
+- [Swiss Ephemeris Documentation](https://www.astro.com/swisseph/swephprg.htm)

package/examples/basic-usage.js

@@ -0,0 +1,301 @@
+/**
+ * Basic Usage Examples for SwissEph Library
+ * 
+ * This file demonstrates fundamental operations with the Swiss Ephemeris
+ * WebAssembly library including planetary calculations, time conversions,
+ * and coordinate transformations.
+ */
+
+import SwissEph from '../src/swisseph.js';
+
+/**
+ * Example 1: Basic Planetary Position Calculation
+ * Calculates the position of the Sun for a specific date and time
+ */
+async function basicPlanetaryPosition() {
+  console.log('=== Basic Planetary Position ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    // Calculate Julian Day for June 15, 2023, 12:00 UTC
+    const jd = swe.julday(2023, 6, 15, 12.0);
+    console.log(`Julian Day: ${jd}`);
+    
+    // Calculate Sun position
+    const sunPosition = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+    
+    console.log(`Sun Position:`);
+    console.log(`  Longitude: ${sunPosition[0].toFixed(6)}°`);
+    console.log(`  Latitude: ${sunPosition[1].toFixed(6)}°`);
+    console.log(`  Distance: ${sunPosition[2].toFixed(6)} AU`);
+    console.log(`  Speed: ${sunPosition[3].toFixed(6)}°/day`);
+    
+    // Convert longitude to zodiac sign
+    const sign = Math.floor(sunPosition[0] / 30);
+    const degree = sunPosition[0] % 30;
+    const signs = ['Aries', 'Taurus', 'Gemini', 'Cancer', 'Leo', 'Virgo',
+                   'Libra', 'Scorpio', 'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces'];
+    
+    console.log(`  Zodiac: ${degree.toFixed(2)}° ${signs[sign]}`);
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Example 2: Multiple Planet Calculation
+ * Calculates positions for all major planets
+ */
+async function multiplePlanets() {
+  console.log('\n=== Multiple Planet Positions ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    const jd = swe.julday(2023, 6, 15, 12.0);
+    
+    const planets = [
+      { id: swe.SE_SUN, name: 'Sun' },
+      { id: swe.SE_MOON, name: 'Moon' },
+      { id: swe.SE_MERCURY, name: 'Mercury' },
+      { id: swe.SE_VENUS, name: 'Venus' },
+      { id: swe.SE_MARS, name: 'Mars' },
+      { id: swe.SE_JUPITER, name: 'Jupiter' },
+      { id: swe.SE_SATURN, name: 'Saturn' },
+      { id: swe.SE_URANUS, name: 'Uranus' },
+      { id: swe.SE_NEPTUNE, name: 'Neptune' },
+      { id: swe.SE_PLUTO, name: 'Pluto' }
+    ];
+    
+    console.log('Planet Positions for June 15, 2023:');
+    
+    for (const planet of planets) {
+      const position = swe.calc_ut(jd, planet.id, swe.SEFLG_SWIEPH);
+      console.log(`${planet.name.padEnd(10)}: ${position[0].toFixed(2)}°`);
+    }
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Example 3: Time Zone Conversion
+ * Demonstrates proper handling of time zones
+ */
+async function timeZoneExample() {
+  console.log('\n=== Time Zone Conversion ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    // Birth time: May 15, 1990, 2:30 PM in New York (UTC-5)
+    const year = 1990;
+    const month = 5;
+    const day = 15;
+    const hour = 14; // 2 PM
+    const minute = 30;
+    const timezone = -5; // UTC-5 (Eastern Daylight Time)
+    
+    // Convert to UTC
+    const utcHour = hour + minute / 60 - timezone;
+    const jd = swe.julday(year, month, day, utcHour);
+    
+    console.log(`Local time: ${year}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')} ${hour}:${minute.toString().padStart(2, '0')} (UTC${timezone})`);
+    console.log(`UTC time: ${year}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')} ${utcHour.toFixed(2)}`);
+    console.log(`Julian Day: ${jd}`);
+    
+    // Calculate Sun position for this time
+    const sunPos = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+    console.log(`Sun position: ${sunPos[0].toFixed(2)}°`);
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Example 4: Sidereal vs Tropical Comparison
+ * Shows the difference between tropical and sidereal calculations
+ */
+async function siderealVsTropical() {
+  console.log('\n=== Sidereal vs Tropical Comparison ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    const jd = swe.julday(2023, 6, 15, 12.0);
+    
+    // Tropical calculation (default)
+    const tropical = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH);
+    
+    // Set Lahiri ayanamsa for sidereal calculation
+    swe.set_sid_mode(swe.SE_SIDM_LAHIRI, 0, 0);
+    
+    // Sidereal calculation
+    const sidereal = swe.calc_ut(jd, swe.SE_SUN, swe.SEFLG_SWIEPH | swe.SEFLG_SIDEREAL);
+    
+    // Get ayanamsa value
+    const ayanamsa = swe.get_ayanamsa(jd);
+    
+    console.log(`Tropical Sun position: ${tropical[0].toFixed(6)}°`);
+    console.log(`Sidereal Sun position: ${sidereal[0].toFixed(6)}°`);
+    console.log(`Ayanamsa (Lahiri): ${ayanamsa.toFixed(6)}°`);
+    console.log(`Difference: ${(tropical[0] - sidereal[0]).toFixed(6)}°`);
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Example 5: Date Conversion Functions
+ * Demonstrates various date and time conversion utilities
+ */
+async function dateConversions() {
+  console.log('\n=== Date Conversion Functions ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    // Calculate Julian Day
+    const jd = swe.julday(2023, 6, 15, 12.5);
+    console.log(`Julian Day for 2023-06-15 12:30: ${jd}`);
+    
+    // Convert back to calendar date
+    const date = swe.revjul(jd, swe.SE_GREG_CAL);
+    console.log(`Reverse conversion: ${date.year}-${date.month}-${date.day} ${date.hour.toFixed(2)}`);
+    
+    // UTC to Julian Day conversion
+    const utcResult = swe.utc_to_jd(2023, 6, 15, 12, 30, 0, swe.SE_GREG_CAL);
+    console.log(`UTC to JD - ET: ${utcResult.julianDayET}, UT: ${utcResult.julianDayUT}`);
+    
+    // Calculate sidereal time
+    const sidTime = swe.sidtime(jd);
+    console.log(`Sidereal time: ${sidTime.toFixed(6)} hours`);
+    
+    // Calculate Delta T
+    const deltaT = swe.deltat(jd);
+    console.log(`Delta T: ${deltaT.toFixed(2)} seconds`);
+    
+    // Day of week
+    const dayOfWeek = swe.day_of_week(jd);
+    const days = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+    console.log(`Day of week: ${days[dayOfWeek]}`);
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Example 6: Degree Utilities
+ * Shows how to work with degree values and conversions
+ */
+async function degreeUtilities() {
+  console.log('\n=== Degree Utilities ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    const degrees = 123.456789;
+    
+    // Normalize degrees
+    console.log(`Original: ${degrees}°`);
+    console.log(`Normalized: ${swe.degnorm(degrees)}°`);
+    console.log(`Normalized (370°): ${swe.degnorm(370)}°`);
+    console.log(`Normalized (-10°): ${swe.degnorm(-10)}°`);
+    
+    // Split degrees into components
+    const split = swe.split_deg(degrees, swe.SE_SPLIT_DEG_ROUND_SEC);
+    console.log(`Split degrees:`);
+    console.log(`  Degrees: ${split.degree}°`);
+    console.log(`  Minutes: ${split.min}'`);
+    console.log(`  Seconds: ${split.second.toFixed(0)}"`);
+    console.log(`  Zodiac sign: ${split.sign} (0=Aries, 1=Taurus, etc.)`);
+    
+    // Zodiacal format
+    const zodiacal = swe.split_deg(degrees, swe.SE_SPLIT_DEG_ZODIACAL);
+    const signs = ['Aries', 'Taurus', 'Gemini', 'Cancer', 'Leo', 'Virgo',
+                   'Libra', 'Scorpio', 'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces'];
+    console.log(`Zodiacal: ${zodiacal.degree}° ${zodiacal.min}' ${zodiacal.second.toFixed(0)}" ${signs[zodiacal.sign]}`);
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Example 7: Library Information
+ * Shows how to get version and other library information
+ */
+async function libraryInfo() {
+  console.log('\n=== Library Information ===');
+  
+  const swe = new SwissEph();
+  await swe.initSwissEph();
+  
+  try {
+    // Get version
+    const version = swe.version();
+    console.log(`Swiss Ephemeris version: ${version}`);
+    
+    // Get planet names
+    console.log('\nPlanet names:');
+    for (let i = 0; i <= 9; i++) {
+      const name = swe.get_planet_name(i);
+      console.log(`  ${i}: ${name}`);
+    }
+    
+    // Show some constants
+    console.log('\nImportant constants:');
+    console.log(`  AU to km: ${swe.SE_AUNIT_TO_KM}`);
+    console.log(`  AU to light-year: ${swe.SE_AUNIT_TO_LIGHTYEAR}`);
+    console.log(`  AU to parsec: ${swe.SE_AUNIT_TO_PARSEC}`);
+    
+  } finally {
+    swe.close();
+  }
+}
+
+/**
+ * Run all examples
+ */
+async function runAllExamples() {
+  console.log('SwissEph Basic Usage Examples\n');
+  
+  await basicPlanetaryPosition();
+  await multiplePlanets();
+  await timeZoneExample();
+  await siderealVsTropical();
+  await dateConversions();
+  await degreeUtilities();
+  await libraryInfo();
+  
+  console.log('\n=== All examples completed ===');
+}
+
+// Export functions for use in other modules
+export {
+  basicPlanetaryPosition,
+  multiplePlanets,
+  timeZoneExample,
+  siderealVsTropical,
+  dateConversions,
+  degreeUtilities,
+  libraryInfo,
+  runAllExamples
+};
+
+// Run examples if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runAllExamples().catch(console.error);
+}