duration-cls

Durations with nanosecond precision for TypeScript and JavaScript. Supports finite and infinite durations (±Infinity), arithmetic, comparisons, and safe serialisation for values larger than Number.MAX_SAFE_INTEGER.

Installation

npm i duration-cls

Quick start

import { Duration } from 'duration-cls'

// Create durations
const a = new Duration({ seconds: 5, nanoseconds: 500 })
const b = new Duration({ milliseconds: 1500 })

// Operations
const sum = a.plus(b)
const diff = a.minus(b)
const scaled = a.times(2)
const ratio = a.div(b) // number

// Comparisons
if (sum.greaterThan(b)) { /* ... */ }

// Components and representation
console.log(sum.toString())
console.log(sum.toIsoString())
console.log(JSON.stringify(sum)) // safe serialisation

Main API

• Constructor: new Duration(options) — options is a partial set of components: weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds (numbers or bigint).
• Static properties:
  • Duration.POSITIVE_INFINITY
  • Duration.NEGATIVE_INFINITY
  • Duration.ZERO
  • Duration.between(start: Date, end: Date)
• Getters (total values as integers):
  • inWholeWeeks
  • inWholeDays
  • inWholeHours
  • inWholeMinutes
  • inWholeSeconds
  • inWholeMilliseconds
  • inWholeMicroseconds
  • inWholeNanoseconds
• Queries:
  • isInfinite()
  • isFinite()
  • isPositive()
  • isNegative()
• Arithmetic:
  • plus(other)
  • minus(other)
  • times(scale: number)
  • div(other: Duration): number, div(scale: number): Duration
  • unaryMinus()
  • absoluteValue()
• Comparisons:
  • equals(other)
  • greaterThan(other)
  • lessThan(other)
  • greaterThanOrEqual(other)
  • lessThanOrEqual(other)
• Serialisation and representation:
  • toComponents(action)
  • toIsoString()
  • toJSON()
  • toString()