@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/SiderealTime.md

@@ -0,0 +1,302 @@
+# Sidereal Time
+
+**Sidereal time** is "star time" -- it measures the rotation of the Earth relative to the distant stars, rather than relative to the Sun. While a **solar day** (noon to noon) is 24 hours, a **sidereal day** (the time for the stars to return to the same position in the sky) is about **23 hours, 56 minutes, and 4 seconds**. The difference arises because the Earth is simultaneously orbiting the Sun: after one full rotation relative to the stars, it has moved about 1 degree along its orbit, so it needs to rotate a little extra to bring the Sun back to the same position.
+
+**Greenwich Sidereal Time (GST)** is the sidereal time at the Prime Meridian (longitude 0 degrees). It tells you which Right Ascension is currently crossing the meridian at Greenwich. To get **Local Sidereal Time (LST)** for any other location, simply add the observer's longitude (in hours):
+
+```
+LST = GST + (longitude_degrees / 15)
+```
+
+Sidereal time is fundamental to observational astronomy (it tells you which stars and constellations are visible right now), and in astrology it is the basis for house calculations: the **ARMC** (Ascensional Right Ascension of the Midheaven) is simply sidereal time multiplied by 15 (converting hours to degrees).
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Greenwich Sidereal Time at J2000.0
+const jd = SwissEph.julianDay(2000, 1, 1, 12);
+const gst = swe.siderealTime(jd);
+
+console.log(`Greenwich Sidereal Time: ${gst.toFixed(6)} hours`);
+// ~18.697374 hours
+
+// Convert to hh:mm:ss
+const h = Math.floor(gst);
+const m = Math.floor((gst - h) * 60);
+const s = ((gst - h) * 60 - m) * 60;
+console.log(`GST: ${h}h ${m}m ${s.toFixed(2)}s`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Local Sidereal Time for any location
+
+To get the local sidereal time, add the observer's longitude (converted to hours by dividing by 15). East longitudes are positive, west longitudes are negative.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2024, 6, 21, 22, ); // June 21, 2024 at 22:00 UT
+
+const gst = swe.siderealTime(jd);
+console.log(`Greenwich Sidereal Time: ${formatHMS(gst)}`);
+
+// Local Sidereal Time for different cities
+const cities = [
+  { name: 'London',    lon: -0.128 },
+  { name: 'New York',  lon: -74.006 },
+  { name: 'Tokyo',     lon: 139.692 },
+  { name: 'Sydney',    lon: 151.209 },
+  { name: 'Mumbai',    lon: 72.878 },
+];
+
+for (const city of cities) {
+  // LST = GST + longitude/15, then normalize to [0, 24)
+  let lst = gst + city.lon / 15;
+  while (lst < 0) lst += 24;
+  while (lst >= 24) lst -= 24;
+
+  console.log(`${city.name.padEnd(12)} LST: ${formatHMS(lst)}`);
+}
+
+function formatHMS(hours: number): string {
+  const h = Math.floor(hours);
+  const m = Math.floor((hours - h) * 60);
+  const s = ((hours - h) * 60 - m) * 60;
+  return `${String(h).padStart(2, '0')}h ${String(m).padStart(2, '0')}m ${s.toFixed(2).padStart(5, '0')}s`;
+}
+
+swe.close();
+```
+
+### What is on the meridian right now?
+
+The Local Sidereal Time directly tells you the Right Ascension that is currently crossing your local meridian (due south in the Northern Hemisphere). Any object with that RA is at its highest point in the sky (its culmination or upper transit).
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_MOON, SE_MARS, SE_JUPITER, SEFLG_EQUATORIAL } from '../../constants';
+
+const swe = new SwissEph();
+
+// Current observer: Los Angeles, some evening
+const lon = -118.243;
+const jd = SwissEph.julianDay(2024, 8, 15, 4); // 4:00 UT = ~9 PM PDT
+
+const gst = swe.siderealTime(jd);
+let lst = gst + lon / 15;
+while (lst < 0) lst += 24;
+while (lst >= 24) lst -= 24;
+
+console.log(`Local Sidereal Time: ${lst.toFixed(4)} hours`);
+console.log(`RA on the meridian: ${lst.toFixed(4)} hours = ${(lst * 15).toFixed(2)} deg`);
+console.log();
+
+// Check how far each planet is from the meridian
+const bodies = [
+  { id: SE_SUN,     name: 'Sun' },
+  { id: SE_MOON,    name: 'Moon' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+];
+
+for (const b of bodies) {
+  const pos = swe.calc(jd, b.id, SEFLG_EQUATORIAL);
+  const raHours = pos.longitude / 15; // Convert RA from degrees to hours
+
+  // Hour angle = LST - RA (how far west of the meridian)
+  let ha = lst - raHours;
+  while (ha < -12) ha += 24;
+  while (ha > 12) ha -= 24;
+
+  const side = ha > 0 ? 'west of meridian' : 'east of meridian';
+  console.log(
+    `${b.name.padEnd(9)} RA: ${raHours.toFixed(2)}h  ` +
+    `HA: ${Math.abs(ha).toFixed(2)}h ${side}` +
+    `${Math.abs(ha) < 1 ? '  <-- NEAR TRANSIT' : ''}`
+  );
+}
+
+swe.close();
+```
+
+### ARMC: Sidereal time as the basis for house cusps
+
+In house calculations, the starting point is the **ARMC** (Ascensional Right Ascension of the MC, also known simply as the MC in Right Ascension). It equals the Local Sidereal Time expressed in degrees:
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// London, J2000.0
+const jd = SwissEph.julianDay(2000, 1, 1, 12);
+const londonLon = -0.128;
+const londonLat = 51.507;
+
+// Get sidereal time and compute ARMC
+const gst = swe.siderealTime(jd);
+let lst = gst + londonLon / 15;
+while (lst < 0) lst += 24;
+while (lst >= 24) lst -= 24;
+
+const armc = lst * 15; // Convert hours to degrees
+console.log(`ARMC: ${armc.toFixed(4)} deg`);
+
+// Verify: the houses() function returns ARMC as well
+const houses = swe.houses(jd, { longitude: londonLon, latitude: londonLat });
+console.log(`ARMC from houses(): ${houses.armc.toFixed(4)} deg`);
+console.log(`MC:  ${houses.mc.toFixed(4)} deg`);
+
+// Note: ARMC and MC are NOT the same thing!
+// ARMC is in Right Ascension (equatorial).
+// MC is the ecliptic longitude where the meridian crosses the ecliptic.
+
+swe.close();
+```
+
+### Sidereal time throughout a day
+
+Sidereal time advances about 24h 03m 56s in one solar day (because a sidereal day is shorter, the sidereal clock gains about 3 minutes and 56 seconds per solar day relative to a normal clock):
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+console.log('Sidereal time at Greenwich, March 20, 2024:');
+console.log('UT Time    GST');
+
+for (let hour = 0; hour <= 24; hour += 3) {
+  const jd = SwissEph.julianDay(2024, 3, 20, hour);
+  const gst = swe.siderealTime(jd);
+
+  const h = Math.floor(gst);
+  const m = Math.floor((gst - h) * 60);
+  const s = ((gst - h) * 60 - m) * 60;
+  console.log(
+    `${String(hour).padStart(2, '0')}:00 UT   ` +
+    `${String(h).padStart(2, '0')}h ${String(m).padStart(2, '0')}m ${s.toFixed(1).padStart(4)}s`
+  );
+}
+
+// Show the sidereal day length
+const jd1 = SwissEph.julianDay(2024, 3, 20, 0);
+const jd2 = SwissEph.julianDay(2024, 3, 21, 0);
+const gst1 = swe.siderealTime(jd1);
+let gst2 = swe.siderealTime(jd2);
+if (gst2 < gst1) gst2 += 24;
+const gain = (gst2 - gst1) - 24;
+console.log(`\nSidereal time gained in 24 solar hours: ${(gain * 60).toFixed(2)} minutes`);
+// ~3.94 minutes
+
+swe.close();
+```
+
+### At what UT does a specific RA transit?
+
+If you want to know when a specific Right Ascension crosses the local meridian:
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// When does RA = 6h 45m (Sirius, approximately) transit at Greenwich?
+const targetRA = 6 + 45 / 60; // 6.75 hours
+
+// Start from midnight on a given date
+const jdStart = SwissEph.julianDay(2024, 1, 15, 0);
+const gstStart = swe.siderealTime(jdStart);
+
+// How many sidereal hours until the target RA reaches the meridian?
+let wait = targetRA - gstStart;
+while (wait < 0) wait += 24;
+
+// Convert sidereal hours to solar hours
+// 1 sidereal hour = 0.99727 solar hours
+const solarHours = wait * 0.99727;
+
+const transitJd = jdStart + solarHours / 24;
+const date = SwissEph.fromJulianDay(transitJd);
+
+console.log(`Sirius (RA ~6h 45m) transits Greenwich at approximately:`);
+console.log(`  ${date.year}-${String(date.month).padStart(2, '0')}-${String(date.day).padStart(2, '0')} ` +
+  `${Math.floor(date.hour)}:${String(Math.floor((date.hour % 1) * 60)).padStart(2, '0')} UT`);
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### Sidereal day vs solar day
+
+A **sidereal day** is one complete rotation of Earth relative to the distant stars: 23h 56m 04.0905s of mean solar time. A **solar day** (noon to noon) is longer because while the Earth rotates, it also advances about 1 degree along its orbit. The Sun appears to drift about 1 degree eastward per day against the background stars, so after one sidereal day the Earth must rotate about 4 more minutes to "catch up" to the Sun.
+
+This means there are approximately 366.25 sidereal days in one year but only 365.25 solar days. The extra sidereal day comes from the Earth's orbital motion itself -- one full orbit adds one extra rotation relative to the stars.
+
+### Mean vs apparent sidereal time
+
+The Swiss Ephemeris `siderealTime()` returns **mean sidereal time** corrected for nutation (effectively giving apparent sidereal time). The distinction:
+
+- **Mean sidereal time** uses the mean equinox, ignoring the short-period nutation oscillation
+- **Apparent sidereal time** accounts for nutation, which causes the equinox to wobble by up to about 1.2 seconds of time (17" of arc)
+
+The nutation correction is small but important for precise house-cusp calculations.
+
+### The relationship to Right Ascension
+
+Right Ascension is measured along the celestial equator, starting from the vernal equinox (the point where the Sun crosses the equator heading north), and increasing eastward. It is measured in hours (0h to 24h), where 1h = 15 degrees.
+
+The Local Sidereal Time is numerically equal to the Right Ascension currently on the observer's meridian. So if LST = 12h 30m, any star with RA = 12h 30m is at its highest point in your sky right now. Stars with smaller RA are west of the meridian (already past their highest), and stars with larger RA are east (still rising).
+
+### Hour Angle
+
+The **Hour Angle (HA)** of an object is the difference between the Local Sidereal Time and the object's Right Ascension:
+
+```
+HA = LST - RA
+```
+
+- HA = 0h: the object is on the meridian (transiting)
+- HA > 0: the object is west of the meridian (past transit, heading toward setting)
+- HA < 0: the object is east of the meridian (still rising, before transit)
+- HA = +6h: the object is on the western horizon (approximately)
+- HA = -6h: the object is on the eastern horizon (approximately)
+
+### ARMC and house calculations
+
+The ARMC (Ascensional Right Ascension of the MC) is the fundamental input for house-cusp calculations. It equals the Local Sidereal Time expressed in degrees (multiply hours by 15). Given the ARMC, the geographic latitude, and the obliquity of the ecliptic, all house systems can compute their cusps.
+
+The MC (Medium Coeli, Midheaven) is the ecliptic longitude where the meridian intersects the ecliptic. It is derived from the ARMC by converting from equatorial to ecliptic coordinates. The MC is NOT simply the ARMC in different units -- the conversion depends on the obliquity.
+
+### Practical uses of sidereal time
+
+- **Telescope alignment**: When setting up a Go-To telescope or an equatorial mount, you need to know the current sidereal time to sync the mount's RA axis
+- **Observing planning**: Knowing the current LST tells you which part of the sky is best placed for observation (objects near the meridian are highest and least affected by atmospheric refraction)
+- **House cusps**: In astrology, sidereal time is the foundation of house calculations via the ARMC
+- **Satellite tracking**: Communication satellites and ground stations use sidereal time to predict satellite positions relative to Earth's rotation
+
+### Sidereal time at the vernal equinox
+
+At the moment of the vernal equinox (when the Sun crosses 0h RA), the Greenwich Sidereal Time at solar noon equals approximately 0h. This is the annual "reset point." From there, sidereal time gains about 3 minutes 56 seconds per solar day, completing a full 24-hour cycle in one year.
+
+Specifically, at the March equinox, the GST at 12:00 UT is close to 0h (it varies slightly because the equinox does not fall at exactly noon). At the June solstice, the GST at noon is close to 6h. At the September equinox, it is close to 12h. At the December solstice, it is close to 18h.
+
+### Input time scale
+
+The `siderealTime()` method expects the input Julian Day to be in **Universal Time (UT)**, regardless of the `timeMode` setting of the SwissEph instance. This is because sidereal time is a measure of Earth's rotation, which is defined in UT. The function internally applies Delta-T to compute the nutation correction.

package/src/SwissEph/UseCases/SolarEclipse.md

@@ -0,0 +1,379 @@
+# Solar Eclipses
+
+A **solar eclipse** occurs when the Moon passes between the Earth and the Sun, blocking some or all of the Sun's light. This happens because the Moon's orbit occasionally brings it directly in line between the Earth and Sun. Despite the Sun being about 400 times larger than the Moon, it is also about 400 times farther away, so they appear nearly the same size in our sky -- making total solar eclipses possible.
+
+Solar eclipses are among the most dramatic astronomical events. They can only happen during a New Moon, but they do not happen at every New Moon because the Moon's orbit is tilted about 5 degrees relative to the ecliptic. Only when the Moon is near one of its orbital nodes (where its orbit crosses the ecliptic plane) can an eclipse occur.
+
+The Swiss Ephemeris can predict solar eclipses with high precision: finding when they happen, what type they are, where the central path falls on Earth, and how the eclipse appears from any given location.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Find the next solar eclipse after January 1, 2024
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const eclipse = swe.solarEclipseGlobal(jd);
+
+// Convert the time of maximum eclipse to a readable date
+const date = SwissEph.fromJulianDay(eclipse.maximum);
+console.log(`Next solar eclipse: ${date.year}-${date.month}-${date.day}`);
+console.log(`Maximum at JD: ${eclipse.maximum.toFixed(6)}`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Finding the 2024 April 8 total solar eclipse
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_ECL_TOTAL } from '../../constants';
+
+const swe = new SwissEph();
+
+// Search for the next total solar eclipse after 2024-01-01
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const eclipse = swe.solarEclipseGlobal(jd, SE_ECL_TOTAL);
+
+const date = SwissEph.fromJulianDay(eclipse.maximum);
+const hours = (date.hour);
+const h = Math.floor(hours);
+const m = Math.floor((hours - h) * 60);
+const s = Math.round(((hours - h) * 60 - m) * 60);
+console.log(`Total solar eclipse: ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}`);
+console.log(`Maximum at: ${h}:${String(m).padStart(2,'0')}:${String(s).padStart(2,'0')} UT`);
+// Total solar eclipse: 2024-04-08
+// Maximum at: 18:17:... UT
+
+swe.close();
+```
+
+### Where is the central path?
+
+Use `solarEclipseWhere` to find the geographic coordinates of the central line at the moment of maximum eclipse.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// First, find the eclipse
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const eclipse = swe.solarEclipseGlobal(jd);
+
+// Now find where the central line falls at maximum
+const where = swe.solarEclipseWhere(eclipse.maximum);
+console.log(`Central path at maximum:`);
+console.log(`  Longitude: ${where.geopos.longitude.toFixed(2)} deg`);
+console.log(`  Latitude:  ${where.geopos.latitude.toFixed(2)} deg`);
+// For the 2024 Apr 8 eclipse: approximately lon=-104, lat=25 (northern Mexico)
+
+console.log(`Eclipse type flags: ${where.type}`);
+console.log(`Obscuration: ${(where.attributes.fraction * 100).toFixed(1)}%`);
+console.log(`Magnitude:   ${where.attributes.magnitude.toFixed(4)}`);
+
+swe.close();
+```
+
+### Tracking the central path across the Earth
+
+You can call `solarEclipseWhere` at different times during the eclipse to trace the entire path of the shadow across the Earth's surface.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const eclipse = swe.solarEclipseGlobal(jd);
+
+// Trace from first central contact to last central contact
+// second = start of central phase, third = end of central phase
+const start = eclipse.second;
+const end = eclipse.third;
+const steps = 20;
+const dt = (end - start) / steps;
+
+console.log('Central path of the solar eclipse:');
+for (let i = 0; i <= steps; i++) {
+  const t = start + i * dt;
+  const where = swe.solarEclipseWhere(t);
+  const date = SwissEph.fromJulianDay(t);
+  const h = Math.floor(date.hour);
+  const m = Math.floor((date.hour - h) * 60);
+  console.log(
+    `  ${h}:${String(m).padStart(2,'0')} UT  ` +
+    `lon=${where.geopos.longitude.toFixed(1)}, lat=${where.geopos.latitude.toFixed(1)}`
+  );
+}
+
+swe.close();
+```
+
+### How does the eclipse look from a specific city?
+
+Use `solarEclipseHow` to get eclipse attributes at a specific location and time, or use `solarEclipseLocal` to find the next eclipse visible from that location.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Dallas, Texas (in the path of the 2024 April 8 total eclipse)
+const dallas = { longitude: -96.797, latitude: 32.7767 };
+
+// Find the next solar eclipse visible from Dallas after 2024-01-01
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const local = swe.solarEclipseLocal(jd, dallas);
+
+const date = SwissEph.fromJulianDay(local.maximum);
+console.log(`Eclipse visible from Dallas on: ${date.year}-${date.month}-${date.day}`);
+
+// Four contact times
+const fmt = (jd: number) => {
+  const d = SwissEph.fromJulianDay(jd);
+  const h = Math.floor(d.hour);
+  const m = Math.floor((d.hour - h) * 60);
+  const s = Math.round(((d.hour - h) * 60 - m) * 60);
+  return `${h}:${String(m).padStart(2,'0')}:${String(s).padStart(2,'0')} UT`;
+};
+
+console.log(`First contact (partial begins):  ${fmt(local.firstContact)}`);
+console.log(`Second contact (total begins):   ${fmt(local.secondContact)}`);
+console.log(`Maximum eclipse:                 ${fmt(local.maximum)}`);
+console.log(`Third contact (total ends):      ${fmt(local.thirdContact)}`);
+console.log(`Fourth contact (partial ends):   ${fmt(local.fourthContact)}`);
+
+// Attributes at maximum
+console.log(`\nEclipse attributes:`);
+console.log(`  Obscuration fraction: ${(local.attributes.fraction * 100).toFixed(1)}%`);
+console.log(`  Magnitude:           ${local.attributes.magnitude.toFixed(4)}`);
+console.log(`  Sun/Moon diameter ratio: ${local.attributes.ratio.toFixed(4)}`);
+console.log(`  Saros cycle:   ${local.attributes.sarosCycle}`);
+console.log(`  Saros member:  ${local.attributes.sarosMember}`);
+
+swe.close();
+```
+
+### Eclipse attributes at a location using `solarEclipseHow`
+
+If you already know the JD of an eclipse (from `solarEclipseGlobal`) and just want to check how it looks from a specific place, `solarEclipseHow` is more direct than `solarEclipseLocal`.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Find the eclipse first
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const eclipse = swe.solarEclipseGlobal(jd);
+
+// Check from multiple cities
+const cities = [
+  { name: 'Dallas',    geo: { longitude: -96.797, latitude: 32.777 } },
+  { name: 'New York',  geo: { longitude: -74.006, latitude: 40.713 } },
+  { name: 'London',    geo: { longitude: -0.128,  latitude: 51.507 } },
+];
+
+for (const city of cities) {
+  const how = swe.solarEclipseHow(eclipse.maximum, city.geo);
+  const fraction = how.attributes.fraction;
+  if (fraction > 0) {
+    console.log(`${city.name}: ${(fraction * 100).toFixed(1)}% obscured, magnitude ${how.attributes.magnitude.toFixed(3)}`);
+  } else {
+    console.log(`${city.name}: eclipse not visible`);
+  }
+}
+
+swe.close();
+```
+
+### Filtering by eclipse type
+
+You can search specifically for total, annular, partial, or hybrid eclipses.
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_ECL_TOTAL, SE_ECL_ANNULAR, SE_ECL_PARTIAL, SE_ECL_ANNULAR_TOTAL,
+} from '../../constants';
+
+const swe = new SwissEph();
+let jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+// Find the next 5 total solar eclipses
+console.log('Next 5 total solar eclipses:');
+for (let i = 0; i < 5; i++) {
+  const ecl = swe.solarEclipseGlobal(jd, SE_ECL_TOTAL);
+  const date = SwissEph.fromJulianDay(ecl.maximum);
+  console.log(`  ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}`);
+  jd = ecl.maximum + 1; // Move past this eclipse to find the next one
+}
+
+// Find the next annular eclipse
+const annular = swe.solarEclipseGlobal(SwissEph.julianDay(2024, 1, 1, 0), SE_ECL_ANNULAR);
+const d = SwissEph.fromJulianDay(annular.maximum);
+console.log(`\nNext annular eclipse: ${d.year}-${d.month}-${d.day}`);
+
+// SE_ECL_ANNULAR_TOTAL (= SE_ECL_HYBRID) finds hybrid eclipses
+// A hybrid eclipse is annular in some parts of the path and total in others
+
+swe.close();
+```
+
+### Searching backward in time
+
+Set `backward` to `true` to search for the most recent past eclipse.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Find the most recent solar eclipse before January 1, 2024
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const eclipse = swe.solarEclipseGlobal(jd, 0, true); // backward = true
+
+const date = SwissEph.fromJulianDay(eclipse.maximum);
+console.log(`Most recent eclipse before 2024: ${date.year}-${date.month}-${date.day}`);
+// 2023-10-14 (annular eclipse across the Americas)
+
+swe.close();
+```
+
+### Listing eclipses over a range of years
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_ECL_TOTAL, SE_ECL_ANNULAR, SE_ECL_PARTIAL, SE_ECL_ANNULAR_TOTAL } from '../../constants';
+
+const swe = new SwissEph();
+
+let jd = SwissEph.julianDay(2024, 1, 1, 0);
+const endJd = SwissEph.julianDay(2030, 1, 1, 0);
+
+const typeNames = (flags: number): string => {
+  if (flags & SE_ECL_TOTAL) return 'Total';
+  if (flags & SE_ECL_ANNULAR_TOTAL) return 'Hybrid';
+  if (flags & SE_ECL_ANNULAR) return 'Annular';
+  if (flags & SE_ECL_PARTIAL) return 'Partial';
+  return 'Unknown';
+};
+
+console.log('Solar eclipses 2024-2029:');
+while (jd < endJd) {
+  const ecl = swe.solarEclipseGlobal(jd);
+  if (ecl.maximum > endJd) break;
+  const date = SwissEph.fromJulianDay(ecl.maximum);
+  console.log(`  ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}  ${typeNames(ecl.type)}`);
+  jd = ecl.maximum + 1;
+}
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### Eclipse types
+
+| Type | Constant | Description |
+|------|----------|-------------|
+| **Total** | `SE_ECL_TOTAL` (4) | The Moon completely covers the Sun's disc. The sky goes dark, the corona becomes visible. Only possible when the Moon is near perigee (closer to Earth). |
+| **Annular** | `SE_ECL_ANNULAR` (8) | The Moon is centered on the Sun but too far away (near apogee) to cover it completely, leaving a bright ring ("annulus") of sunlight around the Moon. |
+| **Partial** | `SE_ECL_PARTIAL` (16) | The Moon covers only part of the Sun's disc. This happens at the edges of a total/annular path, or when the alignment is not precise enough for a central eclipse. |
+| **Hybrid** | `SE_ECL_ANNULAR_TOTAL` (32) | Also called `SE_ECL_HYBRID`. The eclipse is annular at some points on the path and total at others. This rare type occurs when the Moon's shadow tip just barely reaches Earth's surface. |
+
+The `type` field in the result is a bitmask. You can also see `SE_ECL_CENTRAL` (1) if the eclipse has a central path, or `SE_ECL_NONCENTRAL` (2) if it does not. Use bitwise AND to check:
+
+```typescript
+import { SE_ECL_TOTAL, SE_ECL_CENTRAL } from '../../constants';
+
+if (eclipse.type & SE_ECL_TOTAL) {
+  console.log('This is a total eclipse');
+}
+if (eclipse.type & SE_ECL_CENTRAL) {
+  console.log('It has a central path across Earth');
+}
+```
+
+### The four contacts
+
+A solar eclipse has up to four "contact" points, which define the key moments of the eclipse for a specific location:
+
+1. **First contact** (`firstContact` / `first`): The Moon's disc first touches the Sun's disc. Partial phase begins.
+2. **Second contact** (`secondContact` / `second`): The Moon completely covers (or maximally overlaps) the Sun. Totality or annularity begins. Only occurs for total/annular eclipses.
+3. **Third contact** (`thirdContact` / `third`): Totality or annularity ends. The Moon begins to move off the Sun's disc.
+4. **Fourth contact** (`fourthContact` / `fourth`): The Moon's disc completely separates from the Sun. Eclipse ends.
+
+For a partial eclipse, only first and fourth contacts occur (second and third will be 0).
+
+In the **global** result (`solarEclipseGlobal`), the contact times refer to the eclipse overall on Earth's surface. In the **local** result (`solarEclipseLocal`), they refer to the specific observer's location.
+
+### Eclipse magnitude vs obscuration
+
+These are two different measurements that are often confused:
+
+- **Magnitude** (`attributes.magnitude`): The fraction of the Sun's *diameter* covered by the Moon at maximum eclipse. A magnitude of 1.0 means the Moon's diameter exactly matches the Sun's; greater than 1.0 means the Moon is larger (deep total eclipse). For an annular eclipse, magnitude is less than 1.0.
+
+- **Obscuration fraction** (`attributes.fraction`): The fraction of the Sun's *area* that is covered. This is what matters for how much light is blocked. Because area scales with the square of the diameter, a magnitude of 0.5 (half the diameter) covers only about 40% of the area, not 50%.
+
+For total eclipses, the obscuration is 1.0 (100%). For annular eclipses, even though the Moon is centered on the Sun, the obscuration is less than 1.0 because the ring of Sun around the Moon still shines.
+
+### The Saros cycle
+
+The **Saros cycle** is a period of approximately 6,585.3 days (18 years, 11 days, and 8 hours) after which the Sun, Moon, and nodes return to nearly the same relative geometry. This means eclipses tend to repeat in a predictable pattern.
+
+Each eclipse belongs to a **Saros series** (identified by `attributes.sarosCycle`), and its position within that series is given by `attributes.sarosMember`. A Saros series typically produces about 70-80 eclipses over 1,200-1,400 years, starting with small partial eclipses near one pole, progressing to central (total or annular) eclipses, and ending with small partials near the opposite pole.
+
+Because the Saros period is not a whole number of days (the extra 8 hours), each successive eclipse in a series occurs about 120 degrees further west in longitude. After three Saros cycles (54 years 34 days, called an "Exeligmos"), the eclipse returns to approximately the same longitude.
+
+### The `solarEclipseGlobal` result
+
+| Field | Description |
+|-------|-------------|
+| `type` | Bitmask of eclipse type flags |
+| `maximum` | JD of maximum eclipse (greatest magnitude) |
+| `first` | JD when the eclipse first begins anywhere on Earth |
+| `second` | JD when central eclipse begins (or totality/annularity begins) |
+| `third` | JD when central eclipse ends |
+| `fourth` | JD when the eclipse ends everywhere on Earth |
+| `sunrise` | JD of sunrise for the location of maximum (0 if not applicable) |
+| `sunset` | JD of sunset for the location of maximum (0 if not applicable) |
+
+### The `solarEclipseLocal` attributes
+
+| Field | Description |
+|-------|-------------|
+| `fraction` | Obscuration: fraction of Sun's area covered (0.0 to 1.0) |
+| `ratio` | Ratio of apparent lunar diameter to solar diameter |
+| `magnitude` | Eclipse magnitude: fraction of Sun's diameter covered |
+| `sarosCycle` | Saros series number |
+| `sarosMember` | Member number within the Saros series |
+| `solarDiameter` | Apparent diameter of the Sun (arc seconds) |
+| `lunarDiameter` | Apparent diameter of the Moon (arc seconds) |
+| `sarosRepetition` | How many eclipses in this Saros series so far |
+| `eclipseLongitude` | Ecliptic longitude where greatest eclipse occurs |
+| `eclipseLatitude` | Ecliptic latitude where greatest eclipse occurs |
+| `eclipseMagnitude` | Magnitude at the point of greatest eclipse |
+| `sunAltitude` | Altitude of the Sun at the location during maximum |
+
+### Safety note
+
+Never look directly at the Sun during a partial or annular eclipse without proper solar filters. Only during the brief totality phase of a total eclipse (when the Sun is completely covered) is it safe to view without protection. The Swiss Ephemeris helps you calculate exactly when totality begins and ends at your location (second and third contacts), but always exercise caution and use certified eclipse glasses or solar filters.
+
+### Tips for working with eclipse calculations
+
+- When iterating through eclipses, advance `jd` by at least 1 day past the previous eclipse's maximum to avoid finding the same eclipse again.
+- The `type` filter parameter in `solarEclipseGlobal` skips eclipses that do not match. If you pass `SE_ECL_TOTAL`, it will skip annular, partial, and hybrid eclipses and return the next total one.
+- For the most precise local timing, use `solarEclipseLocal` rather than `solarEclipseGlobal` followed by `solarEclipseHow`. The local function finds the eclipse that is actually visible from that location.
+- Contact times that are 0 indicate that contact did not occur (e.g., second and third contacts are 0 for a partial eclipse, since totality/annularity never happens).