@verifyhash/iso-duration 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,153 @@
+# iso-duration
+
+<!-- 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 `iso-duration` 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, zero-network** Node.js library for **ISO 8601
+durations** — the `P3Y6M4DT12H30M5S` strings that show up in JSON Schema
+(`format: duration`), OpenAPI, iCalendar (`RRULE`/`DURATION`), GitHub Actions
+timeouts, Kubernetes manifests, and countless "retry after / cache for / repeat
+every" API fields.
+
+It does four things and nothing else:
+
+- **`parse(str)`** — string → duration object
+- **`format(obj)`** — duration object → canonical string (round-trips `parse`)
+- **`addToDate` / `subtractFromDate`** — calendar-correct `Date` arithmetic
+- **`humanize(obj)`** — `"3 hours 30 minutes"`
+
+No dependencies, no install step, no I/O. Just `index.js` (CommonJS) and pure
+functions. Drop it into any project.
+
+## Who it's for
+
+JavaScript/Node developers who receive or emit ISO 8601 durations from APIs,
+schemas, or schedules and want to parse, normalize, do date math on, or display
+them — without pulling in Luxon/moment/date-fns just for the duration bits.
+
+## The duration object
+
+Every function speaks the same plain object. All keys are optional; missing
+numeric keys are `0`, and `negative` defaults to `false`:
+
+```js
+{ years, months, weeks, days, hours, minutes, seconds, negative }
+```
+
+## Usage
+
+```js
+const iso = require('iso-duration'); // or require('./index.js')
+
+iso.parse('P3Y6M4DT12H30M5S');
+// { years: 3, months: 6, weeks: 0, days: 4,
+//   hours: 12, minutes: 30, seconds: 5, negative: false }
+
+iso.parse('-PT1H30M');   // { ..., hours: 1, minutes: 30, negative: true }
+iso.parse('P2W');        // { ..., weeks: 2 }
+iso.parse('PT0.5H');     // { ..., hours: 0.5 }  (fractional final component)
+
+iso.format({ hours: 3, minutes: 30 });        // 'PT3H30M'
+iso.format({});                               // 'PT0S'
+iso.format({ weeks: 2 });                     // 'P2W'
+iso.format({ hours: 1, negative: true });     // '-PT1H'
+
+iso.humanize({ hours: 3, minutes: 30 });      // '3 hours 30 minutes'
+iso.humanize({ hours: 1 });                   // '1 hour'
+iso.humanize({});                             // '0 seconds'
+
+const start = new Date('2020-01-31T00:00:00Z');
+iso.addToDate(start, { months: 1 });          // 2020-02-29T00:00:00.000Z
+start.toISOString();                          // unchanged — input is never mutated
+iso.subtractFromDate(start, { days: 10 });    // 2020-01-21T00:00:00.000Z
+```
+
+## Two design choices to know about
+
+Libraries genuinely disagree on these two points, so they are spelled out here
+rather than left to surprise you.
+
+### 1. Weeks normalization
+
+ISO 8601 treats `W` (weeks) as mutually exclusive with the other date fields —
+`P2W` is legal, `P1W3D` technically is not. This library is lenient on **input**
+(it will parse `P1W3D` and keep `weeks` and `days` separate) but opinionated on
+**output**:
+
+- `format()` emits `P2W` **only when weeks is the sole non-zero component.**
+- In every other case weeks are folded into days at **1 week = 7 days**
+  (e.g. `format({ weeks: 1, days: 1 })` → `'P8D'`).
+
+This keeps the canonical string valid ISO and guarantees `format` round-trips
+through `parse`: `format(parse(s)) === s` for any canonical `s`, and repeated
+`format(parse(...))` is stable. In date arithmetic, weeks are always treated as
+7 elapsed days.
+
+### 2. Month (and year) overflow clamps
+
+Adding months and years is calendar arithmetic, and calendars have ragged month
+lengths. When the target month is shorter than the source day-of-month, this
+library **clamps to the last day of the target month** — the same rule Luxon,
+Temporal, and date-fns use:
+
+- `Jan 31 + P1M` → **Feb 29** in a leap year, **Feb 28** otherwise.
+- `Mar 31 − P1M` → **Feb 29 / Feb 28** (subtraction clamps the same way).
+
+The arithmetic order is: **years/months are applied first as whole calendar
+steps (with clamping), then weeks/days/hours/minutes/seconds are added as a flat
+elapsed-milliseconds offset.** Because the calendar step happens first, results
+are deterministic and independent of your machine's timezone (all math is done
+in UTC) and the input `Date` is never mutated — a new `Date` is returned.
+
+**Honest limits.** Because day/time components are applied as elapsed
+milliseconds, they do **not** track daylight-saving wall-clock shifts — that is
+correct for UTC/absolute instants but means "+1 day" is always exactly 24 hours,
+not "same local time tomorrow." Fractional **years or months** (rare, e.g.
+`P0.5M`) can't be expressed as an exact number of calendar days, so their
+fractional part is approximated using the mean Gregorian month (30.436875 days);
+integer years/months — the normal case — are always exact.
+
+## Errors
+
+`parse()` throws a descriptive `Error` on malformed input, including: an empty
+string, a missing `P`, a `T` separator with no time components (`"PT"`), a bare
+`"P"`, out-of-order fields (`"P3M6Y"`), and time letters outside the `T` block
+(`"P5S"`).
+
+## Running the tests
+
+One command, no install, no network:
+
+```
+node test/index.test.js
+```
+
+It prints one line per test and exits non-zero if any fail. Coverage includes
+parse/format round-trips, `P2W` weeks, `PT0S` and negatives, fractional seconds,
+Jan-31 + 1-month month-overflow arithmetic, the no-mutation guarantee, humanize
+pluralization, and malformed-input throw cases.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `iso-duration` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install iso-duration
+```
+
+```js
+const iso = require('iso-duration');
+
+iso.parse('P3Y6M4DT12H30M5S');         // { years:3, months:6, days:4, hours:12, minutes:30, seconds:5, ... }
+iso.format({ hours: 3, minutes: 30 }); // 'PT3H30M'
+iso.humanize({ hours: 1, minutes: 30 }); // '1 hour 30 minutes'
+```

package/index.js

@@ -0,0 +1,293 @@
+'use strict';
+
+/*
+ * iso-duration — zero-dependency ISO 8601 duration parse / format /
+ * arithmetic / humanize for Node.js.
+ *
+ * A "duration object" is a plain object with any of these numeric keys plus a
+ * boolean `negative` flag:
+ *
+ *   { years, months, weeks, days, hours, minutes, seconds, negative }
+ *
+ * All keys are optional; missing numeric keys are treated as 0 and `negative`
+ * defaults to false. Every function here is pure — no I/O, no network, no
+ * mutation of its arguments.
+ */
+
+var UNIT_KEYS = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds'];
+
+// Average calendar month / year, used ONLY for the rare case of a *fractional*
+// year or month in date arithmetic (see addToDate). 30.436875 days is the mean
+// Gregorian month (365.2425 / 12).
+var MS_PER_DAY = 86400000;
+var AVG_MONTH_MS = 30.436875 * MS_PER_DAY;
+var AVG_YEAR_MS = 365.2425 * MS_PER_DAY;
+
+// ---------------------------------------------------------------------------
+// parse
+// ---------------------------------------------------------------------------
+
+// P[n]Y[n]M[n]W[n]D [ T[n]H[n]M[n]S ]. A leading '-' (or '+') sets the sign.
+// Numbers may carry a fractional part with '.' or ',' as the decimal mark.
+var NUM = '(\\d+(?:[.,]\\d+)?)';
+var DUR_RE = new RegExp(
+  '^([+-])?P' +
+    '(?:' + NUM + 'Y)?' +
+    '(?:' + NUM + 'M)?' +
+    '(?:' + NUM + 'W)?' +
+    '(?:' + NUM + 'D)?' +
+    '(T' +
+    '(?:' + NUM + 'H)?' +
+    '(?:' + NUM + 'M)?' +
+    '(?:' + NUM + 'S)?' +
+    ')?$'
+);
+
+function toNumber(raw) {
+  if (raw === undefined) return 0;
+  return parseFloat(raw.replace(',', '.'));
+}
+
+/**
+ * Parse an ISO 8601 duration string into a duration object.
+ * Throws an Error with a clear message on malformed input.
+ */
+function parse(str) {
+  if (typeof str !== 'string') {
+    throw new Error('iso-duration.parse: expected a string, got ' + typeof str);
+  }
+  var s = str.trim();
+  if (s === '') {
+    throw new Error('iso-duration.parse: empty string is not a valid duration');
+  }
+  var m = DUR_RE.exec(s);
+  if (!m) {
+    throw new Error(
+      'iso-duration.parse: "' + str + '" is not a valid ISO 8601 duration'
+    );
+  }
+
+  var sign = m[1];
+  var years = m[2];
+  var months = m[3];
+  var weeks = m[4];
+  var days = m[5];
+  var timeBlock = m[6]; // the literal 'T...' block, or undefined
+  var hours = m[7];
+  var minutes = m[8];
+  var seconds = m[9];
+
+  var hasDate =
+    years !== undefined ||
+    months !== undefined ||
+    weeks !== undefined ||
+    days !== undefined;
+  var hasTime =
+    hours !== undefined || minutes !== undefined || seconds !== undefined;
+
+  // A 'T' designator was present but no time components followed it.
+  if (timeBlock !== undefined && !hasTime) {
+    throw new Error(
+      'iso-duration.parse: "' + str + '" has a "T" separator but no time components'
+    );
+  }
+  // "P" (or "-P") alone — no components at all.
+  if (!hasDate && !hasTime) {
+    throw new Error(
+      'iso-duration.parse: "' + str + '" has no duration components'
+    );
+  }
+
+  return {
+    years: toNumber(years),
+    months: toNumber(months),
+    weeks: toNumber(weeks),
+    days: toNumber(days),
+    hours: toNumber(hours),
+    minutes: toNumber(minutes),
+    seconds: toNumber(seconds),
+    negative: sign === '-'
+  };
+}
+
+// ---------------------------------------------------------------------------
+// format
+// ---------------------------------------------------------------------------
+
+function num(obj, key) {
+  var v = obj[key];
+  return typeof v === 'number' && !isNaN(v) ? v : 0;
+}
+
+// Render a number without a trailing ".0" and without locale grouping.
+function fmtNum(n) {
+  return String(n);
+}
+
+/**
+ * Format a duration object into a canonical ISO 8601 string.
+ *
+ * Rules:
+ *  - Zero components are omitted.
+ *  - An all-zero duration formats as "PT0S".
+ *  - A negative duration gets a leading "-".
+ *  - Weeks are emitted as "P2W" ONLY when weeks is the sole non-zero
+ *    component; otherwise weeks are folded into days (1 week = 7 days) so the
+ *    output round-trips through parse().
+ */
+function format(obj) {
+  if (obj == null || typeof obj !== 'object') {
+    throw new Error('iso-duration.format: expected a duration object');
+  }
+
+  var years = num(obj, 'years');
+  var months = num(obj, 'months');
+  var weeks = num(obj, 'weeks');
+  var days = num(obj, 'days');
+  var hours = num(obj, 'hours');
+  var minutes = num(obj, 'minutes');
+  var seconds = num(obj, 'seconds');
+
+  var weeksIsSole =
+    weeks !== 0 &&
+    years === 0 &&
+    months === 0 &&
+    days === 0 &&
+    hours === 0 &&
+    minutes === 0 &&
+    seconds === 0;
+
+  var out = obj.negative ? '-P' : 'P';
+
+  if (weeksIsSole) {
+    return out + fmtNum(weeks) + 'W';
+  }
+
+  // Fold weeks into days for every other case.
+  days = days + weeks * 7;
+
+  if (years !== 0) out += fmtNum(years) + 'Y';
+  if (months !== 0) out += fmtNum(months) + 'M';
+  if (days !== 0) out += fmtNum(days) + 'D';
+
+  if (hours !== 0 || minutes !== 0 || seconds !== 0) {
+    out += 'T';
+    if (hours !== 0) out += fmtNum(hours) + 'H';
+    if (minutes !== 0) out += fmtNum(minutes) + 'M';
+    if (seconds !== 0) out += fmtNum(seconds) + 'S';
+  }
+
+  // All-zero duration.
+  if (out === 'P' || out === '-P') {
+    return 'PT0S';
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// date arithmetic
+// ---------------------------------------------------------------------------
+
+function daysInMonth(year, monthIndex) {
+  // monthIndex 0-11; day 0 of next month = last day of this month.
+  return new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+}
+
+// Add an integer number of calendar months (may be negative), clamping the
+// day-of-month on overflow (Jan 31 + 1 month -> Feb 28/29).
+function addWholeMonths(d, months) {
+  if (months === 0) return;
+  var day = d.getUTCDate();
+  d.setUTCDate(1);
+  d.setUTCMonth(d.getUTCMonth() + months);
+  var dim = daysInMonth(d.getUTCFullYear(), d.getUTCMonth());
+  d.setUTCDate(Math.min(day, dim));
+}
+
+// direction: +1 for addToDate, -1 for subtractFromDate.
+function applyDuration(date, obj, direction) {
+  if (!(date instanceof Date) || isNaN(date.getTime())) {
+    throw new Error('iso-duration: first argument must be a valid Date');
+  }
+  if (obj == null || typeof obj !== 'object') {
+    throw new Error('iso-duration: second argument must be a duration object');
+  }
+
+  var sign = (obj.negative ? -1 : 1) * direction;
+
+  var years = num(obj, 'years');
+  var months = num(obj, 'months');
+
+  var totalMonths = sign * (years * 12 + months);
+  var wholeMonths = totalMonths < 0 ? Math.ceil(totalMonths) : Math.floor(totalMonths);
+  var fracMonths = totalMonths - wholeMonths;
+
+  // 1) Calendar-correct year/month step first (with day clamping).
+  var result = new Date(date.getTime());
+  addWholeMonths(result, wholeMonths);
+
+  // 2) Everything else as elapsed milliseconds. Any fractional month/year
+  //    remainder is approximated with the mean Gregorian month length.
+  var elapsedMs =
+    sign *
+      (num(obj, 'weeks') * 7 * MS_PER_DAY +
+        num(obj, 'days') * MS_PER_DAY +
+        num(obj, 'hours') * 3600000 +
+        num(obj, 'minutes') * 60000 +
+        num(obj, 'seconds') * 1000) +
+    fracMonths * AVG_MONTH_MS;
+
+  return new Date(result.getTime() + elapsedMs);
+}
+
+function addToDate(date, obj) {
+  return applyDuration(date, obj, 1);
+}
+
+function subtractFromDate(date, obj) {
+  return applyDuration(date, obj, -1);
+}
+
+// ---------------------------------------------------------------------------
+// humanize
+// ---------------------------------------------------------------------------
+
+var UNIT_LABELS = {
+  years: 'year',
+  months: 'month',
+  weeks: 'week',
+  days: 'day',
+  hours: 'hour',
+  minutes: 'minute',
+  seconds: 'second'
+};
+
+/**
+ * Render a duration object as an English phrase, e.g. "3 hours 30 minutes".
+ * Zero units are omitted; an all-zero duration returns "0 seconds".
+ * The sign is not rendered — inspect obj.negative for direction.
+ */
+function humanize(obj) {
+  if (obj == null || typeof obj !== 'object') {
+    throw new Error('iso-duration.humanize: expected a duration object');
+  }
+  var parts = [];
+  for (var i = 0; i < UNIT_KEYS.length; i++) {
+    var key = UNIT_KEYS[i];
+    var v = num(obj, key);
+    if (v === 0) continue;
+    var label = UNIT_LABELS[key];
+    var mag = Math.abs(v);
+    parts.push(mag + ' ' + label + (mag === 1 ? '' : 's'));
+  }
+  if (parts.length === 0) return '0 seconds';
+  return parts.join(' ');
+}
+
+module.exports = {
+  parse: parse,
+  format: format,
+  addToDate: addToDate,
+  subtractFromDate: subtractFromDate,
+  humanize: humanize
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@verifyhash/iso-duration",
+  "version": "0.1.0",
+  "description": "Zero-dependency ISO 8601 duration parse, format, calendar-correct date arithmetic, and English humanize for Node.js.",
+  "keywords": [
+    "iso8601",
+    "iso-8601",
+    "duration",
+    "parse",
+    "format",
+    "period",
+    "pt1h30m",
+    "humanize",
+    "date-arithmetic"
+  ],
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "iso-duration"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/iso-duration#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}