@verifyhash/koppen-classifier 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,152 @@
+# koppen-classifier
+
+<!-- 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 `koppen-classifier` 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 that assigns a location its
+**Köppen–Geiger climate class** (e.g. `Cfa`, `BWh`, `Dfb`) from twelve monthly
+mean temperatures and twelve monthly precipitation totals. Pure function, no
+network, no files, no state — give it numbers, get back a code.
+
+The classification logic is a direct port of the **proven** `koppenClass()`
+that has run in production on [weatherhack.com](https://weatherhack.com) to
+label real cities from ERA5 normals. It was lifted, not re-derived, so its
+boundaries match what that site already ships.
+
+## Who it's for
+
+Anyone who has monthly climate normals and wants the Köppen letter code without
+pulling in a heavy geodata package: map/dashboard builders, teaching material,
+data-pipeline enrichment, quiz/trivia generators, worldbuilding tools.
+
+## Install / use
+
+No install step for local use — it's one file with no dependencies. Copy the
+folder in, or `require('./koppen-classifier')`.
+
+```js
+const { classify } = require('koppen-classifier');
+
+// London, UK — monthly arrays run January → December.
+const london = classify({
+  tempsC:   [5.2, 5.3, 7.6, 9.6, 12.9, 16.0, 18.1, 17.8, 15.2, 11.4, 7.8, 5.5],
+  precipMm: [55, 41, 42, 44, 49, 45, 45, 50, 49, 69, 59, 55],
+  lat: 51.5,
+});
+
+console.log(london.code);       // 'Cfb'
+console.log(london.label);      // 'temperate oceanic'
+console.log(london.groupLabel); // 'Temperate'
+```
+
+## API
+
+### `classify(options) → result`
+
+**`options`**
+
+| field        | type       | required | notes |
+|--------------|------------|----------|-------|
+| `tempsC`     | `number[]` | yes      | 12 monthly **mean** temperatures in °C, **Jan → Dec**. |
+| `precipMm`   | `number[]` | yes      | 12 monthly precipitation totals in mm, **Jan → Dec**. |
+| `lat`        | `number`   | one of these | Signed latitude, north positive. Only its **sign** is used, to pick the warm half-year. |
+| `hemisphere` | `string`   | one of these | `'N'` / `'S'` (also `'north'` / `'south'`). Alternative to `lat`. |
+
+Provide **either** `lat` **or** `hemisphere`. If both are present, `lat` wins.
+Invalid input (arrays not length 12, non-finite numbers, no hemisphere given)
+throws a `TypeError` rather than returning a wrong answer.
+
+> Note: pass the monthly **mean** temperature. If your source has separate daily
+> highs and lows, average them first: `mean = (high + low) / 2`. That is exactly
+> what weatherhack does before calling the original function.
+
+**`result`** (a plain object)
+
+| field        | type     | example                | meaning |
+|--------------|----------|------------------------|---------|
+| `code`       | `string` | `'Cfb'`                | Köppen–Geiger class code. |
+| `label`      | `string` | `'temperate oceanic'`  | Human-readable class name. |
+| `group`      | `string` | `'C'`                  | Top-level group letter. |
+| `groupLabel` | `string` | `'Temperate'`          | Top-level group name (Tropical / Arid / Temperate / Continental / Polar). |
+| `blurb`      | `string` | `'A coldest month …'`  | One-sentence plain-language summary. |
+
+## What the algorithm actually does
+
+It applies the standard Köppen decision tree, tested in this order:
+
+1. **B (arid)** first, because aridity overrides temperature. The dryness
+   threshold is `P_th = 20·MAT + offset`, where the offset is **280** if ≥70% of
+   annual precipitation falls in the warm half-year, **140** if 30–70%, else
+   **0**. `BW` (desert) when annual precip `< ½·P_th`, otherwise `BS` (steppe);
+   the `h`/`k` split is at a mean annual temperature of **18 °C**.
+2. **A (tropical)** when the coldest month averages ≥ 18 °C (`Af`/`Am`/`Aw`/`As`).
+3. **E (polar)** when the warmest month is below 10 °C (`ET` tundra, `EF` ice cap).
+4. **C vs D** by the **0 °C coldest-month isotherm**, then a seasonal-precip
+   third letter (`f`/`s`/`w`) and a summer-heat fourth letter (`a`/`b`/`c`/`d`).
+
+The **warm half-year** is April–September in the northern hemisphere and
+October–March in the southern — this is why the hemisphere argument matters, and
+why a southern-hemisphere Mediterranean city (dry *December–February* summer)
+comes out `Cs…` rather than `Cw…`.
+
+### Honest limits
+
+- This is the common textbook variant of the boundaries. Other published
+  variants differ on edge rules (e.g. the exact aridity offset, or a 22 °C vs
+  0 °C `h`/`k` split, or the As/Aw threshold). Results near a boundary can
+  legitimately differ from other tools; this one matches weatherhack's output.
+- It classifies from the **12 monthly normals you supply**. Garbage or
+  non-representative normals in → wrong class out; it has no way to know your
+  inputs are unusual.
+- Southern/northern is derived purely from the sign of `lat` (or the
+  `hemisphere` string). Equatorial locations (`lat` ≈ 0) are treated as northern;
+  for tropical `A` climates the hemisphere choice rarely changes the code.
+- The four-letter `d` sub-code and some rare combinations are emitted but not
+  every one is covered by a named-city fixture in the test suite.
+
+## Tests
+
+One command, no framework, no dependencies:
+
+```
+node test/koppen.test.js
+```
+
+It checks known-city fixtures across every top-level group — London `Cfb`,
+Singapore `Af`, Cairo `BWh`, Moscow `Dfb`, Cape Town `Csb` (southern
+hemisphere), Utqiagvik `ET` (polar) — plus a hemisphere-flip case proving the
+`lat`/`hemisphere` argument changes the result, the return-shape contract, and
+input validation. Exit code is non-zero on any failure.
+
+## Status
+
+Incubator project — an npm-graduation **candidate**, not published. Promotion to
+a real package registry is a separate, human-approved step.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `koppen-classifier` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install koppen-classifier
+```
+
+```js
+const { classify } = require('koppen-classifier');
+
+const london = classify({
+  tempsC:   [5.2, 5.3, 7.6, 9.6, 12.9, 16.0, 18.1, 17.8, 15.2, 11.4, 7.8, 5.5],
+  precipMm: [55, 41, 42, 44, 49, 45, 45, 50, 49, 69, 59, 55],
+  lat: 51.5,
+});
+console.log(london.code); // 'Cfb'
+```

package/index.js

@@ -0,0 +1,167 @@
+'use strict';
+
+// koppen-classifier — a zero-dependency Köppen–Geiger climate classifier.
+//
+// Given a location's twelve monthly mean temperatures (°C) and twelve monthly
+// precipitation totals (mm), classify() returns the Köppen–Geiger climate code
+// (e.g. 'Cfa'), a human-readable label, and the top-level group.
+//
+// The decision tree is a straight port of the PROVEN koppenClass() used in
+// production on weatherhack.com (generate.cjs). The only adaptation is the
+// input shape: weatherhack passes daily-high/low pairs and takes the mean
+// internally as (hi+lo)/2; this library accepts the monthly MEAN temperature
+// directly (tempsC), which is the exact quantity the algorithm consumes. The
+// classification boundaries below are byte-for-byte identical to the source.
+
+// Human-readable names for the Köppen–Geiger codes we can emit. Codes not in
+// the table fall back to the raw code, so the classifier can never crash on an
+// unusual combination.
+const KOPPEN_NAMES = {
+  Af: 'tropical rainforest', Am: 'tropical monsoon',
+  Aw: 'tropical savanna (dry winter)', As: 'tropical savanna (dry summer)',
+  BWh: 'hot desert', BWk: 'cold desert',
+  BSh: 'hot semi-arid (steppe)', BSk: 'cold semi-arid (steppe)',
+  Csa: 'hot-summer Mediterranean', Csb: 'warm-summer Mediterranean', Csc: 'cold-summer Mediterranean',
+  Cwa: 'monsoon-influenced humid subtropical', Cwb: 'subtropical highland', Cwc: 'cold subtropical highland',
+  Cfa: 'humid subtropical', Cfb: 'temperate oceanic', Cfc: 'subpolar oceanic',
+  Dsa: 'Mediterranean-influenced hot-summer continental', Dsb: 'Mediterranean-influenced warm-summer continental',
+  Dsc: 'Mediterranean-influenced subarctic', Dsd: 'Mediterranean-influenced extremely cold subarctic',
+  Dwa: 'monsoon-influenced hot-summer continental', Dwb: 'monsoon-influenced warm-summer continental',
+  Dwc: 'monsoon-influenced subarctic', Dwd: 'monsoon-influenced extremely cold subarctic',
+  Dfa: 'hot-summer humid continental', Dfb: 'warm-summer humid continental',
+  Dfc: 'subarctic', Dfd: 'extremely cold subarctic',
+  ET: 'polar tundra', EF: 'polar ice cap',
+};
+
+// Top-level group (first letter of the code) → short name.
+const GROUP_NAMES = {
+  A: 'Tropical',
+  B: 'Arid',
+  C: 'Temperate',
+  D: 'Continental',
+  E: 'Polar',
+};
+
+function fmt1(n) {
+  return (Math.round(n * 10) / 10).toFixed(1);
+}
+
+// Resolve the hemisphere from the options. Accepts either `lat` (a signed
+// latitude in degrees, north positive) or `hemisphere` ('N'/'S', 'north'/
+// 'south', case-insensitive). `lat` wins if both are given. Returns true for
+// the northern hemisphere.
+function isNorth(opts) {
+  if (typeof opts.lat === 'number' && Number.isFinite(opts.lat)) {
+    return opts.lat >= 0;
+  }
+  if (opts.hemisphere != null) {
+    const h = String(opts.hemisphere).trim().toLowerCase();
+    if (h === 'n' || h === 'north' || h === 'northern') return true;
+    if (h === 's' || h === 'south' || h === 'southern') return false;
+    throw new TypeError(
+      `classify: unrecognised hemisphere ${JSON.stringify(opts.hemisphere)} (use 'N'/'S' or a numeric lat)`);
+  }
+  throw new TypeError("classify: provide either `lat` (number) or `hemisphere` ('N'/'S')");
+}
+
+function assert12(name, arr) {
+  if (!Array.isArray(arr) || arr.length !== 12) {
+    throw new TypeError(`classify: \`${name}\` must be an array of exactly 12 numbers`);
+  }
+  for (let i = 0; i < 12; i++) {
+    if (typeof arr[i] !== 'number' || !Number.isFinite(arr[i])) {
+      throw new TypeError(`classify: \`${name}[${i}]\` must be a finite number`);
+    }
+  }
+}
+
+/**
+ * Classify a location's Köppen–Geiger climate.
+ *
+ * @param {object}   opts
+ * @param {number[]} opts.tempsC     12 monthly MEAN temperatures in °C, Jan → Dec.
+ * @param {number[]} opts.precipMm   12 monthly precipitation totals in mm, Jan → Dec.
+ * @param {number}   [opts.lat]      Signed latitude (north positive). Used only for
+ *                                   its sign, to pick the warm half-year.
+ * @param {string}   [opts.hemisphere] 'N'/'S' (or 'north'/'south') — alternative to `lat`.
+ * @returns {{code:string, label:string, group:string, groupLabel:string, blurb:string}}
+ *   code       e.g. 'Cfa'
+ *   label      human-readable class name, e.g. 'humid subtropical'
+ *   group      top-level letter, e.g. 'C'
+ *   groupLabel top-level name,   e.g. 'Temperate'
+ *   blurb      one-sentence plain-language summary
+ */
+function classify(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('classify: expected an options object { tempsC, precipMm, lat|hemisphere }');
+  }
+  assert12('tempsC', opts.tempsC);
+  assert12('precipMm', opts.precipMm);
+  const north = isNorth(opts);
+
+  // T is the monthly mean temperature directly (weatherhack derives it as
+  // (hi+lo)/2 before this exact point). P is monthly precipitation in mm.
+  const T = opts.tempsC.slice();
+  const P = opts.precipMm.slice();
+
+  const MAT = T.reduce((a, b) => a + b, 0) / 12;
+  const Pann = P.reduce((a, b) => a + b, 0);
+  const Tcold = Math.min(...T);
+  const Twarm = Math.max(...T);
+  const nWarm10 = T.filter((t) => t >= 10).length;
+
+  const summerIdx = north ? [3, 4, 5, 6, 7, 8] : [9, 10, 11, 0, 1, 2];
+  const winterIdx = north ? [9, 10, 11, 0, 1, 2] : [3, 4, 5, 6, 7, 8];
+  const Psummer = summerIdx.reduce((a, i) => a + P[i], 0);
+  const summerShare = Pann > 0 ? Psummer / Pann : 0;
+  const Psmin = Math.min(...summerIdx.map((i) => P[i]));
+  const Psmax = Math.max(...summerIdx.map((i) => P[i]));
+  const Pwmin = Math.min(...winterIdx.map((i) => P[i]));
+  const Pwmax = Math.max(...winterIdx.map((i) => P[i]));
+  const Pmin = Math.min(...P);
+
+  const done = (code) => ({
+    code,
+    label: KOPPEN_NAMES[code] || code,
+    group: code[0],
+    groupLabel: GROUP_NAMES[code[0]] || code[0],
+    blurb: `A coldest month averaging ${fmt1(Tcold)} °C, a warmest month near ${fmt1(Twarm)} °C `
+      + `and about ${Math.round(Pann)} mm of precipitation across the year place it in the `
+      + `${KOPPEN_NAMES[code] || code} band.`,
+  });
+
+  // B (arid) is tested first — it overrides the temperature classes.
+  const offset = summerShare >= 0.7 ? 280 : summerShare >= 0.3 ? 140 : 0;
+  const Pth = 20 * MAT + offset;
+  if (Pann < Pth) {
+    return done('B' + (Pann < 0.5 * Pth ? 'W' : 'S') + (MAT >= 18 ? 'h' : 'k'));
+  }
+
+  // Fourth letter (summer heat) for C/D climates.
+  const heat = () =>
+    Twarm >= 22 ? 'a' : nWarm10 >= 4 ? 'b' : Tcold > -38 ? 'c' : 'd';
+  // Third letter (seasonal precipitation) for C/D climates.
+  const precip = () => {
+    const dryS = Psmin < 40 && Psmin < Pwmax / 3;      // dry summer
+    const dryW = Pwmin < Psmax / 10;                    // dry winter
+    if (dryS && !dryW) return 's';
+    if (dryW && !dryS) return 'w';
+    if (dryS && dryW) return Psmin <= Pwmin ? 's' : 'w';
+    return 'f';
+  };
+
+  // A (tropical): every month's mean ≥ 18 °C (coldest month ≥ 18).
+  if (Tcold >= 18) {
+    let third;
+    if (Pmin >= 60) third = 'f';
+    else if (Pmin >= 100 - Pann / 25) third = 'm';
+    else third = summerShare >= 0.5 ? 'w' : 's'; // dry season in winter → Aw
+    return done('A' + third);
+  }
+  // E (polar): warmest month below 10 °C.
+  if (Twarm < 10) return done(Twarm >= 0 ? 'ET' : 'EF');
+  // C / D by the 0 °C coldest-month isotherm.
+  return done((Tcold > 0 ? 'C' : 'D') + precip() + heat());
+}
+
+module.exports = { classify, KOPPEN_NAMES, GROUP_NAMES };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@verifyhash/koppen-classifier",
+  "version": "0.1.0",
+  "description": "Zero-dependency Köppen–Geiger climate classifier from 12 monthly mean-temperature and precipitation values (hemisphere-aware).",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/koppen.test.js"
+  },
+  "keywords": [
+    "koppen",
+    "koppen-geiger",
+    "climate",
+    "classification",
+    "weather",
+    "geography"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "koppen-classifier"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/koppen-classifier#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}