@padmaj/duration 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# @padmaj/duration
+
+Parse and format duration strings. Zero dependencies. TypeScript-first. Works in Node and browser.
+
+## Install
+
+```bash
+npm install @padmaj/duration
+```
+
+## Usage
+
+### Parse a duration string → milliseconds
+
+```ts
+import { parseDuration } from '@padmaj/duration'
+
+parseDuration('500ms')   // → 500
+parseDuration('30s')     // → 30000
+parseDuration('5m')      // → 300000
+parseDuration('2h')      // → 7200000
+parseDuration('1d')      // → 86400000
+parseDuration('1w')      // → 604800000
+
+// Compound durations
+parseDuration('2h30m')   // → 9000000
+parseDuration('1d12h')   // → 129600000
+parseDuration('2h 30m')  // → 9000000 (spaces OK)
+```
+
+### Format milliseconds → duration string
+
+```ts
+import { formatDuration } from '@padmaj/duration'
+
+formatDuration(500)          // → '500ms'
+formatDuration(30000)        // → '30s'
+formatDuration(9000000)      // → '2h 30m'
+formatDuration(129600000)    // → '1d 12h'
+formatDuration(0)            // → '0ms'
+```
+
+## Supported units
+
+| Unit | Meaning |
+|---|---|
+| `ms` | milliseconds |
+| `s` | seconds |
+| `m` | minutes |
+| `h` | hours |
+| `d` | days |
+| `w` | weeks |
+
+## API
+
+### `parseDuration(input: string): number`
+
+Parses a duration string and returns milliseconds. Throws `DurationError` if the input is empty or contains no recognizable units.
+
+### `formatDuration(ms: number): string`
+
+Formats milliseconds into a human-readable duration string. Throws `RangeError` if the value is negative, `NaN`, or `Infinity`.
+
+### `DurationError`
+
+Extends `Error`. Thrown by `parseDuration` on invalid input.
+
+```ts
+import { parseDuration, DurationError } from '@padmaj/duration'
+
+try {
+  parseDuration('abc')
+} catch (e) {
+  if (e instanceof DurationError) {
+    console.error('Bad duration:', e.message)
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+declare class DurationError extends Error {
+    constructor(input: string);
+}
+declare function parseDuration(input: string): number;
+declare function formatDuration(ms: number): string;
+
+export { DurationError, formatDuration, parseDuration };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+declare class DurationError extends Error {
+    constructor(input: string);
+}
+declare function parseDuration(input: string): number;
+declare function formatDuration(ms: number): string;
+
+export { DurationError, formatDuration, parseDuration };

package/dist/index.js

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DurationError: () => DurationError,
+  formatDuration: () => formatDuration,
+  parseDuration: () => parseDuration
+});
+module.exports = __toCommonJS(index_exports);
+var UNITS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5,
+  w: 6048e5
+};
+var PARSE_RE = /(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)/g;
+var DurationError = class extends Error {
+  constructor(input) {
+    super(`Invalid duration string: "${input}"`);
+    this.name = "DurationError";
+  }
+};
+function parseDuration(input) {
+  const str = input.trim();
+  if (!str) throw new DurationError(input);
+  let total = 0;
+  let matched = false;
+  PARSE_RE.lastIndex = 0;
+  for (const match of str.matchAll(PARSE_RE)) {
+    total += parseFloat(match[1]) * UNITS[match[2]];
+    matched = true;
+  }
+  if (!matched) throw new DurationError(input);
+  return Math.round(total);
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new RangeError(`formatDuration expects a non-negative finite number, got ${ms}`);
+  }
+  if (ms === 0) return "0ms";
+  const units = [
+    ["w", UNITS.w],
+    ["d", UNITS.d],
+    ["h", UNITS.h],
+    ["m", UNITS.m],
+    ["s", UNITS.s],
+    ["ms", UNITS.ms]
+  ];
+  const parts = [];
+  let remaining = Math.round(ms);
+  for (const [unit, value] of units) {
+    if (remaining >= value) {
+      const count = Math.floor(remaining / value);
+      parts.push(`${count}${unit}`);
+      remaining %= value;
+    }
+  }
+  return parts.join(" ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DurationError,
+  formatDuration,
+  parseDuration
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["const UNITS: Record<string, number> = {\n  ms: 1,\n  s:  1_000,\n  m:  60_000,\n  h:  3_600_000,\n  d:  86_400_000,\n  w:  604_800_000,\n}\n\nconst PARSE_RE = /(\\d+(?:\\.\\d+)?)\\s*(ms|s|m|h|d|w)/g\n\nexport class DurationError extends Error {\n  constructor(input: string) {\n    super(`Invalid duration string: \"${input}\"`)\n    this.name = 'DurationError'\n  }\n}\n\nexport function parseDuration(input: string): number {\n  const str = input.trim()\n  if (!str) throw new DurationError(input)\n\n  let total = 0\n  let matched = false\n\n  PARSE_RE.lastIndex = 0\n  for (const match of str.matchAll(PARSE_RE)) {\n    total += parseFloat(match[1]) * UNITS[match[2]]\n    matched = true\n  }\n\n  if (!matched) throw new DurationError(input)\n  return Math.round(total)\n}\n\nexport function formatDuration(ms: number): string {\n  if (!Number.isFinite(ms) || ms < 0) {\n    throw new RangeError(`formatDuration expects a non-negative finite number, got ${ms}`)\n  }\n\n  if (ms === 0) return '0ms'\n\n  const units: [string, number][] = [\n    ['w', UNITS.w],\n    ['d', UNITS.d],\n    ['h', UNITS.h],\n    ['m', UNITS.m],\n    ['s', UNITS.s],\n    ['ms', UNITS.ms],\n  ]\n\n  const parts: string[] = []\n  let remaining = Math.round(ms)\n\n  for (const [unit, value] of units) {\n    if (remaining >= value) {\n      const count = Math.floor(remaining / value)\n      parts.push(`${count}${unit}`)\n      remaining %= value\n    }\n  }\n\n  return parts.join(' ')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAM,QAAgC;AAAA,EACpC,IAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AACN;AAEA,IAAM,WAAW;AAEV,IAAM,gBAAN,cAA4B,MAAM;AAAA,EACvC,YAAY,OAAe;AACzB,UAAM,6BAA6B,KAAK,GAAG;AAC3C,SAAK,OAAO;AAAA,EACd;AACF;AAEO,SAAS,cAAc,OAAuB;AACnD,QAAM,MAAM,MAAM,KAAK;AACvB,MAAI,CAAC,IAAK,OAAM,IAAI,cAAc,KAAK;AAEvC,MAAI,QAAQ;AACZ,MAAI,UAAU;AAEd,WAAS,YAAY;AACrB,aAAW,SAAS,IAAI,SAAS,QAAQ,GAAG;AAC1C,aAAS,WAAW,MAAM,CAAC,CAAC,IAAI,MAAM,MAAM,CAAC,CAAC;AAC9C,cAAU;AAAA,EACZ;AAEA,MAAI,CAAC,QAAS,OAAM,IAAI,cAAc,KAAK;AAC3C,SAAO,KAAK,MAAM,KAAK;AACzB;AAEO,SAAS,eAAe,IAAoB;AACjD,MAAI,CAAC,OAAO,SAAS,EAAE,KAAK,KAAK,GAAG;AAClC,UAAM,IAAI,WAAW,4DAA4D,EAAE,EAAE;AAAA,EACvF;AAEA,MAAI,OAAO,EAAG,QAAO;AAErB,QAAM,QAA4B;AAAA,IAChC,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,MAAM,MAAM,EAAE;AAAA,EACjB;AAEA,QAAM,QAAkB,CAAC;AACzB,MAAI,YAAY,KAAK,MAAM,EAAE;AAE7B,aAAW,CAAC,MAAM,KAAK,KAAK,OAAO;AACjC,QAAI,aAAa,OAAO;AACtB,YAAM,QAAQ,KAAK,MAAM,YAAY,KAAK;AAC1C,YAAM,KAAK,GAAG,KAAK,GAAG,IAAI,EAAE;AAC5B,mBAAa;AAAA,IACf;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,GAAG;AACvB;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,59 @@
+// src/index.ts
+var UNITS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5,
+  w: 6048e5
+};
+var PARSE_RE = /(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)/g;
+var DurationError = class extends Error {
+  constructor(input) {
+    super(`Invalid duration string: "${input}"`);
+    this.name = "DurationError";
+  }
+};
+function parseDuration(input) {
+  const str = input.trim();
+  if (!str) throw new DurationError(input);
+  let total = 0;
+  let matched = false;
+  PARSE_RE.lastIndex = 0;
+  for (const match of str.matchAll(PARSE_RE)) {
+    total += parseFloat(match[1]) * UNITS[match[2]];
+    matched = true;
+  }
+  if (!matched) throw new DurationError(input);
+  return Math.round(total);
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new RangeError(`formatDuration expects a non-negative finite number, got ${ms}`);
+  }
+  if (ms === 0) return "0ms";
+  const units = [
+    ["w", UNITS.w],
+    ["d", UNITS.d],
+    ["h", UNITS.h],
+    ["m", UNITS.m],
+    ["s", UNITS.s],
+    ["ms", UNITS.ms]
+  ];
+  const parts = [];
+  let remaining = Math.round(ms);
+  for (const [unit, value] of units) {
+    if (remaining >= value) {
+      const count = Math.floor(remaining / value);
+      parts.push(`${count}${unit}`);
+      remaining %= value;
+    }
+  }
+  return parts.join(" ");
+}
+export {
+  DurationError,
+  formatDuration,
+  parseDuration
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["const UNITS: Record<string, number> = {\n  ms: 1,\n  s:  1_000,\n  m:  60_000,\n  h:  3_600_000,\n  d:  86_400_000,\n  w:  604_800_000,\n}\n\nconst PARSE_RE = /(\\d+(?:\\.\\d+)?)\\s*(ms|s|m|h|d|w)/g\n\nexport class DurationError extends Error {\n  constructor(input: string) {\n    super(`Invalid duration string: \"${input}\"`)\n    this.name = 'DurationError'\n  }\n}\n\nexport function parseDuration(input: string): number {\n  const str = input.trim()\n  if (!str) throw new DurationError(input)\n\n  let total = 0\n  let matched = false\n\n  PARSE_RE.lastIndex = 0\n  for (const match of str.matchAll(PARSE_RE)) {\n    total += parseFloat(match[1]) * UNITS[match[2]]\n    matched = true\n  }\n\n  if (!matched) throw new DurationError(input)\n  return Math.round(total)\n}\n\nexport function formatDuration(ms: number): string {\n  if (!Number.isFinite(ms) || ms < 0) {\n    throw new RangeError(`formatDuration expects a non-negative finite number, got ${ms}`)\n  }\n\n  if (ms === 0) return '0ms'\n\n  const units: [string, number][] = [\n    ['w', UNITS.w],\n    ['d', UNITS.d],\n    ['h', UNITS.h],\n    ['m', UNITS.m],\n    ['s', UNITS.s],\n    ['ms', UNITS.ms],\n  ]\n\n  const parts: string[] = []\n  let remaining = Math.round(ms)\n\n  for (const [unit, value] of units) {\n    if (remaining >= value) {\n      const count = Math.floor(remaining / value)\n      parts.push(`${count}${unit}`)\n      remaining %= value\n    }\n  }\n\n  return parts.join(' ')\n}\n"],"mappings":";AAAA,IAAM,QAAgC;AAAA,EACpC,IAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AAAA,EACJ,GAAI;AACN;AAEA,IAAM,WAAW;AAEV,IAAM,gBAAN,cAA4B,MAAM;AAAA,EACvC,YAAY,OAAe;AACzB,UAAM,6BAA6B,KAAK,GAAG;AAC3C,SAAK,OAAO;AAAA,EACd;AACF;AAEO,SAAS,cAAc,OAAuB;AACnD,QAAM,MAAM,MAAM,KAAK;AACvB,MAAI,CAAC,IAAK,OAAM,IAAI,cAAc,KAAK;AAEvC,MAAI,QAAQ;AACZ,MAAI,UAAU;AAEd,WAAS,YAAY;AACrB,aAAW,SAAS,IAAI,SAAS,QAAQ,GAAG;AAC1C,aAAS,WAAW,MAAM,CAAC,CAAC,IAAI,MAAM,MAAM,CAAC,CAAC;AAC9C,cAAU;AAAA,EACZ;AAEA,MAAI,CAAC,QAAS,OAAM,IAAI,cAAc,KAAK;AAC3C,SAAO,KAAK,MAAM,KAAK;AACzB;AAEO,SAAS,eAAe,IAAoB;AACjD,MAAI,CAAC,OAAO,SAAS,EAAE,KAAK,KAAK,GAAG;AAClC,UAAM,IAAI,WAAW,4DAA4D,EAAE,EAAE;AAAA,EACvF;AAEA,MAAI,OAAO,EAAG,QAAO;AAErB,QAAM,QAA4B;AAAA,IAChC,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,KAAK,MAAM,CAAC;AAAA,IACb,CAAC,MAAM,MAAM,EAAE;AAAA,EACjB;AAEA,QAAM,QAAkB,CAAC;AACzB,MAAI,YAAY,KAAK,MAAM,EAAE;AAE7B,aAAW,CAAC,MAAM,KAAK,KAAK,OAAO;AACjC,QAAI,aAAa,OAAO;AACtB,YAAM,QAAQ,KAAK,MAAM,YAAY,KAAK;AAC1C,YAAM,KAAK,GAAG,KAAK,GAAG,IAAI,EAAE;AAC5B,mBAAa;AAAA,IACf;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,GAAG;AACvB;","names":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@padmaj/duration",
+  "version": "1.0.0",
+  "description": "Parse and format duration strings. '2h30m' ↔ 9000000ms. Zero dependencies. TypeScript-first.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/padmajp4/duration.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": ["duration", "time", "parse", "format", "ms", "human-readable"],
+  "author": "Padmaj P Kumar",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}