Tiny (~530 bytes) time math library for making date handling and TTLs within your APIs beautiful.

Features

Tiny @ ~530 bytes gzipped total, and tree-shakeable even further.
Fully typed/TypeScript support
Use plain text strings to describe time, not seconds/milliseconds
Get TTLs
Get future dates
Divide durations

Example

import { getTTL, divide, getDatePlus } from 'itty-time' // under 600 bytes

// Easily get TTL in seconds
getTTL('3 hours') // 10800

// Complicated bits?  No problem.  (Oxford comma optional)
getTTL('1 day, 4 hours, and 36 minutes') // 102960

// Need an expiration date?
getDatePlus('5 seconds') // 2022-10-22T23:10:11.824Z
getDatePlus('1 minutes') // 2022-10-22T23:11:06.824Z
getDatePlus('2 months') // 2022-12-23T00:11:58.534Z
getDatePlus('4 years') // 2026-10-22T23:11:58.534Z

// Want to find out how many X are in Y?
divide('1 week').by('days') // 7
divide('2 minutes').by('seconds') // 120
divide('3 days').by('hours') // 72
divide('1 day').by('3 hours') // 8
divide('1 week').by('seconds') // 604800
divide('24 hours').by('minutes') // 1440
divide('3 days').by('hours') // 72
divide('1 day, 30 minutes').by('hours') // 24.5

DISCLAIMER: This is a CONVENIENCE library for making short, readable code.

If you need absolute max performance for iterative work in a single thread, do the operations manually. That's always faster.

Otherwise, you'll probably never feel the difference, but your code sure will! <3

API

`getTTL(duration: string): number`

Returns the number of seconds (as you typically need within a TTL) in the duration string.

getTTL('3 hours') // 10800
getTTL('1 day, 4 hours, and 36 minutes') // 102960

`getDatePlus(duration: string): Date`

Returns a Date object, from Date.now(), with the duration added. So a date from the future.

getDatePlus('5 seconds') // 2022-10-22T23:10:11.824Z
getDatePlus('1 minutes') // 2022-10-22T23:11:06.824Z
getDatePlus('2 months') // 2022-12-23T00:11:58.534Z
getDatePlus('4 years') // 2026-10-22T23:11:58.534Z

`divide(duration1: string).by(duration2: string): number`

Divides one duration by another, in a nice, readable manner.

divide('1 week').by('days') // 7
divide('2 minutes').by('seconds') // 120
divide('3 days').by('hours') // 72
divide('1 day').by('3 hours') // 8
divide('1 week').by('seconds') // 604800
divide('24 hours').by('minutes') // 1440
divide('3 days').by('hours') // 72
divide('1 day, 30 minutes').by('hours') // 24.5

Crisfole/itty-time

README