@verifyhash/iso-duration 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 @@
 # 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
@@ -41,7 +34,7 @@ numeric keys are `0`, and `negative` defaults to `false`:
 ## Usage
 
 ```js
-const iso = require('iso-duration'); // or require('./index.js')
+const iso = require('@verifyhash/iso-duration'); // or require('./index.js')
 
 iso.parse('P3Y6M4DT12H30M5S');
 // { years: 3, months: 6, weeks: 0, days: 4,
@@ -66,6 +59,20 @@ start.toISOString();                          // unchanged — input is never mu
 iso.subtractFromDate(start, { days: 10 });    // 2020-01-21T00:00:00.000Z
 ```
 
+## API
+
+Five exports, all pure functions over the duration object above:
+
+- `parse(str)` — ISO 8601 duration string → duration object. Throws
+  `TypeError` on malformed input (see Errors below).
+- `format(obj)` — duration object → canonical ISO string (`'PT0S'` for empty).
+- `humanize(obj)` — duration object → plain-English phrase like
+  `'3 hours 30 minutes'`.
+- `addToDate(date, obj)` — returns a **new** `Date` shifted forward by the
+  duration; the input date is never mutated. Calendar-aware for months/years
+  (with the overflow clamp described below).
+- `subtractFromDate(date, obj)` — same, shifted backward.
+
 ## Two design choices to know about
 
 Libraries genuinely disagree on these two points, so they are spelled out here
@@ -137,15 +144,12 @@ 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
+npm install @verifyhash/iso-duration
 ```
 
 ```js
-const iso = require('iso-duration');
+const iso = require('@verifyhash/iso-duration');
 
 iso.parse('P3Y6M4DT12H30M5S');         // { years:3, months:6, days:4, hours:12, minutes:30, seconds:5, ... }
 iso.format({ hours: 3, minutes: 30 }); // 'PT3H30M'

package/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Type declarations for @verifyhash/iso-duration — zero-dependency ISO 8601
+ * duration parse, format, calendar-correct date arithmetic, and English
+ * humanize.
+ *
+ * Every function is pure: no I/O, no network, no mutation of its arguments.
+ */
+
+/**
+ * A duration object as ACCEPTED by format(), addToDate(), subtractFromDate()
+ * and humanize(): every key is optional. Missing/NaN/non-number unit values
+ * are treated as 0 and `negative` defaults to false. Unit values may be
+ * fractional.
+ */
+export interface DurationInput {
+  years?: number;
+  months?: number;
+  weeks?: number;
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  /** True for a negative duration (a leading '-' in the ISO string). */
+  negative?: boolean;
+}
+
+/**
+ * A duration object as RETURNED by parse(): every unit key is present
+ * (0 when the component was absent from the string) and `negative` is a
+ * definite boolean.
+ */
+export interface Duration {
+  years: number;
+  months: number;
+  weeks: number;
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  negative: boolean;
+}
+
+/**
+ * Parse an ISO 8601 duration string (e.g. "P1Y2M3DT4H5M6S", "PT1H30M",
+ * "-P2W"; fractions with '.' or ',' are accepted) into a duration object.
+ * Throws an Error with a clear message on malformed input (non-string, empty,
+ * bare "P", "T" with no time components, or anything off-grammar).
+ */
+export function parse(str: string): Duration;
+
+/**
+ * Format a duration object into a canonical ISO 8601 string. 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 folded into days (1 week = 7 days) so the
+ * output round-trips through parse(). Throws on a non-object argument.
+ */
+export function format(obj: DurationInput): string;
+
+/**
+ * Add a duration to a Date, returning a NEW Date (the input is not mutated).
+ * Whole years/months step the calendar with day-of-month clamping
+ * (Jan 31 + P1M -> Feb 28/29); weeks/days/hours/minutes/seconds are exact
+ * elapsed milliseconds; a fractional year/month remainder is approximated
+ * with the mean Gregorian month (30.436875 days). Throws on an invalid Date
+ * or a non-object duration.
+ */
+export function addToDate(date: Date, obj: DurationInput): Date;
+
+/**
+ * Subtract a duration from a Date, returning a NEW Date. Same calendar rules
+ * as addToDate() with the sign flipped.
+ */
+export function subtractFromDate(date: Date, obj: DurationInput): Date;
+
+/**
+ * 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. Throws on a
+ * non-object argument.
+ */
+export function humanize(obj: DurationInput): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verifyhash/iso-duration",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zero-dependency ISO 8601 duration parse, format, calendar-correct date arithmetic, and English humanize for Node.js.",
   "keywords": [
     "iso8601",
@@ -14,13 +14,15 @@
     "date-arithmetic"
   ],
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "node test/index.test.js"
   },
   "license": "MIT",
   "files": [
     "index.js",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"