@vvo/tzdb

What is @vvo/tzdb?

@vvo/tzdb is an npm package that provides a comprehensive database of time zones. It allows developers to easily access and manipulate time zone data, including retrieving time zone names, offsets, and other related information.

What are @vvo/tzdb's main functionalities?

Get all time zones

This feature allows you to retrieve a list of all available time zones. The code sample demonstrates how to use the `getTimeZones` function to get an array of time zone objects.

const { getTimeZones } = require('@vvo/tzdb');
const timeZones = getTimeZones();
console.log(timeZones);

Get time zone by name

This feature allows you to retrieve detailed information about a specific time zone by its name. The code sample shows how to use the `getTimeZone` function to get details for the 'America/New_York' time zone.

const { getTimeZone } = require('@vvo/tzdb');
const timeZone = getTimeZone('America/New_York');
console.log(timeZone);

Get time zone offset

This feature allows you to get the offset of a specific time zone. The code sample demonstrates how to use the `getTimeZoneOffset` function to get the offset for the 'America/New_York' time zone.

const { getTimeZoneOffset } = require('@vvo/tzdb');
const offset = getTimeZoneOffset('America/New_York');
console.log(offset);

Other packages similar to @vvo/tzdb

moment-timezone

Moment-timezone is a popular package that extends the Moment.js library to handle time zones. It provides similar functionalities to @vvo/tzdb, such as retrieving time zone data and converting between time zones. However, it is built on top of Moment.js, which can be heavier and more complex compared to @vvo/tzdb.

luxon

Luxon is a modern JavaScript library for working with dates and times. It includes built-in support for time zones and offers a more modern API compared to Moment.js. Luxon provides similar functionalities to @vvo/tzdb but also includes additional features for date and time manipulation.

date-fns-tz

Date-fns-tz is an extension of the date-fns library that adds support for time zones. It provides functions to convert dates between time zones and to get time zone offsets. Date-fns-tz offers a lightweight and functional approach to handling time zones, similar to @vvo/tzdb.

README

tzdb

This is a list and npm package of:

• "simplified" IANA time zones with their alternative names like Pacific Time instead of America/Los_Angeles, along with major cities for each time zone.
• all existing raw IANA time zones names
• "raw" offsets along with current time offsets

The data and npm packages are automatically updated whenever there are changes to https://www.geonames.org/ which is generated from IANA databases.

This is useful whenever you want to build a time zone select menu in your application.

NPM package

Installation:

npm add @vvo/tzdb

Usage:

import { getTimeZones, rawTimeZones, timeZonesNames } from "@vvo/tzdb";

API

getTimeZones()

const timeZones = getTimeZones();

This method returns an array of time zones objects:

[
  // ...
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    group: ["America/Los_Angeles"],
    countryName: "United States",
    mainCities: ["Los Angeles", "San Diego"],
    rawOffsetInMinutes: -480, // "raw" time zone offset, when there's no DST in place
    rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego",
    currentTimeOffsetInMinutes: -420, // "current" time zone offset, this is why getTimeZones() is a method and not just an object: it can only work at runtime
    currentTimeFormat: "-07:00 Pacific Time - Los Angeles, San Diego",
  },
  // ...
];

When relevant, time zones are grouped. The rules for grouping are:

• if the time zones are in the same country
• if the DST or summer time offsets are the same
• if the non DST, non summer time offsets are the same
• then we group the time zones
• the "main" time zone name (name attribute), is always the one from the most populated city

Here's a grouping example:

{
  name: 'America/Dawson_Creek',
  alternativeName: 'Mountain Time',
  group: [ 'America/Creston', 'America/Dawson_Creek', 'America/Fort_Nelson' ],
  countryName: 'Canada',
  mainCities: [ 'Fort St. John', 'Creston' ],
  rawOffsetInMinutes: -420,
  rawFormat: '-07:00 Mountain Time - Fort St. John, Creston',
  currentTimeOffsetInMinutes: -420,
  currentTimeFormat: '-07:00 Mountain Time - Fort St. John, Creston'
}

rawTimeZones

This is an array of time zone objects without the current time information:

[
  // ...
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    group: ["America/Los_Angeles"],
    countryName: "United States",
    mainCities: ["Los Angeles", "San Diego"],
    rawOffsetInMinutes: -480,
    rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego",
  },
  // ...
];

timeZonesNames

This is an array of time zone names:

[
  // ...
  "America/Juneau",
  "America/Kentucky/Louisville",
  "America/Kentucky/Monticello",
  "America/Kralendijk",
  "America/La_Paz",
  "America/Lima",
  "America/Los_Angeles",
  "America/Lower_Princes",
  "America/Maceio",
  "America/Managua",
  "America/Manaus",
  "America/Marigot",
  "America/Martinique",
  "America/Matamoros",
  // ...
];

Notes

• We provide two cities when grouping happens, ranked by population
• We provide alternative names ("Pacific Time" for "America/Los_Angeles") and remove "Standard", "Daylight" or "Summer" from them
• If you're using this to build a time zone selector and saving to a database then:
  • make sure to save the name attribute (America/Los_Angeles) in your database
  • when displaying the select with a default value from your database, either select the time zone name that matches, or if the time zone name is part of the group. Example:

const value = timeZones.find((timeZone) => {
  return (
    dbData.timeZone === timeZone.name ||
    timeZone.group.includes(dbData.timeZone)
  );
});