@philiprehberger/duration-ts

Parse, format, and manipulate time durations

Installation

npm install @philiprehberger/duration-ts

Usage

import { duration, Duration } from '@philiprehberger/duration-ts';

const timeout = duration('5m 30s');
timeout.toMilliseconds(); // 330000
timeout.humanize();       // "5 minutes, 30 seconds"
timeout.toISO();          // "PT5M30S"

duration('1h').add('30m').short(); // "1h 30m"
Duration.between(start, end).toSeconds(); // 42.5

Parsing

duration('2h 30m');     // human format
duration('PT2H30M');    // ISO 8601
duration(9000000);      // milliseconds

Arithmetic

duration('1h')
  .add('30m')
  .subtract('15m')
  .multiply(2)
  .humanize(); // "2 hours, 30 minutes"

Relative Time

duration('2d').toRelative();      // "2 days ago"
duration('-3h').toRelative();     // "in 3 hours"
duration('500ms').toRelative();   // "just now"

Clamping

duration('5m').clamp('1m', '3m').humanize();  // "3 minutes"
duration('30s').clamp('1m', '1h').humanize(); // "1 minute"

Quantization

duration('1m 30s').roundTo('m').humanize(); // "2 minutes"
duration('7h').roundTo('d').humanize();     // "0 milliseconds"
duration('14h').roundTo('d').humanize();    // "1 day"

Between Two Dates

const start = new Date('2026-01-01');
const end = new Date('2026-01-03');
Duration.between(start, end).humanize(); // "2 days"
Duration.between(start, end).toRelative(); // "2 days ago"

API

| Method | Description | |--------|-------------| | duration(input) | Create from string or milliseconds | | Duration.between(a, b) | Duration between two dates | | .humanize() | "2 hours, 30 minutes" | | .short() | "2h 30m" | | .toISO() | "PT2H30M" | | .toRelative() | "2 days ago", "in 3 hours", "just now" | | .toMilliseconds() / .toSeconds() / .toMinutes() / .toHours() / .toDays() | Convert to number | | .add(other) / .subtract(other) | Arithmetic | | .multiply(n) / .divide(n) / .abs() | Arithmetic | | .clamp(min, max) | Constrain duration within bounds | | .roundTo(unit) | Round to nearest unit (ms, s, m, h, d, w) | | .equals(other) / .isLongerThan(other) / .isShorterThan(other) / .isZero() | Comparison |

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT