@verifyhash/wind-scale 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,200 @@
+# wind-scale
+
+<!-- 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 `wind-scale` as a placeholder — replace it
+> (and the `npm install` line below) with the real published name/scope before
+> running `npm publish`.
+
+Zero-dependency, pure-JavaScript wind utilities: convert speeds between the five
+units meteorologists actually use, and classify a wind on the three scales the
+public sees on forecasts — the Beaufort force scale, the Saffir-Simpson
+hurricane scale, and the official U.S. National Weather Service wind-chill
+temperature.
+
+No dependencies, no network, no I/O. Every function is pure: given the same
+inputs it always returns the same value and mutates nothing. It runs anywhere
+Node.js runs and is trivial to vendor into a browser bundle.
+
+## Who it's for
+
+- Weather / marine / aviation dashboards that receive wind in one unit (say
+  METAR knots) and must display another (mph, km/h).
+- Anyone turning a raw wind speed into a human label ("Force 7, near gale" or
+  "Category 3 hurricane").
+- Cold-climate apps computing the "feels-like" wind-chill temperature with the
+  correct, current NWS formula instead of the obsolete pre-2001 one.
+
+## Install / use
+
+It's a single file with no dependencies. Copy `src/wind-scale.js` into your
+project or `require` it directly:
+
+```js
+const { convert, beaufort, saffirSimpson, windChill } = require('./src/wind-scale.js');
+```
+
+## API
+
+### `convert(value, fromUnit, toUnit) -> number`
+
+Convert a wind speed between any two of these units:
+
+| code   | unit             |
+|--------|------------------|
+| `ms`   | metres/second    |
+| `kmh`  | kilometres/hour  |
+| `mph`  | miles/hour       |
+| `kn`   | knots            |
+| `fts`  | feet/second      |
+
+Exact factors relative to 1 m/s:
+`1 m/s = 3.6 km/h = 2.2369362920544 mph = 1.9438444924406 kn = 3.280839895 ft/s`.
+
+```js
+convert(10, 'ms', 'kmh');   // 36
+convert(100, 'kmh', 'mph'); // 62.137119223733...
+convert(50, 'kn', 'mph');   // 57.539019...
+```
+
+Throws `TypeError` if `value` is not a finite number and `RangeError` for an
+unknown unit code.
+
+### `beaufort(speedMs) -> { force, description, minMs, maxMs }`
+
+Classify a wind speed **in metres per second** on the 0–12 Beaufort scale. The
+result gives the integer `force`, its standard WMO `description`, and the band's
+bounds in m/s: `minMs` (inclusive lower bound) and `maxMs` (exclusive upper
+bound; `Infinity` for Force 12). Bands are contiguous — the `maxMs` of one force
+equals the `minMs` of the next.
+
+Boundaries (m/s), Force 0 below 0.5 up to Force 12 at 32.7 and above:
+
+| force | m/s band     | description     |
+|-------|--------------|-----------------|
+| 0     | < 0.5        | Calm            |
+| 1     | 0.5–1.6      | Light air       |
+| 2     | 1.6–3.4      | Light breeze    |
+| 3     | 3.4–5.5      | Gentle breeze   |
+| 4     | 5.5–8.0      | Moderate breeze |
+| 5     | 8.0–10.8     | Fresh breeze    |
+| 6     | 10.8–13.9    | Strong breeze   |
+| 7     | 13.9–17.2    | Near gale       |
+| 8     | 17.2–20.8    | Gale            |
+| 9     | 20.8–24.5    | Strong gale     |
+| 10    | 24.5–28.5    | Storm           |
+| 11    | 28.5–32.7    | Violent storm   |
+| 12    | >= 32.7      | Hurricane force |
+
+```js
+beaufort(9.0);
+// { force: 5, description: 'Fresh breeze', minMs: 8, maxMs: 10.8 }
+
+beaufort(40);
+// { force: 12, description: 'Hurricane force', minMs: 32.7, maxMs: Infinity }
+```
+
+If your speed is in another unit, feed it through `convert` first:
+`beaufort(convert(20, 'kn', 'ms'))`.
+
+Throws `TypeError` for non-finite input and `RangeError` for negative speeds.
+
+### `saffirSimpson(sustainedMph) -> { category, label }`
+
+Classify a tropical cyclone by its **1-minute sustained wind in mph**. Uses the
+Saffir-Simpson Hurricane Wind Scale plus the U.S. National Hurricane Center's
+sub-hurricane designations. `category` is `'TD'`, `'TS'`, or the number `1`–`5`.
+
+| category | sustained mph | label                 |
+|----------|---------------|-----------------------|
+| `'TD'`   | < 39          | Tropical Depression   |
+| `'TS'`   | 39–73         | Tropical Storm        |
+| `1`      | 74–95         | Category 1 Hurricane  |
+| `2`      | 96–110        | Category 2 Hurricane  |
+| `3`      | 111–129       | Category 3 Hurricane  |
+| `4`      | 130–156       | Category 4 Hurricane  |
+| `5`      | >= 157        | Category 5 Hurricane  |
+
+```js
+saffirSimpson(35);  // { category: 'TD', label: 'Tropical Depression' }
+saffirSimpson(74);  // { category: 1,   label: 'Category 1 Hurricane' }
+saffirSimpson(160); // { category: 5,   label: 'Category 5 Hurricane' }
+```
+
+Throws `TypeError` for non-finite input and `RangeError` for negative speeds.
+
+### `windChill(tempF, windMph) -> number`
+
+Wind chill temperature in degrees Fahrenheit using the official 2001 NWS /
+Environment Canada formula:
+
+```
+WC = 35.74 + 0.6215*T - 35.75*V^0.16 + 0.4275*T*V^0.16
+```
+
+with `T` air temperature in °F and `V` wind speed in mph (at the standard 10 m
+anemometer height).
+
+**Validity range.** The NWS defines this formula only for **air temperature ≤ 50 °F
+and wind speed > 3 mph**. Outside that domain wind chill is not meaningful, so
+this function returns the input air temperature (`tempF`) unchanged when
+`tempF > 50` or `windMph <= 3`. Inside the valid domain it returns the raw
+formula value (not rounded); published NWS charts round to the nearest whole
+degree, so expect sub-degree differences from a chart cell.
+
+```js
+windChill(0, 35);  // -27.40...  (NWS chart cell: -27)
+windChill(40, 5);  //  36.47...  (NWS chart cell: 36)
+windChill(60, 20); //  60        (T > 50 F -> out of range, returns tempF)
+windChill(20, 2);  //  20        (V <= 3 mph -> out of range, returns tempF)
+```
+
+Throws `TypeError` if either argument is not a finite number, and `RangeError`
+for negative wind speed.
+
+## Running the tests
+
+One command, no install step (uses only `node:assert`):
+
+```
+node test/wind-scale.test.js
+```
+
+The suite checks round-trip and cross-unit conversions, every Beaufort force
+boundary (and the value just below it), every Saffir-Simpson category boundary,
+and ten published NWS wind-chill chart cells.
+
+## Status / limitations
+
+- Beaufort m/s thresholds follow the widely published WMO table rounded to one
+  decimal; different sources round the knot-derived cut points slightly
+  differently, so a value sitting exactly on a boundary may differ by one force
+  from another table.
+- `saffirSimpson` expects 1-minute sustained wind in mph, the U.S. convention.
+  Agencies using 10-minute sustained winds (much of the world) will classify the
+  same storm differently — convert your averaging period first.
+- Wind chill is only valid for cold, windy conditions (≤ 50 °F, > 3 mph); it is
+  not a general "feels like" index and says nothing about heat or humidity.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `wind-scale` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install wind-scale
+```
+
+```js
+const { convert, beaufort, saffirSimpson, windChill } = require('wind-scale');
+
+convert(10, 'ms', 'kmh'); // 36
+beaufort(9.0);            // { force: 5, description: 'Fresh breeze', minMs: 8, maxMs: 10.8 }
+saffirSimpson(100);       // { category: 2, label: 'Category 2 Hurricane' }  (sustained mph)
+windChill(20, 15);        // 6.22  (°F, from tempF=20, windMph=15)
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@verifyhash/wind-scale",
+  "version": "0.1.0",
+  "description": "Zero-dependency wind speed conversions plus Beaufort, Saffir-Simpson, and the official 2001 NWS wind-chill formula.",
+  "keywords": [
+    "wind",
+    "beaufort",
+    "saffir-simpson",
+    "hurricane",
+    "wind-chill",
+    "knots",
+    "meteorology",
+    "conversion"
+  ],
+  "main": "src/wind-scale.js",
+  "scripts": {
+    "test": "node test/wind-scale.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "src/wind-scale.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "wind-scale"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/wind-scale#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}

package/src/wind-scale.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * wind-scale — zero-dependency wind speed conversions and meteorological scales.
+ *
+ * Provides four pure functions:
+ *   - convert(value, fromUnit, toUnit)  unit conversion among m/s, km/h, mph, kn, ft/s
+ *   - beaufort(speedMs)                 Beaufort force (0-12) from a speed in m/s
+ *   - saffirSimpson(sustainedMph)       Saffir-Simpson hurricane category from sustained mph
+ *   - windChill(tempF, windMph)         2001 NWS wind chill temperature (deg F)
+ *
+ * No I/O, no network, no external dependencies. Every function is pure and
+ * deterministic: same inputs always produce the same output, and nothing is
+ * mutated or observed outside the return value.
+ */
+
+// --- unit conversion -------------------------------------------------------
+
+/**
+ * Conversion factors expressed as "how many of this unit equal 1 metre/second".
+ * These are exact per the task specification:
+ *   1 m/s = 3.6 km/h = 2.2369362920544 mph = 1.9438444924406 kn = 3.280839895 ft/s
+ *
+ * (1 knot = 1 nautical mile/hour = 1852 m / 3600 s; 1 mph = 1609.344 m / 3600 s;
+ *  1 ft/s = 0.3048 m / s.)
+ */
+const FACTORS = Object.freeze({
+  ms: 1,
+  kmh: 3.6,
+  mph: 2.2369362920544,
+  kn: 1.9438444924406,
+  fts: 3.280839895,
+});
+
+const UNIT_NAMES = Object.freeze(Object.keys(FACTORS));
+
+function isFiniteNumber(x) {
+  return typeof x === 'number' && Number.isFinite(x);
+}
+
+/**
+ * Convert a wind speed between any two supported units.
+ *
+ * @param {number} value    the numeric speed to convert (finite number)
+ * @param {string} fromUnit one of 'ms','kmh','mph','kn','fts'
+ * @param {string} toUnit   one of 'ms','kmh','mph','kn','fts'
+ * @returns {number}        the value expressed in toUnit
+ *
+ * @example
+ *   convert(10, 'ms', 'kmh')  // => 36
+ *   convert(100, 'kmh', 'mph') // => 62.137... (100 km/h in mph)
+ *   convert(50, 'kn', 'kn')   // => 50 (round-trip identity)
+ */
+function convert(value, fromUnit, toUnit) {
+  if (!isFiniteNumber(value)) {
+    throw new TypeError(`convert: value must be a finite number, got ${value}`);
+  }
+  if (!Object.prototype.hasOwnProperty.call(FACTORS, fromUnit)) {
+    throw new RangeError(
+      `convert: unknown fromUnit '${fromUnit}', expected one of ${UNIT_NAMES.join(', ')}`
+    );
+  }
+  if (!Object.prototype.hasOwnProperty.call(FACTORS, toUnit)) {
+    throw new RangeError(
+      `convert: unknown toUnit '${toUnit}', expected one of ${UNIT_NAMES.join(', ')}`
+    );
+  }
+  // Convert to the m/s base, then out to the target unit.
+  const ms = value / FACTORS[fromUnit];
+  return ms * FACTORS[toUnit];
+}
+
+// --- Beaufort wind force scale --------------------------------------------
+
+/**
+ * Beaufort force table. Each entry gives the inclusive lower bound in m/s
+ * (`minMs`) and the standard WMO description. Boundaries follow the widely
+ * published m/s thresholds: Force 0 is below 0.5 m/s, Force 12 (hurricane
+ * force) begins at 32.7 m/s. A given force f spans [minMs[f], minMs[f+1]).
+ */
+const BEAUFORT = Object.freeze([
+  { force: 0, minMs: 0.0, description: 'Calm' },
+  { force: 1, minMs: 0.5, description: 'Light air' },
+  { force: 2, minMs: 1.6, description: 'Light breeze' },
+  { force: 3, minMs: 3.4, description: 'Gentle breeze' },
+  { force: 4, minMs: 5.5, description: 'Moderate breeze' },
+  { force: 5, minMs: 8.0, description: 'Fresh breeze' },
+  { force: 6, minMs: 10.8, description: 'Strong breeze' },
+  { force: 7, minMs: 13.9, description: 'Near gale' },
+  { force: 8, minMs: 17.2, description: 'Gale' },
+  { force: 9, minMs: 20.8, description: 'Strong gale' },
+  { force: 10, minMs: 24.5, description: 'Storm' },
+  { force: 11, minMs: 28.5, description: 'Violent storm' },
+  { force: 12, minMs: 32.7, description: 'Hurricane force' },
+]);
+
+/**
+ * Classify a wind speed (in metres per second) on the Beaufort scale.
+ *
+ * @param {number} speedMs wind speed in m/s (finite, >= 0)
+ * @returns {{force:number, description:string, minMs:number, maxMs:number}}
+ *   force is 0..12; minMs/maxMs are the inclusive lower and exclusive upper
+ *   bounds of that force band in m/s. For Force 12 maxMs is Infinity.
+ *
+ * @example
+ *   beaufort(0.2)  // => { force: 0, description: 'Calm', minMs: 0, maxMs: 0.5 }
+ *   beaufort(9.0)  // => { force: 5, description: 'Fresh breeze', minMs: 8, maxMs: 10.8 }
+ *   beaufort(40)   // => { force: 12, description: 'Hurricane force', minMs: 32.7, maxMs: Infinity }
+ */
+function beaufort(speedMs) {
+  if (!isFiniteNumber(speedMs)) {
+    throw new TypeError(`beaufort: speedMs must be a finite number, got ${speedMs}`);
+  }
+  if (speedMs < 0) {
+    throw new RangeError(`beaufort: speedMs must be >= 0, got ${speedMs}`);
+  }
+  // Find the highest force whose lower bound is <= speedMs.
+  let idx = 0;
+  for (let i = 0; i < BEAUFORT.length; i++) {
+    if (speedMs >= BEAUFORT[i].minMs) idx = i;
+    else break;
+  }
+  const entry = BEAUFORT[idx];
+  const next = BEAUFORT[idx + 1];
+  return {
+    force: entry.force,
+    description: entry.description,
+    minMs: entry.minMs,
+    maxMs: next ? next.minMs : Infinity,
+  };
+}
+
+// --- Saffir-Simpson hurricane wind scale ----------------------------------
+
+/**
+ * Classify a tropical cyclone by its 1-minute sustained wind in mph on the
+ * Saffir-Simpson Hurricane Wind Scale, extended downward with the U.S.
+ * National Hurricane Center's sub-hurricane designations:
+ *   TD (tropical depression) < 39 mph
+ *   TS (tropical storm)      39-73 mph
+ *   Category 1               74-95 mph
+ *   Category 2               96-110 mph
+ *   Category 3               111-129 mph  (major hurricane)
+ *   Category 4               130-156 mph  (major hurricane)
+ *   Category 5               >= 157 mph   (major hurricane)
+ *
+ * @param {number} sustainedMph sustained wind speed in mph (finite, >= 0)
+ * @returns {{category:('TD'|'TS'|1|2|3|4|5), label:string}}
+ *
+ * @example
+ *   saffirSimpson(35)  // => { category: 'TD', label: 'Tropical Depression' }
+ *   saffirSimpson(74)  // => { category: 1,   label: 'Category 1 Hurricane' }
+ *   saffirSimpson(160) // => { category: 5,   label: 'Category 5 Hurricane' }
+ */
+function saffirSimpson(sustainedMph) {
+  if (!isFiniteNumber(sustainedMph)) {
+    throw new TypeError(
+      `saffirSimpson: sustainedMph must be a finite number, got ${sustainedMph}`
+    );
+  }
+  if (sustainedMph < 0) {
+    throw new RangeError(`saffirSimpson: sustainedMph must be >= 0, got ${sustainedMph}`);
+  }
+  if (sustainedMph < 39) return { category: 'TD', label: 'Tropical Depression' };
+  if (sustainedMph < 74) return { category: 'TS', label: 'Tropical Storm' };
+  if (sustainedMph < 96) return { category: 1, label: 'Category 1 Hurricane' };
+  if (sustainedMph < 111) return { category: 2, label: 'Category 2 Hurricane' };
+  if (sustainedMph < 130) return { category: 3, label: 'Category 3 Hurricane' };
+  if (sustainedMph < 157) return { category: 4, label: 'Category 4 Hurricane' };
+  return { category: 5, label: 'Category 5 Hurricane' };
+}
+
+// --- NWS wind chill --------------------------------------------------------
+
+/**
+ * Wind chill temperature using the official 2001 U.S. National Weather Service
+ * / Environment Canada formula:
+ *
+ *   WC = 35.74 + 0.6215*T - 35.75*V^0.16 + 0.4275*T*V^0.16
+ *
+ * where T is air temperature in degrees Fahrenheit and V is the wind speed in
+ * miles per hour (measured at the standard 10 m anemometer height).
+ *
+ * VALIDITY: the formula is only defined by the NWS for air temperature at or
+ * below 50 deg F AND wind speed above 3 mph. Outside that domain wind chill is
+ * not meaningful, so this function returns the input air temperature (tempF)
+ * unchanged when tempF > 50 or windMph <= 3. Within the valid domain it returns
+ * the raw formula result (not rounded); published NWS charts round to the
+ * nearest whole degree.
+ *
+ * @param {number} tempF   air temperature in degrees Fahrenheit (finite)
+ * @param {number} windMph wind speed in mph (finite, >= 0)
+ * @returns {number}       wind chill temperature in deg F, or tempF if out of range
+ *
+ * @example
+ *   windChill(0, 35)   // => -27.4  (NWS chart cell: -27)
+ *   windChill(40, 5)   // => 36.4   (NWS chart cell: 36)
+ *   windChill(60, 20)  // => 60     (T > 50 F: out of range, returns tempF)
+ *   windChill(20, 2)   // => 20     (V <= 3 mph: out of range, returns tempF)
+ */
+function windChill(tempF, windMph) {
+  if (!isFiniteNumber(tempF)) {
+    throw new TypeError(`windChill: tempF must be a finite number, got ${tempF}`);
+  }
+  if (!isFiniteNumber(windMph)) {
+    throw new TypeError(`windChill: windMph must be a finite number, got ${windMph}`);
+  }
+  if (windMph < 0) {
+    throw new RangeError(`windChill: windMph must be >= 0, got ${windMph}`);
+  }
+  // Outside the NWS validity domain the formula is undefined; return tempF.
+  if (tempF > 50 || windMph <= 3) {
+    return tempF;
+  }
+  const v16 = Math.pow(windMph, 0.16);
+  return 35.74 + 0.6215 * tempF - 35.75 * v16 + 0.4275 * tempF * v16;
+}
+
+module.exports = {
+  convert,
+  beaufort,
+  saffirSimpson,
+  windChill,
+  // handy for callers / tests
+  FACTORS,
+  BEAUFORT,
+  UNITS: UNIT_NAMES,
+};