date-fns-timezone - npm Package Compare versions

Comparing version 0.0.1 to 0.1.0

dist/formatToTimeZone.js

@@ -7,3 +7,2 @@ 'use strict';
 
-var parse = _interopDefault(require('date-fns/parse'));
 var formatDate = _interopDefault(require('date-fns/format'));
@@ -81,3 +80,3 @@ var timezoneSupport = require('timezone-support');
  * @param {Date|String|Number} date - the original date
- * @param {String} [format='YYYY-MM-DDTHH:mm:ss.SSSZ'] - the string of tokens
+ * @param {String} formatString - the string of formatting tokens
  * @param {Object} options - the object with options
@@ -109,6 +108,5 @@ * @param {Object} [options.locale=enLocale] - the locale object
 
-function formatToTimeZone(date, format, options) {
+function formatToTimeZone(date, formatString, options) {
   var timeZone = options.timeZone,
       convertTimeZone = options.convertTimeZone;
-  date = parse(date);
   timeZone = timezoneSupport.findTimeZone(timeZone);
@@ -122,4 +120,4 @@ timeZone = timezoneSupport.getUTCOffset(date, timeZone);
 
-  format = formatTimeZoneTokens(format, timeZone);
-  return formatDate(date, format, options);
+  formatString = formatTimeZoneTokens(formatString, timeZone);
+  return formatDate(date, formatString, options);
 }
@@ -126,0 +124,0 @@

dist/index.js

@@ -9,2 +9,4 @@ 'use strict';
 var timezoneSupport = require('timezone-support');
+var parseFormat = require('timezone-support/dist/parse-format');
+var lookupConvert = require('timezone-support/dist/lookup-convert');
 var formatDate = _interopDefault(require('date-fns/format'));
@@ -83,20 +85,101 @@
  * @category Common Helpers
- * @summary Convert the given argument to an instance of Date from the specified time zone.
+ * @summary Parse the date string and convert it to the local time.
  *
  * @description
- * Parse the given argument to an instance of Date and convert it from the specified time zone to the local time.
+ * Return the date parsed from the date string, using the given format string, and convert the parsed date to the local time.
  *
- * If the argument is an instance of Date, the function returns its clone.
+ * The following tokens will be recognized in the format string then:
  *
- * If the argument is a number, it is treated as a timestamp.
+ * | Token  | Input example    | Description                       |
+ * |--------|------------------|-----------------------------------|
+ * | `YY`   | 18               | Two-digit year                    |
+ * | `YYYY` | 2018             | Four-digit year                   |
+ * | `M`    | 1-12             | Month, beginning at 1             |
+ * | `MM`   | 01-12            | Month, 2-digits                   |
+ * | `D`    | 1-31             | Day of month                      |
+ * | `DD`   | 01-31            | Day of month, 2-digits            |
+ * | `H`    | 0-23             | Hours                             |
+ * | `HH`   | 00-23            | Hours, 2-digits                   |
+ * | `h`    | 1-12             | Hours, 12-hour clock              |
+ * | `hh`   | 01-12            | Hours, 12-hour clock, 2-digits    |
+ * | `m`    | 0-59             | Minutes                           |
+ * | `mm`   | 00-59            | Minutes, 2-digits                 |
+ * | `s`    | 0-59             | Seconds                           |
+ * | `ss`   | 00-59            | Seconds, 2-digits                 |
+ * | `S`    | 0-9              | Hundreds of milliseconds, 1-digit |
+ * | `SS`   | 00-99            | Tens of milliseconds, 2-digits    |
+ * | `SSS`  | 000-999          | Milliseconds, 3-digits            |
+ * | `z`    | EST              | Time zone abbreviation            |
+ * | `Z`    | -5:00            | Offset from UTC, 2-digits         |
+ * | `ZZ`   | -0500            | Compact offset from UTC, 2-digits |
+ * | `A`    | AM PM            | Post or ante meridiem, upper-case |
+ * | `a`    | am pm            | Post or ante meridiem, lower-case |
  *
- * If an argument is a string, the function tries to parse it.
- * Function accepts complete ISO 8601 formats as well as partial implementations.
- * ISO 8601: http://en.wikipedia.org/wiki/ISO_8601
+ * To escape characters in the format string, wrap them in square brackets (e.g. `[G]`). Punctuation symbols (-:/.()) do not need to be wrapped.
  *
- * If all above fails, the function passes the given argument to Date constructor.
+ * The time zone has to be specified as a canonical name from the [IANA time zone list]{@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.
  *
+ * @param {String} dateString - the value to convert
+ * @param {String} formatString - the custom format to parse the date from
+ * @returns {Date} the parsed date in the local time zone
+ *
+ * @example
+ * // Parse string '11.2.2014 11:30:30' to date in Berlin:
+ * var result = parseFromTimeZone('11.2.2014 11:30:30', 'D.M.YYYY H:mm:ss')
+ * //=> Tue Feb 11 2014 10:30:30 UTC
+ *
+ * // Parse string '02/11/2014 11:30:30' to date, New York time:
+ * var result = parseFromString('02/11/2014 11:30:30 AM GMT-0500 (EDT)',
+ *   'MM/DD/YYYY h:mm:ss.SSS A [GMT]ZZ (z)')
+ * //=> Tue Feb 11 2014 16:30:30 UTC
+ */
+
+function parseFromString(dateString, formatString) {
+  var time = parseFormat.parseZonedTime(dateString, formatString);
+  return lookupConvert.convertTimeToDate(time);
+}
+
+/** @module date-fns */
+/**
+ * @category Common Helpers
+ * @summary Parse the date string and convert it from the specified time zone to the local time.
+ *
+ * @description
+ * Return the date parsed from the date string, optionally using the given format string, and convert the parsed date from the given time zone to the local time.
+ *
+ * If the format string is omitted, the date string will be parsed by `date-fns/parse`, which supports extended ISO 8601 formats.
+ *
+ * The following tokens will be recognized in the format string then:
+ *
+ * | Token  | Input example    | Description                       |
+ * |--------|------------------|-----------------------------------|
+ * | `YY`   | 18               | Two-digit year                    |
+ * | `YYYY` | 2018             | Four-digit year                   |
+ * | `M`    | 1-12             | Month, beginning at 1             |
+ * | `MM`   | 01-12            | Month, 2-digits                   |
+ * | `D`    | 1-31             | Day of month                      |
+ * | `DD`   | 01-31            | Day of month, 2-digits            |
+ * | `H`    | 0-23             | Hours                             |
+ * | `HH`   | 00-23            | Hours, 2-digits                   |
+ * | `h`    | 1-12             | Hours, 12-hour clock              |
+ * | `hh`   | 01-12            | Hours, 12-hour clock, 2-digits    |
+ * | `m`    | 0-59             | Minutes                           |
+ * | `mm`   | 00-59            | Minutes, 2-digits                 |
+ * | `s`    | 0-59             | Seconds                           |
+ * | `ss`   | 00-59            | Seconds, 2-digits                 |
+ * | `S`    | 0-9              | Hundreds of milliseconds, 1-digit |
+ * | `SS`   | 00-99            | Tens of milliseconds, 2-digits    |
+ * | `SSS`  | 000-999          | Milliseconds, 3-digits            |
+ * | `z`    | EST              | Time zone abbreviation            |
+ * | `Z`    | -5:00            | Offset from UTC, 2-digits         |
+ * | `ZZ`   | -0500            | Compact offset from UTC, 2-digits |
+ * | `A`    | AM PM            | Post or ante meridiem, upper-case |
+ * | `a`    | am pm            | Post or ante meridiem, lower-case |
+ *
+ * To escape characters in the format string, wrap them in square brackets (e.g. `[G]`). Punctuation symbols (-:/.()) do not need to be wrapped.
+ *
  * The time zone has to be specified as a canonical name from the [IANA time zone list]{@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.
  *
- * @param {Date|String|Number} argument - the value to convert
+ * @param {String} dateString - the value to convert
+ * @param {String} [formatString] - the custom format to parse the date from
  * @param {Object} options - the object with options
@@ -108,3 +191,3 @@ * @param {0 | 1 | 2} [options.additionalDigits=2] - the additional number of digits in the extended year format
  * @example
- * // Convert string '2014-02-11T11:30:30' to date, New York time:
+ * // Parse string '2014-02-11 11:30:30 AM' to date, New York time:
  * var result = parseFromTimeZone('2014-02-11 11:30:30',
@@ -115,14 +198,33 @@ *   { timeZone: 'America/New_York' })
  * @example
+ * // Parse string '11.2.2014 11:30:30' to date, Berlin time:
+ * var result = parseFromTimeZone('11.2.2014 11:30:30',
+ *   'D.M.YYYY H:mm:ss', { timeZone: 'Europe/Berlin' })
+ * //=> Tue Feb 11 2014 10:30:30 UTC
+ *
+ * @example
  * // Parse string '+02014101', if the additional number of digits
  * // in the extended year format is 1, Madrid time:
  * var result = parseFromTimeZone('+02014101',
- *   { additionalDigits: 1,  timeZone: 'Europe/Madrid' })
+ *   { additionalDigits: 1, timeZone: 'Europe/Madrid' })
  * //=> Fri Apr 10 2014 22:00:00 UTC
  */
 
-function parseFromTimeZone(argument, options) {
-  var date = parse(argument, options);
-  var timeZone = options.timeZone;
+function parseFromTimeZone(dateString, formatString, options) {
+  if (typeof formatString !== 'string') {
+    options = formatString;
+    formatString = undefined;
+  }
+
+  var _options = options,
+      timeZone = _options.timeZone;
   timeZone = timezoneSupport.findTimeZone(timeZone);
 
+  if (formatString) {
+    var time = parseFormat.parseZonedTime(dateString, formatString);
+    var unixTime = timezoneSupport.getUnixTime(time, timeZone);
+    return new Date(unixTime);
+  }
+
+  var date = parse(dateString, options);
+
   var _getUTCOffset = timezoneSupport.getUTCOffset(date, timeZone),
@@ -132,4 +234,3 @@ offset = _getUTCOffset.offset;
   offset -= date.getTimezoneOffset();
-  date = new Date(date.valueOf() - offset * 60 * 1000);
-  return date;
+  return new Date(date.valueOf() + offset * 60 * 1000);
 }
@@ -206,3 +307,3 @@
  * @param {Date|String|Number} date - the original date
- * @param {String} [format='YYYY-MM-DDTHH:mm:ss.SSSZ'] - the string of tokens
+ * @param {String} formatString - the string of formatting tokens
  * @param {Object} options - the object with options
@@ -234,6 +335,5 @@ * @param {Object} [options.locale=enLocale] - the locale object
 
-function formatToTimeZone(date, format, options) {
+function formatToTimeZone(date, formatString, options) {
   var timeZone = options.timeZone,
       convertTimeZone = options.convertTimeZone;
-  date = parse(date);
   timeZone = timezoneSupport.findTimeZone(timeZone);
@@ -247,4 +347,4 @@ timeZone = timezoneSupport.getUTCOffset(date, timeZone);
 
-  format = formatTimeZoneTokens(format, timeZone);
-  return formatDate(date, format, options);
+  formatString = formatTimeZoneTokens(formatString, timeZone);
+  return formatDate(date, formatString, options);
 }
@@ -289,3 +389,4 @@
 exports.convertToTimeZone = convertToTimeZone;
+exports.parseFromString = parseFromString;
 exports.parseFromTimeZone = parseFromTimeZone;
 exports.formatToTimeZone = formatToTimeZone;

dist/index.umd.js

@@ -1,2 +0,2 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("date-fns/parse"),require("timezone-support"),require("date-fns/format")):"function"==typeof define&&define.amd?define(["exports","date-fns/parse","timezone-support","date-fns/format"],t):t(e.dateFnsTimezone={},e.dateFns.parse,e["timezone-support"],e.dateFns.format)}(this,function(e,a,s,u){"use strict";function n(e){return 9<e?e:"0"+e}function m(e,t){return(e<=0?(e=-e,"+"):"-")+n(Math.floor(e/60))+t+n(e%60)}a=a&&a.hasOwnProperty("default")?a.default:a,u=u&&u.hasOwnProperty("default")?u.default:u,e.convertToLocalTime=function(e,t){var n=a(e),f=s.findTimeZone(t.timeZone),o=s.getUTCOffset(n,f).offset;return o=n.getTimezoneOffset()-o,new Date(n.valueOf()-60*o*1e3)},e.convertToTimeZone=function(e,t){var n=a(e),f=s.findTimeZone(t.timeZone),o=s.getUTCOffset(n,f).offset;return o-=n.getTimezoneOffset(),new Date(n.valueOf()-60*o*1e3)},e.parseFromTimeZone=function(e,t){var n=a(e,t),f=t.timeZone;f=s.findTimeZone(f);var o=s.getUTCOffset(n,f).offset;return o-=n.getTimezoneOffset(),n=new Date(n.valueOf()-60*o*1e3)},e.formatToTimeZone=function(e,t,n){var f,o=n.timeZone,r=n.convertTimeZone;if(e=a(e),o=s.findTimeZone(o),o=s.getUTCOffset(e,o),!1!==r){var i=o.offset-e.getTimezoneOffset();e=new Date(e.valueOf()-60*i*1e3)}return f=o,t=t.replace(/z|ZZ?/g,function(e){switch(e){case"z":return"["+f.abbreviation+"]";case"Z":return m(f.offset,":");default:return m(f.offset,"")}}),u(e,t,n)},Object.defineProperty(e,"__esModule",{value:!0})});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("date-fns/parse"),require("timezone-support"),require("timezone-support/dist/parse-format"),require("timezone-support/dist/lookup-convert"),require("date-fns/format")):"function"==typeof define&&define.amd?define(["exports","date-fns/parse","timezone-support","timezone-support/dist/parse-format","timezone-support/dist/lookup-convert","date-fns/format"],t):t(e.dateFnsTimezone={},e.dateFns.parse,e["timezone-support"],e.parseFormat,e.lookupConvert,e.dateFns.format)}(this,function(e,s,u,m,o,a){"use strict";function n(e){return 9<e?e:"0"+e}function p(e,t){return(e<=0?(e=-e,"+"):"-")+n(Math.floor(e/60))+t+n(e%60)}s=s&&s.hasOwnProperty("default")?s.default:s,a=a&&a.hasOwnProperty("default")?a.default:a,e.convertToLocalTime=function(e,t){var n=s(e),o=u.findTimeZone(t.timeZone),r=u.getUTCOffset(n,o).offset;return r=n.getTimezoneOffset()-r,new Date(n.valueOf()-60*r*1e3)},e.convertToTimeZone=function(e,t){var n=s(e),o=u.findTimeZone(t.timeZone),r=u.getUTCOffset(n,o).offset;return r-=n.getTimezoneOffset(),new Date(n.valueOf()-60*r*1e3)},e.parseFromString=function(e,t){var n=m.parseZonedTime(e,t);return o.convertTimeToDate(n)},e.parseFromTimeZone=function(e,t,n){"string"!=typeof t&&(n=t,t=void 0);var o=n.timeZone;if(o=u.findTimeZone(o),t){var r=m.parseZonedTime(e,t),f=u.getUnixTime(r,o);return new Date(f)}var i=s(e,n),a=u.getUTCOffset(i,o).offset;return a-=i.getTimezoneOffset(),new Date(i.valueOf()+60*a*1e3)},e.formatToTimeZone=function(e,t,n){var o,r=n.timeZone,f=n.convertTimeZone;if(r=u.findTimeZone(r),r=u.getUTCOffset(e,r),!1!==f){var i=r.offset-e.getTimezoneOffset();e=new Date(e.valueOf()-60*i*1e3)}return o=r,t=t.replace(/z|ZZ?/g,function(e){switch(e){case"z":return"["+o.abbreviation+"]";case"Z":return p(o.offset,":");default:return p(o.offset,"")}}),a(e,t,n)},Object.defineProperty(e,"__esModule",{value:!0})});
 //# sourceMappingURL=index.umd.js.map

