Time Zone Support

Lightweight time zone listing and date converting. Intended for adding time zone support to high-level date libraries, but also for direct application usage.

• Tiny code base - 3.5 KB minified, 1.5 KB gzipped. Do not pack unnecessary weight in your application.
• Packed time zone data - 175 KB minified, 22.5 KB gzipped. Single time zones are unpacked on demand.
• Generated from the official time zone database version 2018e. Canonical time zone names, aliases, UTC offsets, and daylight-saving time changes.
• Minimal interface for time zone lookup and conversions. Parsing, formatting and manipulating dates is usually the task for a higher-level date library.

• Synopsis
• Installation and Loading
  • Specific Environments
• Usage Scenarios
• Design Concepts
• API Reference
• Library Integrations
• Contributing
• Release History
• License

Synopsis

const {
  listTimeZones, findTimeZone, getZonedTime, getUnixTime
} = require('timezone-support')

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

// Find a particular time zone: { name: 'Europe/Berlin', ... }
const berlin = findTimeZone('Europe/Berlin')

// Convert a date to a specific time zone: { year, month, day, dayOfWeek,
// hours, minutes, seconds, milliseconds, epoch, zone: { abbreviation, offset } }
const nativeDate = new Date()
const berlinTime = getZonedTime(nativeDate, berlin)

// Convert a time from a specific time zone: native Date object
const berlinTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0 }
const nativeDate = new Date(getUnixTime(berlinTime, berlin))

Installation and Loading

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

$ npm i timezone-support --save

Specific Environments

Load the main module in an application using CommonJS modules:

const { findTimeZone, getZonedTime } = require('timezone-support')

Load the main module in an application using ES6 modules:

import {
  findTimeZone, getZonedTime
} from './node_modules/timezone-support/src/index.js'

Load the main module in the browser with plain JavaScript:

<script src="./node_modules/timezone-support/dist/index.umd.js"></script>
<script>
  (() => {
    const { findTimeZone, getZonedTime } = window['timezone-support']
  })()
</script>

Load the main module in the browser with RequireJS:

<script src="./node_modules/timezone-support/dist/index.umd.js"></script>
<script>
  require(['timezone-support'], ({ findTimeZone, getZonedTime }) => {
  })
</script>

Library Integrations

• Day.js - timeZone plugin supplies parsing from and formatting to an arbitrary time zone
• date-fns - date-fns-timezone provides functions for parsing from and formatting to an arbitrary time zone and time zone conversions for the native Date object.

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-18 v1.3.0 Maintain the property dayOfWeek in the time object.
• 2018-09-16 v1.2.0 Add a new getUTCOffset method for more lightweight integrations.
• 2018-09-03 v1.1.0 Set the property epoch to the time object.
• 2018-09-02 v1.0.0 Initial release

License

Copyright (c) 2018 Ferdinand Prantl

Licensed under the MIT license.