# Important

You probably want the original version by VVO:

- [Github - https://github.com/vvo/tzdb](https://github.com/vvo/tzdb)
- [NPM - https://www.npmjs.com/package/@vvo/tzdb](https://www.npmjs.com/package/@vvo/tzdb)

All credit to the [original author VVO](https://github.com/vvo)

# Fork Changes

This fork moves [deprecated time zone names](https://data.iana.org/time-zones/data/backward) to their own key in the time zone object, instead of grouping them with `group`:

```js
{
  "name": "America/New_York",
  "alternativeName": "Eastern Time",
  "group": [
    "America/Detroit",
    "America/Indiana/Indianapolis",
    "America/Indiana/Marengo",
    "America/Indiana/Petersburg",
    "America/Indiana/Vevay",
    "America/Indiana/Vincennes",
    "America/Indiana/Winamac",
    "America/Kentucky/Louisville",
    "America/Kentucky/Monticello",
    "America/New_York"
  ],
  "deprecatedNames": [
    "US/Michigan",
    "America/Fort_Wayne",
    "America/Indianapolis",
    "US/East-Indiana",
    "America/Louisville",
    "US/Eastern"
  ],
  "continentCode": "NA",
  "continentName": "North America",
  "countryName": "United States",
  "countryCode": "US",
  "mainCities": ["New York City", "Brooklyn", "Queens", "Philadelphia"],
  "rawOffsetInMinutes": -300,
  "abbreviation": "EST",
  "rawFormat": "-05:00 Eastern Time - New York City, Brooklyn, Queens, Philadelphia"
}
```

Useful if you don't want or need to support the deprecated time zones...

## `getUngroupedTimeZones()`

This fork also adds the `getUngroupedTimeZones()` function, which returns an array of simplified time zone objects with current time information. We prefer this for creating time zone selection boxes when deprecated time zones are not required.

```js
[
  // ...
  {
    name: "America/Los_Angeles",
    currentTimeOffsetInMinutes: -420, // "current" time zone offset, this is why getUngroupedTimeZones() is a method and not just an object: it works at runtime
    currentTimeFormat: "(UTC -7) America/Los Angeles",
  },
  // ...
];
```

# tzdb [![GitHub license](https://img.shields.io/github/license/sytexa/tzdb?style=flat)](https://github.com/sytexa/tzdb/blob/main/LICENSE) [![Tests](https://github.com/sytexa/tzdb/workflows/CI/badge.svg)](https://github.com/sytexa/tzdb/actions)

This is a list and npm package of:

- "simplified" [IANA time zones](https://www.iana.org/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
- also includes [deprecated time zone names](https://data.iana.org/time-zones/data/backward) for compatibility

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:

````bash
npm add @sytexa/tzdb


Usage:

```js
import { getTimeZones, getUngroupedTimeZones, rawTimeZones, timeZonesNames } from "@sytexa/tzdb";
````

## API

### getTimeZones()

```js
const timeZones = getTimeZones();
```

This method returns an array of time zones objects:

```js
[
  // ...
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    group: ["America/Los_Angeles"],
    deprecatedNames: [],
    continentCode: "NA",
    continentName: "North America",
    countryName: "United States",
    countryCode: "US",
    mainCities: ["Los Angeles", "San Diego", "San Jose", "San Francisco"],
    rawOffsetInMinutes: -480,
    abbreviation: "PST",
    rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
    currentTimeOffsetInMinutes: -420, // "current" time zone offset, this is why getTimeZones() is a method and not just an object: it works 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:

```js
{
  name: "America/Dawson_Creek",
  alternativeName: "Mountain Time",
  group: ["America/Creston", "America/Dawson_Creek", "America/Fort_Nelson"],
  deprecatedNames: [],
  continentCode: "NA",
  continentName: "North America",
  countryName: "Canada",
  countryCode: "CA",
  mainCities: ["Fort St. John", "Creston", "Fort Nelson"],
  rawOffsetInMinutes: -420,
  abbreviation: "MST",
  rawFormat: "-07:00 Mountain Time - Fort St. John, Creston, Fort Nelson",
  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:

```js
[
  // ...
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    group: ["America/Los_Angeles"],
    deprecatedNames: [],
    continentCode: "NA",
    continentName: "North America",
    countryName: "United States",
    countryCode: "US",
    mainCities: ["Los Angeles", "San Diego", "San Jose", "San Francisco"],
    rawOffsetInMinutes: -480,
    abbreviation: "PST",
    rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
  },
  // ...
];
```

### timeZonesNames

This is an array of time zone names:

```js
[
  // ...
  "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:

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