From 237390bd20bb26d6212c918d85d8e1c594c8f809 Mon Sep 17 00:00:00 2001 From: OB Date: Thu, 21 May 2026 16:09:52 +0700 Subject: [PATCH 1/2] docs(location-timezone): add Compared to alternatives section Mirrors the pattern from @coroboros/clone: feature-presence table plus a positioning paragraph. Compares against `i18n-iso-countries`, `countries-list`, `geo-tz` (different input model: lat/lng polygon), and `city-timezones` (closest peer in shape). TOC updated; section sits between Limitations and Contributing. --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index f41a8e4..2e3e7b4 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ Curated UN country names, CIA Factbook official forms, ISO 3166-1 codes, ANSI FI - [API](#api) - [Subpath exports](#subpath-exports) - [Limitations](#limitations) +- [Compared to alternatives](#compared-to-alternatives) - [Contributing](#contributing) - [License](#license) @@ -916,6 +917,21 @@ Sizes include the chunked dependencies each subpath transitively pulls. The merg - **Timezone set is snapshot** — IANA timezones are captured once when the data is rebuilt; the runtime does not re-query `Intl`. Rebuild and republish on tz-database changes. - **No reverse geocoding** — `findLocationsByCoordinates` filters a bounding box; it does not return the nearest city. +## Compared to alternatives + +| Feature | `i18n-iso-countries` | `countries-list` | `geo-tz` | `city-timezones` | **`@coroboros/location-timezone`** | +| ---------------------------------------------------- | :------------------: | :--------------: | :---------------: | :-----------------: | :--------------------------------: | +| Country names with UN + CIA official forms | no | no | no | no | yes | +| ISO 3166-1 alpha-2 / alpha-3 codes | yes | yes | no | yes | yes | +| Capital data with coordinates + IANA timezone | no | no (name only) | no | no | yes | +| US state codes — ANSI FIPS + USPS | no | no | no | USPS only | yes | +| City data with coordinates | no | no | no | ~7,300 | ~40,000 | +| Timezone lookup by city name | no | no | no (lat/lng only) | yes (O(n) scan) | yes (O(1) Map) | +| Cross-references resolved across domains | no | no | n/a | no | yes | +| Runtime dependencies | 1 | 0 | 4 | 0 | 1 (`zipson`) | + +The consolidation is the differentiator. Country-only packages (`i18n-iso-countries`, `countries-list`) cover ISO codes and names, nothing else. `geo-tz` and `tz-lookup` solve a different input model: lat/lng polygon → timezone, useful when you only know coordinates. `city-timezones` is the closest peer in shape, resolving country and timezone from a city name. It carries ~7,300 cities with no capitals or state-FIPS codes, and runs every lookup through `Array.filter`. `@coroboros/location-timezone` carries all five domains: countries, capitals, ~40,000 cities, US states ANSI, IANA timezones. The library builds Map and Set indexes once at module load. Cross-references resolve at parse time, so `findCapitalOfCountryIso('JP').country` returns the same object as `findCountryByIso('JP')`. + ## Contributing Bug reports and PRs welcome. From 9d49c67493df2f28b58c7482ecdad4a30c00f652 Mon Sep 17 00:00:00 2001 From: OB Date: Thu, 21 May 2026 16:36:06 +0700 Subject: [PATCH 2/2] docs(location-timezone): rewrite opener for public README 'The consolidation is the differentiator' was abstract on both sides. Replaced with a direct statement that names the consolidation shape. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e3e7b4..02b054b 100644 --- a/README.md +++ b/README.md @@ -930,7 +930,7 @@ Sizes include the chunked dependencies each subpath transitively pulls. The merg | Cross-references resolved across domains | no | no | n/a | no | yes | | Runtime dependencies | 1 | 0 | 4 | 0 | 1 (`zipson`) | -The consolidation is the differentiator. Country-only packages (`i18n-iso-countries`, `countries-list`) cover ISO codes and names, nothing else. `geo-tz` and `tz-lookup` solve a different input model: lat/lng polygon → timezone, useful when you only know coordinates. `city-timezones` is the closest peer in shape, resolving country and timezone from a city name. It carries ~7,300 cities with no capitals or state-FIPS codes, and runs every lookup through `Array.filter`. `@coroboros/location-timezone` carries all five domains: countries, capitals, ~40,000 cities, US states ANSI, IANA timezones. The library builds Map and Set indexes once at module load. Cross-references resolve at parse time, so `findCapitalOfCountryIso('JP').country` returns the same object as `findCountryByIso('JP')`. +The gap is single-package consolidation across all five domains. Country-only packages (`i18n-iso-countries`, `countries-list`) cover ISO codes and names, nothing else. `geo-tz` and `tz-lookup` solve a different input model: lat/lng polygon → timezone, useful when you only know coordinates. `city-timezones` is the closest peer in shape, resolving country and timezone from a city name. It carries ~7,300 cities with no capitals or state-FIPS codes, and runs every lookup through `Array.filter`. `@coroboros/location-timezone` carries all five domains: countries, capitals, ~40,000 cities, US states ANSI, IANA timezones. The library builds Map and Set indexes once at module load. Cross-references resolve at parse time, so `findCapitalOfCountryIso('JP').country` returns the same object as `findCountryByIso('JP')`. ## Contributing