dist/parseFromTimeZone.js

@@ -9,2 +9,3 @@ 'use strict';
 var timezoneSupport = require('timezone-support');
+var parseFormat = require('timezone-support/dist/parse-format');
 
@@ -14,20 +15,42 @@ /** @module date-fns */
  * @category Common Helpers
- * @summary Convert the given argument to an instance of Date from the specified time zone.
+ * @summary Parse the date string and convert it from the specified time zone to the local time.
  *
  * @description
- * Parse the given argument to an instance of Date and convert it from the specified time zone to the local time.
+ * Return the date parsed from the date string, optionally using the given format string, and convert the parsed date from the given time zone to the local time.
  *
- * If the argument is an instance of Date, the function returns its clone.
+ * If the format string is omitted, the date string will be parsed by `date-fns/parse`, which supports extended ISO 8601 formats.
  *
- * If the argument is a number, it is treated as a timestamp.
+ * The following tokens will be recognized in the format string then:
  *
- * If an argument is a string, the function tries to parse it.
- * Function accepts complete ISO 8601 formats as well as partial implementations.
- * ISO 8601: http://en.wikipedia.org/wiki/ISO_8601
+ * | Token  | Input example    | Description                       |
+ * |--------|------------------|-----------------------------------|
+ * | `YY`   | 18               | Two-digit year                    |
+ * | `YYYY` | 2018             | Four-digit year                   |
+ * | `M`    | 1-12             | Month, beginning at 1             |
+ * | `MM`   | 01-12            | Month, 2-digits                   |
+ * | `D`    | 1-31             | Day of month                      |
+ * | `DD`   | 01-31            | Day of month, 2-digits            |
+ * | `H`    | 0-23             | Hours                             |
+ * | `HH`   | 00-23            | Hours, 2-digits                   |
+ * | `h`    | 1-12             | Hours, 12-hour clock              |
+ * | `hh`   | 01-12            | Hours, 12-hour clock, 2-digits    |
+ * | `m`    | 0-59             | Minutes                           |
+ * | `mm`   | 00-59            | Minutes, 2-digits                 |
+ * | `s`    | 0-59             | Seconds                           |
+ * | `ss`   | 00-59            | Seconds, 2-digits                 |
+ * | `S`    | 0-9              | Hundreds of milliseconds, 1-digit |
+ * | `SS`   | 00-99            | Tens of milliseconds, 2-digits    |
+ * | `SSS`  | 000-999          | Milliseconds, 3-digits            |
+ * | `z`    | EST              | Time zone abbreviation            |
+ * | `Z`    | -5:00            | Offset from UTC, 2-digits         |
+ * | `ZZ`   | -0500            | Compact offset from UTC, 2-digits |
+ * | `A`    | AM PM            | Post or ante meridiem, upper-case |
+ * | `a`    | am pm            | Post or ante meridiem, lower-case |
  *
