@verifyhash/wbgt-heat-stress 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,162 @@
+# wbgt-heat-stress
+
+<!-- publish-prep -->
+> **TODO (owner): pick the final npm name/scope before publishing.**
+> The npm package name is **not** finalized. `package.json` keeps the working
+> slug `wbgt-heat-stress` as a placeholder — replace it (and the install line
+> below) with the real published name/scope before any `npm publish`.
+> Graduation to npm is a **needs-human** decision, not something this project does.
+
+A tiny, **zero-dependency** Node library for the three most-used heat-stress
+indices, each returned with a plain-language **risk category**:
+
+- **`heatIndex(tempC, relHumidityPct)`** — the US National Weather Service
+  "feels-like" apparent temperature (Rothfusz regression).
+- **`humidex(tempC, dewpointC)`** — Environment Canada's humidex comfort index.
+- **`wbgt(tempC, relHumidityPct, opts)`** — a **Wet-Bulb Globe Temperature
+  approximation** with the white/green/yellow/red/black flag band.
+
+Every export is a **pure function**: no I/O, no network, no daemon, no
+dependencies, and no mutation of its arguments. Same inputs → same output.
+Units are Celsius, percent RH, and (for outdoor WBGT) m/s wind and W/m² solar.
+
+## Who it's for
+
+- **Occupational safety** — flag heat-stress risk for outdoor/industrial crews
+  against the WBGT flag conditions used by OSHA guidance and the US military.
+- **Sports & athletics** — apply the American College of Sports Medicine WBGT
+  activity bands for training and event go/no-go decisions.
+- **Weather & wellness apps** — show an honest "feels like" number (heat index
+  or humidex) without pulling in a heavy scientific package or calling an API.
+
+If you already have a psychrometrics library, this one is complementary: it
+focuses on the *stress indices and their risk bands*, not on general moist-air
+math.
+
+## Install / use
+
+Zero dependencies — vendor the folder or (after the owner finalizes the name)
+`npm install <final-name>`.
+
+```js
+const { heatIndex, humidex, wbgt, wbgtFlag } = require('wbgt-heat-stress');
+
+heatIndex(32.22, 70);
+// { heatIndexF: 105.9, heatIndexC: 41.1, risk: 'danger' }
+
+humidex(30, 15);
+// { humidex: 33.97, risk: 'some discomfort' }
+
+wbgt(30, 50);
+// { wbgtC: 29.26, flag: 'green', mode: 'indoor' }
+
+wbgt(30, 50, { solarWm2: 900, windMs: 1.5 });
+// { wbgtC: ~31.0, flag: 'yellow', mode: 'outdoor' }
+
+wbgtFlag(31.5); // 'red'  — band a WBGT you measured elsewhere
+```
+
+## Running the tests
+
+One command, no framework, no dependencies:
+
+```sh
+node test/index.test.js
+```
+
+It exits `0` on success and non-zero on any failure. The suite checks fixtures
+at published reference points — a NWS heat-index table cell, an Environment
+Canada humidex example, and every WBGT flag-band boundary — each within a stated
+tolerance, plus the input guards.
+
+## The formulas (and their sources)
+
+### Heat index — NWS/NOAA Rothfusz regression
+
+Apparent temperature from air temperature and relative humidity. The NWS first
+evaluates Steadman's simple formula; if that value is **below 80 °F (26.7 °C)**
+the Rothfusz regression does not apply and the simple value is used (the
+documented **low-temperature fallback** — below ~80 °F the heat index is
+essentially the air temperature). Otherwise the full Rothfusz polynomial runs,
+with the low-humidity (RH < 13 %) and high-humidity (RH > 85 %) corrections.
+This is the exact method behind the published NWS heat-index chart and is
+accurate to about **±1.3 °F**. Source: Rothfusz, L.P. (1990), *NWS Technical
+Attachment SR 90-23*; Steadman, R.G. (1979).
+
+Risk bands (NWS, °F): `none` < 80, `caution` 80–90, `extreme caution` 90–103,
+`danger` 103–124, `extreme danger` ≥ 124.
+
+### Humidex — Environment Canada
+
+```
+humidex = Tair + 0.5555 * (e - 10)
+e = 6.11 * exp(5417.7530 * (1/273.16 - 1/(Tdew + 273.15)))   [hPa]
+```
+
+Humidex is a unitless comfort index reported on the Celsius scale. When the dew
+point implies dry air (`e ≤ 10 hPa`) humidex would fall below the air
+temperature; Environment Canada does not report that, so the value is clamped to
+the air temperature. Source: Masterton, J.M. & Richardson, F.A. (1979),
+Environment Canada.
+
+Comfort bands (°C-scale): `none` < 30, `some discomfort` 30–39,
+`great discomfort` 40–45, `dangerous` ≥ 46.
+
+### WBGT — an APPROXIMATION (read this carefully)
+
+**True WBGT cannot be computed from air temperature and humidity alone.** The
+real index is `WBGT = 0.7·Tnwb + 0.2·Tg + 0.1·Ta`, where **Tg is the temperature
+of a 150 mm matte-black globe** in the actual sun/wind and **Tnwb is a naturally
+ventilated wet-bulb** — both require physical sensors. This library does **not**
+pretend to that accuracy. It provides two documented approximations:
+
+**Indoor / shaded (default).** The Australian Bureau of Meteorology simplified
+regression, valid where there is no direct solar load (indoors, or fully
+shaded):
+
+```
+WBGT = 0.567 * Ta + 0.393 * e + 3.94
+e    = (RH/100) * 6.105 * exp(17.27*Ta/(237.7 + Ta))   [hPa]
+```
+
+This is the standard substitute when no globe sensor is available and is what
+many heat-safety apps display for indoor/shaded conditions.
+
+**Outdoor (when you pass `opts.solarWm2`).** The shade estimate **plus a coarse
+solar-load term** — direct sun raises the globe temperature and hence WBGT,
+while wind ventilates the globe and lowers it:
+
+```
+dSolar = 3.2 * (solarWm2 / 1000) / sqrt(1 + windMs)   [°C], capped at 4 °C
+```
+
+so ~1000 W/m² midday sun in light wind adds a few °C, tapering with wind.
+
+**Honest limits.**
+- The outdoor `dSolar` term is a **rough heuristic, not a validated model**. It
+  is tuned to give plausible magnitudes, not sensor-grade accuracy. Do not use
+  outdoor mode as the sole basis for a real occupational go/no-go decision in
+  the sun — **measure with a black-globe WBGT meter** for that.
+- Even the indoor ABM regression carries its own scatter (order ~±1 °C) versus
+  instrumented readings and was fit for typical outdoor screen conditions.
+- Humidity must be a real measurement; a bad RH propagates directly into WBGT.
+- This library computes numbers and risk bands only. It is **not** a substitute
+  for an employer's heat-illness prevention program or medical judgement.
+
+Flag bands (US military / American College of Sports Medicine), °C converted
+from the canonical °F cut-points:
+
+| Flag   | WBGT (°C)   | WBGT (°F)   | Meaning                          |
+|--------|-------------|-------------|----------------------------------|
+| white  | < 27.8      | < 82.0      | low risk                         |
+| green  | 27.8 – 29.3 | 82.0 – 84.9 | use discretion, hydrate          |
+| yellow | 29.4 – 31.0 | 85.0 – 87.9 | active caution; limit exertion   |
+| red    | 31.1 – 32.1 | 88.0 – 89.9 | high risk; curtail hard activity |
+| black  | ≥ 32.2      | ≥ 90.0      | extreme; cancel/relocate         |
+
+`wbgtFlag(wbgtC)` is exported separately so you can band a WBGT you obtained
+from a real sensor.
+
+## License
+
+MIT — see `LICENSE`. (Copyright holder is a placeholder pending owner sign-off.)

