Tiny (~500 bytes) time math library for making date handling and TTLs within your APIs beautiful.
Features
- Tiny @ ~500 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
WARNING - pre-release
This API, specifically around the naming of exposed functions may likely change in the next few days. In the meantime, use/play at your own risk. API changes will be broadcasted here and on Discord.
CHANGELOG - pre-release
- v0.1.x to v0.2.x - renamed:
getTTL-->getSeconds,getDatePlus-->datePlus, added optional "from" param todatePlus.// old getTTL('1 hour') // new getSeconds('1 hour') // old getDatePlus('1 hour') // new datePlus('1 hour') // added functionality datePlus('1 hour', optionalDate?: Date)
Example
import { getSeconds, divide, datePlus } from 'itty-time' // under 600 bytes
// Easily get TTL in seconds
getSeconds('3 hours') // 10800
// Complicated bits? No problem. (Oxford comma optional)
getSeconds('1 day, 4 hours, and 36 minutes') // 102960
// Need an expiration date?
datePlus('5 seconds') // 2022-10-22T23:10:11.824Z
datePlus('1 minutes') // 2022-10-22T23:11:06.824Z
datePlus('2 months') // 2022-12-23T00:11:58.534Z
datePlus('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
getSeconds(duration: string): number
Returns the number of seconds (as you typically need within a TTL) in the duration string.
getSeconds('3 hours') // 10800
getSeconds('1 day, 4 hours, and 36 minutes') // 102960
datePlus(duration: string, from?: Date): Date
Adds a duration to a date (default is Date.now()), returning the future date.
datePlus('5 seconds') // 2022-10-22T23:10:11.824Z
datePlus('1 minutes') // 2022-10-22T23:11:06.824Z
datePlus('2 months') // 2022-12-23T00:11:58.534Z
datePlus('4 years') // 2026-10-22T23:11:58.534Z
// or from another date
datePlus('1 minutes', datePlus('1 year')) // 2023-10-22T23:11:06.824Z
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
6 Dec 16, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
5 Dec 23, 2022
2 Jun 9, 2022
3 Jun 30, 2022
4 Jul 17, 2022
37 Jan 1, 2023
26 Dec 25, 2022