- * If all above fails, the function passes the given argument to Date constructor.
+ * To escape characters in the format string, wrap them in square brackets (e.g. `[G]`). Punctuation symbols (-:/.()) do not need to be wrapped.
  *
  * The time zone has to be specified as a canonical name from the [IANA time zone list]{@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.
  *
- * @param {Date|String|Number} argument - the value to convert
+ * @param {String} dateString - the value to convert
+ * @param {String} [formatString] - the custom format to parse the date from
  * @param {Object} options - the object with options
@@ -39,3 +62,3 @@ * @param {0 | 1 | 2} [options.additionalDigits=2] - the additional number of digits in the extended year format
  * @example
- * // Convert string '2014-02-11T11:30:30' to date, New York time:
+ * // Parse string '2014-02-11 11:30:30 AM' to date, New York time:
  * var result = parseFromTimeZone('2014-02-11 11:30:30',
@@ -46,14 +69,33 @@ *   { timeZone: 'America/New_York' })
  * @example
+ * // Parse string '11.2.2014 11:30:30' to date, Berlin time:
+ * var result = parseFromTimeZone('11.2.2014 11:30:30',
+ *   'D.M.YYYY H:mm:ss', { timeZone: 'Europe/Berlin' })
+ * //=> Tue Feb 11 2014 10:30:30 UTC
+ *
+ * @example
  * // Parse string '+02014101', if the additional number of digits
  * // in the extended year format is 1, Madrid time:
  * var result = parseFromTimeZone('+02014101',
- *   { additionalDigits: 1,  timeZone: 'Europe/Madrid' })
+ *   { additionalDigits: 1, timeZone: 'Europe/Madrid' })
  * //=> Fri Apr 10 2014 22:00:00 UTC
  */
 
