@verifyhash/uv-index 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,158 @@
+# uv-index
+
+A **zero-dependency, network-free clear-sky UV-index estimator** for Node.js.
+
+Give it a place (latitude / longitude), a date and time, and — optionally — the
+total-column ozone and site elevation. It computes the sun's elevation angle and
+derives an approximate **clear-sky erythemal UV index (UVI)**, the matching
+**WHO/WMO exposure category** (Low / Moderate / High / Very High / Extreme), and
+a rough **burn-time** for fair skin.
+
+Everything runs locally with the Node standard library. No network calls, no npm
+dependencies, no API keys.
+
+## Who it's for
+
+Developers building **sun-safety**, **weather**, or **outdoor-planning** features
+who want a fast, offline estimate of "how strong will the sun be here, right now,
+if the sky is clear?" — for example:
+
+- a hiking / beach / gardening app that shades a timeline by UV strength,
+- a "reapply sunscreen" nudge that scales with the clear-sky UV ceiling,
+- a backfill for historical or future dates where no measured UVI feed exists,
+- a sanity bound to cross-check a measured/forecast UVI feed against.
+
+It is a **planning-grade ceiling**, not a sensor. If you need the *actual* UVI
+right now, use a measured feed (they capture the clouds and haze this model
+deliberately ignores).
+
+## Install / use
+
+No install step — it is a single self-contained module. Copy the `uv-index/`
+folder into your project and `require` it:
+
+```js
+const { estimateUVIndex } = require('./uv-index');
+
+const r = estimateUVIndex({
+  lat: 23.44,           // + North
+  lon: 0,               // + East
+  date: new Date('2023-06-21T12:00:00Z'), // a full UTC instant (date + time)
+  ozoneDU: 300,         // optional, total-column ozone in Dobson Units (default 300)
+  elevationM: 0,        // optional, site elevation in metres (default 0)
+  skinType: 'II',       // optional, Fitzpatrick I–VI for burn time (default 'II')
+});
+
+console.log(r);
+// {
+//   uvi: 12.499,               // continuous clear-sky UV index
+//   uviRounded: 12,            // rounded, as UVI is officially reported
+//   category: 'Extreme',       // WHO/WMO band
+//   solarElevationDeg: 89.6,   // sun altitude above the horizon
+//   sunAboveHorizon: true,
+//   burnTimeMinutes: 13,       // ~minutes of clear-sky sun to one MED (skin II)
+//   inputs: { lat: 23.44, lon: 0, ozoneDU: 300, elevationM: 0, skinType: 'II' }
+// }
+```
+
+`date` is interpreted as a **UTC instant** (both date and time-of-day matter —
+this is an instantaneous estimate, not a daily one). To model a specific local
+clock time, convert it to UTC first.
+
+### Other exports
+
+```js
+const {
+  estimateUVIndex, // the main estimator (above)
+  categoryFor,     // (uvi) -> { category, min, max }  — WHO band for a UVI value
+  burnTimeMinutes, // (uvi, skinType='II') -> minutes to one MED, or null at UVI 0
+  solarElevation,  // (lat, lon, Date) -> sun elevation in degrees (vendored math)
+} = require('./uv-index');
+```
+
+## How the number is built
+
+1. **Solar elevation** is computed with the NOAA solar-position algorithm
+   (Meeus-derived), **vendored into `lib/solar.js`** — see "Vendored solar math"
+   below. If the sun is at or below the horizon, UVI is exactly `0`.
+2. **Clear-sky UVI** from the elevation `h`:
+
+   ```
+   μ0  = sin(h)                     # = cos(solar zenith angle)
+   UVI = 12.5 · μ0^2.42 · (Ω/300)^(-1.23) · (1 + 0.06 · z_km)
+   ```
+
+   - `12.5` is the base coefficient tuned so an overhead sun at 300 DU ozone and
+     sea level peaks near the low-Extreme band, matching observed clear-sky
+     maxima of ~12 at sea level.
+   - `2.42` is a common empirical exponent for the erythemal (sunburn-weighted)
+     UV response versus solar elevation.
+   - `Ω` is total-column ozone in Dobson Units; the `-1.23` exponent is the
+     erythemal Radiation Amplification Factor (~1.2 fractional UV change per 1%
+     ozone; literature values span ~1.1–1.4).
+   - `z_km` is site elevation in km; `+6% per km` sits in the field-observed
+     ~5–10%/km range.
+3. **Category** maps the UVI (rounded to the nearest whole number, as UVI is
+   officially reported) to the WHO/WMO bands: `0–2 Low`, `3–5 Moderate`,
+   `6–7 High`, `8–10 Very High`, `11+ Extreme`.
+4. **Burn time** is the physical time to accumulate one Minimal Erythemal Dose
+   (MED) for the chosen Fitzpatrick skin type:
+   `t = MED / (UVI · 0.025 W/m² · 60 s)` minutes, using MED values of
+   200 / 250 / 350 / 450 / 600 / 1000 J/m² for skin types I–VI.
+
+## Honest limits — read this
+
+This is a **CLEAR-SKY model**. It answers "what is the sun's UV *ceiling* under a
+cloudless, clean sky?" and nothing more:
+
+- **No clouds.** Real clouds can cut UVI by 50%+ (or, with bright broken cloud,
+  briefly *raise* it slightly). This model never sees them, so on an overcast day
+  its number will read **too high**.
+- **No aerosols / haze / pollution.** Urban or smoky air absorbs UV; the model
+  ignores it and will overestimate in hazy conditions.
+- **No surface albedo boost.** Fresh snow (up to ~+90%), sand, and water reflect
+  UV upward; the model does not add that, so it can read **too low** on snow.
+- **The ozone and elevation terms are approximations.** The 300 DU reference, the
+  `-1.23` ozone exponent, and the `+6%/km` altitude factor are single-value
+  fits, not a radiative-transfer computation. Real ozone varies ~230–500 DU by
+  latitude and season; if you don't pass a value the model assumes 300 DU.
+- **Geometric sun angle, no refraction.** Near sunrise/sunset (elevation within
+  ~0.5° of the horizon) the true, refracted sun may be marginally higher than
+  the geometric elevation used here; the UV contribution there is negligible
+  anyway.
+- **Mid-latitude clear-sky peaks read on the high side.** Because there are no
+  clouds or aerosols, a clear-sky summer noon at ~50° latitude lands near the top
+  of the observed 7–9 window (this library returns ~9). That is the intended
+  clear-sky ceiling, not a typical measured value.
+- **Not medical advice.** Burn time is an order-of-magnitude physical estimate;
+  actual sunburn onset depends on sunscreen, reflection, medication, and
+  individual skin. **This is not a substitute for a measured UVI feed.**
+
+Use it for planning, shading UIs, and offline estimates — not for anything where
+being wrong by a few index points on a cloudy or hazy day matters.
+
+## Vendored solar math
+
+The solar-elevation geometry in `lib/solar.js` is a trimmed **copy** of the
+sibling `solar-calc` project in this incubator (`tools/solar-calc/index.js`,
+v0.1.0 — the `solarElevation` / NOAA `sunPosition` path). It is copied in on
+purpose so `uv-index` has **zero runtime dependencies** and never networks to or
+`require`s another package. Both are MIT-licensed and share the NOAA Global
+Monitoring Laboratory Solar Calculator algorithm.
+
+## Running the tests
+
+One command, no framework, no dependencies:
+
+```sh
+node test/index.test.js
+```
+
+The suite covers: sun below the horizon → UVI 0, a high-UVI low-latitude
+solar-noon case, a documented mid-latitude clear-sky band plus a winter contrast,
+WHO category boundaries, ozone/elevation correction direction, burn-time physics,
+and invalid-input rejection.
+
+## License
+
+MIT — see `LICENSE`.

