duration-string v3.0.2

Duration String

A JavaScript library for working with time durations.

Highlights

• Supports TypeScript!
• Supports Node and browser
• Includes full JSX documentation
• Code weighs only 12kB

Installation

Node / TypeScript

npm install duration-string --save

Web

<script src="https://joker876.github.io/duration-string/dist/index.js"></script>

Usage

Duration String exports Duration class. It can be imported like this:

import { Duration } from 'duration-string';

Constructor

Constructor requires from 1 to 2 arguments:

new Duration(date1: Date, date2?: Date)

• date1 - the beginning date of the duration.
• date2 - the ending date of the duration. Optional, defaults to new Date().

If the dates are placed in the wrong order, i.e. beggining date is higher than ending date, they are swapped and saved in the correct order.

Static methods

Duration.fromNumber(ms: number)

Requires one argument:

• ms - the duration in milliseconds.

It will return a new Duration instance, with the starting date being new Date(0), and ending date being new Date(ms).

Instance methods

Duration.prototype.valueOf()

Returns the duration in milliseconds.

Duration.prototype.toString(ommit_empty?: boolean, threshold?: number)

Returns the duration, converted to a human-readable format. Example output may be: 1y 1m 1d 1h 1min 1s 1ms

There are two possible arguments:

• ommit_empty - if the value near the unit is equal to 0, it is ommitted, and not added to the final string.
• threshold - if set to a number higher than 0, it trims that many lowest units from the value.

// Examples

let duration = new Duration(new Date('2020-01-01T03:24:01'), new Date('2021-01-24T08:11:56.176');

duration.toString()         // 1y 0m 24d 3h 47min 55s 176ms
duration.toString(true)     // 1y 24d 3h 47min 55s 176ms
duration.toString(false, 3) // 1y 0m 24d 3h

Duration.prototype.toSimple()

Returns the highest non-zero unit, and returns it.

It returns an array containing the value of the unit and the unit as two separate elements.

Duration.prototype.formattedString(format: string)

When given a string, formats the duration according to the given pattern. Certain patterns are replaced with real values, which are the properties of that Duration instance. The patterns are:

• Standard patterns:
  • {{y}} - Duration.prototype.trailing_years
  • {{m}} - Duration.prototype.trailing_months
  • {{w}} - Duration.prototype.trailing_weeks
  • {{d}} - Duration.prototype.trailing_days
  • {{h}} - Duration.prototype.trailing_hours
  • {{min}} - Duration.prototype.trailing_minutes
  • {{s}} - Duration.prototype.trailing_seconds
  • {{ms}} - Duration.prototype.trailing_milliseconds
• Total patterns:
  • {{Y}} - Duration.prototype.years
  • {{M}} - Duration.prototype.months
  • {{W}} - Duration.prototype.weeks
  • {{D}} - Duration.prototype.days
  • {{H}} - Duration.prototype.hours
  • {{MIN}} - Duration.prototype.minutes
  • {{S}} - Duration.prototype.seconds
  • {{MS}} - Duration.prototype.milliseconds

Total patterns are replaced with floating-point values, rounded to integers by default. This can, however, be changed by adding a number after the name, separated with the pipe (|) character, such as: {{H:4}}. The number defines how many decimal places should the value be rounded to.

//Examples
let duration = new Duration(new Date('2020-01-01T03:24:01'), new Date('2021-01-24T08:11:56.176');

duration.formattedString('{{h}}:{{min}}')        // 4:47
duration.formattedString('{{H}}h ago')           // 9341h ago
duration.formattedString('{{D:5}} days')         // 389.19994 days

Duration.prototype.getOverlapDuration(duration: Duration)

Returns a new instance of Duration in which the two durations overlap.

If there is no overlap, returns a duration of 0 ms.

• duration - the second duration, used to calculate the overlap. Required. Must be an instance of Duration.

Instance properties

All instances of Duration have the properties listed in the table.

All examples below are for the following duration:

let duration = new Duration(new Date('2020-01-01T03:24:01'), new Date('2021-03-24T08:11:56.176');