date-fns-timezone

date-fns-timezone

utm_content=prantlf/date-fns-timezone&utm_campaign=Badge_Grade)

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.

• Synopsis
• Installation and Loading
  • Specific Environments
• Usage Scenarios
  • List all available time zones
  • Parse a date from a string in a specific time zone
  • Format a date to a string in specific time zone
  • Change the time zone of date
• API Reference
• Contributing
• Release History
• License

Synopsis

const { listTimeZones } = require('timezone-support')
const { parseFromTimeZone, formatToTimeZone } = require('date-fns-timezone')

// List canonical time zone names: [ 'Africa/Abidjan', ... ]
const timeZones = listTimeZones()

// Set the date to "2018-09-01T16:01:36.386Z"
const date = parseFromTimeZone('2018-09-01 18:01:36.386', { timeZone: 'Europe/Berlin' })

// Set the output to "1.9.2018 18:01:36.386 GMT+02:00 (CEST)"
const date = new Date('2018-09-01Z16:01:36.386Z')
const format = 'D.M.YYYY HH:mm:ss.SSS [GMT]Z (z)'
const output = formatToTimeZone(date, format, { timeZone: 'Europe/Berlin' })

Installation and Loading

This module can be installed in your project using NPM or Yarn. Make sure, that you use Node.js version 6 or newer.

$ npm i date-fns-timezone --save

$ yarn add date-fns-timezone

Specific Environments

Load the main module in an application using CommonJS modules:

const {
  convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
 } = require('date-fns-timezone')

Load only specific modules in an application using CommonJS modules:

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:

import {
  convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
} from './node_modules/date-fns-timezone/src/index.js'

Load only specific modules in an application using ES6 modules:

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:

<script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script>
<script src="https://unpkg.com/timezone-support@1.2.1/dist/index.umd.js"></script>
<script src="https://unpkg.com/date-fns-timezone@0.0.1/dist/index.umd.js"></script>
<script>
  (() => {
    const {
      convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
    } = window.dateFnsTimezone
  })()
</script>

Load the main module in the browser with RequireJS:

<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/timezone-support@1.2.1/dist/index.umd.js"></script>
<script src="https://unpkg.com/date-fns-timezone@0.0.1/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.

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.

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, { timeZone })
// Contains date "2018-09-02T18:04:30.982Z"

See the function 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.

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 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 yet. The date has to be converted from the user time zone to the browser-local time to become valid.

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.

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 and 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.

convertToLocalTime

convertToTimeZone

parseFromTimeZone

formatToTimeZone

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 2018-09-17 v0.0.1 Initial release

License

Copyright (c) 2018 Ferdinand Prantl

Licensed under the MIT license.