package/index.js

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * uv-index — zero-dependency, network-free CLEAR-SKY UV-index estimator.
+ *
+ * Given a place (lat/lon), a date and time, and optionally the total-column
+ * ozone and site elevation, this estimates the clear-sky erythemal UV index,
+ * maps it to the WHO exposure category (Low / Moderate / High / Very High /
+ * Extreme), and gives a rough burn-time for fair skin.
+ *
+ * IT IS A CLEAR-SKY MODEL. There are no clouds, no aerosols/haze, no surface
+ * albedo (snow/water) boost, and the ozone & elevation terms are simple
+ * approximations. Treat the number as a clear-sky *ceiling*, not a measurement.
+ * See README.md → "Honest limits".
+ *
+ * Every export is a PURE function: no I/O, no network, no globals mutated, and
+ * ZERO runtime dependencies. The solar-elevation geometry is vendored in
+ * ./lib/solar.js (copied from the sibling solar-calc project, NOAA algorithm).
+ */
+
+const { solarElevation } = require('./lib/solar');
+
+const rad = (d) => (d * Math.PI) / 180;
+
+// Reference total-column ozone (Dobson Units) the base coefficient is tuned to.
+const REF_OZONE_DU = 300;
+// Radiation Amplification Factor for erythemal UV: a ~1.2 fractional drop in
+// UV per +1% ozone. Literature values cluster around 1.1–1.4; we use 1.23.
+const OZONE_RAF = 1.23;
+// Base coefficient: overhead sun (elevation 90°), 300 DU ozone, sea level.
+// Chosen so a tropical clear-sky solar noon peaks around the low-Extreme band,
+// consistent with observed clear-sky maxima of ~12 at sea level.
+const BASE_COEFF = 12.5;
+// Exponent on cos(zenith) = sin(elevation). ~2.4 is a common empirical fit for
+// the erythemal (sunburn-weighted) UV response versus solar elevation.
+const ELEV_EXPONENT = 2.42;
+// UV rises with altitude because there is less atmosphere overhead. Field
+// studies report ~5–10% more erythemal UV per 1000 m; we use 6%/km.
+const ALTITUDE_PER_KM = 0.06;
+
+// Minimal Erythemal Dose (J/m² of erythemally-weighted UV) by Fitzpatrick skin
+// type. Type II ("fair, usually burns") is the default guidance audience.
+const MED_BY_SKIN_TYPE = {
+  I: 200, // very fair, always burns
+  II: 250, // fair, usually burns
+  III: 350, // medium, sometimes burns
+  IV: 450, // olive, rarely burns
+  V: 600, // brown, very rarely burns
+  VI: 1000, // deeply pigmented, extremely rarely burns
+};
+
+// 1 UV-index unit == 0.025 W/m² of erythemally-weighted irradiance (WHO/WMO
+// definition). Energy accumulated per minute at index U = U*0.025*60 J/m².
+const WPM2_PER_UVI = 0.025;
+
+/**
+ * Map a UV index to its WHO/WMO exposure category. Categorisation uses the
+ * value ROUNDED to the nearest whole number, exactly as UVI is reported:
+ *   0–2 Low · 3–5 Moderate · 6–7 High · 8–10 Very High · 11+ Extreme.
+ * @param {number} uvi
+ * @returns {{category:string, min:number, max:number|null}}
+ */
+function categoryFor(uvi) {
+  if (!Number.isFinite(uvi) || uvi < 0) {
+    throw new TypeError('categoryFor: uvi must be a finite number >= 0');
+  }
+  const r = Math.round(uvi);
+  if (r <= 2) return { category: 'Low', min: 0, max: 2 };
+  if (r <= 5) return { category: 'Moderate', min: 3, max: 5 };
+  if (r <= 7) return { category: 'High', min: 6, max: 7 };
+  if (r <= 10) return { category: 'Very High', min: 8, max: 10 };
+  return { category: 'Extreme', min: 11, max: null };
+}
+
+/**
+ * Approximate minutes of clear-sky exposure to reach one Minimal Erythemal Dose
+ * (the onset of visible sunburn) for a given Fitzpatrick skin type. Returns
+ * null when UVI is 0 (no meaningful burn risk).
+ *
+ *   t = MED / (UVI * 0.025 W/m² * 60 s)   [minutes]
+ *
+ * This is a physical order-of-magnitude figure, NOT medical advice; real burn
+ * onset depends on sunscreen, reflection, medication and individual skin.
+ *
+ * @param {number} uvi
+ * @param {'I'|'II'|'III'|'IV'|'V'|'VI'} [skinType='II']
+ * @returns {number|null} minutes, rounded to the nearest minute, or null
+ */
+function burnTimeMinutes(uvi, skinType = 'II') {
+  if (!Number.isFinite(uvi) || uvi < 0) {
+    throw new TypeError('burnTimeMinutes: uvi must be a finite number >= 0');
+  }
+  const med = MED_BY_SKIN_TYPE[skinType];
+  if (med === undefined) {
+    throw new TypeError(
+      `burnTimeMinutes: unknown skinType "${skinType}" (use I–VI)`
+    );
+  }
+  if (uvi === 0) return null;
+  const minutes = med / (uvi * WPM2_PER_UVI * 60);
+  return Math.round(minutes);
+}
+
+/**
+ * Estimate the CLEAR-SKY UV index and derived guidance for a place and moment.
+ *
+ * @param {Object} opts
+ * @param {number} opts.lat            latitude in degrees, + North  [-90, 90]
+ * @param {number} opts.lon            longitude in degrees, + East  [-180, 180]
+ * @param {Date}   opts.date           a full JS Date instant (UTC-based)
+ * @param {number} [opts.ozoneDU=300]  total-column ozone in Dobson Units
+ * @param {number} [opts.elevationM=0] site elevation above sea level, metres
+ * @param {'I'|'II'|'III'|'IV'|'V'|'VI'} [opts.skinType='II'] for burn time
+ * @returns {{
+ *   uvi:number, uviRounded:number, category:string,
+ *   solarElevationDeg:number, sunAboveHorizon:boolean,
+ *   burnTimeMinutes:number|null,
+ *   inputs:{lat:number,lon:number,ozoneDU:number,elevationM:number,skinType:string}
+ * }}
+ */
+function estimateUVIndex(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('estimateUVIndex: expected an options object');
+  }
+  const {
+    lat,
+    lon,
+    date,
+    ozoneDU = REF_OZONE_DU,
+    elevationM = 0,
+    skinType = 'II',
+  } = opts;
+
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+    throw new TypeError('estimateUVIndex: date must be a valid JS Date');
+  }
+  if (!Number.isFinite(ozoneDU) || ozoneDU <= 0) {
+    throw new TypeError('estimateUVIndex: ozoneDU must be a positive number');
+  }
+  if (!Number.isFinite(elevationM) || elevationM < 0) {
+    throw new TypeError('estimateUVIndex: elevationM must be >= 0');
+  }
+  // solarElevation validates lat/lon and throws on out-of-range values.
+  const elevationDeg = solarElevation(lat, lon, date);
+
+  let uvi = 0;
+  const sunAboveHorizon = elevationDeg > 0;
+  if (sunAboveHorizon) {
+    const mu0 = Math.sin(rad(elevationDeg)); // cos(zenith) = sin(elevation)
+    const base = BASE_COEFF * Math.pow(mu0, ELEV_EXPONENT);
+    const ozoneFactor = Math.pow(ozoneDU / REF_OZONE_DU, -OZONE_RAF);
+    const altitudeFactor = 1 + ALTITUDE_PER_KM * (elevationM / 1000);
+    uvi = base * ozoneFactor * altitudeFactor;
+    if (uvi < 0) uvi = 0; // numerical guard; the model is non-negative already
+  }
+
+  const uviRounded = Math.round(uvi);
+  return {
+    uvi,
+    uviRounded,
+    category: categoryFor(uvi).category,
+    solarElevationDeg: elevationDeg,
+    sunAboveHorizon,
+    burnTimeMinutes: burnTimeMinutes(uvi, skinType),
+    inputs: { lat, lon, ozoneDU, elevationM, skinType },
+  };
+}
+
+module.exports = {
+  estimateUVIndex,
+  categoryFor,
+  burnTimeMinutes,
+  solarElevation,
+  // constants exposed for advanced use / testing
+  MED_BY_SKIN_TYPE,
+  REF_OZONE_DU,
+};

