TypeScript icon, indicating that this package has built-in type declarations

1.0.6 • Public • Published


Version Bundle Size Coverage Status Issues Discord

Ultra-small (~390 bytes) library for TTL date math and converting ms durations to and from strings.


  • Tiny. The entire library is ~390 bytes, and fully tree-shakeable.
  • Convert string durations to ms/seconds.
  • Convert ms to human-readable string durations.
  • Add durations to dates.

Comparison to other top-rated libraries

library string to ms ms to string date math size1
itty-time 391b
@lukeed/ms 435b
ms 938b
pretty-ms 1.04kB
humanize-duration 6.74kB

1: minified and gzipped  


The only function most folks care about in terms of raw performance is string to ms conversion. In this, itty stacks up pretty well, being significantly faster than ms, but falling to the insanely-optimized @lukeed/ms.


Moral of the story, probably don't use ms.

Use Luke's if you want the absolute fastest parsing, or itty if you want some of the other functions as well. If you're byte-counting, itty wins again, but if you're byte-counting that hard, you're probably better off with raw ms math if you can stomach it.


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


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.3kB1, it's over 20x the size of this 280 byte function.

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

import { duration } from 'itty-time'

// "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(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')

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

Package Sidebar


npm i itty-time

Weekly Downloads






Unpacked Size

19.2 kB

Total Files


Last publish


  • krwhitley