diff --git a/README.md b/README.md index ed4bad4..cfea9c0 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,15 @@ such as '-0200' or '+04:00', but not IANA time zone names. **Note:** `date-fns` is a peer dependency of this library. +If you find this library useful, why not + +Buy Me A Coffee + ## Table of Contents - [Overview](#overview) - [Date and time zone formatting](#date-and-time-zone-formatting) - - [`formatAsZonedTime`](#formataszonedtime) - Formats a date in the provided time zone, + - [`formatInTimeZone`](#formataszonedtime) - Formats a date in the provided time zone, regardless of the system time zone - [Time zone offset helpers](#time-zone-offset-helpers) - [`zonedTimeToUtc`](#zonedtimetoutc) - Given a date and any time zone, returns a `Date` with the equivalent UTC time @@ -48,7 +52,7 @@ common time zone related use cases. ## Date and time zone formatting -### `formatAsZonedTime` +### `formatInTimeZone` This function takes a `Date` instance in the system's local time or an ISO8601 string, and an IANA time zone name or offset string. It then formats this date in the target time zone @@ -62,24 +66,27 @@ It supports the same format tokens as `date-fns/format`, and adds full support f Unlike `date-fns/format`, the `z..zzzz`, `x..xxxxx`, `X..XXXXX` and `O..OOO` tokens will all print the formatted value of the provided time zone rather than the system time zone. +An invalid date or time zone input will result in an `Invalid Date` passed to `date-fns/format`, +which will throw a `RangeError`. + For most use cases this is the only function from this library you will need. ```javascript -import { formatAsZonedTime } from 'date-fns-tz' +import { formatInTimeZone } from 'date-fns-tz' const date = new Date('2014-10-25T10:46:20Z') -formatAsZonedTime(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ssXXX') // 2014-10-25 06:46:20-04:00 -formatAsZonedTime(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 06:46:20 EST -formatAsZonedTime(date, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 10:46:20 GMT+2 +formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ssXXX') // 2014-10-25 06:46:20-04:00 +formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 06:46:20 EST +formatInTimeZone(date, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 10:46:20 GMT+2 // The time zone name is generated by the Intl API which works best when a locale is also provided import enGB from 'date-fns/locale/en-GB' -formatAsZonedTime(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz', { locale: enGB }) +formatInTimeZone(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz', { locale: enGB }) // 2014-10-25 10:46:20 CEST -formatAsZonedTime(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzzz', { locale: enGB }) +formatInTimeZone(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzzz', { locale: enGB }) // 2014-10-25 10:46:20 Central European Summer Time ``` @@ -95,6 +102,7 @@ this local time should be shown when accessing the site from anywhere in the wor ### `zonedTimeToUtc` Given a date and any time zone, returns a `Date` with the equivalent UTC time. +An invalid date string or time zone will result in an `Invalid Date`. ```ts zonedTimeToUtc(date: Date|Number|String, timeZone: String): Date @@ -120,6 +128,7 @@ postToServer(utcDate.toISOString(), timeZone) // post 2014-06-25T17:00:00.000Z, ### `utcToZonedTime` Returns a `Date` which will format as the local time of any time zone from a specific UTC time. +An invalid date string or time zone will result in an `Invalid Date`. ```js utcToZonedTime(date: Date|Number|String, timeZone: String): Date @@ -155,6 +164,8 @@ For time zones where daylight savings time is applicable a `Date` should be pass the second parameter to ensure the offset correctly accounts for DST at that time of year. When omitted, the current date is used. +For invalid time zones, `NaN` is returned. + ```javascript import { getTimezoneOffset } from 'date-fns-tz' @@ -172,7 +183,7 @@ const result = getTimezoneOffset('America/New_York', new Date(2016, 6, 1)) ### `format` -The `format` function exported from this library is used under the hood by `formatAsZonedTime` +The `format` function exported from this library is used under the hood by `formatInTimeZone` and extends `date-fns/format` with full time zone support for: - The `z..zzz` Unicode tokens: _short specific non-location format_ @@ -188,12 +199,14 @@ zone (if provided, see below) rather than the system time zone. Since a JavaScript `Date` instance cannot convey the time zone information to the `format` function it is necessary to pass the `timeZone` value as an option on the third argument of `format`. +Similar to `date-fns/format`, when an invalid date or time zone is used a `RangeError` is thrown. + To format a date showing time for a specific time zone other than the system time zone, the -`format` function can be combined with `utcToZonedTime`. This is what `formatAsZonedTime` does +`format` function can be combined with `utcToZonedTime`. This is what `formatInTimeZone` does internally. _To clarify, the `format` function will never change the underlying date, it must be changed to a zoned time before passing it to `format`._ -In most cases there is no need to use `format` rather than `formatAsZonedTime`. The only time +In most cases there is no need to use `format` rather than `formatInTimeZone`. The only time this makes sense is when `utcToZonedTime` has been applied to a date once, and you want to format it multiple times to different outputs. @@ -229,6 +242,8 @@ format(parisDate, 'yyyy-MM-dd HH:mm:ss zzzz', { The `toDate` function can be used to parse a `Date` from a string containing a date and time representing time in any time zone by providing an IANA time zone name on the `timeZone` option. +An invalid date string or time zone will result in an `Invalid Date`. + ```javascript import { toDate, format } from 'date-fns-tz'