@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/NodesAndApsides.md

@@ -0,0 +1,307 @@
+# Nodes and Apsides
+
+**Planetary nodes** and **apsides** describe key geometric features of a planet's orbit.
+
+**Nodes** are the two points where a planet's orbit crosses the ecliptic plane (the plane of Earth's orbit around the Sun). Every planet orbits the Sun on a slightly tilted plane, and these planes intersect the ecliptic at two points:
+- The **ascending node** is where the planet crosses the ecliptic going northward (from below to above the plane).
+- The **descending node** is where it crosses going southward.
+
+The most well-known nodes are the **lunar nodes**. In Vedic astrology, the ascending node is called **Rahu** and the descending node is **Ketu**. In Western astrology, they are known as the **North Node** and **South Node**. But every planet has its own pair of nodes -- they are simply less commonly used.
+
+**Apsides** are the points where a planet is closest to and farthest from the body it orbits:
+- **Perihelion**: the point of closest approach to the Sun (for the Moon: **perigee**, closest to Earth).
+- **Aphelion**: the point of greatest distance from the Sun (for the Moon: **apogee**, farthest from Earth).
+
+The Moon's apogee has special significance in astrology as **Black Moon Lilith** (the mean apogee) or **Osculating Lilith** (the true, instantaneous apogee).
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON, SE_NODBIT_MEAN } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 1, 1, 12);
+
+const result = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_MEAN);
+
+console.log(`Moon ascending node:  ${result.ascendingNode.longitude.toFixed(4)} deg`);
+console.log(`Moon descending node: ${result.descendingNode.longitude.toFixed(4)} deg`);
+console.log(`Moon perigee:         ${result.perihelion.longitude.toFixed(4)} deg`);
+console.log(`Moon apogee:          ${result.aphelion.longitude.toFixed(4)} deg`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Moon's nodes: mean vs osculating
+
+The **mean node** moves smoothly backward through the zodiac at about 19.3 degrees per year. The **osculating (true) node** wobbles around the mean with perturbations of up to ~1.5 degrees. Most Western astrologers use the mean node; Vedic astrology traditionally uses the true node.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON, SE_NODBIT_MEAN, SE_NODBIT_OSCU } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 6, 15, 12);
+
+const mean = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_MEAN);
+const oscu = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_OSCU);
+
+console.log(`Mean ascending node:       ${mean.ascendingNode.longitude.toFixed(4)} deg`);
+console.log(`Osculating ascending node: ${oscu.ascendingNode.longitude.toFixed(4)} deg`);
+console.log(`Difference: ${(oscu.ascendingNode.longitude - mean.ascendingNode.longitude).toFixed(4)} deg`);
+
+// The descending node is always roughly 180 degrees from the ascending node
+console.log(`\nMean descending node:      ${mean.descendingNode.longitude.toFixed(4)} deg`);
+
+// Speed of the mean node (retrograde, so negative)
+console.log(`Mean node speed: ${mean.ascendingNode.longitudeSpeed.toFixed(6)} deg/day`);
+
+swe.close();
+```
+
+### Tracking the Moon's nodal cycle
+
+The Moon's nodes complete a full retrograde circuit of the zodiac in approximately 18.6 years (6,798 days). This is the famous **nodal cycle** (or **Metonic-adjacent cycle**) that governs the timing of eclipses.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON, SE_NODBIT_MEAN } from '../../constants';
+
+const swe = new SwissEph();
+const signs = ['Ari','Tau','Gem','Can','Leo','Vir','Lib','Sco','Sag','Cap','Aqu','Pis'];
+
+// Track the North Node's position at the start of each year
+console.log('North Node position by year:');
+for (let year = 2020; year <= 2038; year++) {
+  const jd = SwissEph.julianDay(year, 1, 1, 0);
+  const result = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_MEAN);
+  const lon = result.ascendingNode.longitude;
+  const signIdx = Math.floor(lon / 30);
+  const degInSign = lon - signIdx * 30;
+  console.log(`  ${year}  ${degInSign.toFixed(1).padStart(5)} deg ${signs[signIdx]}  (${lon.toFixed(2)} deg)`);
+}
+// After ~18.6 years, the node returns to the same position
+
+swe.close();
+```
+
+### Planetary nodes (Mars, Jupiter, Saturn)
+
+Every planet has its own pair of orbital nodes. These move much more slowly than the Moon's nodes.
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_MARS, SE_JUPITER, SE_SATURN,
+  SE_NODBIT_MEAN, SE_NODBIT_OSCU,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+
+const planets = [
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+];
+
+for (const p of planets) {
+  const mean = swe.nodesApsides(jd, p.id, SE_NODBIT_MEAN);
+  const oscu = swe.nodesApsides(jd, p.id, SE_NODBIT_OSCU);
+
+  console.log(`${p.name}:`);
+  console.log(`  Mean asc. node:  ${mean.ascendingNode.longitude.toFixed(4)} deg`);
+  console.log(`  Oscu asc. node:  ${oscu.ascendingNode.longitude.toFixed(4)} deg`);
+  console.log(`  Mean perihelion:  ${mean.perihelion.longitude.toFixed(4)} deg`);
+  console.log(`  Mean aphelion:    ${mean.aphelion.longitude.toFixed(4)} deg`);
+  console.log();
+}
+
+swe.close();
+```
+
+### Mars apsides: perihelion and aphelion
+
+Mars has a notably eccentric orbit (e ~= 0.093). Its perihelion and aphelion distances differ by about 0.28 AU.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS, SE_NODBIT_MEAN } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+
+const result = swe.nodesApsides(jd, SE_MARS, SE_NODBIT_MEAN);
+
+console.log(`Mars perihelion longitude: ${result.perihelion.longitude.toFixed(4)} deg`);
+console.log(`Mars perihelion distance:  ${result.perihelion.distance.toFixed(6)} AU`);
+console.log(`Mars aphelion longitude:   ${result.aphelion.longitude.toFixed(4)} deg`);
+console.log(`Mars aphelion distance:    ${result.aphelion.distance.toFixed(6)} AU`);
+
+// Speed of perihelion precession (very slow)
+console.log(`Perihelion speed: ${result.perihelion.longitudeSpeed.toFixed(8)} deg/day`);
+
+swe.close();
+```
+
+### Black Moon Lilith: mean vs osculating apogee
+
+In astrology, "Black Moon Lilith" usually refers to the mean lunar apogee. The osculating (true) Lilith is the instantaneous apogee, which can differ significantly.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON, SE_NODBIT_MEAN, SE_NODBIT_OSCU } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 3, 20, 12);
+
+const mean = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_MEAN);
+const oscu = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_OSCU);
+
+console.log(`Mean Lilith (apogee):       ${mean.aphelion.longitude.toFixed(4)} deg`);
+console.log(`Osculating Lilith (apogee): ${oscu.aphelion.longitude.toFixed(4)} deg`);
+console.log(`Difference: ${(oscu.aphelion.longitude - mean.aphelion.longitude).toFixed(4)} deg`);
+
+// Mean Lilith moves about 40.7 deg/year (direct motion, unlike the nodes)
+console.log(`Mean Lilith speed: ${mean.aphelion.longitudeSpeed.toFixed(6)} deg/day`);
+
+swe.close();
+```
+
+### The focal point (SE_NODBIT_FOPOINT)
+
+An elliptical orbit has two focal points. The Sun (or Earth, for the Moon) sits at one focus. The `SE_NODBIT_FOPOINT` flag returns the **second (empty) focus** of the orbital ellipse instead of the aphelion. This is sometimes used in esoteric astrology as an alternative to Lilith.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON, SE_NODBIT_OSCU, SE_NODBIT_FOPOINT } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 1, 1, 12);
+
+// Osculating aphelion (normal)
+const oscu = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_OSCU);
+console.log(`Osculating apogee (Lilith):   ${oscu.aphelion.longitude.toFixed(4)} deg`);
+
+// Focal point: use SE_NODBIT_OSCU | SE_NODBIT_FOPOINT
+const focal = swe.nodesApsides(jd, SE_MOON, SE_NODBIT_OSCU | SE_NODBIT_FOPOINT);
+console.log(`Second focal point:           ${focal.aphelion.longitude.toFixed(4)} deg`);
+
+// The focal point and apogee are close but not identical because the orbit is not
+// a perfect ellipse — perturbations shift the apsidal line.
+
+swe.close();
+```
+
+### Barycentric osculating nodes
+
+The `SE_NODBIT_OSCU_BAR` method computes osculating elements relative to the **solar system barycenter** rather than the Sun. This matters for precise orbital mechanics because the Sun itself wobbles due to Jupiter and other giant planets.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER, SE_NODBIT_OSCU, SE_NODBIT_OSCU_BAR } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+
+const helio = swe.nodesApsides(jd, SE_JUPITER, SE_NODBIT_OSCU);
+const bary  = swe.nodesApsides(jd, SE_JUPITER, SE_NODBIT_OSCU_BAR);
+
+console.log('Jupiter ascending node:');
+console.log(`  Heliocentric osculating:  ${helio.ascendingNode.longitude.toFixed(4)} deg`);
+console.log(`  Barycentric osculating:   ${bary.ascendingNode.longitude.toFixed(4)} deg`);
+
+console.log('Jupiter perihelion:');
+console.log(`  Heliocentric:  ${helio.perihelion.longitude.toFixed(4)} deg`);
+console.log(`  Barycentric:   ${bary.perihelion.longitude.toFixed(4)} deg`);
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### What are orbital nodes?
+
+Every planet orbits the Sun in a plane that is slightly tilted relative to the ecliptic. The **inclination** measures this tilt (e.g., Mercury ~7 degrees, Mars ~1.85 degrees, Pluto ~17 degrees). The line where the planet's orbital plane intersects the ecliptic plane is called the **line of nodes**. The two endpoints of this line (projected onto the ecliptic) are the ascending and descending nodes.
+
+The ascending node is conventionally denoted by the symbol &#9738; and the descending node by &#9739;. The **longitude of the ascending node** (often written as capital omega) is one of the six classical Keplerian orbital elements.
+
+### Mean vs osculating elements
+
+This is one of the most important distinctions in orbital mechanics:
+
+- **Mean elements** are averaged values that describe the smoothly varying, long-term behavior of an orbit. They filter out short-period perturbations from other planets. The mean node of the Moon, for example, regresses steadily at about 19.3 degrees per year with no wobbles.
+
+- **Osculating elements** describe the instantaneous orbit -- the ellipse that the body would follow if all perturbations were suddenly turned off at that moment. They capture the real-time wobbles caused by gravitational tugs from other bodies.
+
+For the Moon, the osculating node can differ from the mean node by up to about 1.5 degrees due to solar perturbations. For astrology, the mean node is more commonly used in Western traditions because it produces smoother transits. Vedic astrology, however, traditionally uses the true (osculating) node.
+
+### The method parameter
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `SE_NODBIT_MEAN` | 1 | Mean elements. Smooth, averaged motion. Only available for Moon and planets with defined mean element models. |
+| `SE_NODBIT_OSCU` | 2 | Osculating (heliocentric) elements. Instantaneous orbit at the given moment. Available for all bodies. |
+| `SE_NODBIT_OSCU_BAR` | 4 | Osculating elements relative to the solar system barycenter instead of the Sun. More physically meaningful for precise work. |
+| `SE_NODBIT_FOPOINT` | 256 | Instead of returning the aphelion position, returns the **second focal point** of the orbital ellipse. Can be combined with `SE_NODBIT_OSCU` or `SE_NODBIT_OSCU_BAR` using bitwise OR. |
+
+Methods can be combined: `SE_NODBIT_OSCU | SE_NODBIT_FOPOINT` gives the osculating second focal point.
+
+### The return object
+
+The `nodesApsides()` method returns four `PlanetPosition` objects:
+
+| Field | Description |
+|-------|-------------|
+| `ascendingNode` | Position of the ascending node (longitude, latitude, distance, speeds) |
+| `descendingNode` | Position of the descending node |
+| `perihelion` | Position of the point of closest approach to the Sun (or Earth for Moon) |
+| `aphelion` | Position of the point of greatest distance (or the second focal point if `SE_NODBIT_FOPOINT` is set) |
+
+Each position includes:
+- `longitude`: ecliptic longitude in degrees (0-360)
+- `latitude`: ecliptic latitude in degrees (usually near 0 for nodes, can be nonzero for apsides)
+- `distance`: heliocentric distance in AU at that orbital point
+- `longitudeSpeed`, `latitudeSpeed`, `distanceSpeed`: daily rates of change
+
+### The 18.6-year nodal cycle of the Moon
+
+The Moon's nodes regress (move backward through the zodiac) with a period of about 18.6 years (6,798.4 days). This cycle is fundamental to eclipse prediction: eclipses can only occur when the Sun is near one of the Moon's nodes. Because the nodes regress, eclipse "seasons" shift earlier each year by about 19 days.
+
+The 18.6-year cycle also causes the **nutation** of Earth's axis -- a small wobble of ~9 arc-seconds superimposed on the 26,000-year precession cycle. This is why nutation and lunar nodes are so closely connected in the Swiss Ephemeris internals.
+
+### Perihelion precession
+
+The apsidal line (the line connecting perihelion and aphelion) slowly rotates forward through the zodiac. For Mercury, this precession is about 574 arc-seconds per century -- and it was the famous anomalous 43 arc-seconds per century of Mercury's perihelion precession that provided one of the first confirmations of Einstein's general relativity.
+
+For the Moon, the apsidal line (perigee/apogee) advances at about 40.7 degrees per year, completing a full cycle in about 8.85 years.
+
+### Black Moon Lilith in detail
+
+"Black Moon Lilith" in astrology refers to the lunar apogee, but there are several variants:
+
+| Variant | Source | Description |
+|---------|--------|-------------|
+| **Mean Lilith** | `SE_MEAN_APOG` (12) via `calc()`, or `nodesApsides()` with `SE_NODBIT_MEAN` | Smooth mean apogee. Moves steadily at ~40.7 deg/year. Most commonly used in astrology. |
+| **Osculating Lilith** | `SE_OSCU_APOG` (13) via `calc()`, or `nodesApsides()` with `SE_NODBIT_OSCU` | True instantaneous apogee. Wobbles significantly -- can differ from mean by 30 degrees or more. |
+| **Interpolated Lilith** | Some Swiss Ephemeris versions | An interpolation that smooths out extreme wobbles of the osculating Lilith. |
+| **Second focal point** | `nodesApsides()` with `SE_NODBIT_OSCU | SE_NODBIT_FOPOINT` | The empty focus of the Moon's orbital ellipse. Very close to osculating Lilith for nearly circular orbits, but differs for eccentric orbits. |
+
+The `calc()` method with `SE_MEAN_APOG` or `SE_OSCU_APOG` is typically the simplest way to get Lilith's position. The `nodesApsides()` method gives you additional control over the calculation method.
+
+### Practical considerations
+
+- **For astrology**: Mean nodes are standard in most traditions. Use `SE_NODBIT_MEAN` for charts.
+- **For astronomy**: Osculating elements are physically meaningful. Use `SE_NODBIT_OSCU` or `SE_NODBIT_OSCU_BAR`.
+- **For eclipses**: The true (osculating) node determines the actual geometry, but the mean node gives a better sense of the long-term pattern.
+- **SE_NODBIT_MEAN** is only available for the Moon and planets. For asteroids and other minor bodies, you must use `SE_NODBIT_OSCU`.
+- Nodal and apsidal positions are given in ecliptic coordinates. The `distance` field for a node represents the heliocentric distance of the planet when it crosses the ecliptic, which is useful for understanding the orbital geometry.

