@verifyhash/psychrometrics 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,185 @@
+# psychrometrics
+
+<!-- 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 `psychrometrics` as a placeholder — replace it
+> (and the `npm install` line below) with the real published name/scope before
+> running `npm publish`.
+
+A tiny, **zero-dependency** Node library for humidity and moist-air math:
+saturation vapour pressure, dew point, relative and absolute humidity, the NOAA
+heat index, and Stull's wet-bulb temperature.
+
+Every export is a **pure function**: no I/O, no network, no daemon, no
+dependencies, and no mutation of its arguments. The same inputs always give the
+same output. Everything is in SI-friendly units — degrees Celsius, percent RH,
+hectopascals (hPa == millibars), and grams per cubic metre.
+
+## Who it's for
+
+Developers building **HVAC**, **weather**, or **agriculture** tools who need
+reliable moist-air numbers without pulling in a large scientific package or
+hitting an API:
+
+- an HVAC/indoor-climate app converting between temperature, RH, and dew point;
+- a weather dashboard showing "feels like" (heat index) and wet-bulb stress;
+- an agriculture / greenhouse model tracking condensation risk (dew point) and
+  vapour density (absolute humidity).
+
+## Install / use
+
+Copy the folder in, or `require` it directly — there is nothing to install.
+
+```js
+const psy = require('./psychrometrics'); // path to this folder
+
+psy.dewPoint(30, 50);               // → 18.45  (°C)
+psy.saturationVaporPressure(20);    // → 23.33  (hPa)
+psy.heatIndex(32, 70);              // → 40.4   (°C, "feels like")
+psy.absoluteHumidity(20, 50);       // → 8.62   (g/m³)
+psy.wetBulb(20, 50);                // → 13.70  (°C)
+```
+
+## Run the tests
+
+One command, offline, no framework:
+
+```sh
+node test/psychrometrics.test.js
+```
+
+It exits `0` on success and prints `N passed, 0 failed`. (Or `npm test`.)
+
+## API
+
+All temperatures are **°C**, all relative humidity is **percent (0..100)**,
+vapour pressure is **hPa**, absolute humidity is **g/m³**.
+
+### `saturationVaporPressure(tempC) → hPa`
+
+Saturation vapour pressure of water over a flat liquid surface.
+
+- **Formula:** Magnus/Tetens form, `es = 6.1094 · exp(17.625·T / (243.04 + T))`,
+  using the Alduchov & Eskridge (1996) "AERK" coefficients (*J. Appl. Meteorol.*
+  35, 601–609).
+- **Accuracy:** better than **0.4 %** over roughly **−40 °C … +50 °C**.
+- **Caveats:** over ice (below 0 °C) the true saturation pressure is slightly
+  lower than this over-liquid value; if you need frost-point work, use an
+  over-ice coefficient set. Not valid far outside the fitted range.
+- Reference: `es(0 °C) = 6.1094 hPa`, `es(20 °C) ≈ 23.3 hPa`.
+
+### `dewPoint(tempC, rhPct) → °C`
+
+Temperature to which the air must cool (at constant pressure and water content)
+to reach saturation.
+
+- **Formula:** analytic Magnus inverse of `saturationVaporPressure`, with the
+  same AERK coefficients, so `dewPoint` and `relativeHumidity` are mutually
+  consistent.
+- **Domain:** `rhPct` in `[0, 100]`. At `100 %` the dew point equals the air
+  temperature; at `0 %` it is `-Infinity` (dry air never saturates on cooling).
+- **Accuracy:** inherits the < 0.4 % vapour-pressure fit; dew-point error is
+  typically a few hundredths of a degree versus an exact inversion.
+- Reference: `dewPoint(30, 50) ≈ 18.4 °C`.
+
+### `relativeHumidity(tempC, dewPointC) → %`
+
+Relative humidity from air temperature and dew point, as the ratio of
+saturation vapour pressure at the dew point to that at the air temperature.
+
+- **Formula:** `100 · es(dewPointC) / es(tempC)`.
+- **Round-trip:** `relativeHumidity(T, dewPoint(T, rh)) ≈ rh` to machine
+  precision (verified in the tests).
+- **Caveat:** returns **> 100** when `dewPointC > tempC` (supersaturation);
+  that is intentional, not clamped, so callers can detect bad/edge inputs.
+
+### `absoluteHumidity(tempC, rhPct) → g/m³`
+
+Mass of water vapour per cubic metre of air (vapour density).
+
+- **Formula:** ideal-gas law on the vapour partial pressure,
+  `AH = e / (Rv · T_K)` with `e = es(T)·RH/100` in Pa, `Rv = 461.5 J/(kg·K)`,
+  `T_K = T + 273.15`, result converted to g/m³.
+- **Domain:** `rhPct` in `[0, 100]`. Linear in RH at fixed temperature.
+- **Caveat:** treats vapour as an ideal gas (excellent at ambient conditions;
+  small errors near boiling). Independent of barometric pressure, since it is a
+  density, not a mixing ratio.
+- Reference: `absoluteHumidity(20, 100) ≈ 17.3 g/m³` (saturated 20 °C air).
+
+### `heatIndex(tempC, rhPct) → °C`
+
+Apparent "feels-like" temperature from heat and humidity.
+
+- **Formula:** NOAA/NWS **Rothfusz regression**. Computed internally in °F and
+  returned in °C. Matching the NWS reference implementation, it first tries the
+  simpler Steadman average; if that stays below **80 °F (≈ 27 °C)** the heat
+  index is essentially the air temperature and that value is returned.
+  Otherwise the full 9-term polynomial is applied, followed by the two
+  documented corrections — a **low-RH** subtraction (RH < 13 %, 80–112 °F) and a
+  **high-RH** addition (RH > 85 %, 80–87 °F).
+- **Valid range:** the regression is fit for **hot, humid** conditions, roughly
+  **T ≳ 27 °C** and **RH ≳ 40 %**. Outside that the returned value approaches the
+  air temperature and should be read as "no meaningful heat stress," not as a
+  precise apparent temperature. Heat index also assumes shade and light wind;
+  direct sun can add up to ~8 °C.
+- Reference: `heatIndex(32, 70) ≈ 40 °C` (well above the 32 °C air temperature).
+
+### `wetBulb(tempC, rhPct) → °C`
+
+Wet-bulb temperature: the lowest temperature reachable by evaporative cooling at
+the given humidity — a key metric for heat stress and cooling-tower design.
+
+- **Formula:** Stull (2011), *"Wet-Bulb Temperature from Relative Humidity and
+  Air Temperature"*, **J. Appl. Meteorol. Climatol. 50, 2267–2269**, an
+  empirical closed-form fit (no iteration).
+- **Valid range:** standard **sea-level pressure (1013.25 hPa)**, roughly
+  **−20 °C ≤ T ≤ 50 °C** and **5 % ≤ RH ≤ 99 %**, where it agrees with an exact
+  psychrometric solver to about **±1 °C**. Error grows at very low RH / very low
+  temperature.
+- **Caveat:** **not** altitude-corrected — at high elevation (lower pressure)
+  the true wet bulb is lower than this returns.
+- Reference: `wetBulb(20, 50) ≈ 13.7 °C` (Stull's worked example).
+
+## Domain guards
+
+Inputs are validated so unit mistakes fail loudly instead of silently
+producing garbage:
+
+- Every numeric argument must be a **finite number** or a `TypeError` is thrown.
+- `rhPct` must be within **`[0, 100]` percent** or a `RangeError` is thrown. The
+  library **throws rather than clamps** — a caller who accidentally passes a
+  `0..1` fraction (or a percentage over 100) finds out immediately. The test
+  suite covers this behaviour.
+
+## Honest limits
+
+- These are **standard engineering approximations**, not a full equation-of-state
+  psychrometric solver. For most HVAC/weather/agriculture work they are well
+  within measurement noise; for research-grade work near the edges of the stated
+  ranges, use a dedicated reference implementation.
+- Saturation is computed **over liquid water**; sub-freezing frost-point work
+  needs an over-ice variant.
+- `heatIndex` and `wetBulb` are empirical regressions valid in the ranges noted
+  above; outside them they degrade gracefully but are not authoritative.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `psychrometrics` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install psychrometrics
+```
+
+```js
+const psy = require('psychrometrics');
+
+psy.dewPoint(30, 50);  // 18.45  (°C)
+psy.heatIndex(32, 70); // 40.4   (°C, "feels like")
+psy.wetBulb(20, 50);   // 13.70  (°C)
+```

package/index.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * psychrometrics — zero-dependency humidity & moist-air math.
+ *
+ * Every export is a PURE function: no I/O, no network, no globals mutated, no
+ * arguments mutated, no dependencies. Given the same inputs it always returns
+ * the same output.
+ *
+ * The core saturation-vapour-pressure relation and its dew-point inverse use
+ * the Magnus form with the Alduchov & Eskridge (1996) "AERK" coefficients
+ * (a = 17.625, b = 243.04 °C, e0 = 6.1094 hPa), which fit water-vapour
+ * saturation to better than 0.4 % over roughly -40 °C .. +50 °C. Heat index
+ * follows the NOAA/NWS Rothfusz regression; wet-bulb follows Stull (2011).
+ * Sources are cited per-function below and in the README.
+ *
+ * UNITS (consistent throughout)
+ *   tempC, dewPointC   air / dew-point temperature in degrees Celsius
+ *   rhPct              relative humidity in percent, 0 .. 100
+ *   pressure           hectopascals (hPa, == millibars)
+ *   absolute humidity  grams of water vapour per cubic metre (g/m^3)
+ *
+ * DOMAIN GUARDS
+ *   All inputs must be finite numbers or a TypeError is thrown. Relative
+ *   humidity must be within [0, 100] or a RangeError is thrown (we throw rather
+ *   than silently clamp so a caller's unit bug — e.g. passing a 0..1 fraction —
+ *   surfaces immediately). See validateRh below.
+ */
+
+// ---------------------------------------------------------------------------
+// Magnus / Alduchov-Eskridge (1996) coefficients over liquid water.
+// es(T) = E0 * exp(A * T / (B + T)),  T in °C, es in hPa.
+// ---------------------------------------------------------------------------
+const A = 17.625;
+const B = 243.04; // °C
+const E0 = 6.1094; // hPa, saturation vapour pressure at 0 °C
+
+// Specific gas constant for water vapour, J/(kg·K).
+const RV = 461.5;
+const KELVIN = 273.15;
+
+// ---------------------------------------------------------------------------
+// Input validation helpers
+// ---------------------------------------------------------------------------
+function num(name, v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) {
+    throw new TypeError(`${name} must be a finite number, got ${v}`);
+  }
+  return v;
+}
+
+function validateRh(rhPct) {
+  num('rhPct', rhPct);
+  if (rhPct < 0 || rhPct > 100) {
+    throw new RangeError(
+      `rhPct must be in [0, 100] percent, got ${rhPct} ` +
+        '(note: this API uses percent, not a 0..1 fraction)'
+    );
+  }
+  return rhPct;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Saturation vapour pressure — Magnus/Tetens form (hPa)
+// ---------------------------------------------------------------------------
+/**
+ * Saturation vapour pressure of water in air, in hectopascals (hPa == mbar).
+ * Magnus formula with Alduchov & Eskridge (1996) coefficients over liquid
+ * water. Accurate to < 0.4 % across ~ -40 °C .. +50 °C.
+ *   es(20 °C) ≈ 23.34 hPa; es(0 °C) = 6.1094 hPa.
+ * @param {number} tempC air temperature, °C
+ * @returns {number} saturation vapour pressure, hPa
+ */
+function saturationVaporPressure(tempC) {
+  num('tempC', tempC);
+  return E0 * Math.exp((A * tempC) / (B + tempC));
+}
+
+// ---------------------------------------------------------------------------
+// 2. Dew point — Magnus inverse (°C)
+// ---------------------------------------------------------------------------
+/**
+ * Dew-point temperature: the temperature to which air must cool (at constant
+ * pressure and water content) to reach saturation. Magnus inverse.
+ *   dewPoint(30, 50) ≈ 18.45 °C.
+ * @param {number} tempC air temperature, °C
+ * @param {number} rhPct relative humidity, percent 0..100
+ * @returns {number} dew-point temperature, °C
+ */
+function dewPoint(tempC, rhPct) {
+  num('tempC', tempC);
+  validateRh(rhPct);
+  // RH of 0 has no finite dew point (dry air never saturates on cooling).
+  if (rhPct === 0) return -Infinity;
+  const alpha = Math.log(rhPct / 100) + (A * tempC) / (B + tempC);
+  return (B * alpha) / (A - alpha);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Relative humidity from temperature and dew point (%)
+// ---------------------------------------------------------------------------
+/**
+ * Relative humidity (%) from air temperature and dew point, as the ratio of
+ * saturation vapour pressure at the dew point to that at the air temperature.
+ * Inverse-consistent with dewPoint(): relativeHumidity(T, dewPoint(T, rh)) ≈ rh.
+ * @param {number} tempC air temperature, °C
+ * @param {number} dewPointC dew-point temperature, °C
+ * @returns {number} relative humidity, percent (may exceed 100 if dewPointC > tempC)
+ */
+function relativeHumidity(tempC, dewPointC) {
+  num('tempC', tempC);
+  num('dewPointC', dewPointC);
+  return (
+    100 *
+    (saturationVaporPressure(dewPointC) / saturationVaporPressure(tempC))
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 4. Absolute humidity — mass of vapour per unit volume (g/m^3)
+// ---------------------------------------------------------------------------
+/**
+ * Absolute humidity: mass of water vapour per cubic metre of air, in g/m^3.
+ * Derived from the ideal-gas law for the vapour partial pressure:
+ *   AH = e / (Rv · T_K),  e = es(T)·RH/100 (Pa), Rv = 461.5 J/(kg·K).
+ * At 20 °C / 50 % RH ≈ 8.6 g/m^3; saturated 20 °C air holds ≈ 17.3 g/m^3.
+ * @param {number} tempC air temperature, °C
+ * @param {number} rhPct relative humidity, percent 0..100
+ * @returns {number} absolute humidity, g/m^3
+ */
+function absoluteHumidity(tempC, rhPct) {
+  num('tempC', tempC);
+  validateRh(rhPct);
+  const ePa = saturationVaporPressure(tempC) * (rhPct / 100) * 100; // hPa -> Pa
+  const kgPerM3 = ePa / (RV * (tempC + KELVIN));
+  return kgPerM3 * 1000; // kg -> g
+}
+
+// ---------------------------------------------------------------------------
+// 5. Heat index — NOAA/NWS Rothfusz regression (returns °C)
+// ---------------------------------------------------------------------------
+/**
+ * Apparent temperature ("feels like") from heat and humidity, via the NOAA/NWS
+ * Rothfusz regression. Computed internally in °F, returned in °C.
+ *
+ * Method (matching the NWS reference implementation):
+ *   1. Try the simple Steadman average first. If it stays below 80 °F, that
+ *      value is the heat index (the full regression is only fit for hot,
+ *      humid conditions).
+ *   2. Otherwise apply the full Rothfusz polynomial, then the two documented
+ *      corrections: a low-RH subtraction (RH < 13 %, 80..112 °F) and a high-RH
+ *      addition (RH > 85 %, 80..87 °F).
+ *
+ * VALID RANGE: meaningful mainly for T ≳ 27 °C (80 °F) and RH ≳ 40 %. Below
+ * that the heat index ≈ air temperature and this returns the Steadman value.
+ * @param {number} tempC air temperature, °C
+ * @param {number} rhPct relative humidity, percent 0..100
+ * @returns {number} heat index (apparent temperature), °C
+ */
+function heatIndex(tempC, rhPct) {
+  num('tempC', tempC);
+  validateRh(rhPct);
+
+  const T = (tempC * 9) / 5 + 32; // °F
+  const R = rhPct;
+
+  // Steadman "simple" formula, averaged with the dry-bulb temperature.
+  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) {
+    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 ((hiF - 32) * 5) / 9; // °F -> °C
+}
+
+// ---------------------------------------------------------------------------
+// 6. Wet-bulb temperature — Stull (2011) approximation (°C)
+// ---------------------------------------------------------------------------
+/**
+ * Wet-bulb temperature via Stull's (2011) empirical fit,
+ *   "Wet-Bulb Temperature from Relative Humidity and Air Temperature",
+ *   J. Appl. Meteorol. Climatol. 50, 2267–2269.
+ * Valid at standard sea-level pressure (1013.25 hPa) for roughly
+ *   -20 °C ≤ T ≤ 50 °C and 5 % ≤ RH ≤ 99 %,
+ * where it agrees with an exact psychrometric solver to about ±1 °C (larger
+ * error at very low RH / very low T). Not corrected for altitude.
+ *   wetBulb(20, 50) ≈ 13.7 °C.
+ * @param {number} tempC air temperature, °C
+ * @param {number} rhPct relative humidity, percent 0..100
+ * @returns {number} wet-bulb temperature, °C
+ */
+function wetBulb(tempC, rhPct) {
+  num('tempC', tempC);
+  validateRh(rhPct);
+  const T = tempC;
+  const R = rhPct;
+  return (
+    T * Math.atan(0.151977 * Math.sqrt(R + 8.313659)) +
+    Math.atan(T + R) -
+    Math.atan(R - 1.676331) +
+    0.00391838 * Math.pow(R, 1.5) * Math.atan(0.023101 * R) -
+    4.686035
+  );
+}
+
+module.exports = {
+  saturationVaporPressure,
+  dewPoint,
+  relativeHumidity,
+  absoluteHumidity,
+  heatIndex,
+  wetBulb,
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@verifyhash/psychrometrics",
+  "version": "0.1.0",
+  "description": "Zero-dependency humidity & moist-air math: saturation vapour pressure, dew point, relative & absolute humidity, NOAA heat index, and Stull wet-bulb temperature.",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/psychrometrics.test.js"
+  },
+  "keywords": [
+    "psychrometrics",
+    "humidity",
+    "dew-point",
+    "relative-humidity",
+    "absolute-humidity",
+    "vapor-pressure",
+    "heat-index",
+    "wet-bulb",
+    "magnus",
+    "hvac",
+    "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": "psychrometrics"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/psychrometrics#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}