-function parseFromTimeZone(argument, options) {
-  var date = parse(argument, options);
-  var timeZone = options.timeZone;
+function parseFromTimeZone(dateString, formatString, options) {
+  if (typeof formatString !== 'string') {
+    options = formatString;
+    formatString = undefined;
+  }
+
+  var _options = options,
+      timeZone = _options.timeZone;
   timeZone = timezoneSupport.findTimeZone(timeZone);
 
+  if (formatString) {
+    var time = parseFormat.parseZonedTime(dateString, formatString);
+    var unixTime = timezoneSupport.getUnixTime(time, timeZone);
+    return new Date(unixTime);
+  }
+
+  var date = parse(dateString, options);
+
   var _getUTCOffset = timezoneSupport.getUTCOffset(date, timeZone),
@@ -63,6 +105,5 @@ offset = _getUTCOffset.offset;
   offset -= date.getTimezoneOffset();
-  date = new Date(date.valueOf() - offset * 60 * 1000);
-  return date;
+  return new Date(date.valueOf() + offset * 60 * 1000);
 }
 
 exports.parseFromTimeZone = parseFromTimeZone;

package.json

 {
   "name": "date-fns-timezone",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Parsing and formatting date strings using IANA time zones for date-fns.",
@@ -76,6 +76,6 @@ "author": {
     "date-fns": "^1.29.0",
-    "timezone-support": "^1.2.1"
+    "timezone-support": "^1.3.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.0.1",
+    "@babel/core": "^7.1.0",
     "babel-core": "^7.0.0-bridge.0",
@@ -82,0 +82,0 @@ "babel-jest": "^23.6.0",

README.md

@@ -11,3 +11,3 @@ # date-fns-timezone
 
-Provides parsing and formatting date strings and time zone conversions supporting [IANA time zones]. Date parsing, formatting and other queries and manipulations are provided by [date-fns]. List of canonical time zone names and time zone conversions are provided by [timezone-support].
+Provides parsing and formatting date strings and time zone conversions supporting [IANA time zones], following the design of functions in [date-fns]. List of canonical time zone names is provided by [timezone-support].
 
@@ -147,2 +147,8 @@ - [Synopsis](#synopsis)
 // Contains date "2018-09-02T10:04:30.982Z"
+
+const enteredTime = '09/02/2018 12:04:30.982 PM'
+const customFormat = 'MM/DD/YYYY h:mm:ss.SSS A'
+const timeZone = 'America/New_York'
+const storedDate = parseFromTimeZone(enteredTime, { timeZone })
+// Contains date "2018-09-02T18:04:30.982Z"
 ```
@@ -149,0 +155,0 @@

src/formatToTimeZone.js

 /** @module date-fns */
 
-import parse from 'date-fns/parse'
 import formatDate from 'date-fns/format'
@@ -75,3 +74,3 @@ import { findTimeZone, getUTCOffset } from 'timezone-support'
  * @param {Date|String|Number} date - the original date
- * @param {String} [format='YYYY-MM-DDTHH:mm:ss.SSSZ'] - the string of tokens
+ * @param {String} formatString - the string of formatting tokens
  * @param {Object} options - the object with options
@@ -102,5 +101,4 @@ * @param {Object} [options.locale=enLocale] - the locale object
  */
-function formatToTimeZone (date, format, options) {
+function formatToTimeZone (date, formatString, options) {
   let { timeZone, convertTimeZone } = options
-  date = parse(date)
   timeZone = findTimeZone(timeZone)
@@ -112,4 +110,4 @@ timeZone = getUTCOffset(date, timeZone)
   }
-  format = formatTimeZoneTokens(format, timeZone)
-  return formatDate(date, format, options)
+  formatString = formatTimeZoneTokens(formatString, timeZone)
+  return formatDate(date, formatString, options)
 }
@@ -116,0 +114,0 @@

src/index.js

 export { convertToLocalTime } from './convertToLocalTime'
 export { convertToTimeZone } from './convertToTimeZone'
+export { parseFromString } from './parseFromString'
 export { parseFromTimeZone } from './parseFromTimeZone'
 export { formatToTimeZone } from './formatToTimeZone'

src/parseFromTimeZone.js

 /** @module date-fns */
 
 import parse from 'date-fns/parse'
-import { findTimeZone, getUTCOffset } from 'timezone-support'
+import { findTimeZone, getUTCOffset, getUnixTime } from 'timezone-support'
+import { parseZonedTime } from 'timezone-support/dist/parse-format'
 
 /**
  * @category Common Helpers
- * @summary Convert the given argument to an instance of Date from the specified time zone.
+ * @summary Parse the date string and convert it from the specified time zone to the local time.
  *
  * @description
- * Parse the given argument to an instance of Date and convert it from the specified time zone to the local time.
+ * Return the date parsed from the date string, optionally using the given format string, and convert the parsed date from the given time zone to the local time.
  *
- * If the argument is an instance of Date, the function returns its clone.
+ * If the format string is omitted, the date string will be parsed by `date-fns/parse`, which supports extended ISO 8601 formats.
  *
- * If the argument is a number, it is treated as a timestamp.
+ * The following tokens will be recognized in the format string then:
  *
- * If an argument is a string, the function tries to parse it.
- * Function accepts complete ISO 8601 formats as well as partial implementations.
- * ISO 8601: http://en.wikipedia.org/wiki/ISO_8601
+ * | Token  | Input example    | Description                       |
+ * |--------|------------------|-----------------------------------|
+ * | `YY`   | 18               | Two-digit year                    |
+ * | `YYYY` | 2018             | Four-digit year                   |
+ * | `M`    | 1-12             | Month, beginning at 1             |
+ * | `MM`   | 01-12            | Month, 2-digits                   |
+ * | `D`    | 1-31             | Day of month                      |
+ * | `DD`   | 01-31            | Day of month, 2-digits            |
+ * | `H`    | 0-23             | Hours                             |
+ * | `HH`   | 00-23            | Hours, 2-digits                   |
+ * | `h`    | 1-12             | Hours, 12-hour clock              |
+ * | `hh`   | 01-12            | Hours, 12-hour clock, 2-digits    |
+ * | `m`    | 0-59             | Minutes                           |
+ * | `mm`   | 00-59            | Minutes, 2-digits                 |
+ * | `s`    | 0-59             | Seconds                           |
+ * | `ss`   | 00-59            | Seconds, 2-digits                 |
+ * | `S`    | 0-9              | Hundreds of milliseconds, 1-digit |
+ * | `SS`   | 00-99            | Tens of milliseconds, 2-digits    |
+ * | `SSS`  | 000-999          | Milliseconds, 3-digits            |
+ * | `z`    | EST              | Time zone abbreviation            |
+ * | `Z`    | -5:00            | Offset from UTC, 2-digits         |
+ * | `ZZ`   | -0500            | Compact offset from UTC, 2-digits |
+ * | `A`    | AM PM            | Post or ante meridiem, upper-case |
+ * | `a`    | am pm            | Post or ante meridiem, lower-case |
  *
- * If all above fails, the function passes the given argument to Date constructor.
+ * To escape characters in the format string, wrap them in square brackets (e.g. `[G]`). Punctuation symbols (-:/.()) do not need to be wrapped.
  *
  * The time zone has to be specified as a canonical name from the [IANA time zone list]{@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.
  *
- * @param {Date|String|Number} argument - the value to convert
+ * @param {String} dateString - the value to convert
+ * @param {String} [formatString] - the custom format to parse the date from
  * @param {Object} options - the object with options
@@ -32,3 +55,3 @@ * @param {0 | 1 | 2} [options.additionalDigits=2] - the additional number of digits in the extended year format
  * @example
- * // Convert string '2014-02-11T11:30:30' to date, New York time:
+ * // Parse string '2014-02-11 11:30:30 AM' to date, New York time:
  * var result = parseFromTimeZone('2014-02-11 11:30:30',
@@ -39,18 +62,32 @@ *   { timeZone: 'America/New_York' })
  * @example
+ * // Parse string '11.2.2014 11:30:30' to date, Berlin time:
+ * var result = parseFromTimeZone('11.2.2014 11:30:30',
+ *   'D.M.YYYY H:mm:ss', { timeZone: 'Europe/Berlin' })
+ * //=> Tue Feb 11 2014 10:30:30 UTC
+ *
+ * @example
  * // Parse string '+02014101', if the additional number of digits
  * // in the extended year format is 1, Madrid time:
  * var result = parseFromTimeZone('+02014101',
- *   { additionalDigits: 1,  timeZone: 'Europe/Madrid' })
+ *   { additionalDigits: 1, timeZone: 'Europe/Madrid' })
  * //=> Fri Apr 10 2014 22:00:00 UTC
  */
-function parseFromTimeZone (argument, options) {
-  let date = parse(argument, options)
+function parseFromTimeZone (dateString, formatString, options) {
+  if (typeof formatString !== 'string') {
+    options = formatString
+    formatString = undefined
+  }
   let { timeZone } = options
   timeZone = findTimeZone(timeZone)
+  if (formatString) {
+    const time = parseZonedTime(dateString, formatString)
+    const unixTime = getUnixTime(time, timeZone)
+    return new Date(unixTime)
+  }
+  const date = parse(dateString, options)
   let { offset } = getUTCOffset(date, timeZone)
   offset -= date.getTimezoneOffset()
-  date = new Date(date.valueOf() - offset * 60 * 1000)
-  return date
+  return new Date(date.valueOf() + offset * 60 * 1000)
 }
 
 export { parseFromTimeZone }

No alert changes

Improved metrics

Total package byte prevSize

89863

increased by11.29%

Number of package files

17

increased by6.25%

Lines of code

1081

increased by37.01%

Number of lines in readme file

237

increased by2.6%

Dependency changes

• Updatedtimezone-support@^1.3.1