package/src/SwissEph/UseCases/Occultation.md

@@ -0,0 +1,352 @@
+# Occultations
+
+A **lunar occultation** occurs when the Moon passes directly in front of another celestial body -- a planet, star, or asteroid -- temporarily hiding it from view. The word "occultation" comes from the Latin *occultare*, meaning "to conceal." While solar eclipses are technically a special case of occultation (the Moon occulting the Sun), the term "occultation" in astronomy usually refers to the Moon hiding other objects.
+
+Occultations are significant to astronomers for several reasons:
+
+- **Precise timing**: Because the Moon has no atmosphere, a star disappears and reappears almost instantaneously (within milliseconds). Timing these events precisely allows measurement of the Moon's position to very high accuracy, which has historically helped refine our knowledge of the lunar orbit and Earth's rotation.
+- **Binary star discovery**: If a star winks out in two steps instead of one, it reveals an unsuspected close binary pair too tight to resolve with telescopes. Many binary stars were first discovered this way.
+- **Stellar diameters**: A star does not vanish truly instantaneously -- the light diffracts around the Moon's edge, producing a brief Fresnel diffraction pattern. By analyzing this pattern with high-speed photometry, astronomers can measure the angular diameter of the star.
+- **Asteroid occultations**: When an asteroid passes in front of a star, the shadow cast on Earth reveals the asteroid's precise size and shape. Citizen scientists across the predicted shadow path record the timing, and combining their observations produces a silhouette profile of the asteroid.
+- **Historical importance**: Before modern techniques like radar ranging and space missions, lunar occultations were one of the primary methods for determining precise positions of celestial objects, especially radio sources in the early days of radio astronomy.
+
+The Swiss Ephemeris can predict occultations of planets and fixed stars by the Moon -- finding when they happen globally, where they are visible, and how they appear from a specific location.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER } from '../../constants';
+
+const swe = new SwissEph();
+
+// Find the next occultation of Jupiter by the Moon after 2024-01-01
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const occ = swe.occultationGlobal(jd, SE_JUPITER);
+
+const date = SwissEph.fromJulianDay(occ.maximum);
+console.log(`Next Jupiter occultation: ${date.year}-${date.month}-${date.day}`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Finding the next occultation of a planet
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_VENUS, SE_MARS, SE_JUPITER, SE_SATURN,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+const fmt = (jd: number) => {
+  const d = SwissEph.fromJulianDay(jd);
+  return `${d.year}-${String(d.month).padStart(2,'0')}-${String(d.day).padStart(2,'0')}`;
+};
+
+const planets = [
+  { id: SE_VENUS,   name: 'Venus' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+];
+
+for (const p of planets) {
+  const occ = swe.occultationGlobal(jd, p.id);
+  console.log(`Next occultation of ${p.name}: ${fmt(occ.maximum)}`);
+}
+
+swe.close();
+```
+
+### Occultation of a fixed star
+
+You can search for the Moon occulting a fixed star by passing the star name and using planet = 0.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+// Find the next occultation of Regulus (Alpha Leonis) by the Moon
+// Planet parameter should be 0 when using a star name
+const occ = swe.occultationGlobal(jd, 0, 'Regulus');
+
+const date = SwissEph.fromJulianDay(occ.maximum);
+console.log(`Next Regulus occultation: ${date.year}-${date.month}-${date.day}`);
+
+// Contact times
+const fmt = (jd: number) => {
+  if (jd === 0) return '(n/a)';
+  const d = SwissEph.fromJulianDay(jd);
+  const h = Math.floor(d.hour);
+  const m = Math.floor((d.hour - h) * 60);
+  return `${h}:${String(m).padStart(2,'0')} UT`;
+};
+
+console.log(`  First contact:  ${fmt(occ.first)}`);
+console.log(`  Maximum:        ${fmt(occ.maximum)}`);
+console.log(`  Fourth contact: ${fmt(occ.fourth)}`);
+
+swe.close();
+```
+
+### Where is the occultation visible?
+
+Use `occultationWhere` to find the geographic coordinates where the occultation is visible at a given moment.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+// Find the next Jupiter occultation
+const occ = swe.occultationGlobal(jd, SE_JUPITER);
+
+// Where is it visible at maximum?
+const where = swe.occultationWhere(occ.maximum, SE_JUPITER);
+
+console.log(`Occultation visible from:`);
+console.log(`  Longitude: ${where.geopos.longitude.toFixed(2)} deg`);
+console.log(`  Latitude:  ${where.geopos.latitude.toFixed(2)} deg`);
+console.log(`  Type flags: ${where.type}`);
+
+swe.close();
+```
+
+### Local occultation: is it visible from my city?
+
+Use `occultationLocal` to find when the next occultation of a given body is visible from a specific location.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+const london = { longitude: -0.128, latitude: 51.507 };
+
+// Find the next Jupiter occultation visible from London
+const local = swe.occultationLocal(jd, SE_JUPITER, london);
+
+const fmt = (jd: number) => {
+  if (jd === 0) return '(n/a)';
+  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 `${d.year}-${String(d.month).padStart(2,'0')}-${String(d.day).padStart(2,'0')} ${h}:${String(m).padStart(2,'0')}:${String(s).padStart(2,'0')} UT`;
+};
+
+console.log(`Jupiter occultation visible from London:`);
+console.log(`  Disappearance (1st contact): ${fmt(local.firstContact)}`);
+console.log(`  Maximum:                     ${fmt(local.maximum)}`);
+console.log(`  Reappearance (4th contact):  ${fmt(local.fourthContact)}`);
+
+// Attributes
+console.log(`  Magnitude: ${local.attributes.magnitude.toFixed(4)}`);
+
+swe.close();
+```
+
+### Occultation of a fixed star from a specific location
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+const tokyo = { longitude: 139.692, latitude: 35.690 };
+
+// Find the next occultation of Aldebaran visible from Tokyo
+const local = swe.occultationLocal(jd, 0, tokyo, 'Aldebaran');
+
+const date = SwissEph.fromJulianDay(local.maximum);
+console.log(`Aldebaran occultation from Tokyo: ${date.year}-${date.month}-${date.day}`);
+
+const fmt = (jd: number) => {
+  if (jd === 0) return '(n/a)';
+  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(`  Star disappears: ${fmt(local.firstContact)}`);
+console.log(`  Star reappears:  ${fmt(local.fourthContact)}`);
+
+swe.close();
+```
+
+### Filtering by occultation type
+
+Like solar eclipses, occultations can be total (the planet/star is completely hidden), annular (for large planets where the Moon does not completely cover them -- rare), or partial.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER, SE_ECL_TOTAL } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+
+// Find only total occultations of Jupiter
+const occ = swe.occultationGlobal(jd, SE_JUPITER, null, SE_ECL_TOTAL);
+
+const date = SwissEph.fromJulianDay(occ.maximum);
+console.log(`Next total Jupiter occultation: ${date.year}-${date.month}-${date.day}`);
+
+swe.close();
+```
+
+### Listing occultations over a period
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_VENUS } from '../../constants';
+
+const swe = new SwissEph();
+
+let jd = SwissEph.julianDay(2024, 1, 1, 0);
+const endJd = SwissEph.julianDay(2030, 1, 1, 0);
+
+console.log('Venus occultations by the Moon, 2024-2029:');
+while (jd < endJd) {
+  const occ = swe.occultationGlobal(jd, SE_VENUS);
+  if (occ.maximum > endJd) break;
+
+  const date = SwissEph.fromJulianDay(occ.maximum);
+  const where = swe.occultationWhere(occ.maximum, SE_VENUS);
+  console.log(
+    `  ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}` +
+    `  lon=${where.geopos.longitude.toFixed(1)}, lat=${where.geopos.latitude.toFixed(1)}`
+  );
+
+  jd = occ.maximum + 1;
+}
+
+swe.close();
+```
+
+### Searching backward
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SATURN } from '../../constants';
+
+const swe = new SwissEph();
+
+// Find the most recent Saturn occultation before 2025-01-01
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+const occ = swe.occultationGlobal(jd, SE_SATURN, null, 0, true);
+
+const date = SwissEph.fromJulianDay(occ.maximum);
+console.log(`Most recent Saturn occultation: ${date.year}-${date.month}-${date.day}`);
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### How occultations differ from eclipses
+
+Although the Swiss Ephemeris uses similar functions and type constants for both, occultations and eclipses are conceptually different:
+
+| Aspect | Solar Eclipse | Occultation |
+|--------|--------------|-------------|
+| **Occulting body** | Moon | Moon |
+| **Occulted body** | Sun | Planet or star |
+| **Apparent size of occulted body** | ~0.5 degrees (large) | Tiny (stars are points; planets are a few arc-seconds to ~1 arc-minute) |
+| **Duration** | Minutes to hours | Seconds (stars) to ~1 hour (planets) |
+| **Visibility path** | Narrow, ~100-200 km | Can be wider or narrower depending on geometry |
+
+### Disappearance and reappearance
+
+When the Moon occults a star, two dramatic events occur:
+
+1. **Disappearance** (immersion, first contact): The star vanishes almost instantaneously as the Moon's leading edge passes over it. For a bright star, this is a striking sight -- one moment the star is shining, the next instant it is gone. Because the Moon has no atmosphere, there is no gradual fading.
+
+2. **Reappearance** (emersion, fourth contact): The star suddenly reappears from behind the Moon's trailing edge. If the Moon is a waxing crescent, the reappearance happens on the Moon's dark limb, making it particularly dramatic as the star seems to pop out of darkness.
+
+For planets, which have a measurable angular diameter, the disappearance and reappearance are not instantaneous but take several seconds as the Moon gradually covers and then uncovers the planetary disc.
+
+### Grazing occultations
+
+A **grazing occultation** occurs when the star passes very close to the Moon's edge (the limb). Because the Moon's limb is not perfectly smooth -- it has mountains, craters, and valleys -- the star may blink on and off multiple times as it passes behind mountain peaks and reappears in valleys. These events are scientifically valuable because they map the Moon's limb profile with high precision.
+
+### The contact points
+
+The result structure for occultations is the same as for solar eclipses:
+
+| Field | Description |
+|-------|-------------|
+| `first` / `firstContact` | Occultation begins (star/planet starts to disappear) |
+| `second` / `secondContact` | Complete disappearance (total occultation begins) |
+| `maximum` | Mid-occultation |
+| `third` / `thirdContact` | Reappearance begins (total occultation ends) |
+| `fourth` / `fourthContact` | Occultation fully ends (star/planet fully visible again) |
+
+For a star (which is a point source), second and third contacts coincide with first and fourth contacts respectively -- the star is either visible or it is not. The second/third contacts are more meaningful for planets with measurable apparent diameters.
+
+### The type bitmask
+
+Occultation results use the same type constants as solar eclipses:
+
+| Constant | Value | Meaning |
+|----------|-------|---------|
+| `SE_ECL_TOTAL` | 4 | The body is completely hidden by the Moon |
+| `SE_ECL_ANNULAR` | 8 | The Moon is smaller than the body (theoretically possible for very nearby planets, but extremely rare in practice) |
+| `SE_ECL_PARTIAL` | 16 | Only part of the body is covered |
+| `SE_ECL_CENTRAL` | 1 | The occultation has a central line across Earth |
+| `SE_ECL_NONCENTRAL` | 2 | No central line |
+
+### The `starname` parameter
+
+When searching for occultations of fixed stars:
+- Pass the star name as a string (e.g., `'Regulus'`, `'Aldebaran'`, `'Spica'`, `'Antares'`)
+- Set the `planet` parameter to `0`
+- The star name follows the same conventions as `swe.fixedStar()` -- you can use the traditional name, the Bayer designation, or a catalog number
+
+When searching for occultations of planets:
+- Pass the planet constant (e.g., `SE_JUPITER`, `SE_VENUS`)
+- Set `starname` to `null` (or omit it)
+
+### Attributes
+
+The occultation attributes are the same type as solar eclipse attributes (`EclipseAttributes`). The most relevant fields for occultations are:
+
+- `fraction`: How much of the occulted body's area is covered (1.0 for a total occultation of a star)
+- `magnitude`: How much of the occulted body's diameter is covered
+- `sarosCycle` / `sarosMember`: Saros series information (occultations also follow Saros-like cycles)
+
+### Historical importance of occultations
+
+Lunar occultations have played a crucial role in the history of astronomy:
+
+- **Navigation**: Before GPS and accurate clocks, sailors could determine their longitude by timing lunar occultations and comparing with predicted times in almanacs.
+- **Radio astronomy**: In the 1960s, lunar occultations of radio sources were one of the few ways to determine precise positions of radio-emitting objects. The occultation of the radio source 3C 273 in 1962 led to the identification of quasars.
+- **Lunar topography**: Grazing occultation observations contributed significantly to mapping the Moon's limb profile before space missions provided direct measurements.
+- **Stellar astronomy**: Thousands of close binary stars and stellar diameters have been measured through occultation timing, providing data that would be difficult or impossible to obtain by other means.
+
+### Tips
+
+- Occultation searches can be slower than eclipse searches because the Moon must be checked against specific planet/star positions rather than the Sun's predictable path.
+- When iterating through occultations, advance `jd` by at least 1 day past the previous result.
+- Not all global occultations are visible from any given location. Use `occultationLocal` to find events visible from your specific location.
+- The brightest stars that are regularly occulted by the Moon lie near the ecliptic: Aldebaran, Regulus, Spica, and Antares. These are the most commonly observed occultations.
+- Planetary occultations are rarer but more spectacular to observe, especially for bright planets like Venus and Jupiter.