package/index.js

@@ -0,0 +1,285 @@
+'use strict';
+
+/**
+ * wbgt-heat-stress — zero-dependency heat-stress indices.
+ *
+ * Three PURE functions (no I/O, no network, no globals mutated, no arguments
+ * mutated, no dependencies — same inputs always give the same output):
+ *
+ *   heatIndex(tempC, relHumidityPct)   NWS/NOAA "apparent temperature" (°C)
+ *   humidex(tempC, dewpointC)          Environment Canada humidex (°C-scale)
+ *   wbgt(tempC, relHumidityPct, opts)  Wet-Bulb Globe Temperature APPROXIMATION
+ *
+ * Each returns the index value AND, where the metric defines one, a risk
+ * category. `wbgt` returns { wbgtC, flag, mode }. A standalone `wbgtFlag`
+ * classifier is also exported so callers can band a WBGT they computed
+ * elsewhere (e.g. from a real black-globe sensor).
+ *
+ * UNITS
+ *   tempC, dewpointC   degrees Celsius
+ *   relHumidityPct     relative humidity, percent, 0..100
+ *   opts.windMs        10 m wind speed, metres/second (outdoor mode)
+ *   opts.solarWm2      global solar irradiance, W/m^2 (outdoor mode)
+ *
+ * SOURCES (also cited per-function and in README.md)
+ *   Heat index — Rothfusz, L.P. (1990), NWS Technical Attachment SR 90-23; the
+ *     regression the US National Weather Service publishes its heat-index table
+ *     from, with the low-humidity / high-humidity corrections and the Steadman
+ *     low-temperature fallback.
+ *   Humidex — Masterton & Richardson (1979), Environment Canada; e computed
+ *     from dew point with the WMO/Buck-style saturation relation Canada uses.
+ *   WBGT (shade) — the Australian Bureau of Meteorology simplified WBGT:
+ *     WBGT = 0.567*Ta + 0.393*e + 3.94, valid for shaded/indoor conditions.
+ *   WBGT flags — the WBGT flag-colour bands (white/green/yellow/red/black) used
+ *     by the US military and the American College of Sports Medicine.
+ */
+
+// ---------------------------------------------------------------------------
+// Input guards. Throw rather than silently coerce so a caller's unit bug
+// (e.g. passing RH as a 0..1 fraction) surfaces immediately.
+// ---------------------------------------------------------------------------
+function num(name, v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) {
+    throw new TypeError(`${name} must be a finite number, got ${String(v)}`);
+  }
+}
+
+function validateRh(rhPct) {
+  num('relHumidityPct', rhPct);
+  if (rhPct < 0 || rhPct > 100) {
+    throw new RangeError(
+      `relHumidityPct must be within [0, 100], got ${rhPct}`
+    );
+  }
+}
+
+const cToF = (c) => (c * 9) / 5 + 32;
+const fToC = (f) => ((f - 32) * 5) / 9;
+
+// ---------------------------------------------------------------------------
+// Saturation / actual vapour pressure helpers (hPa == millibars).
+// ---------------------------------------------------------------------------
+
+// Tetens-form saturation vapour pressure over water, as used by the Australian
+// Bureau of Meteorology alongside its simplified WBGT regression.
+// es(T) = 6.105 * exp(17.27 * T / (237.7 + T)),  T in °C, es in hPa.
+function satVapPressureBoM(tempC) {
+  return 6.105 * Math.exp((17.27 * tempC) / (237.7 + tempC));
+}
+
+// Saturation vapour pressure over water using the coefficient set Environment
+// Canada uses for humidex: e_sat(Td) = 6.11 * exp(5417.7530 * (1/273.16 - 1/T)),
+// T in kelvin. Evaluated at the dew point it gives the ACTUAL vapour pressure.
+function vapPressureHumidex(dewpointC) {
+  const Tk = dewpointC + 273.15;
+  return 6.11 * Math.exp(5417.753 * (1 / 273.16 - 1 / Tk));
+}
+
+// ---------------------------------------------------------------------------
+// 1) HEAT INDEX  (NWS/NOAA Rothfusz regression)
+// ---------------------------------------------------------------------------
+/**
+ * Apparent ("feels-like") temperature from air temperature and relative
+ * humidity, following the US National Weather Service.
+ *
+ * Method: the NWS first evaluates Steadman's simple formula. If that averaged
+ * value is < 80 °F the Rothfusz regression does not apply and the simple value
+ * is used (this is the documented LOW-TEMPERATURE FALLBACK — below roughly
+ * 26.7 °C / 80 °F the heat index is essentially the air temperature). Otherwise
+ * the full Rothfusz regression is used, with the low-humidity (RH < 13 %) and
+ * high-humidity (RH > 85 %) corrections. The regression is the basis of the
+ * published NWS heat-index chart and is accurate to about ±1.3 °F.
+ *
+ * @param {number} tempC          air temperature, °C
+ * @param {number} relHumidityPct relative humidity, percent 0..100
+ * @returns {{ heatIndexC:number, heatIndexF:number, risk:string }}
+ */
+function heatIndex(tempC, relHumidityPct) {
+  num('tempC', tempC);
+  validateRh(relHumidityPct);
+
+  const T = cToF(tempC); // °F
+  const R = relHumidityPct;
+
+  // Steadman "simple" apparent temperature, averaged with dry-bulb.
+  const simple = 0.5 * (T + 61.0 + (T - 68.0) * 1.2 + R * 0.094);
+  const avg = (simple + T) / 2;
+
+  let hiF;
+  if (avg < 80) {
+    // Low-temperature fallback: Rothfusz not valid here.
+    hiF = avg;
+  } else {
+    hiF =
+      -42.379 +
+      2.04901523 * T +
+      10.14333127 * R -
+      0.22475541 * T * R -
+      0.00683783 * T * T -
+      0.05481717 * R * R +
+      0.00122874 * T * T * R +
+      0.00085282 * T * R * R -
+      0.00000199 * T * T * R * R;
+
+    if (R < 13 && T >= 80 && T <= 112) {
+      hiF -= ((13 - R) / 4) * Math.sqrt((17 - Math.abs(T - 95)) / 17);
+    } else if (R > 85 && T >= 80 && T <= 87) {
+      hiF += ((R - 85) / 10) * ((87 - T) / 5);
+    }
+  }
+
+  return {
+    heatIndexF: hiF,
+    heatIndexC: fToC(hiF),
+    risk: heatIndexRisk(hiF),
+  };
+}
+
+// NWS heat-index caution bands (°F thresholds):
+//   < 80        none        (fallback region)
+//   80  – 90    caution
+//   90  – 103   extreme caution
+//   103 – 124   danger
+//   >= 124      extreme danger
+function heatIndexRisk(hiF) {
+  if (hiF < 80) return 'none';
+  if (hiF < 90) return 'caution';
+  if (hiF < 103) return 'extreme caution';
+  if (hiF < 124) return 'danger';
+  return 'extreme danger';
+}
+
+// ---------------------------------------------------------------------------
+// 2) HUMIDEX  (Environment Canada)
+// ---------------------------------------------------------------------------
+/**
+ * Canadian humidex from air temperature and dew point.
+ *
+ *   humidex = Tair + 0.5555 * (e - 10)
+ *   e = 6.11 * exp(5417.7530 * (1/273.16 - 1/(Td + 273.15)))   [hPa]
+ *
+ * Humidex is a unitless comfort index reported on the Celsius scale. If the
+ * dew point implies e <= 10 hPa (dry air) humidex is not defined above the air
+ * temperature, so we clamp to the air temperature (Environment Canada does not
+ * report a humidex below the air temperature).
+ *
+ * @param {number} tempC     air temperature, °C
+ * @param {number} dewpointC dew-point temperature, °C
+ * @returns {{ humidex:number, risk:string }}
+ */
+function humidex(tempC, dewpointC) {
+  num('tempC', tempC);
+  num('dewpointC', dewpointC);
+  if (dewpointC > tempC + 1e-9) {
+    throw new RangeError(
+      `dewpointC (${dewpointC}) cannot exceed tempC (${tempC})`
+    );
+  }
+
+  const e = vapPressureHumidex(dewpointC);
+  const h = tempC + 0.5555 * (e - 10);
+  const value = h < tempC ? tempC : h;
+
+  return { humidex: value, risk: humidexRisk(value) };
+}
+
+// Environment Canada humidex comfort bands (°C-scale):
+//   < 30    none / comfortable
+//   30 – 39 some discomfort
+//   40 – 45 great discomfort; avoid exertion
+//   >= 46   dangerous; heat stroke possible
+function humidexRisk(h) {
+  if (h < 30) return 'none';
+  if (h < 40) return 'some discomfort';
+  if (h < 46) return 'great discomfort';
+  return 'dangerous';
+}
+
+// ---------------------------------------------------------------------------
+// 3) WBGT  (Wet-Bulb Globe Temperature APPROXIMATION)
+// ---------------------------------------------------------------------------
+/**
+ * Approximate Wet-Bulb Globe Temperature.
+ *
+ * INDOOR / SHADED (default) — Australian Bureau of Meteorology regression:
+ *   WBGT = 0.567 * Ta + 0.393 * e + 3.94
+ *   e = (RH/100) * 6.105 * exp(17.27*Ta/(237.7+Ta))   [hPa]
+ * This needs only air temperature and humidity; it is the standard simple
+ * substitute when no black-globe sensor is available and there is no direct
+ * sun load (indoors, or fully shaded outdoors).
+ *
+ * OUTDOOR (opts.solarWm2 given) — the shade estimate PLUS a coarse solar-load
+ * term. Direct sun raises the globe temperature and hence WBGT; wind ventilates
+ * the globe and reduces it. This term is a rough heuristic, NOT a validated
+ * model — see the honest-limits note in README.md. The increment is:
+ *   dSolar = 3.2 * (solarWm2 / 1000) / sqrt(1 + windMs)   [°C], capped at 4 °C
+ * so full midday sun (~1000 W/m^2) in light wind adds a few °C, tapering with
+ * wind. For real occupational decisions in the sun, measure with a globe sensor.
+ *
+ * @param {number} tempC          air temperature, °C
+ * @param {number} relHumidityPct relative humidity, percent 0..100
+ * @param {object} [opts]
+ * @param {number} [opts.solarWm2] global solar irradiance, W/m^2 (enables outdoor)
+ * @param {number} [opts.windMs=1] wind speed, m/s (outdoor ventilation)
+ * @returns {{ wbgtC:number, flag:string, mode:'indoor'|'outdoor' }}
+ */
+function wbgt(tempC, relHumidityPct, opts) {
+  num('tempC', tempC);
+  validateRh(relHumidityPct);
+  const o = opts || {};
+
+  const e = (relHumidityPct / 100) * satVapPressureBoM(tempC);
+  let wbgtC = 0.567 * tempC + 0.393 * e + 3.94;
+  let mode = 'indoor';
+
+  if (o.solarWm2 !== undefined && o.solarWm2 !== null) {
+    num('opts.solarWm2', o.solarWm2);
+    if (o.solarWm2 < 0) {
+      throw new RangeError(`opts.solarWm2 must be >= 0, got ${o.solarWm2}`);
+    }
+    let wind = o.windMs === undefined || o.windMs === null ? 1 : o.windMs;
+    num('opts.windMs', wind);
+    if (wind < 0) {
+      throw new RangeError(`opts.windMs must be >= 0, got ${wind}`);
+    }
+    let dSolar = (3.2 * (o.solarWm2 / 1000)) / Math.sqrt(1 + wind);
+    if (dSolar > 4) dSolar = 4; // cap the heuristic
+    wbgtC += dSolar;
+    mode = 'outdoor';
+  }
+
+  return { wbgtC, flag: wbgtFlag(wbgtC), mode };
+}
+
+/**
+ * Classify a WBGT (°C) into the flag-colour band used by the US military and
+ * the American College of Sports Medicine. Boundaries (°C, converted from the
+ * canonical °F cut-points):
+ *
+ *   white   WBGT < 27.8 °C    (< 82.0 °F)   low
+ *   green   27.8 – 29.3 °C    (82.0–84.9 °F)
+ *   yellow  29.4 – 31.0 °C    (85.0–87.9 °F)
+ *   red     31.1 – 32.1 °C    (88.0–89.9 °F)
+ *   black   >= 32.2 °C        (>= 90.0 °F)   highest risk
+ *
+ * @param {number} wbgtC
+ * @returns {string} 'white' | 'green' | 'yellow' | 'red' | 'black'
+ */
+function wbgtFlag(wbgtC) {
+  num('wbgtC', wbgtC);
+  if (wbgtC >= 32.2) return 'black';
+  if (wbgtC >= 31.1) return 'red';
+  if (wbgtC >= 29.4) return 'yellow';
+  if (wbgtC >= 27.8) return 'green';
+  return 'white';
+}
+
+module.exports = {
+  heatIndex,
+  humidex,
+  wbgt,
+  wbgtFlag,
+  // low-level helpers, exported for testing / advanced use
+  heatIndexRisk,
+  humidexRisk,
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@verifyhash/wbgt-heat-stress",
+  "version": "0.1.0",
+  "description": "Zero-dependency heat-stress indices: NWS heat index, Environment Canada humidex, and a Wet-Bulb Globe Temperature (WBGT) approximation with risk flags.",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "keywords": [
+    "wbgt",
+    "wet-bulb-globe-temperature",
+    "heat-index",
+    "humidex",
+    "heat-stress",
+    "apparent-temperature",
+    "feels-like",
+    "occupational-safety",
+    "sports-safety",
+    "meteorology",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "wbgt-heat-stress"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/wbgt-heat-stress#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}