@verifyhash/climate-normals 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+Copyright (c) 2026 verifyhash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,5 @@
 # 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.
@@ -198,15 +191,12 @@ 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
+npm install @verifyhash/climate-normals
 ```
 
 ```js
-const climate = require('climate-normals');
+const climate = require('@verifyhash/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)

package/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Type declarations for @verifyhash/climate-normals — zero-dependency climate
+ * math over monthly normals.
+ *
+ * The canonical month object is { hi, lo, pr?, rh?, ws? }: average daily high
+ * / low temperature (°C), monthly precipitation (mm, pleasantness only),
+ * relative humidity (%, apparent-temp only), wind speed (m/s, apparent-temp
+ * only). Functions only read the fields they document. "months" arrays are in
+ * calendar order (index 0 = January); year-summarising functions require
+ * exactly 12 entries.
+ */
+
+/** One month of normals. Only hi/lo are always required. */
+export interface MonthNormal {
+  /** Average daily HIGH temperature, °C. */
+  hi: number;
+  /** Average daily LOW temperature, °C. */
+  lo: number;
+  /** Average monthly PRECIPITATION, mm (pleasantness only). */
+  pr?: number;
+  /** Average RELATIVE HUMIDITY, % (apparent-temp only). */
+  rh?: number;
+  /** Average WIND SPEED, m/s (apparent-temp only). */
+  ws?: number;
+}
+
+/** Non-leap days per month (Feb = 28). */
+export const DAYS_IN_MONTH: number[];
+/** Default degree-day base temperature, °C (18). */
+export const HDD_BASE: number;
+/** Comfort band lower bound, °C mean daily temperature (18). */
+export const COMFORT_LO: number;
+/** Comfort band upper bound, °C mean daily temperature (24). */
+export const COMFORT_HI: number;
+/** Rain penalty per mm for the pleasantness heuristic (0.03). */
+export const RAIN_PENALTY_PER_MM: number;
+/** Avg high (°C) at/above which the heat index applies (27). */
+export const FEELS_WARM_HI: number;
+/** Avg low (°C) at/below which wind chill applies (10). */
+export const FEELS_COLD_LO: number;
+
+/** Mean daily temperature of a month = (hi + lo) / 2, in °C. */
+export function meanTemp(month: { hi: number; lo: number }): number;
+
+/** Result of degreeDays(). */
+export interface DegreeDaysResult {
+  /** Per-month raw (unrounded) degree-days. */
+  rows: Array<{ i: number; mean: number; hdd: number; cdd: number }>;
+  /** Rounded annual heating degree-day total. */
+  hdd: number;
+  /** Rounded annual cooling degree-day total. */
+  cdd: number;
+  /** Whichever total is larger (ties count as heating). */
+  dominated: 'heating' | 'cooling';
+}
+
+/**
+ * Heating & cooling degree-days for a year of monthly normals (exactly 12
+ * months, Jan..Dec). Base defaults to 18 °C.
+ */
+export function degreeDays(
+  months: Array<{ hi: number; lo: number }>,
+  base?: number
+): DegreeDaysResult;
+
+/**
+ * NWS Heat Index (Rothfusz regression): apparent temperature in °C for air
+ * temperature tC (°C) and relative humidity rh (%).
+ */
+export function heatIndex(tC: number, rh: number): number;
+
+/**
+ * NWS wind chill (2001 revision): apparent temperature in °C for air
+ * temperature tC (°C) and wind speed ws (m/s). Below ~4.8 km/h wind the air
+ * temperature is returned unchanged; never warmer than tC.
+ */
+export function windChill(tC: number, ws: number): number;
+
+/** Options for apparentTemperature(). */
+export interface ApparentTemperatureOptions {
+  /** Avg high (°C) at/above which the heat index applies (default 27). */
+  warmThreshold?: number;
+  /** Avg low (°C) at/below which wind chill applies (default 10). */
+  coldThreshold?: number;
+}
+
+/** Result of apparentTemperature(). */
+export interface ApparentTemperatureResult {
+  feelsHi: number;
+  feelsLo: number;
+  hiMode: 'actual' | 'heat';
+  loMode: 'actual' | 'wind';
+  /** feelsHi - hi (≥ 0): how much hotter humidity makes the day. */
+  dHot: number;
+  /** lo - feelsLo (≥ 0): how much colder wind makes the night. */
+  dCold: number;
+}
+
+/**
+ * Apparent ("feels like") daily high and low for one month of normals,
+ * folding in humidity (heat index) and/or wind (wind chill) when the
+ * thresholds are met.
+ */
+export function apparentTemperature(
+  month: { hi: number; lo: number; rh?: number; ws?: number },
+  opts?: ApparentTemperatureOptions
+): ApparentTemperatureResult;
+
+/**
+ * Day-to-night temperature swing across a year (exactly 12 months). `annual`
+ * is the mean of the 12 swings; `big`/`small` are the month indices of the
+ * largest and smallest swings (first month wins ties).
+ */
+export function diurnalRange(months: Array<{ hi: number; lo: number }>): {
+  swings: number[];
+  annual: number;
+  big: number;
+  small: number;
+};
+
+/**
+ * Annual mean-temperature range and its continentality classification
+ * (exactly 12 months). `warm`/`cold` are month indices; `range` is rounded to
+ * one decimal °C; `klass` is 'maritime / oceanic',
+ * 'transitional / moderately continental', or 'continental'.
+ */
+export function continentality(months: Array<{ hi: number; lo: number }>): {
+  warm: number;
+  cold: number;
+  warmMean: number;
+  coldMean: number;
+  range: number;
+  klass: string;
+};
+
+/**
+ * Pleasantness (comfort) score for a single month — LOWER is more
+ * comfortable; a month inside the 18–24 °C band with no rain scores 0.
+ */
+export function pleasantnessScore(month: {
+  hi: number;
+  lo: number;
+  pr?: number;
+}): {
+  mean: number;
+  tempPenalty: number;
+  rainPenalty: number;
+  score: number;
+};
+
+/**
+ * Rank a year of months (exactly 12) from most to least pleasant. `ranked`
+ * holds month indices best-first; ties keep calendar order.
+ */
+export function rankMonths(
+  months: Array<{ hi: number; lo: number; pr?: number }>
+): {
+  scored: Array<{
+    i: number;
+    mean: number;
+    tempPenalty: number;
+    rainPenalty: number;
+    score: number;
+  }>;
+  ranked: number[];
+};

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@verifyhash/climate-normals",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
+  "types": "index.d.ts",
   "type": "commonjs",
   "scripts": {
     "test": "node test/index.test.js"
@@ -23,7 +24,8 @@
   "license": "MIT",
   "files": [
     "index.js",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"