@verifyhash/moon-phase 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# moon-phase
+
+<!-- publish-prep -->
+> **TODO (owner): pick the final npm name/scope before publishing.**
+> The npm package name is **not** finalized by this project. Convention used here:
+> `package.json` keeps the working slug `moon-phase` as a placeholder — replace it
+> (and the `npm install` line below) with the real published name/scope before
+> running `npm publish`.
+
+A **zero-dependency, pure-function** Node library that turns any instant into the
+Moon's phase: its phase angle, the fraction of the disk that is lit, the synodic
+age in days, the canonical phase name, and the Brown lunation number.
+
+No network, no external dependencies, no servers, no I/O. Every export is a pure
+function of a single `Date` and never mutates its argument. `require()` it and go.
+
+```js
+const moon = require('./index.js');
+
+const d = new Date('2024-01-25T17:54:00Z'); // a full moon
+moon.phaseName(d);           // 'Full'
+moon.illuminatedFraction(d); // ~1.0
+moon.moonAge(d);             // ~14.75  (days since the last new moon)
+moon.moonPhaseAngle(d);      // ~179.85 (Sun-Moon elongation, degrees)
+moon.lunation(d);            // 1250    (Brown Lunation Number)
+```
+
+## Who it's for
+
+Developers who need the Moon's phase without pulling in a heavyweight ephemeris:
+
+- **Weather / almanac apps** — show tonight's phase and % illumination next to
+  the forecast.
+- **Astronomy & astrophotography planners** — a dark-sky (new moon) or
+  full-moon window finder, or a "how washed-out will the sky be" estimate.
+- **Tide and fishing tools** — spring/neap tides track the new/full syzygy, and
+  the phase angle is a cheap proxy for it.
+- **Calendar / UI widgets** — a correct moon glyph for any date.
+
+It is a *geocentric phase* model: it answers "what phase is the Moon in?", not
+"when does the Moon rise here?" or "where is it in my sky?". For observer-local
+rise/set/altitude you want a different tool (e.g. a full ephemeris).
+
+## API
+
+All functions take a JS `Date` interpreted as a **UTC instant** (date *and*
+time). The time of day matters: the Moon moves ~12°/day, so one hour shifts the
+elongation by ~0.5°. A date-only value like `new Date('2024-01-11')` is treated
+as `00:00 UTC` that day.
+
+| Function | Returns |
+| --- | --- |
+| `moonPhaseAngle(date)` | Sun-Moon elongation in degrees, `[0, 360)`. 0° = New, 90° = First Quarter, 180° = Full, 270° = Last Quarter. |
+| `illuminatedFraction(date)` | Fraction of the disk lit, `[0, 1]`. 0 at new, 1 at full, ~0.5 at the quarters. |
+| `moonAge(date)` | Days since the last new moon (synodic age), `[0, ~29.53)`. |
+| `phaseName(date)` | One of the 8 canonical phases: `New`, `Waxing Crescent`, `First Quarter`, `Waxing Gibbous`, `Full`, `Waning Gibbous`, `Last Quarter`, `Waning Crescent`. |
+| `lunation(date)` | Brown Lunation Number (integer) of the lunation in progress. |
+
+`phaseName` bins the elongation into eight 45°-wide sectors, each centred on its
+defining angle — so `New` covers 337.5°–360°–22.5°, `First Quarter` covers
+67.5°–112.5°, and so on. The narrow "instant" phases (New, the two quarters,
+Full) are the sectors straddling their exact angles.
+
+## Algorithm & citation
+
+The geometry follows **Jean Meeus, *Astronomical Algorithms* (2nd ed., 1998)**:
+
+1. Evaluate the Moon's mean elongation `D`, the Sun's mean anomaly `M`, and the
+   Moon's mean anomaly `M′` from the standard polynomials in Julian centuries
+   `T` from J2000.0 (Meeus ch. 47).
+2. Form the true Sun-Moon elongation by adding the leading periodic terms of the
+   phase-angle series (Meeus ch. 48, eq. 48.4 — the published "low accuracy"
+   method), giving the phase angle `i` and elongation `180° − i`.
+3. Illuminated fraction `k = (1 + cos i) / 2` (Meeus eq. 48.1).
+
+The synodic month is taken as `29.530588853` days (Meeus ch. 47). The Brown
+lunation number is anchored to the new moon of **2000-01-06 18:14 UTC**
+(Meeus lunation index `k = 0`), whose Brown Lunation Number is 953; Brown
+lunation 1 was the new moon of 1923-01-17.
+
+## Accuracy — honest limits
+
+This is a **simplified** model. It keeps only the largest periodic terms and no
+planetary perturbations, so:
+
+- **Phase angle / elongation:** within about **0.5°** of the full Meeus solution
+  for dates within a couple of centuries of J2000.
+- **Illuminated fraction:** within about **1%** — a few percent near a thin
+  crescent, where a 0.5° angle error has the most leverage.
+- **Synodic age (`moonAge`):** derived from the true elongation via the *mean*
+  synodic month, so it can drift up to roughly **0.5 day** from a true almanac
+  age, because the Moon's angular speed varies over its ~27.5-day anomalistic
+  (perigee/apogee) cycle. Treat it as good to a *fraction of a day*, not to the
+  minute.
+- **No topocentric / parallax correction:** this is the geocentric phase, which
+  is what "the phase of the Moon" almost always means.
+
+If you need to-the-minute event times (exact new/full moon instants) or a
+sky-position ephemeris, use a full-precision library instead. This one is for
+"what phase, how lit, how old, what's it called" — fast, dependency-free, and
+accurate enough for UI, planning, and forecasting overlays.
+
+## Tests
+
+Run the full suite (a tiny built-in assert harness — no framework, no deps):
+
+```
+node test/moon.test.js
+```
+
+It exits non-zero on any failure. Fixtures use published new/full/quarter-moon
+instants (NASA GSFC phase tables / timeanddate.com), and the suite also checks
+that illumination increases monotonically across the waxing half-lunation, that
+the phase-name bins are ordered and complete over a lunation, that inputs are not
+mutated, and that invalid input throws. Stated tolerances: 1.5° on the phase
+angle at a documented event, 0.02 on the illuminated fraction at the quarters,
+and 0.15 day on the synodic age.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `moon-phase` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install moon-phase
+```
+
+```js
+const moon = require('moon-phase');
+
+const d = new Date('2024-01-25T17:54:00Z'); // a full moon
+moon.phaseName(d);           // 'Full'
+moon.illuminatedFraction(d); // ~1.0
+moon.lunation(d);            // 1250 (Brown Lunation Number)
+```

package/index.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/**
+ * moon-phase — zero-dependency lunar phase & illumination math.
+ *
+ * Every export is a PURE function: no I/O, no network, no globals mutated, no
+ * argument mutation, no dependencies. It turns any instant (a UTC JS Date) into
+ * the Moon's phase angle, illuminated fraction, synodic age, canonical phase
+ * name, and Brown lunation number.
+ *
+ * ALGORITHM
+ *   The geometry follows Jean Meeus, "Astronomical Algorithms" (2nd ed., 1998),
+ *   chapter 49 (the mean elongation / mean-anomaly series) and chapter 48's
+ *   low-accuracy phase-angle formula (48.4). We evaluate the Moon's mean
+ *   elongation D, the Sun's mean anomaly M, and the Moon's mean anomaly M' from
+ *   the standard polynomials in Julian centuries T, then add the leading
+ *   periodic terms to obtain the true Sun-Moon elongation and phase angle. The
+ *   illuminated fraction is k = (1 + cos i) / 2 where i is the phase angle
+ *   (Meeus 48.1). This is the same "low accuracy" method NASA and many almanac
+ *   tools quote as good to a few tenths of a degree in phase angle.
+ *
+ * ACCURACY (honest limits — this is a SIMPLIFIED model)
+ *   - Phase angle / elongation: within ~0.5° of the full Meeus solution for
+ *     dates within a couple of centuries of J2000; it omits the smaller
+ *     periodic terms and all planetary perturbations.
+ *   - Illuminated fraction: within ~1% (a few percent near the thin crescent,
+ *     where a 0.5° angle error matters most).
+ *   - Synodic age (moonAge): derived from the true elongation via the MEAN
+ *     synodic month, so it can drift up to ~0.5 day from a true almanac age
+ *     because the Moon's angular speed varies with its ~27.5-day anomalistic
+ *     cycle (perigee/apogee). Treat it as good to a fraction of a day, not to
+ *     the minute.
+ *   - No topocentric / parallax correction: this is the GEOCENTRIC phase, which
+ *     is what "the phase of the Moon" almost always means. It is not a rise/set
+ *     or an observer-altitude calculation.
+ *
+ * INPUT
+ *   Every function takes a JS Date interpreted as a UTC INSTANT (date + time).
+ *   Unlike a daily sunrise calc, the time of day matters here: the Moon moves
+ *   ~12° per day, so an hour changes the elongation by ~0.5°. Passing a
+ *   date-only value like new Date('2024-01-11') is treated as 00:00 UTC that
+ *   day. Inputs are never mutated.
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+// Mean length of the synodic month (new moon to new moon), in days. Meeus 47.
+const SYNODIC_MONTH = 29.530588853;
+
+// Julian Day of the Unix epoch 1970-01-01T00:00:00Z.
+const JULIAN_UNIX_EPOCH = 2440587.5;
+const MS_PER_DAY = 86400000;
+
+// Reference new moon used for the Brown lunation number: the new moon of
+// 2000-01-06 at 18:14 UTC has Julian Day ~2451550.1 and is Meeus lunation
+// index k = 0 (Meeus 49.1). The Brown Lunation Number of that new moon is 953,
+// so BLN = floor(k) + 953. (Brown lunation 1 = the new moon of 1923-01-17.)
+const NEWMOON_2000_JD = 2451550.1;
+const BROWN_LUNATION_OFFSET = 953;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const rad = (d) => (d * Math.PI) / 180;
+const deg = (r) => (r * 180) / Math.PI;
+
+// Normalise degrees into [0, 360).
+function norm360(x) {
+  let r = x % 360;
+  if (r < 0) r += 360;
+  return r;
+}
+
+// Julian Day (including fractional day) for a JS Date instant. Does NOT mutate.
+function julianDay(date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+    throw new TypeError('moon-phase: expected a valid JS Date (UTC instant)');
+  }
+  return date.getTime() / MS_PER_DAY + JULIAN_UNIX_EPOCH;
+}
+
+// Meeus fundamental arguments (degrees) at Julian Day jd.
+// Returns { D, M, Mp } — Moon's mean elongation, Sun's mean anomaly, Moon's
+// mean anomaly. Polynomials from Meeus "Astronomical Algorithms" ch. 47.
+function fundamentalArguments(jd) {
+  const T = (jd - 2451545.0) / 36525; // Julian centuries from J2000.0
+
+  const D =
+    297.8501921 +
+    445267.1114034 * T -
+    0.0018819 * T * T +
+    (T * T * T) / 545868 -
+    (T * T * T * T) / 113065000;
+
+  const M =
+    357.5291092 +
+    35999.0502909 * T -
+    0.0001536 * T * T +
+    (T * T * T) / 24490000;
+
+  const Mp =
+    134.9633964 +
+    477198.8675055 * T +
+    0.0087414 * T * T +
+    (T * T * T) / 69699 -
+    (T * T * T * T) / 14712000;
+
+  return { D: norm360(D), M: norm360(M), Mp: norm360(Mp) };
+}
+
+// True Sun-Moon elongation (degrees) at Julian Day jd. This is the geocentric
+// angular distance Moon-from-Sun measured in the direction of the Moon's
+// motion: 0° = new, 90° = first quarter, 180° = full, 270° = last quarter.
+// It is 180° minus the Meeus phase angle (48.4).
+function elongationAtJD(jd) {
+  const { D, M, Mp } = fundamentalArguments(jd);
+  // Meeus 48.4 gives the phase angle i; elongation = 180 - i, so the sign of
+  // every periodic term flips relative to the i-formula.
+  const elong =
+    D +
+    6.289 * Math.sin(rad(Mp)) -
+    2.100 * Math.sin(rad(M)) +
+    1.274 * Math.sin(rad(2 * D - Mp)) +
+    0.658 * Math.sin(rad(2 * D)) +
+    0.214 * Math.sin(rad(2 * Mp)) +
+    0.110 * Math.sin(rad(D));
+  return norm360(elong);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * moonPhaseAngle(date) → the Sun-Moon elongation in degrees, in [0, 360).
+ * 0° = New, 90° = First Quarter, 180° = Full, 270° = Last Quarter. This is the
+ * "age angle" that drives phaseName() and moonAge().
+ */
+function moonPhaseAngle(date) {
+  return elongationAtJD(julianDay(date));
+}
+
+/**
+ * illuminatedFraction(date) → fraction of the Moon's disk that is lit, [0, 1].
+ * 0 at new moon, 1 at full moon, ~0.5 at the quarters. Uses k = (1 + cos i)/2
+ * with i the phase angle = 180° - elongation (Meeus 48.1).
+ */
+function illuminatedFraction(date) {
+  const elong = elongationAtJD(julianDay(date));
+  const i = 180 - elong; // phase angle in degrees
+  const k = (1 + Math.cos(rad(i))) / 2;
+  // Guard against tiny floating-point excursions outside [0, 1].
+  if (k < 0) return 0;
+  if (k > 1) return 1;
+  return k;
+}
+
+/**
+ * moonAge(date) → days since the last new moon (synodic age), in [0, ~29.53).
+ * Derived from the true elongation via the mean synodic month, so it is good to
+ * a fraction of a day (see ACCURACY note above), not to the minute.
+ */
+function moonAge(date) {
+  const elong = elongationAtJD(julianDay(date));
+  return (elong / 360) * SYNODIC_MONTH;
+}
+
+// The 8 canonical phases, in elongation order starting at New. Each occupies a
+// 45°-wide bin centred on its defining angle (New at 0°, First Quarter at 90°,
+// Full at 180°, Last Quarter at 270°). The narrow "instant" phases (New, the
+// quarters, Full) are the bins that straddle those exact angles.
+const PHASE_NAMES = [
+  'New',
+  'Waxing Crescent',
+  'First Quarter',
+  'Waxing Gibbous',
+  'Full',
+  'Waning Gibbous',
+  'Last Quarter',
+  'Waning Crescent',
+];
+
+/**
+ * phaseName(date) → one of the 8 canonical phase names (see PHASE_NAMES).
+ * Binned by elongation into 45° sectors, so the boundaries between, e.g.,
+ * "Waxing Crescent" and "First Quarter" fall at 67.5°, 112.5°, etc.
+ */
+function phaseName(date) {
+  const elong = elongationAtJD(julianDay(date));
+  // Shift by 22.5° so the New bin is centred on 0° (i.e. 337.5°..360°..22.5°).
+  const index = Math.floor(norm360(elong + 22.5) / 45) % 8;
+  return PHASE_NAMES[index];
+}
+
+/**
+ * lunation(date) → the Brown Lunation Number of the lunation in progress on the
+ * given date (integer). Brown lunation 1 began at the new moon of 1923-01-17;
+ * the new moon of 2000-01-06 is number 953. Accurate to the correct lunation
+ * for any date within a few centuries of J2000.
+ */
+function lunation(date) {
+  const jd = julianDay(date);
+  // Whole synodic months elapsed since the 2000-01-06 new moon. floor() gives
+  // the lunation currently in progress (the count increments at each new moon).
+  const k = Math.floor((jd - NEWMOON_2000_JD) / SYNODIC_MONTH);
+  return k + BROWN_LUNATION_OFFSET;
+}
+
+module.exports = {
+  moonPhaseAngle,
+  illuminatedFraction,
+  moonAge,
+  phaseName,
+  lunation,
+  // constants exposed for advanced use / testing
+  SYNODIC_MONTH,
+  // internals exposed for testing
+  _julianDay: julianDay,
+  _elongationAtJD: elongationAtJD,
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@verifyhash/moon-phase",
+  "version": "0.1.0",
+  "description": "Zero-dependency lunar phase & illumination math (simplified Meeus method): phase angle, illuminated fraction, synodic age, canonical phase name, and Brown lunation number for any UTC instant.",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/moon.test.js"
+  },
+  "keywords": [
+    "moon",
+    "lunar",
+    "moon-phase",
+    "illuminated-fraction",
+    "moon-age",
+    "synodic",
+    "lunation",
+    "meeus",
+    "astronomy",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "moon-phase"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/moon-phase#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}