@vvo/tzdb 6.199.0 → 6.201.0

package/README.md

@@ -1,6 +1,6 @@
 # tzdb [![npm version](https://badge.fury.io/js/%40vvo%2Ftzdb.svg)](https://www.npmjs.com/package/@vvo/tzdb)
 
-Time zones for building a time zone picker, always up to date.
+Always up to date time zones for time zone pickers, and the country of any time zone.
 
 ```js
 import { getTimeZones } from "@vvo/tzdb";
@@ -14,7 +14,8 @@ getTimeZones().map((timeZone) => timeZone.currentTimeFormat);
 - 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.
-- No dependencies, ESM and CommonJS, TypeScript types, 16 kB gzipped.
+- The country of a visitor's time zone, to guess where they are without an IP lookup.
+- No dependencies, ESM and CommonJS, TypeScript types.
 
 ## Always up to date
 
@@ -70,10 +71,30 @@ timeZones.filter((timeZone) =>
 );
 ```
 
+## Country of a visitor
+
+```js
+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"
+```
+
+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
 
 ```js
-import { getTimeZones, rawTimeZones, timeZonesNames, abbreviations, tzdbVersion } from "@vvo/tzdb";
+import {
+  getTimeZones,
+  getCountryCode,
+  rawTimeZones,
+  timeZonesNames,
+  abbreviations,
+  tzdbVersion,
+} from "@vvo/tzdb";
 ```
 
 ### getTimeZones(options)
@@ -105,12 +126,18 @@ Options:
 - `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`.
+- `date`: computes the `current*` fields at this date instead of now, like the date of a meeting.
 - `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.
 
 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.
 
+### getCountryCode(timeZone)
+
+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`.
+
 ### rawTimeZones
 
 The same list without the `current*` fields, sorted by standard offset.
@@ -128,6 +155,20 @@ means Central Standard Time (-06:00), China Standard Time (+08:00) and Cuba Stan
 
 The IANA tz database release behind the data, like `"2026e"`.
 
+## Compared to countries-and-timezones
+
+|                                   | @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 |
+| Abbreviations that follow DST     | Yes                          | No                                  |
+| Translations                      | Any language the browser has | No                                  |
+| Country of a time zone            | 4 kB                         | 9 kB                                |
+| Picker list with cities and names | 17 kB                        | Not available                       |
+
+Sizes are minified and gzipped. countries-and-timezones weighs 9 kB in total, without cities, display
+names or abbreviations.
+
 ## 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