@verifyhash/climate-normals 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,218 @@
+# climate-normals
+
+<!-- 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 `climate-normals` 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 of climate math over **monthly
+normals** — heating/cooling degree-days, apparent ("feels like") temperature,
+diurnal range, a continentality index, and a monthly pleasantness score.
+
+Every export is a **pure function**: no I/O, no network, no dependencies, no
+mutation of its arguments. The formulas are lifted verbatim from the proven
+[weatherhack](../../weatherhack) page generator (`generate.cjs`) — this package
+is the shared engine those city pages already use, extracted so other tools can
+reuse the exact same, already-validated math rather than reinventing it.
+
+## Who it's for
+
+- Building weather/climate pages, dashboards, or "best time to visit" tools and
+  wanting energy-demand, comfort, and climate-character numbers from a simple
+  12-month normals table.
+- Anyone who needs the standard NWS Heat Index / Wind Chill or the standard
+  base-18 °C degree-day accounting as small, testable functions.
+
+It is **not** a forecasting library and not a substitute for a metered energy
+audit or published frost dates: it works on long-term monthly *averages*, so it
+cannot capture an individual hot-and-humid afternoon, a cold-and-windy night, or
+a late-spring frost. Use it for climatology, not day-level prediction.
+
+## Install / use
+
+No install step, no dependencies. Copy the folder in and require it:
+
+```js
+const climate = require('./climate-normals');
+```
+
+### The month object
+
+A "normal" is one month's long-term average. The canonical shape is:
+
+| field | meaning | unit | used by |
+|-------|---------|------|---------|
+| `hi`  | average daily **high** temperature | °C | all temperature functions |
+| `lo`  | average daily **low** temperature  | °C | all temperature functions |
+| `pr`  | average monthly **precipitation**  | mm | `pleasantnessScore` / `rankMonths` |
+| `rh`  | average **relative humidity**      | %  | `apparentTemperature` (heat index) |
+| `ws`  | average **wind speed**             | m/s | `apparentTemperature` (wind chill) |
+
+A month may omit fields a given function doesn't read. Functions that summarise
+a whole year take a `months` array of **exactly 12** entries in calendar order
+(index 0 = January).
+
+## API
+
+### `degreeDays(months, base = 18)`
+
+Heating (HDD) and cooling (CDD) degree-days for a year.
+
+For each month, with `mean = (hi + lo) / 2` and `days = DAYS_IN_MONTH[i]`
+(non-leap: `[31,28,31,30,31,30,31,31,30,31,30,31]`):
+
+```
+HDD = max(0, base - mean) × days
+CDD = max(0, mean - base) × days
+```
+
+summed over the 12 months. `base` defaults to **18 °C** — the point below which
+buildings typically need heating and above which they need cooling. Degree-days
+track roughly with heating and air-conditioning energy use.
+
+Returns `{ rows, hdd, cdd, dominated }`: `rows[i] = { i, mean, hdd, cdd }` with
+**raw (unrounded)** per-month degree-days; `hdd`/`cdd` are the **rounded** annual
+totals (unitless °C·days); `dominated` is `'heating'` or `'cooling'` (ties count
+as heating).
+
+```js
+climate.degreeDays(london).hdd; // 2360  (base 18 °C)
+```
+
+### `heatIndex(tC, rh)` → °C
+
+NWS **Heat Index** (Rothfusz regression). Apparent temperature for air
+temperature `tC` (°C) and relative humidity `rh` (%). The regression is defined
+in °F, so the function converts in and out; below ~80 °F it uses the NWS simple
+linear estimate, and it applies the NWS low-humidity (`rh < 13`) and
+high-humidity (`rh > 85`) adjustment terms. Humidity can only make warm air feel
+hotter. Example: `heatIndex(30.3, 86.8) ≈ 40.8 °C`.
+
+### `windChill(tC, ws)` → °C
+
+NWS **Wind Chill** (2001 revision). Apparent temperature for air temperature
+`tC` (°C) and wind speed `ws` (m/s). Internally works in °C and km/h
+(`km/h = ws × 3.6`); it is only defined above ~4.8 km/h, so at lower wind the air
+temperature is returned unchanged, and the result is clamped to never read warmer
+than `tC` (wind only makes cold air feel colder). Example:
+`windChill(0, 10) ≈ -7.1 °C`.
+
+### `apparentTemperature(month, opts?)`
+
+Combines a month's temperature with its humidity and/or wind, exactly as the
+weatherhack "feels like" section does:
+
+- **feelsHi** = `heatIndex(hi, rh)` when `rh` is present **and** `hi ≥ warmThreshold`
+  (default **27 °C**) **and** the heat index reads hotter than `hi`; otherwise `hi`.
+- **feelsLo** = `windChill(lo, ws)` when `ws` is present **and** `lo ≤ coldThreshold`
+  (default **10 °C**) **and** the wind chill reads colder than `lo`; otherwise `lo`.
+
+`opts` may override `{ warmThreshold, coldThreshold }` (°C). Returns
+`{ feelsHi, feelsLo, hiMode, loMode, dHot, dCold }` where `hiMode`/`loMode` are
+`'actual'` or `'heat'`/`'wind'`, `dHot = feelsHi - hi` (≥0 °C, how much hotter
+humidity makes the day) and `dCold = lo - feelsLo` (≥0 °C, how much colder wind
+makes the night). With neither `rh` nor `ws`, it simply restates the thermometer.
+
+### `diurnalRange(months)`
+
+Day-to-night temperature swing across the year. For each month `swing = hi - lo`
+(°C). Returns `{ swings, annual, big, small }`: `swings` is the 12 monthly
+swings, `annual` is their mean (°C), and `big`/`small` are the month indices of
+the largest and smallest swing (first month wins ties). Big swings are typical of
+dry, continental, or high-altitude places; small swings of humid coastal ones.
+
+### `continentality(months)`
+
+Annual mean-temperature range and its continentality class. The warmest month is
+the one with the highest average daily **high**, the coldest the one with the
+lowest average daily **low**; the **range** is the difference between those two
+months' **mean** daily temperatures (`(hi + lo) / 2`), rounded to one decimal °C.
+Classification:
+
+| range (°C) | `klass` |
+|------------|---------|
+| `< 10`         | `maritime / oceanic` |
+| `10 – 20` (inclusive) | `transitional / moderately continental` |
+| `> 20`         | `continental` |
+
+Returns `{ warm, cold, warmMean, coldMean, range, klass }` (`warm`/`cold` are
+month indices; `warmMean`/`coldMean`/`range` are °C).
+
+### `pleasantnessScore(month)`
+
+Comfort score for a single month — **lower is more comfortable**. With
+`mean = (hi + lo) / 2`:
+
+```
+tempPenalty = mean < 18 ? 18 - mean : mean > 24 ? mean - 24 : 0
+rainPenalty = (pr ?? 0) × 0.03      // ≈100 mm ~ being 3 °C off the band
+score       = tempPenalty + rainPenalty
+```
+
+The comfort band is **18–24 °C** mean daily temperature; a month inside it with
+no rain scores 0. Returns `{ mean, tempPenalty, rainPenalty, score }` (mean in
+°C; penalties/score are unitless heuristic points). This is a deliberately simple,
+transparent heuristic, not a physiological comfort model.
+
+### `rankMonths(months)`
+
+Ranks a 12-month year from most to least pleasant using `pleasantnessScore`.
+Returns `{ scored, ranked }`: `scored[i]` adds `{ i }` to each month's score
+object; `ranked` is an array of month indices, best-first (ties keep calendar
+order).
+
+### Constants
+
+Exported for reference and reuse: `DAYS_IN_MONTH`, `HDD_BASE` (18),
+`COMFORT_LO` (18), `COMFORT_HI` (24), `RAIN_PENALTY_PER_MM` (0.03),
+`FEELS_WARM_HI` (27), `FEELS_COLD_LO` (10), and the helper `meanTemp(month)`.
+
+## Running the tests
+
+One command, from this directory:
+
+```
+node test/index.test.js
+```
+
+It prints one `ok - …` line per test and exits **0** when all pass, non-zero on
+the first failure (via `node:assert`). The suite has no dependencies and makes no
+network calls. It covers every function with a real-city fixture (London and
+Singapore 2020–2024 ERA5 normals) plus edge cases: all-cold and all-warm cities,
+custom degree-day bases, the continentality threshold boundaries, missing
+humidity/wind, missing precipitation, tie-breaking, and input-mutation checks.
+
+## Provenance
+
+Formulas ported from `weatherhack/generate.cjs`:
+`degreeDays()`, `heatIndexC()` / `windChillC()` / `feelsLikeStats()`,
+`diurnalStats()`, `annualRangeStats()`, and `bestTimeToVisit()`'s comfort
+heuristic (`comfortScore()`). The normals fixtures come from weatherhack's ERA5
+2020–2024 dataset. No math was invented here.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `climate-normals` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install climate-normals
+```
+
+```js
+const climate = require('climate-normals');
+
+const july = { hi: 23.5, lo: 14.0, pr: 45, rh: 65, ws: 3.2 };
+climate.meanTemp(july);            // 18.75  (°C, midpoint of hi/lo)
+climate.apparentTemperature(july); // { feelsHi, feelsLo, hiMode, loMode, ... }
+climate.pleasantnessScore(july);   // { mean, tempPenalty, rainPenalty, score }
+
+// Whole-year helpers take a 12-element array (index 0 = January):
+// climate.degreeDays(months).hdd → heating degree-days (base 18 °C)
+```

package/index.js

@@ -0,0 +1,338 @@
+'use strict';
+
+/**
+ * climate-normals — zero-dependency climate math over monthly normals.
+ *
+ * Every export here is a PURE function: no I/O, no network, no globals mutated.
+ * The formulas are lifted verbatim from the proven weatherhack generator
+ * (weatherhack/generate.cjs), not reinvented — see README.md for the exact
+ * source function each one ports.
+ *
+ * A "normal" is one month's long-term average. The canonical month object is:
+ *   { hi, lo, pr, rh, ws }
+ *     hi  — average daily HIGH temperature, °C
+ *     lo  — average daily LOW temperature, °C
+ *     pr  — average monthly PRECIPITATION, mm        (pleasantness only)
+ *     rh  — average RELATIVE HUMIDITY, %             (apparent-temp only)
+ *     ws  — average WIND SPEED, m/s                  (apparent-temp only)
+ * Functions only read the fields they document; a month may omit the rest.
+ *
+ * "months" arrays are expected in calendar order (index 0 = January). Functions
+ * that summarise a whole year require exactly 12 entries.
+ */
+
+// ---------------------------------------------------------------------------
+// Documented constants (match generate.cjs)
+// ---------------------------------------------------------------------------
+
+// Non-leap days per month (Feb = 28). Degree-day totals are climatological
+// estimates, so the leap-day rounding is immaterial. (generate.cjs L902)
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+// Default degree-day base temperature, °C (generate.cjs HDD_BASE, L911).
+const HDD_BASE = 18;
+
+// Comfort band, °C mean daily temperature, for the pleasantness heuristic
+// (generate.cjs COMFORT_LO / COMFORT_HI, L507).
+const COMFORT_LO = 18;
+const COMFORT_HI = 24;
+
+// Rain penalty per mm for the pleasantness heuristic (generate.cjs L520:
+// `v.pr * 0.03`) — ~100 mm costs about as much as being 3 °C off the band.
+const RAIN_PENALTY_PER_MM = 0.03;
+
+// Thresholds that decide when humidity / wind are worth folding into the
+// apparent temperature (generate.cjs FEELS_WARM_HI / FEELS_COLD_LO, L1691).
+const FEELS_WARM_HI = 27; // avg high (°C) at/above which the heat index applies
+const FEELS_COLD_LO = 10; // avg low  (°C) at/below which wind chill applies
+
+// ---------------------------------------------------------------------------
+// Small internal helpers
+// ---------------------------------------------------------------------------
+
+function requireMonths(months, needFull) {
+  if (!Array.isArray(months)) {
+    throw new TypeError('months must be an array');
+  }
+  if (needFull && months.length !== 12) {
+    throw new RangeError('months must have exactly 12 entries (one per calendar month)');
+  }
+  return months;
+}
+
+function num(x, field) {
+  if (typeof x !== 'number' || !Number.isFinite(x)) {
+    throw new TypeError('month.' + field + ' must be a finite number');
+  }
+  return x;
+}
+
+/**
+ * Mean daily temperature of a month = (hi + lo) / 2, in °C.
+ * (generate.cjs uses `(v.hi + v.lo) / 2` throughout.)
+ */
+function meanTemp(month) {
+  return (num(month.hi, 'hi') + num(month.lo, 'lo')) / 2;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Heating & cooling degree-days   (ports degreeDays(), generate.cjs L912)
+// ---------------------------------------------------------------------------
+
+/**
+ * Heating & cooling degree-days for a year of monthly normals.
+ *
+ * For each month, with mean = (hi + lo) / 2 and days = DAYS_IN_MONTH[i]:
+ *   HDD = max(0, base - mean) × days
+ *   CDD = max(0, mean - base) × days
+ * summed over the year. Base defaults to 18 °C — the point below which
+ * buildings typically need heating and above which they need cooling.
+ *
+ * @param {Array<{hi:number,lo:number}>} months  exactly 12 months, Jan..Dec
+ * @param {number} [base=18]  base temperature, °C
+ * @returns {{rows:Array<{i:number,mean:number,hdd:number,cdd:number}>,
+ *            hdd:number, cdd:number, dominated:'heating'|'cooling'}}
+ *          rows hold per-month raw (unrounded) degree-days; hdd/cdd are the
+ *          rounded annual totals; `dominated` is whichever total is larger
+ *          (ties count as heating, matching generate.cjs `hdd >= cdd`).
+ */
+function degreeDays(months, base = HDD_BASE) {
+  requireMonths(months, true);
+  if (typeof base !== 'number' || !Number.isFinite(base)) {
+    throw new TypeError('base must be a finite number');
+  }
+  let hddTotal = 0;
+  let cddTotal = 0;
+  const rows = months.map((v, i) => {
+    const mean = meanTemp(v);
+    const days = DAYS_IN_MONTH[i];
+    const hdd = Math.max(0, base - mean) * days;
+    const cdd = Math.max(0, mean - base) * days;
+    hddTotal += hdd;
+    cddTotal += cdd;
+    return { i, mean, hdd, cdd };
+  });
+  const hdd = Math.round(hddTotal);
+  const cdd = Math.round(cddTotal);
+  return { rows, hdd, cdd, dominated: hdd >= cdd ? 'heating' : 'cooling' };
+}
+
+// ---------------------------------------------------------------------------
+// 2. Apparent temperature  (ports heatIndexC/windChillC/feelsLikeStats,
+//    generate.cjs L1658 / L1680 / L1708)
+// ---------------------------------------------------------------------------
+
+/**
+ * NWS Heat Index (Rothfusz regression). Returns the apparent ("feels like")
+ * temperature in °C for air temperature `tC` (°C) and relative humidity
+ * `rh` (%). The regression is defined in °F, so we convert in and out. Below
+ * ~80 °F the simpler linear estimate is used; the low-/high-humidity
+ * adjustments match the NWS reference implementation. (generate.cjs L1658)
+ */
+function heatIndex(tC, rh) {
+  num(tC, 'tC');
+  num(rh, 'rh');
+  const T = tC * 9 / 5 + 32; // °F
+  let hiF = 0.5 * (T + 61 + (T - 68) * 1.2 + rh * 0.094);
+  if ((hiF + T) / 2 >= 80) {
+    hiF = -42.379 + 2.04901523 * T + 10.14333127 * rh
+      - 0.22475541 * T * rh - 0.00683783 * T * T - 0.05481717 * rh * rh
+      + 0.00122874 * T * T * rh + 0.00085282 * T * rh * rh
+      - 0.00000199 * T * T * rh * rh;
+    if (rh < 13 && T >= 80 && T <= 112) {
+      hiF -= ((13 - rh) / 4) * Math.sqrt((17 - Math.abs(T - 95)) / 17);
+    } else if (rh > 85 && T >= 80 && T <= 87) {
+      hiF += ((rh - 85) / 10) * ((87 - T) / 5);
+    }
+  }
+  return (hiF - 32) * 5 / 9;
+}
+
+/**
+ * NWS wind chill (2001 revision). Returns the apparent temperature in °C for
+ * air temperature `tC` (°C) and wind speed `ws` (m/s). The formula works in
+ * °C and km/h and is only defined above ~4.8 km/h, so below that the air
+ * temperature is returned unchanged; wind can only make cold air feel colder,
+ * so the result is never warmer than `tC`. (generate.cjs L1680)
+ */
+function windChill(tC, ws) {
+  num(tC, 'tC');
+  num(ws, 'ws');
+  const V = ws * 3.6; // m/s -> km/h
+  if (V < 4.8) return tC;
+  const p = Math.pow(V, 0.16);
+  const wc = 13.12 + 0.6215 * tC - 11.37 * p + 0.3965 * tC * p;
+  return Math.min(wc, tC);
+}
+
+/**
+ * Apparent ("feels like") daily high and low for one month of normals,
+ * combining temperature with humidity and/or wind exactly as feelsLikeStats()
+ * does (generate.cjs L1723-1737):
+ *   - feelsHi = heatIndex(hi, rh)  when rh is present AND hi >= warmThreshold
+ *               AND the heat index reads hotter than hi; else hi.
+ *   - feelsLo = windChill(lo, ws)  when ws is present AND lo <= coldThreshold
+ *               AND the wind chill reads colder than lo; else lo.
+ *
+ * @param {{hi:number,lo:number,rh?:number,ws?:number}} month
+ * @param {{warmThreshold?:number, coldThreshold?:number}} [opts]
+ * @returns {{feelsHi:number, feelsLo:number,
+ *            hiMode:'actual'|'heat', loMode:'actual'|'wind',
+ *            dHot:number, dCold:number}}
+ *          dHot = feelsHi - hi (≥0, how much hotter humidity makes the day);
+ *          dCold = lo - feelsLo (≥0, how much colder wind makes the night).
+ */
+function apparentTemperature(month, opts = {}) {
+  const warm = opts.warmThreshold == null ? FEELS_WARM_HI : opts.warmThreshold;
+  const cold = opts.coldThreshold == null ? FEELS_COLD_LO : opts.coldThreshold;
+  const hi = num(month.hi, 'hi');
+  const lo = num(month.lo, 'lo');
+  let feelsHi = hi;
+  let feelsLo = lo;
+  let hiMode = 'actual';
+  let loMode = 'actual';
+  if (typeof month.rh === 'number' && Number.isFinite(month.rh) && hi >= warm) {
+    const hi2 = heatIndex(hi, month.rh);
+    if (hi2 > hi) { feelsHi = hi2; hiMode = 'heat'; }
+  }
+  if (typeof month.ws === 'number' && Number.isFinite(month.ws) && lo <= cold) {
+    const lo2 = windChill(lo, month.ws);
+    if (lo2 < lo) { feelsLo = lo2; loMode = 'wind'; }
+  }
+  return { feelsHi, feelsLo, hiMode, loMode, dHot: feelsHi - hi, dCold: lo - feelsLo };
+}
+
+// ---------------------------------------------------------------------------
+// 3. Diurnal range   (ports diurnalStats(), generate.cjs L1111)
+// ---------------------------------------------------------------------------
+
+/**
+ * Day-to-night temperature swing across a year of monthly normals.
+ * For each month swing = hi - lo (°C); `annual` is the mean of the 12 swings;
+ * `big`/`small` are the indices of the largest and smallest swings.
+ * (First month wins ties, matching generate.cjs strict `>` / `<`.)
+ *
+ * @param {Array<{hi:number,lo:number}>} months  exactly 12 months, Jan..Dec
+ * @returns {{swings:number[], annual:number, big:number, small:number}}
+ */
+function diurnalRange(months) {
+  requireMonths(months, true);
+  const swings = [];
+  let big = 0;
+  let small = 0;
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    const sw = num(months[i].hi, 'hi') - num(months[i].lo, 'lo');
+    swings.push(sw);
+    sum += sw;
+    if (sw > swings[big]) big = i;
+    if (sw < swings[small]) small = i;
+  }
+  return { swings, annual: sum / 12, big, small };
+}
+
+// ---------------------------------------------------------------------------
+// 4. Continentality  (ports annualRangeStats(), generate.cjs L373)
+// ---------------------------------------------------------------------------
+
+/**
+ * Annual mean-temperature range and its continentality classification.
+ * The warmest month is the one with the highest average daily HIGH and the
+ * coldest the one with the lowest average daily LOW; the range is the
+ * difference between those two months' MEAN daily temperatures, rounded to
+ * one decimal °C. Classification thresholds (generate.cjs L388-397):
+ *   range < 10        → 'maritime / oceanic'
+ *   10 <= range <= 20 → 'transitional / moderately continental'
+ *   range > 20        → 'continental'
+ *
+ * @param {Array<{hi:number,lo:number}>} months  exactly 12 months, Jan..Dec
+ * @returns {{warm:number, cold:number, warmMean:number, coldMean:number,
+ *            range:number, klass:string}}
+ */
+function continentality(months) {
+  requireMonths(months, true);
+  for (let i = 0; i < 12; i++) {
+    num(months[i].hi, 'hi');
+    num(months[i].lo, 'lo');
+  }
+  let warm = 0;
+  let cold = 0;
+  for (let i = 1; i < 12; i++) {
+    if (months[i].hi > months[warm].hi) warm = i;
+    if (months[i].lo < months[cold].lo) cold = i;
+  }
+  const warmMean = (months[warm].hi + months[warm].lo) / 2;
+  const coldMean = (months[cold].hi + months[cold].lo) / 2;
+  const range = Math.round((warmMean - coldMean) * 10) / 10;
+  let klass;
+  if (range < 10) klass = 'maritime / oceanic';
+  else if (range <= 20) klass = 'transitional / moderately continental';
+  else klass = 'continental';
+  return { warm, cold, warmMean, coldMean, range, klass };
+}
+
+// ---------------------------------------------------------------------------
+// 5. Monthly pleasantness score  (ports bestTimeToVisit()'s heuristic /
+//    comfortScore(), generate.cjs L516-521 / L2181)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pleasantness (comfort) score for a single month. LOWER is more comfortable.
+ *   mean        = (hi + lo) / 2
+ *   tempPenalty = mean < 18 ? 18 - mean : mean > 24 ? mean - 24 : 0
+ *   rainPenalty = pr * 0.03            (pr defaults to 0 when absent)
+ *   score       = tempPenalty + rainPenalty
+ * A month sitting inside the 18–24 °C band with no rain scores 0.
+ *
+ * @param {{hi:number,lo:number,pr?:number}} month
+ * @returns {{mean:number, tempPenalty:number, rainPenalty:number, score:number}}
+ */
+function pleasantnessScore(month) {
+  const mean = meanTemp(month);
+  const tempPenalty = mean < COMFORT_LO ? COMFORT_LO - mean
+    : mean > COMFORT_HI ? mean - COMFORT_HI : 0;
+  let pr = 0;
+  if (month.pr != null) pr = num(month.pr, 'pr');
+  const rainPenalty = pr * RAIN_PENALTY_PER_MM;
+  return { mean, tempPenalty, rainPenalty, score: tempPenalty + rainPenalty };
+}
+
+/**
+ * Rank a year of months from most to least pleasant (ascending score).
+ * Stable-ish: ties keep calendar order because Array.prototype.sort is stable
+ * in Node and we sort a mapped copy. Returns per-month scored rows plus the
+ * ranked index order.
+ *
+ * @param {Array<{hi:number,lo:number,pr?:number}>} months  exactly 12 months
+ * @returns {{scored:Array<{i:number,mean:number,tempPenalty:number,
+ *            rainPenalty:number,score:number}>, ranked:number[]}}
+ *          `ranked` is month indices best-first.
+ */
+function rankMonths(months) {
+  requireMonths(months, true);
+  const scored = months.map((v, i) => Object.assign({ i }, pleasantnessScore(v)));
+  const ranked = scored.slice().sort((a, b) => a.score - b.score).map((x) => x.i);
+  return { scored, ranked };
+}
+
+module.exports = {
+  // constants
+  DAYS_IN_MONTH,
+  HDD_BASE,
+  COMFORT_LO,
+  COMFORT_HI,
+  RAIN_PENALTY_PER_MM,
+  FEELS_WARM_HI,
+  FEELS_COLD_LO,
+  // helpers
+  meanTemp,
+  // functions
+  degreeDays,
+  heatIndex,
+  windChill,
+  apparentTemperature,
+  diurnalRange,
+  continentality,
+  pleasantnessScore,
+  rankMonths,
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@verifyhash/climate-normals",
+  "version": "0.1.0",
+  "description": "Zero-dependency climate math over monthly normals: heating/cooling degree-days, apparent (\"feels like\") temperature, diurnal range, a continentality index, and a monthly pleasantness score.",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "keywords": [
+    "climate",
+    "climate-normals",
+    "degree-days",
+    "heating-degree-days",
+    "cooling-degree-days",
+    "apparent-temperature",
+    "heat-index",
+    "wind-chill",
+    "continentality",
+    "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": "climate-normals"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/climate-normals#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}