itty-time

v1 Documentation  |   Discord

---

Ultra-small (~450 bytes) library for simplifying date math and TTLs.

Features

• Tiny. The entire library is ~450 bytes, or take only what you need.
• Use text strings (including multi-part) to describe durations.
• Add durations to dates.
• Get human-readable durations from ms duration.
• Works everywhere.

Comparison to other top-rated libraries

library	string to ms	ms to string	multi-part	date math	size1	relative size2
itty-time	✅	✅	✅	✅	450b	1.05x
@lukeed/ms3	✅	✅	❌	❌	428b	1x
ms	✅	❌	❌	❌	938b	2.04x
pretty-ms	❌	✅	✅	❌	1.04kB	2.31x
humanize-duration	❌	✅	✅	❌	6.74kB	15x

^{1: minified and gzipped   2: smaller is better   3: this ~2x the speed for single-unit parsing}

---

seconds/ms

seconds(duration: string) => number
ms(duration: string) => number

TTL math is a maintenance nightmare. It's a pain to write, a pain to read, and when you update the math later, you'll probably forget to update the comment, causing all sorts of mayhem.

const TTL = 2 * 7 * 24 * 60 * 60 * 1000 // 2 weeks, right?

Here's a better way.

import { ms, seconds } from 'itty-time'

// to seconds
seconds('2 weeks') // 1209600

// to milliseconds
ms('2 weeks') // 1209600000

// handles multi-part inputs :)
ms('3 days, 2.5 hours, and 1 minute') // 268260000

duration

duration(ms: number) => string

Of course, we sometimes need to go the other direction. Want to tell a user how long ago something happened? How much time they have left?

You could build it yourself, or import the fantastic humanize-duration library that inspired this, but at 6.3kB¹, it's 20x the size of this function (300 bytes).

^{1: of course humanize-duration can also do much, much more.}

import { duration } from 'itty-time'

duration(3750000)
// "1 hour, 2 minutes, 30 seconds"

// limit number of segments returned
duration(3750000, { parts: 2 })
// "1 hour, 2 minutes"

// change the delimiter
duration(3750000, { join: ' --> ' })
// "1 hour --> 2 minutes --> 30 seconds"

// or get the raw components
duration(3750000, { join: false })
/*
  [
    ['hour', 1],
    ['minutes', 2],
    ['seconds', 30]
  ]
/*

datePlus

datePlus(duration: string, from = new Date) => Date

Sometimes you need a TTL for some point in the future, but sometimes you need the actual date. You could convert it all yourself... or use this.

import { datePlus } from 'itty-time'

// from right now
datePlus('2 months, 1 week')

// or from a different date
datePlus('2 months', datePlus('1 week'))