๐ A zero dependency, date utility library that uses the native Intl.DateTimeFormat
api to work with Date
objects.
pnpm install @n8io/date
Don't take my word for it, play with the demo examples.
- Zero dependencies, has a tiny footprint with no extra bloat from time zone data
- Works with all IANA time zones
- Accounts for daylight savings time for time zones that observe it
- Uses the native
Intl.DateTimeFormat
api for all calculations - We only deal with native
Date
objects, no monkey patching data types
This function generates a specifically configured instance of a Intl.DateTimeFormat
that is used to determine time zone relative dates.
Please note that creating an instance of the formatter can be an expensive operation and should be done sparingly. This is especially important to keep in mind for scenarios that need to be as fast as possible.
import { makeTimeZoneOffsetFormatter } from '@n8io/date'
const timeZone = 'America/New_York'
const formatter = makeTimeZoneOffsetFormatter(timeZone)
formatter.format(new Date('2023-01-01T05:00:00.000Z')) // 01/01/2023, 00:00:00
This function returns the UTC offset in minutes for a given date and time zone.
import { getTimeZoneUtcOffsetInMinutes } from '@n8io/date'
const timeZone: IanaTimeZone = 'America/New_York'
const formatter = makeTimeZoneOffsetFormatter(timeZone)
const januaryDate = new Date('2023-01-01T12:00:00.000Z')
const julyDate = new Date('2023-07-01T12:00:00.000Z')
// The offset in minutes in January for America/New_York is...
getTimeZoneUtcOffsetInMinutes(januaryDate, formatter)
// -300 because the date is during daylight savings time
// The offset in minutes in July for America/New_York is...
getTimeZoneUtcOffsetInMinutes(julyDate, formatter)
// -240 because the date is during standard time
This function is handy when you need a specific date and time in a specific time zone.
NOTE: The plain date string must be in yyyy-mm-dd hh:mm:ss
format
import { makeTimeZoneOffsetFormatter, plainDateStringToTimeZoneDate } from '@n8io/date'
const timeZone = 'America/New_York'
const formatter = makeTimeZoneOffsetFormatter(timeZone)
const date = plainDateStringToTimeZoneDate(
'2023-01-01 20:00:00',
formatter,
)
date.toLocalString('en', { timeZone }) // 1/1/2023, 8:00:00 PM in New York
date.toISOString() // '2023-01-02T01:00:00.000Z'
We welcome contributions from the community. If you'd like to contribute to this project, please follow these steps:
- Fork the repository.
- Create a new branch for your feature or bug fix.
- Make your changes and write tests if applicable.
- Commit your changes and push them to your fork.
- Open a pull request to the main repository.