package/lib/solar.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * solar.js — VENDORED solar-elevation math.
+ *
+ * This is a trimmed, self-contained copy of the solar-position geometry from
+ * the sibling `solar-calc` project in this incubator (tools/solar-calc,
+ * index.js). It is COPIED IN ON PURPOSE so uv-index has ZERO runtime
+ * dependencies and never reaches over the network or requires another package.
+ *
+ * PINNED SOURCE: tools/solar-calc/index.js @ v0.1.0 (the `instantaneous` /
+ * `solarElevation` path, plus the NOAA `sunPosition` helper it depends on).
+ *
+ * The geometry follows the algorithm published by NOAA's Global Monitoring
+ * Laboratory Solar Calculator (https://gml.noaa.gov/grad/solcalc/), a
+ * simplified form of Jean Meeus, "Astronomical Algorithms" (2nd ed.).
+ *
+ * Only the pieces uv-index needs are kept: solarElevation(lat, lon, Date).
+ * Everything is a pure function — no I/O, no globals mutated, no deps.
+ */
+
+// Trig helpers (JS Math is in radians; the NOAA formulas are in degrees).
+const rad = (d) => (d * Math.PI) / 180;
+const deg = (r) => (r * 180) / Math.PI;
+
+const MS_PER_DAY = 86400000;
+const JULIAN_UNIX_EPOCH = 2440587.5; // Julian Day of 1970-01-01T00:00:00Z
+
+// Julian Day for a given UTC-millisecond instant.
+function julianDay(ms) {
+  return ms / MS_PER_DAY + JULIAN_UNIX_EPOCH;
+}
+
+// Julian centuries since the J2000.0 epoch (JD 2451545.0).
+function julianCentury(jd) {
+  return (jd - 2451545) / 36525;
+}
+
+// Sun declination (degrees) and equation of time (minutes) for century T.
+function sunPosition(t) {
+  let l0 = (280.46646 + t * (36000.76983 + t * 0.0003032)) % 360;
+  if (l0 < 0) l0 += 360;
+
+  const m = 357.52911 + t * (35999.05029 - 0.0001537 * t);
+  const e = 0.016708634 - t * (0.000042037 + 0.0000001267 * t);
+
+  const c =
+    Math.sin(rad(m)) * (1.914602 - t * (0.004817 + 0.000014 * t)) +
+    Math.sin(rad(2 * m)) * (0.019993 - 0.000101 * t) +
+    Math.sin(rad(3 * m)) * 0.000289;
+
+  const trueLong = l0 + c;
+  const omega = 125.04 - 1934.136 * t;
+  const lambda = trueLong - 0.00569 - 0.00478 * Math.sin(rad(omega));
+
+  const seconds = 21.448 - t * (46.815 + t * (0.00059 - t * 0.001813));
+  const e0 = 23 + (26 + seconds / 60) / 60;
+  const obliq = e0 + 0.00256 * Math.cos(rad(omega));
+
+  const declination = deg(
+    Math.asin(Math.sin(rad(obliq)) * Math.sin(rad(lambda)))
+  );
+
+  const y = Math.tan(rad(obliq / 2)) ** 2;
+  const eqTime =
+    4 *
+    deg(
+      y * Math.sin(2 * rad(l0)) -
+        2 * e * Math.sin(rad(m)) +
+        4 * e * y * Math.sin(rad(m)) * Math.cos(2 * rad(l0)) -
+        0.5 * y * y * Math.sin(4 * rad(l0)) -
+        1.25 * e * e * Math.sin(2 * rad(m))
+    );
+
+  return { declination, eqTime };
+}
+
+/**
+ * Solar elevation (altitude) in degrees above the horizon for a given instant.
+ * Positive = above the horizon. GEOMETRIC elevation of the Sun's centre; it
+ * does not add atmospheric refraction, so values very near 0° differ from an
+ * apparent, refracted horizon by up to ~0.5°.
+ *
+ * @param {number} lat  latitude in degrees, + North
+ * @param {number} lon  longitude in degrees, + East
+ * @param {Date}   date a full JS Date instant (date + time, interpreted in UTC)
+ * @returns {number} elevation in degrees (can be negative when below horizon)
+ */
+function solarElevation(lat, lon, date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+    throw new TypeError('solar.js: solarElevation needs a valid JS Date instant');
+  }
+  if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+    throw new TypeError('solar.js: lat must be a number in [-90, 90]');
+  }
+  if (!Number.isFinite(lon) || lon < -180 || lon > 180) {
+    throw new TypeError('solar.js: lon must be a number in [-180, 180]');
+  }
+
+  const ms = date.getTime();
+  const { declination: decl, eqTime } = sunPosition(
+    julianCentury(julianDay(ms))
+  );
+
+  const dayStart = Date.UTC(
+    date.getUTCFullYear(),
+    date.getUTCMonth(),
+    date.getUTCDate()
+  );
+  const utcMinutes = (ms - dayStart) / 60000;
+
+  let trueSolarTime = (utcMinutes + eqTime + 4 * lon) % 1440;
+  if (trueSolarTime < 0) trueSolarTime += 1440;
+
+  let hourAngle = trueSolarTime / 4 - 180;
+  if (hourAngle < -180) hourAngle += 360;
+
+  const cosZenith =
+    Math.sin(rad(lat)) * Math.sin(rad(decl)) +
+    Math.cos(rad(lat)) * Math.cos(rad(decl)) * Math.cos(rad(hourAngle));
+  const zenith = deg(Math.acos(Math.max(-1, Math.min(1, cosZenith))));
+  return 90 - zenith;
+}
+
+module.exports = { solarElevation, _sunPosition: sunPosition };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@verifyhash/uv-index",
+  "version": "0.1.0",
+  "description": "Zero-dependency, network-free clear-sky UV-index estimator: solar-elevation-driven UVI, WHO exposure category, and burn-time guidance from lat/lon/date/time (+ optional ozone and elevation).",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "keywords": [
+    "uv-index",
+    "uvi",
+    "ultraviolet",
+    "clear-sky",
+    "sun-safety",
+    "sunburn",
+    "erythemal",
+    "solar-elevation",
+    "who-uv",
+    "weather",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "lib/solar.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "uv-index"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/uv-index#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}