From 8a9e8dddc7474d52718f494cca3e799fde5600a2 Mon Sep 17 00:00:00 2001 From: Ferdinand Prantl Date: Thu, 27 Sep 2018 00:59:53 +0200 Subject: [PATCH] docs: Add reference documentation Move the documentation form readme to separate files. --- .vscode/settings.json | 1 - README.md | 173 +----------------- docs/API.md | 357 ++++++++++++++++++++++++++++++++++++++ docs/usage.md | 86 +++++++++ src/convertToLocalTime.js | 8 +- src/convertToTimeZone.js | 10 +- src/formatToTimeZone.js | 16 +- src/parseFromString.js | 17 +- src/parseFromTimeZone.js | 14 +- 9 files changed, 485 insertions(+), 197 deletions(-) create mode 100644 docs/API.md create mode 100644 docs/usage.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 4e2d83d..28e3968 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,7 +1,6 @@ { "files.exclude": { "coverage": true, - "docs": true, "node_modules": true }, "search.exclude": { diff --git a/README.md b/README.md index 717bcfc..2266670 100644 --- a/README.md +++ b/README.md @@ -9,15 +9,12 @@ 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]. +### Table of Contents + - [Synopsis](#synopsis) -- [Installation and Loading](#installation-and-loading) - - [Specific Environments](#specific-environments) -- [Usage Scenarios](#usage-scenarios) - - [List all available time zones](#list-all-available-time-zones) - - [Parse a date from a string in a specific time zone](#parse-a-date-from-a-string-in-a-specific-time-zone) - - [Format a date to a string in specific time zone](#format-a-date-to-a-string-in-specific-time-zone) - - [Change the time zone of date](#change-the-time-zone-of-date) -- [API Reference](#api-reference) +- [Installation and Getting Started](#installation-and-getting-started) +- [Usage Scenarios](./docs/usage.md#usage-scenarios) +- [API Reference](./docs/API.md#api-reference) - [Contributing](#contributing) - [Release History](#release-history) - [License](#license) @@ -40,7 +37,7 @@ const format = 'D.M.YYYY HH:mm:ss.SSS [GMT]Z (z)' const output = formatToTimeZone(date, format, { timeZone: 'Europe/Berlin' }) ``` -## Installation and Loading +## Installation and Getting Started This module can be installed in your project using [NPM] or [Yarn]. Make sure, that you use [Node.js] version 6 or newer. @@ -52,164 +49,13 @@ $ npm i date-fns-timezone --save $ yarn add date-fns-timezone ``` -### Specific Environments - -Load the main module in an application using CommonJS modules: - -```js -const { - convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone - } = require('date-fns-timezone') -``` - -Load only specific modules in an application using CommonJS modules: - -```js -const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime') -const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone') -const { parseFromTimeZone } = require('date-fns-timezone/dist/parseFromTimeZone') -const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone') -``` - -Load the main module in an application using ES6 modules: - -```js -import { - convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone -} from './node_modules/date-fns-timezone/src/index.js' -``` - -Load only specific modules in an application using ES6 modules: - -```js -import { convertToLocalTime } from './node_modules/date-fns-timezone/src/convertToLocalTime.js' -import { convertToTimeZone } from './node_modules/date-fns-timezone/src/convertToTimeZone.js' -import { parseFromTimeZone } from './node_modules/date-fns-timezone/src/parseFromTimeZone.js' -import { formatToTimeZone } from './node_modules/date-fns-timezone/src/formatToTimeZone.js' -``` - -Load the main module in the browser with plain JavaScript: - -```html - - - - -``` - -Load the main module in the browser with [RequireJS]: - -```html - - - - - -``` - -## Usage Scenarios - -The minimal, but powerful API of this module provides functionality for the most usual usage scenarios in your web applications. - -### List all available time zones - -Users may need to choose the time zone, which they want to see and enter dates in. Time zones can be listed in a dropdown for the user to choose from, for example. - -```js -const { listTimeZones } = require('timezone-support') -const timeZones = listTimeZones() -``` - -See the function [listTimeZones] for more information. - -### Parse a date from a string in a specific time zone - -Dates are usually entered in a time zone chosen by the user, but they are supposed to be stored in UTC. After the user input is parsed, the result date needs to be converted from the user time zone to the native `Date` object, which maintains the date in the browser-local time zone and UTC. - -```js -const { parseZonedTime } = require('date-fns-timezone/dist/parseFromTimeZone') - -const enteredTime = '2018-09-02 12:04:30.982' -const timeZone = 'Europe/Berlin' -const storedDate = parseFromTimeZone(enteredTime, { timeZone }) -// 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, customFormat, { timeZone }) -// Contains date "2018-09-02T18:04:30.982Z" -``` - -See the function [parseFromTimeZone](#parsefromtimezone) for more information. - -### Format a date to a string in specific time zone - -Dates are supposed to be stored in UTC, but they are usually displayed in a time zone chosen by the user. Before the date value is formatted, it needs to be converted to the user time zone. - -```js -const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone') - -const storedDate = new Date('2018-09-02T10:04:30.982Z') -const format = 'D.M.YYYY H:mm:ss [GMT]Z (z)' -const timeZone = 'Europe/Berlin' -const displayedTime = formatToTimeZone(storedDate, format, { timeZone }) -// Contains string "2.9.2018 12:04:30 GMT+02:00 (CEST)" -``` - -See the function [formatToTimeZone](#formattotimezone) for more information. - -### Change the time zone of date - -Date pickers usually supply the date, which the user selected, and the time zone is implied from the user settings. The local time in the date value is not the browser-local time and the UTC value cannot be used. The date has to be converted from the user time zone to the browser-local time to become valid. - -```js -const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime') - -const chosenDate = new Date(2018, 8, 2, 12, 4, 30, 982) -const timeZone = 'Europe/Berlin' -const storedDate = convertToLocalTime(chosenDate, { timeZone }) -// Contains date "2018-09-02T10:04:30.982Z" -``` - -Date pickers are usually initialized by a date in the time zone implied from the user settings. However, the browser-local time may be different. The date has to be converted from the browser-local time to the user time zone before passed to the picker. Such date can be formatted only by using its getters (getFullYear, getMonth, ...); it is invalid for computations and comparisons, because it cannot be related to UTC. +Functions are exposed as named exports from the package modules, for example: ```js -const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone') - -const storedDate = new Date('2018-09-02T10:04:30.982Z') -const timeZone = 'Europe/Berlin' -const defaultDate = convertToTimeZone(storedDate, { timeZone }) -// Contains date "2018-09-02 12:04:30.982" +const { parseFromTimeZone, formatToTimeZone } = require('date-fns-timezone') ``` -See functions [convertToLocalTime](#converttolocaltime) and [convertToTimeZone](#converttotimezone) for more information. - -## API Reference - -The API consists of functions only. They are divided to three modules, which you can load separately or together depending on your usage scenario. - -### date-fns-timezone/dist/index - -Main package module for Node.js application. CommonJS format. Includes all functions from the other modules. - -### date-fns-timezone/dist/index.umd.js - -Main package module first of all for web browsers. UMD format, minified. Includes all functions from the other modules. Make sure, that you include `script` elements for `date-fns` and `timezone-support` on your web page before this one [as documented earlier](#specific-environments). - -### convertToLocalTime -### convertToTimeZone -### parseFromTimeZone -### formatToTimeZone +You can read more about the [module loading](./docs/API.md#loading) in other environments, like with ES6 or in web browsers. [Usage scenarios](./docs/usage.md#usage-scenarios) demonstrate applications of this library in typical real-world scenarios. The [API reference](./docs/API.md#api-reference) lists all functions with a description of their functionality. ## Contributing @@ -233,4 +79,3 @@ Licensed under the MIT license. [NPM]: https://www.npmjs.com/ [Yarn]: https://yarnpkg.com/ [RequireJS]: https://requirejs.org/ -[listTimeZones]: https://github.com/prantlf/timezone-support#listtimezones diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..d6d91a7 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,357 @@ +# API Reference + +The API consists of functions only. They are divided to three modules, which you can load separately or together depending on your usage scenario. + +### Table of Contents + +- [Loading](#loading) +- [Modules](#modules) + - [index-js](#index-js) + - [index.umd.js](#index-umd-js) +- [Functions](#functions) + - [convertToLocalTime](#converttolocaltime) + - [convertToTimeZone](#converttotimezone) + - [formatToTimeZone](#formattotimezone) + - [parseFromString](#parsefromstring) + - [parseFromTimeZone](#parsefromtimezone) + +## Loading + +Load the main module in an application using CommonJS modules: + +```js +const { + convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone + } = require('date-fns-timezone') +``` + +Load only specific modules in an application using CommonJS modules: + +```js +const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime') +const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone') +const { parseFromTimeZone } = require('date-fns-timezone/dist/parseFromTimeZone') +const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone') +``` + +Load the main module in an application using ES6 modules: + +```js +import { + convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone +} from './node_modules/date-fns-timezone/src/index.js' +``` + +Load only specific modules in an application using ES6 modules: + +```js +import { convertToLocalTime } from './node_modules/date-fns-timezone/src/convertToLocalTime.js' +import { convertToTimeZone } from './node_modules/date-fns-timezone/src/convertToTimeZone.js' +import { parseFromTimeZone } from './node_modules/date-fns-timezone/src/parseFromTimeZone.js' +import { formatToTimeZone } from './node_modules/date-fns-timezone/src/formatToTimeZone.js' +``` + +Load the main module in the browser with plain JavaScript: + +```html + + + + +``` + +Load the main module in the browser with [RequireJS]: + +```html + + + + + +``` + +The last example shows also, how to load a specific version of the library from CDN. + +## Modules + +Modules in the `src` directory require ES6 including the new module syntax, as available in Node.js 8 and newer. Modules in the `dist` directory require ES5 and follow the CommonJS standard for older Node.js releases. Files `dist/*.umd.js` require ES5, are minified and follow the UMD standard to work well in web browsers. + +Except for the `index` module including all functions, each function is exposed in a separate module with the same name as the function name and `.js` and `.umd.js` suffixes. You can load the separate modules, if you cannot use a bundler supporting tree-shaking for the size optimization. + +### index.js + +Main package module for Node.js application. CommonJS format. Includes all functions from the other modules. + +### index.umd.js + +Main package module first of all for web browsers. UMD format, minified. Includes all functions from the other modules. Make sure, that you include `script` elements for `date-fns` and `timezone-support` on your web page before this one [as documented earlier](#loading). + +## Functions + +Functions converting to an arbitrary time zone accept either a `Date` object, or a UNIX timestamp. (The UNIX timestamp is the time from the epoch in milliseconds, as returned by `date.prototype.getTime`.) They produce a complete [time object]. Functions converting from an arbitrary time zone accept a [time object] and return the UNIX timestamp. + +### convertToLocalTime + +``` +convertToLocalTime(date: Date|String|Number, options: Object) : Date +``` + +Converts the given date from the given time zone to the local time and returns it as a new `Date` object. Getters for local time parts of the input `Date` object (`getFullYear`, `getMonth`, ...) will be assumed to return time in the given time zone. + +* `argument` (Date|String|Number) - the value to convert +* `options` (Object) - the object with options +* `options.timeZone` (String) - the canonical name of the source time zone + +The time zone has to be specified as a canonical name from the [IANA time zone list]. + +```js +const { convertToLocalTime } = require('date-fns-timezone') +// Convert the time in the New York time zone to the local time: +const date = new Date(2018, 8, 2, 10, 0) +const result = convertToLocalTime(date, { timeZone: 'America/New_York' }) +// Returns { date: Date, zone: { abbreviation: 'EDT', offset: -360 } +// The date will be "2018-09-02T16:00:00Z". +``` + +### convertToTimeZone + +``` +convertToTimeZone(date: Date|Number|String, options: Object) : Date +``` + +Converts the given date from the local time to the given time zone and returns a new `Date` object, which has its local time set to it. The returned `Date` object should not be used form comparisons or other computations. Only the its getters for the local time parts can be used (`getFullYear`, `getMonth`, ...). + +* `argument` (Date|String|Number) - the value to convert +* `options` (Object) - the object with options +* `options.timeZone` (String) - the canonical name of the target time zone + +The time zone has to be specified as a canonical name from the [IANA time zone list]. + +```js +const { convertToTimeZone } = require('date-fns-timezone') +// Convert the current local time to the New York time zone: +var result = convertToTimeZone(new Date(), { timeZone: 'America/New_York' }) +// Returns { date: Date, zone: { abbreviation: 'EST', offset: -300 } +``` + +### formatToTimeZone + +``` +formatToTimeZone(date: Date|String|Number, format: String, options: Object) : String +``` + +Returns the formatted date string in the given format, after converting it to the given time zone. + +The input date will be converted to the given time zone by default, using its UTC timestamp. If the local time in the input date is already in the given time zone, set `options.convertTimeZone` to `false`. Otherwise the date will be considered in local time and converted. + +* `argument` (Date|String|Number) - the original date +* `format` (String) - the string of formatting tokens +* `options` (Object) - the object with options +* `options.locale` (Object) - the locale object; optional, defaults to English +* `options.timeZone` (String) - the canonical name of the target time zone +* `options.convertTimeZone` (String) - if the date should be converted to the given time zone before formatting; optional, defaults to `true` + +The locale can be loaded and applied in the same way, as it works for the function [`format` from date-fns](https://date-fns.org/v1.29.0/docs/format). + +The time zone has to be specified as a canonical name from the [IANA time zone list]. + +The following tokens are recognized in the format string: + +| Unit | Token | Result examples | +|-------------------------|-------|----------------------------------| +| Month | M | 1, 2, ..., 12 | +| | Mo | 1st, 2nd, ..., 12th | +| | MM | 01, 02, ..., 12 | +| | MMM | Jan, Feb, ..., Dec | +| | MMMM | January, February, ..., December | +| Quarter | Q | 1, 2, 3, 4 | +| | Qo | 1st, 2nd, 3rd, 4th | +| Day of month | D | 1, 2, ..., 31 | +| | Do | 1st, 2nd, ..., 31st | +| | DD | 01, 02, ..., 31 | +| Day of year | DDD | 1, 2, ..., 366 | +| | DDDo | 1st, 2nd, ..., 366th | +| | DDDD | 001, 002, ..., 366 | +| Day of week | d | 0, 1, ..., 6 | +| | do | 0th, 1st, ..., 6th | +| | dd | Su, Mo, ..., Sa | +| | ddd | Sun, Mon, ..., Sat | +| | dddd | Sunday, Monday, ..., Saturday | +| Day of ISO week | E | 1, 2, ..., 7 | +| ISO week | W | 1, 2, ..., 53 | +| | Wo | 1st, 2nd, ..., 53rd | +| | WW | 01, 02, ..., 53 | +| Year | YY | 00, 01, ..., 99 | +| | YYYY | 1900, 1901, ..., 2099 | +| ISO week-numbering year | GG | 00, 01, ..., 99 | +| | GGGG | 1900, 1901, ..., 2099 | +| AM/PM | A | AM, PM | +| | a | am, pm | +| | aa | a.m., p.m. | +| Hour | H | 0, 1, ... 23 | +| | HH | 00, 01, ... 23 | +| | h | 1, 2, ..., 12 | +| | hh | 01, 02, ..., 12 | +| Minute | m | 0, 1, ..., 59 | +| | mm | 00, 01, ..., 59 | +| Second | s | 0, 1, ..., 59 | +| | ss | 00, 01, ..., 59 | +| 1/10 of second | S | 0, 1, ..., 9 | +| 1/100 of second | SS | 00, 01, ..., 99 | +| Millisecond | SSS | 000, 001, ..., 999 | +| Timezone abbreviation | z | CET, CEST, EST, EDT, ... | +| Timezone offset to UTC | Z | -01:00, +00:00, ... +12:00 | +| | ZZ | -0100, +0000, ..., +1200 | +| Seconds timestamp | X | 512969520 | +| Milliseconds timestamp | x | 512969520900 | + +To escape characters in the format string, wrap them in square brackets (e.g. `[GMT]`). Punctuation symbols (-:/.()) do not need to be wrapped. + +```js +const { formatToTimeZone } = require('date-fns-timezone') +// Represent midnight on 11 February 2014, UTC in middle-endian format, New York time: +const result = formatToTimeZone( + new Date(Date.UTC(2014, 1, 11)), 'MM/dd/yyyy h:mm A [GMT]Z (z)', + { timeZone: 'America/New_York' } +) +// Returns '02/10/2014 7:00 PM GMT-0500 (EST)' +``` + +```js +// Represent noon on 2 July 2014 in Esperanto, Madrid time: +const { formatToTimeZone } = require('date-fns-timezone') +const locale = require('date-fns/locale/eo') +const result = formatToTimeZone( + new Date(2014, 6, 2, 12), "HH:mm, do 'de' MMMM yyyy (Zz)", + { locale, timeZone: 'Europe/Madrid', convertTimeZone: false } +) +// Returns '12:00, 2-a de julio 2014 (+02:00 CEST)' +``` + +### parseFromString + +``` +parseFromString(input: String, format: String) : Date +``` + +Returns the date parsed from the date string using the given format string and converts the parsed date to the local time. + +* `input` (String) - the string to parse +* `format` (String) - the custom format to parse the date from + +The following tokens are recognized in the format string: + +| 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. + +```js +// Parse string '11.2.2014 11:30:30' to date in Berlin: +const result = parseFromTimeZone( + '11.2.2014 11:30:30', 'D.M.YYYY H:mm:ss') +// Returns Tue Feb 11 2014 10:30:30 UTC +``` + +```js +// Parse string '02/11/2014 11:30:30' to date, New York time: +const result = parseFromString( + '02/11/2014 11:30:30 AM GMT-0500 (EDT)', + 'MM/DD/YYYY h:mm:ss.SSS A [GMT]ZZ (z)') +// Returns Tue Feb 11 2014 16:30:30 UTC +``` + +### parseFromTimeZone + +``` +parseFromTimeZone(input: String, format: String, options: Object) : Date +``` + +Returns the date parsed from the date string, optionally using the given format string, and converts the parsed date from the given time zone to the local time. + +* `input` (String) - the string to parse +* `format` (String) - the custom format to parse the date from; optional +* `options` (Object) - the object with options +* `options.timeZone` (String) - the canonical name of the source time zone + +If the format string is omitted, the date string will be parsed by [`date-fns/parse`](https://date-fns.org/v1.29.0/docs/parse), which supports extended ISO 8601 formats. + +The time zone has to be specified as a canonical name from the [IANA time zone list]. + +The following tokens are recognized in the format string: + +| 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. + +```js +// Parse string '2014-02-11 11:30:30 AM' to date, New York time: +const result = parseFromTimeZone( + '2014-02-11 11:30:30', { timeZone: 'America/New_York' }) +// Returns Tue Feb 11 2014 16:30:30 UTC +``` + +```js +// Parse string '11.2.2014 11:30:30' to date, Berlin time: +const result = parseFromTimeZone( + '11.2.2014 11:30:30', 'D.M.YYYY H:mm:ss', + { timeZone: 'Europe/Berlin' }) +// Returns Tue Feb 11 2014 10:30:30 UTC +``` + +[time object]: ./design.md#time-object +[IANA time zone list]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..c5cd78a --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,86 @@ +# Usage Scenarios + +The minimal, but powerful API of this module provides functionality for the most usual usage scenarios in your web applications. + +### Table of Contents + +- [List all available time zones](#list-all-available-time-zones) +- [Parse a date from a string in a specific time zone](#parse-a-date-from-a-string-in-a-specific-time-zone) +- [Format a date to a string in specific time zone](#format-a-date-to-a-string-in-specific-time-zone) +- [Change the time zone of date](#change-the-time-zone-of-date) + +### List all available time zones + +Users may need to choose the time zone, which they want to see and enter dates in. Time zones can be listed in a dropdown for the user to choose from, for example. + +```js +const { listTimeZones } = require('timezone-support') +const timeZones = listTimeZones() +``` + +See the function [listTimeZones] for more information. + +### Parse a date from a string in a specific time zone + +Dates are usually entered in a time zone chosen by the user, but they are supposed to be stored in UTC. After the user input is parsed, the result date needs to be converted from the user time zone to the native `Date` object, which maintains the date in the browser-local time zone and UTC. + +```js +const { parseZonedTime } = require('date-fns-timezone/dist/parseFromTimeZone') + +const enteredTime = '2018-09-02 12:04:30.982' +const timeZone = 'Europe/Berlin' +const storedDate = parseFromTimeZone(enteredTime, { timeZone }) +// 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, customFormat, { timeZone }) +// Contains date "2018-09-02T18:04:30.982Z" +``` + +See the function [parseFromTimeZone](#./API.md#parsefromtimezone) for more information. + +### Format a date to a string in specific time zone + +Dates are supposed to be stored in UTC, but they are usually displayed in a time zone chosen by the user. Before the date value is formatted, it needs to be converted to the user time zone. + +```js +const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone') + +const storedDate = new Date('2018-09-02T10:04:30.982Z') +const format = 'D.M.YYYY H:mm:ss [GMT]Z (z)' +const timeZone = 'Europe/Berlin' +const displayedTime = formatToTimeZone(storedDate, format, { timeZone }) +// Contains string "2.9.2018 12:04:30 GMT+02:00 (CEST)" +``` + +See the function [formatToTimeZone](./API.md#formattotimezone) for more information. + +### Change the time zone of date + +Date pickers usually supply the date, which the user selected, and the time zone is implied from the user settings. The local time in the date value is not the browser-local time and the UTC value cannot be used. The date has to be converted from the user time zone to the browser-local time to become valid. + +```js +const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime') + +const chosenDate = new Date(2018, 8, 2, 12, 4, 30, 982) +const timeZone = 'Europe/Berlin' +const storedDate = convertToLocalTime(chosenDate, { timeZone }) +// Contains date "2018-09-02T10:04:30.982Z" +``` + +Date pickers are usually initialized by a date in the time zone implied from the user settings. However, the browser-local time may be different. The date has to be converted from the browser-local time to the user time zone before passed to the picker. Such date can be formatted only by using its getters (`getFullYear`, `getMonth`, ...); it is invalid for computations and comparisons, because it cannot be related to UTC. + +```js +const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone') + +const storedDate = new Date('2018-09-02T10:04:30.982Z') +const timeZone = 'Europe/Berlin' +const defaultDate = convertToTimeZone(storedDate, { timeZone }) +// Contains date "2018-09-02 12:04:30.982" +``` + +See functions [convertToLocalTime](./API.md#converttolocaltime) and [convertToTimeZone](./API.md#converttotimezone) for more information. + +[listTimeZones]: https://github.com/prantlf/timezone-support/blob/master/docs/API.md#listtimezones diff --git a/src/convertToLocalTime.js b/src/convertToLocalTime.js index 501aeea..e568829 100644 --- a/src/convertToLocalTime.js +++ b/src/convertToLocalTime.js @@ -20,9 +20,11 @@ import { findTimeZone, getUTCOffset } from 'timezone-support' * @returns {Date} the parsed date in the local time zone * * @example - * // Convert the current time to the New York time zone: - * var result = convertToLocalTime(new Date(), { timeZone: 'America/New_York' }) - * //=> { date: Date, zone: { abbreviation: 'EST', offset: -300 } + * // Convert the time in the New York time zone to the local time: + * const date = new Date(2018, 8, 2, 10, 0) + * const result = convertToLocalTime(date, { timeZone: 'America/New_York' }) + * // Returns { date: Date, zone: { abbreviation: 'EDT', offset: -360 } + * // The date will be "2018-09-02T16:00:00Z". */ function convertToLocalTime (argument, options) { let date = parse(argument) diff --git a/src/convertToTimeZone.js b/src/convertToTimeZone.js index 437119b..97a1453 100644 --- a/src/convertToTimeZone.js +++ b/src/convertToTimeZone.js @@ -16,13 +16,13 @@ import { findTimeZone, getUTCOffset } from 'timezone-support' * * @param {Date|String|Number} argument - the value to convert * @param {Object} options - the object with options - * @param {String} options.timeZone - the canonical name of the source time zone - * @returns {Date} the parsed date in the local time zone + * @param {String} options.timeZone - the canonical name of the target time zone + * @returns {Date} the parsed date in the target time zone * * @example - * // Convert the current time to the New York time zone: - * var result = convertToTimeZone(new Date(), { timeZone: 'America/New_York' }) - * //=> { date: Date, zone: { abbreviation: 'EST', offset: -300 } + * // Convert the current local time to the New York time zone: + * const result = convertToTimeZone(new Date(), { timeZone: 'America/New_York' }) + * Returns { date: Date, zone: { abbreviation: 'EST', offset: -300 } */ function convertToTimeZone (argument, options) { let date = parse(argument) diff --git a/src/formatToTimeZone.js b/src/formatToTimeZone.js index bba90a8..4a52080 100644 --- a/src/formatToTimeZone.js +++ b/src/formatToTimeZone.js @@ -8,15 +8,15 @@ import { findTimeZone, getUTCOffset } from 'timezone-support' * @summary Format the date in the specified time zone. * * @description - * Return the formatted date string in the given format, after converting it, optionally, to the given time zone. + * Returns the formatted date string in the given format, after converting it to the given time zone. * * The input date will be converted to the given time zone by default, using its UTC timestamp. - * If the local time in the input date is already in the given time zone, set `options.useLocal` to `true`. - * If the UTC time in the input date is already in the given time zone, set `options.useUTC` to `true`. + * If the local time in the input date is already in the given time zone, set `options.convertTimeZone` + * to `false`. Otherwise the date will be considered in local time and converted. * * 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}. * - * Accepted tokens: + * The following tokens are recognized in the format string: * * | Unit | Token | Result examples | * |-------------------------|-------|----------------------------------| @@ -85,17 +85,17 @@ import { findTimeZone, getUTCOffset } from 'timezone-support' * 'MM/dd/yyyy h:mm A [GMT]Z (z)', * { timeZone: 'America/New_York' } * ) - * //=> '02/10/2014 7:00 PM GMT-0500 (EST)' + * // Returns '02/10/2014 7:00 PM GMT-0500 (EST)' * * @example * // Represent noon on 2 July 2014 in Esperanto, Madrid time: - * var eoLocale = require('date-fns/locale/eo') + * var locale = require('date-fns/locale/eo') * var result = formatToTimeZone( * new Date(2014, 6, 2, 12), * "HH:mm, do 'de' MMMM yyyy (Zz)", - * { locale: eo, timeZone: 'Europe/Madrid', convertTimeZone: false } + * { locale, timeZone: 'Europe/Madrid', convertTimeZone: false } * ) - * //=> '12:00, 2-a de julio 2014 (+02:00 CEST)' + * // Returns '12:00, 2-a de julio 2014 (+02:00 CEST)' */ function formatToTimeZone (date, formatString, options) { let { timeZone, convertTimeZone } = options diff --git a/src/parseFromString.js b/src/parseFromString.js index be9e595..3f3386e 100644 --- a/src/parseFromString.js +++ b/src/parseFromString.js @@ -8,9 +8,9 @@ import { convertTimeToDate } from 'timezone-support/dist/lookup-convert' * @summary Parse the date string and convert it to the local time. * * @description - * Return the date parsed from the date string, using the given format string, and convert the parsed date to the local time. + * Returns the date parsed from the date string using the given format string and converts the parsed date to the local time. * - * The following tokens will be recognized in the format string then: + * The following tokens are recognized in the format string: * * | Token | Input example | Description | * |--------|------------------|-----------------------------------| @@ -39,21 +39,20 @@ import { convertTimeToDate } from 'timezone-support/dist/lookup-convert' * * 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 {String} dateString - the value to convert + * @param {String} dateString - the string to parse * @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 + * const result = parseFromTimeZone('11.2.2014 11:30:30', 'D.M.YYYY H:mm:ss') + * // Returns Tue Feb 11 2014 10:30:30 UTC * + * @example * // 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)', + * const 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 + * // Returns Tue Feb 11 2014 16:30:30 UTC */ function parseFromString (dateString, formatString) { const time = parseZonedTime(dateString, formatString) diff --git a/src/parseFromTimeZone.js b/src/parseFromTimeZone.js index 0bb1b05..19c455f 100644 --- a/src/parseFromTimeZone.js +++ b/src/parseFromTimeZone.js @@ -9,11 +9,11 @@ import { parseZonedTime } from 'timezone-support/dist/parse-format' * @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. + * Returns 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: + * The following tokens are recognized in the format string: * * | Token | Input example | Description | * |--------|------------------|-----------------------------------| @@ -44,7 +44,7 @@ import { parseZonedTime } from 'timezone-support/dist/parse-format' * * 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} dateString - the string to parse * @param {String} [formatString] - the custom format to parse the date from * @param {Object} options - the object with options * @param {0 | 1 | 2} [options.additionalDigits=2] - the additional number of digits in the extended year format @@ -53,15 +53,15 @@ import { parseZonedTime } from 'timezone-support/dist/parse-format' * * @example * // Parse string '2014-02-11 11:30:30 AM' to date, New York time: - * var result = parseFromTimeZone('2014-02-11 11:30:30', + * const result = parseFromTimeZone('2014-02-11 11:30:30', * { timeZone: 'America/New_York' }) - * //=> Tue Feb 11 2014 16:30:30 UTC + * // Returns Tue Feb 11 2014 16:30:30 UTC * * @example * // Parse string '11.2.2014 11:30:30' to date, Berlin time: - * var result = parseFromTimeZone('11.2.2014 11:30:30', + * const 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 + * // Returns Tue Feb 11 2014 10:30:30 UTC * * @example * // Parse string '+02014101', if the additional number of digits