date-fns-tz - npm Package Compare versions

Comparing version 1.0.8 to 1.0.9

package.json

 {
   "name": "date-fns-tz",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "sideEffects": false,
@@ -5,0 +5,0 @@ "description": "Time zone support for date-fns v2 with the browser Intl API",

README.md

 # date-fns-tz
 
-Time zone support for [date-fns](https://date-fns.org/) v2.0.0.
-
-Dependency free IANA time zone support is implemented via the
-[Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) to keep 
-actual time zone data out of code bundles. Modern browsers all support the 
+Time zone support for [date-fns](https://date-fns.org/) v2.0.0 using the
+[Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). By using
+the browser API no time zone data needs to be included in code bundles. Modern browsers all support the
 [necessary features](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Browser_compatibility),
@@ -14,6 +12,2 @@ and for those that don't a [polyfill](https://github.com/yahoo/date-time-format-timezone) can be used.
 
-*This work was initially proposed in PR [date-fns/#707](https://github.com/date-fns/date-fns/pull/707), but won't
-be considered until `date-fns` version 2 has been released. It is my hope that these features will eventually 
-make it into `date-fns` or at least contribute to the conversation and that this project will be deprecated.* 
-
 ## Table of Contents
@@ -23,3 +17,3 @@
 - [Time Zone Helpers](#time-zone-helpers)
-    - [`zonedTimeToUtc`](#zonedtimetoutc) - Get the UTC date/time from a date representing local time in a given time zone
+    - [`zonedTimeToUtc`](#zonedtimetoutc) - Given a date and any time zone, returns a `Date` with the equivalent UTC time
     - [`utcToZonedTime`](#utctozonedtime) - Get a date/time representing local time in a given time zone from the UTC date
@@ -29,2 +23,3 @@ - [Time Zone Formatting](#time-zone-formatting)
     - [`toDate`](#todate) - Can be used to create a zoned Date from a string containing an offset or IANA time zone
+- [Usage with Node.js](#usage-with-nodejs)
 
@@ -34,13 +29,13 @@ ## Overview
 Working with UTC or ISO date strings is easy, and so is working with JS dates when all times
-are displayed in a user's local time in the browser. The difficulty comes when working with another 
-time zone's local time, other than the current system's, like on a Node server or when showing the time 
+are displayed in a user's local time in the browser. The difficulty comes when working with another
+time zone's local time, other than the current system's, like on a Node server or when showing the time
 of an event in a specific time zone, like an event in LA at 8pm PST regardless of where a user resides.
 
-In this case there are two relevant pieces of information: 
+In this case there are two relevant pieces of information:
  - a fixed moment in time in the form of a timestamp, UTC or ISO date string, and
  - the time zone descriptor, usually an offset or IANA time zone name (e.g. `America/New_York`).
 
-Libraries like Moment and Luxon, which provide their own date time classes, manage these timestamp and time 
-zone values internally. Sine `date-fns` always returns a plain JS Date, which implicitly has the current 
-system's time zone, helper functions are provided for handling common time zone related use cases. 
+Libraries like Moment and Luxon, which provide their own date time classes, manage these timestamp and time
+zone values internally. Sine `date-fns` always returns a plain JS Date, which implicitly has the current
+system's time zone, helper functions are provided for handling common time zone related use cases.
 
@@ -50,3 +45,3 @@ ## Time Zone Helpers
 To discuss the usage of the time zone helpers let's assume we're writing a system where administrators set
-up events which will be start at a specific time in the venue's local time, and this local time should be 
+up events which will start at a specific time in the venue's local time, and this local time should be
 shown when accessing the site from anywhere in the world.
@@ -56,3 +51,3 @@
 
-**Get a date with the correct UTC time for the date/time in a specific time zone**
+**Given a date and any time zone, returns a `Date` with the equivalent UTC time**
 
@@ -63,5 +58,5 @@ ```js
 
-Say a user is asked to input the date/time and time zone of an event. A date/time picker will typically 
-return a Date instance with the chosen date, in the user's local time zone, and a select input might 
-provide the actual IANA time zone name. 
+Say a user is asked to input the date/time and time zone of an event. A date/time picker will typically
+return a Date instance with the chosen date, in the user's local time zone, and a select input might
+provide the actual IANA time zone name.
 
@@ -73,3 +68,3 @@ In order to work with this info effectively it is necessary to find the equivalent UTC time:
 
-const date = getDatePickerValue()     // e.g. 2014-06-25 10:00:00 (picked in any time zone) 
+const date = getDatePickerValue()     // e.g. 2014-06-25 10:00:00 (picked in any time zone)
 const timeZone = getTimeZoneValue()   // e.g. America/Los_Angeles
@@ -91,3 +86,3 @@
 Say the server provided a UTC date/time and a time zone which should be used as initial values for the above form.
-The date/time picker will take a Date input which will be in the user's local time zone, but the date value 
+The date/time picker will take a Date input which will be in the user's local time zone, but the date value
 must be that of the target time zone.
@@ -110,10 +105,21 @@
 
-The `format` function exported from this library extends `date-fns/format` with full time zone support:
+The `format` function exported from this library extends `date-fns/format` with full time zone support for:
 
 - The `z..zzz` Unicode tokens: *short specific non-location format*
 - The `zzzz` Unicode token: *long specific non-location format*
-- Using the name of any IANA time zone or offset by specifying a `timeZone` option;
-  when using this option the `x..xxxxx`, `X..XXXXX` and `O..OOO` tokens will also use the provided
-  time zone rather than the system time zone.
 
+When using those tokens with `date-fns/format` it falls back to GMT timezones, and always uses the local
+system timezone. For example `zzz` in New York would return `GMT-4` instead of the desired `EST`, whereas
+this extended `format` function will return the latter.
+
+To format a date to a string showing time for a specific time zone, which can be different from the system
+time zone, the `format` function can be combined with `utcToZonedTime` as shown in the example below. *To
+clarify, the `format` function will never change the underlying date, it must be changed to a zoned time
+before passing it to `format`.*
+
+Since a zoned time `Date` instance cannot convey the time zone information to the `format` function it is
+necessary to pass the same `timeZone` value as an option on the third argument of `format`. When using this
+option the `z..zzzz`, `x..xxxxx`, `X..XXXXX` and `O..OOO` tokens will all print the provided time zone rather
+than the system time zone.
+
 ```javascript
@@ -135,16 +141,12 @@ import { format, utcToZonedTime } from 'date-fns-tz'
 import enGB from 'date-fns/locale/en-GB'
-enGB.code = 'en-GB'
-format(parisDate, 'yyyy-MM-dd HH:mm:ss zzz', { timeZone: 'Europe/Paris', locale: enGB }) 
+
+format(parisDate, 'yyyy-MM-dd HH:mm:ss zzz', { timeZone: 'Europe/Paris', locale: enGB })
 // 2014-10-25 10:46:20 CEST
-format(parisDate, 'yyyy-MM-dd HH:mm:ss zzzz', { timeZone: 'Europe/Paris', locale: enGB }) 
+format(parisDate, 'yyyy-MM-dd HH:mm:ss zzzz', { timeZone: 'Europe/Paris', locale: enGB })
 // 2014-10-25 10:46:20 Central European Summer Time
 ```
 
-**Caveat:** Note that when using a locale the language code of the locale should be added to the import
-somewhere in the project so `format` can identify the locale. Once this library is absorbed into `date-fns`
-this can be added to each locale natively.
-
 ### `toDate`
 
-The `toDate` function can be used to create a zoned Date from a string containing an offset or IANA 
+The `toDate` function can be used to create a zoned Date from a string containing an offset or IANA
 time zone, or by providing the `timeZone` option.
@@ -175,18 +177,20 @@
 
+## Usage with Node.js
+
+Node.js supports the `Intl` API. From v13 Node.js ships with full ICU data included in the binary, however
+the current LTS version 12.14 is still built with the `small-icu` flag and only contains ICU data for the
+`en-US` locale. To use this library with Node.js 12 and any locale other than `en-US` it should be run
+with
+[ICU data provided at runtime](https://nodejs.org/docs/latest-v12.x/api/intl.html#intl_providing_icu_data_at_runtime).
+
 ## Credit
 
 The idea of using the Intl API for time zone support was inspired by the [Luxon](https://github.com/moment/luxon)
-library. 
+library.
 
-The initial port of the idea into date-fns was done by [@benmccan](https://github.com/benmccann) in 
+The initial port of the idea into date-fns was done by [@benmccan](https://github.com/benmccann) in
 [date-fns/#676](https://github.com/date-fns/date-fns/pull/676).
 
-## Alternatives
-
-The [`date-fns-timezone`](https://github.com/prantlf/date-fns-timezone) library provides similar functionality
-for `date-fns` version 1 by bundling time zone data. This does have the advantage of making parsing time zone 
-long and short names possible.
-
 ## License
 
 MIT © Marnus Weststrate

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

166822

increased by0.19%

Number of lines in readme file

185

increased by2.21%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes