-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move the documentation form readme to separate files.
- Loading branch information
Showing
9 changed files
with
485 additions
and
197 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,6 @@ | ||
| { | ||
| "files.exclude": { | ||
| "coverage": true, | ||
| "docs": true, | ||
| "node_modules": true | ||
| }, | ||
| "search.exclude": { | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script> | ||
| <script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script> | ||
| <script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script> | ||
| <script> | ||
| (() => { | ||
| const { | ||
| convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone | ||
| } = window.dateFnsTimezone | ||
| })() | ||
| </script> | ||
| ``` | ||
|
|
||
| Load the main module in the browser with [RequireJS]: | ||
|
|
||
| ```html | ||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script> | ||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script> | ||
| <script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script> | ||
| <script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script> | ||
| <script> | ||
| require(['date-fns-timezone'], ({ parseFromTimeZone, formatToTimeZone }) => { | ||
| }) | ||
| </script> | ||
| ``` | ||
|
|
||
| ## 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 | ||
Oops, something went wrong.