@vvo/tzdb 6.198.0 → 6.200.0

package/README.md

@@ -1,182 +1,183 @@
-# tzdb [![GitHub license](https://img.shields.io/github/license/vvo/tzdb?style=flat)](https://github.com/vvo/tzdb/blob/main/LICENSE) [![Tests](https://github.com/vvo/tzdb/workflows/CI/badge.svg)](https://github.com/vvo/tzdb/actions) [![npm version](https://badge.fury.io/js/%40vvo%2Ftzdb.svg)](https://www.npmjs.com/package/@vvo/tzdb) [![minizipped size](https://badgen.net/bundlephobia/minzip/@vvo/tzdb@latest)](https://bundlephobia.com/result?p=@vvo/tzdb@latest)
+# tzdb [![npm version](https://badge.fury.io/js/%40vvo%2Ftzdb.svg)](https://www.npmjs.com/package/@vvo/tzdb)
 
-This is a list and npm package of:
+Always up to date time zones for time zone pickers, and the country of any time zone.
 
-- "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
+```js
+import { getTimeZones } from "@vvo/tzdb";
+
+getTimeZones().map((timeZone) => timeZone.currentTimeFormat);
+// [..., "-07:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco", ...]
+```
 
-The data and npm packages are **automatically updated** whenever there are changes to https://www.geonames.org/ which is generated from IANA databases.
+- Every [IANA time zone](https://www.iana.org/time-zones), grouped by country and clock, with major
+  cities.
+- Current offsets and abbreviations: PDT in summer, PST in winter.
+- Every current and deprecated IANA name, so saved values always find their entry.
+- Names in any language the browser supports.
+- The country of a visitor's time zone, to guess where they are without an IP lookup.
+- No dependencies, ESM and CommonJS, TypeScript types.
 
-This is useful whenever you want to build a time zone select menu in your application.
+## Always up to date
 
-## NPM package
+Every day, a [GitHub workflow](.github/workflows/release.yml) compiles the latest
+[IANA tz database](https://data.iana.org/time-zones/tzdb/), takes city populations from
+[GeoNames](https://www.geonames.org/), tests the result and publishes a new version when something
+changed.
 
-Installation:
+Current offsets come from the browser or Node.js at runtime. A site that never updates this package
+still follows daylight saving changes, and agrees with the offsets `Intl.DateTimeFormat` gives the
+rest of the app.
+
+## Time zone picker
 
 ```bash
 npm add @vvo/tzdb
 ```
 
-Usage:
+```jsx
+import { getTimeZones } from "@vvo/tzdb";
 
-```js
-import { getTimeZones, rawTimeZones, timeZonesNames, abbreviations } from "@vvo/tzdb";
+const timeZones = getTimeZones();
+
+// Saved values can be any IANA name, like "Asia/Calcutta" or "US/Pacific"
+function findTimeZone(name) {
+  return timeZones.find((timeZone) => timeZone.group.includes(name));
+}
+
+function TimeZonePicker({ value, onChange }) {
+  const selected = findTimeZone(value ?? Intl.DateTimeFormat().resolvedOptions().timeZone);
+  return (
+    <select value={selected?.name} onChange={(event) => onChange(event.target.value)}>
+      {timeZones.map((timeZone) => (
+        <option key={timeZone.name} value={timeZone.name}>
+          {timeZone.currentTimeFormat}
+        </option>
+      ))}
+    </select>
+  );
+}
 ```
 
-## API
+Save `name` in the database: every `Intl` API and date library accepts it.
 
-### getTimeZones()
+To search, match the query against the fields people type:
 
 ```js
-const timeZones = getTimeZones();
-
-// You can also provide an optional parameter to include UTC in the result.
-// This adds a time zone with the name "UTC" and a fixed offset of 0.
-const timeZonesWithUtc = getTimeZones({ includeUtc: true });
+timeZones.filter((timeZone) =>
+  [timeZone.currentTimeFormat, timeZone.countryName, timeZone.abbreviation, ...timeZone.group]
+    .join(" ")
+    .toLowerCase()
+    .includes(query.toLowerCase()),
+);
 ```
 
-This method returns an array of time zones objects:
+## Country of a visitor
 
 ```js
-[
-  // ...
-  {
-    name: "America/Los_Angeles",
-    alternativeName: "Pacific Time",
-    group: ["America/Los_Angeles"],
-    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",
-  },
-  // ...
-];
+import { getCountryCode } from "@vvo/tzdb";
+
+const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone; // "Europe/Paris"
+getCountryCode(timeZone); // "FR"
+new Intl.DisplayNames(["en"], { type: "region" }).of("FR"); // "France"
 ```
 
-When relevant, time zones are grouped. The rules for grouping are:
+It knows every IANA name, including old ones browsers still return, like `Asia/Calcutta`. It weighs
+4 kB and does not load the time zone list.
+
+## API
 
-- 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
+```js
+import {
+  getTimeZones,
+  getCountryCode,
+  rawTimeZones,
+  timeZonesNames,
+  abbreviations,
+  tzdbVersion,
+} from "@vvo/tzdb";
+```
 
-Here's a grouping example:
+### getTimeZones(options)
+
+Returns time zones sorted by current offset:
 
 ```js
 {
-  name: "America/Dawson_Creek",
-  alternativeName: "Mountain Time",
-  group: ["America/Creston", "America/Dawson_Creek", "America/Fort_Nelson"],
+  name: "America/Los_Angeles",
+  alternativeName: "Pacific Time",
+  group: ["America/Los_Angeles", "US/Pacific", "PST8PDT"],
   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",
+  countryName: "United States",
+  countryCode: "US",
+  mainCities: ["Los Angeles", "San Diego", "San Jose", "San Francisco"],
+  rawOffsetInMinutes: -480,
+  abbreviation: "PST",
+  dstAbbreviation: "PDT", // only for zones with daylight saving time
+  rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
   currentTimeOffsetInMinutes: -420,
-  currentTimeFormat: "-07:00 Mountain Time - Fort St. John, Creston"
+  currentTimeFormat: "-07:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
+  currentAbbreviation: "PDT",
 }
 ```
 
-### rawTimeZones
+Options:
 
-This is an array of time zone objects without the current time information:
+- `locale`: translates `alternativeName`, `countryName` and `continentName`. With `"fr"`, Los Angeles
+  shows as "-07:00 heure du Pacifique nord-américain - Los Angeles, ...". City names stay as they are.
+- `includeUtc`: adds `Etc/UTC`, whose group includes `UTC` and `GMT`.
+- `includeGmtOffsets`: adds the fixed offsets `Etc/GMT-14` to `Etc/GMT+12`. As in POSIX, the sign
+  is inverted: `Etc/GMT+5` is 5 hours behind UTC.
 
-```js
-[
-  // ...
-  {
-    name: "America/Los_Angeles",
-    alternativeName: "Pacific Time",
-    group: ["America/Los_Angeles"],
-    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",
-  },
-  // ...
-];
-```
+Zones the browser does not know yet are left out, since `Intl` could not format dates in them.
+Runtimes without `Intl` time zone support get every zone at its standard offset.
 
-### timeZonesNames
+### getCountryCode(timeZone)
 
-This is an array of time zone names:
+The [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of an IANA time zone
+name, or `undefined` for names without a country like `UTC`.
 
-```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",
-  // ...
-];
-```
+### rawTimeZones
+
+The same list without the `current*` fields, sorted by standard offset.
+
+### timeZonesNames
+
+Every IANA time zone name from [zone.tab](https://data.iana.org/time-zones/tzdb/zone.tab).
 
 ### abbreviations
 
-This is an object mapping timezone abbreviations to their full forms:
+Long names mapped to abbreviations, like `"Central European Summer Time": "CEST"`. Careful, CST
+means Central Standard Time (-06:00), China Standard Time (+08:00) and Cuba Standard Time (-05:00).
 
-```js
-{
-  // ...
-  "Australian Central Daylight Time": "ACDT",
-  "Australian Central Standard Time": "ACST",
-  "Australian Central Time": "ACT",
-  "Australian Central Western Standard Time": "ACWST",
-  "Australian Eastern Daylight Time": "AEDT",
-  "Australian Eastern Standard Time": "AEST",
-  "Australian Eastern Time": "AET",
-  "Australian Western Daylight Time": "AWDT",
-  "Australian Western Standard Time": "AWST",
-  "Azerbaijan Summer Time": "AZST",
-  "Azerbaijan Time": "AZT",
-  "Azores Summer Time": "AZOST",
-  "Azores Time": "AZOT",
-  "Bangladesh Standard Time": "BST",
-  "Bhutan Time": "BTT",
-  "Bolivia Time": "BOT",
-  // ...
-};
-```
+### tzdbVersion
 
-**Caution:** Although abbreviations can be easy to lookup, they can be misleading. For example: CST can refer to Central Standard Time (-06.00 UTC), China Standard Time (+06.00 UTC) or Cuba Standard Time (-05.00 UTC). And abbreviation full forms don't directly map to any property in the time zone objects returned by `rawTimeZones` or `getTimeZones()`.
+The IANA tz database release behind the data, like `"2026e"`.
 
-## Notes
+## Compared to countries-and-timezones
 
-- 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:
+|                                    | @vvo/tzdb                    | countries-and-timezones             |
+| ---------------------------------- | ---------------------------- | ----------------------------------- |
+| Data updates                       | Every day, automatically     | By hand                             |
+| Current offsets                    | From the browser, at runtime | Computed when the package was built |
+| Grouped list with cities and names | Yes                          | No                                  |
+| Abbreviations that follow DST      | Yes                          | No                                  |
+| Translations                       | Any language the browser has | No                                  |
+| Country of a time zone             | 4 kB                         | 9 kB                                |
+| Everything                         | 17 kB                        | 9 kB                                |
 
-```js
-const value = timeZones.find((timeZone) => {
-  return dbData.timeZone === timeZone.name || timeZone.group.includes(dbData.timeZone);
-});
-```
+Sizes are minified and gzipped.
+
+## How time zones are grouped
+
+Zones share an entry when they are in the same country and their clocks show the same time for the
+next two years. Detroit and New York had different rules a century ago, so IANA keeps both, but
+they share an entry today.
+
+`alternativeName` is the English name from [CLDR](https://cldr.unicode.org/) without "Standard",
+"Daylight" or "Summer". When summer and winter names differ, like "Greenwich Mean Time" and "British
+Summer Time", it is CLDR's generic name, "United Kingdom Time". Several countries share names like
+"Eastern Time", so show `countryName` or `mainCities` next to it.
+
+Abbreviations come from IANA. When IANA has none, like "+03", they come from `abbreviations` or
+read "GMT+3".

package/abbreviations.json

@@ -44,6 +44,7 @@
   "Bravo Time Zone": "B",
   "British Summer Time": "BST",
   "Brunei Darussalam Time": "BNT",
+  "Brunei Time": "BNT",
   "Cape Verde Time": "CVT",
   "Casey Time": "CAST",
   "Cayman Islands Daylight Saving Time": "CIDST",
@@ -58,8 +59,10 @@
   "Central Time": "CT",
   "Chamorro Standard Time": "ChST",
   "Charlie Time Zone": "C",
+  "Chatham Daylight Time": "CHADT",
   "Chatham Island Daylight Time": "CHADT",
   "Chatham Island Standard Time": "CHAST",
+  "Chatham Standard Time": "CHAST",
   "Chatham Time": "CHAST",
   "Chile Standard Time": "CLT",
   "Chile Summer Time": "CLST",
@@ -77,6 +80,7 @@
   "Cuba Standard Time": "CST",
   "Davis Time": "DAVT",
   "Delta Time Zone": "D",
+  "Dumont d’Urville Time": "DDUT",
   "Dumont-d'Urville Time": "DDUT",
   "Dumont-d’Urville Time": "DDUT",
   "East Africa Time": "EAT",
@@ -113,6 +117,8 @@
   "Gilbert Island Time": "GILT",
   "Gilbert Islands Time": "GILT",
   "Golf Time Zone": "G",
+  "Greenland Standard Time": "WGT",
+  "Greenland Summer Time": "WGST",
   "Greenwich Mean Time": "GMT",
   "Gulf Standard Time": "GST",
   "Guyana Time": "GYT",
@@ -138,6 +144,8 @@
   "Japan Standard Time": "JST",
   "Kamchatka Summer Time": "PETST",
   "Kamchatka Time": "PETT",
+  "Khovd Standard Time": "HOVT",
+  "Khovd Summer Time": "HOVST",
   "Kilo Time Zone": "K",
   "Korea Standard Time": "KST",
   "Korean Time": "KST",
@@ -174,6 +182,8 @@
   "Newfoundland Standard Time": "NST",
   "Niue Time": "NUT",
   "Norfolk Daylight Time": "NFDT",
+  "Norfolk Island Daylight Time": "NFDT",
+  "Norfolk Island Standard Time": "NFT",
   "Norfolk Island Time": "NFT",
   "Norfolk Time": "NFT",
   "November Time Zone": "N",
@@ -218,6 +228,8 @@
   "South Africa Standard Time": "SAST",
   "South Georgia Time": "GST",
   "Srednekolymsk Time": "SRET",
+  "St. Pierre & Miquelon Daylight Time": "PMDT",
+  "St. Pierre & Miquelon Standard Time": "PMST",
   "St. Pierre & Miquelon Time": "PM",
   "Suriname Time": "SRT",
   "Syowa Time": "SYOT",
@@ -225,12 +237,15 @@
   "Taipei Time": "TWT",
   "Tajikistan Time": "TJT",
   "Tango Time Zone": "T",
+  "Timor-Leste Time": "TLT",
   "Tokelau Time": "TKT",
   "Tonga Summer Time": "TOST",
   "Tonga Time": "TOT",
   "Turkey Time": "TRT",
   "Turkmenistan Time": "TMT",
   "Tuvalu Time": "TVT",
+  "Türkiye Standard Time": "TRT",
+  "Türkiye Time": "TRT",
   "Ulaanbaatar Summer Time": "ULAST",
   "Ulaanbaatar Time": "ULAT",
   "Uniform Time Zone": "U",