@johnmorrisdotca/kuni 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-10-09
+
+### Added
+
+- **Each country's capital in Japanese**: `country(code).capital` is now `{ en, ja }` (東京, キーウ), from Wikidata, for all 245 countries that have a capital.
+- **`@johnmorrisdotca/kuni/facts`**, a new entry so the main one stays small: for every country its population and area with the year each is for, the coordinates of the country and of its capital, the countries it shares a land border with (`[]` for an island), the side of the road it drives on, and CLDR's first day of the week, measurement system, paper size and clock. `facts(code)`, `allFacts()`, `distanceKm(from, to)` and `FACTS_READ`, the day Wikidata was read. Plain numbers and codes, for a build script to read as they are.
+- **`@johnmorrisdotca/kuni/subdivision-facts`** and **`/subdivision-facts/<code>`**: each subdivision's capital (in English and Japanese, with a reading in kana for Japan's prefectural capitals), population, area and coordinates, one country at a time, with `loadSubdivisionFacts(code)`. Complete for Japan's 47 prefectures.
+- **`@johnmorrisdotca/kuni/groupings`**: 107 groupings, each named in English and Japanese with its members, definition, source, licence and the day it was true. The seven continents; the 30 UN M49 areas; 23 international bodies (the UN, the EU with its candidates, the euro area, Schengen, the EEA, NATO, the G7 and G20, the OECD, ASEAN, the African Union, the Arab League, the GCC, the Commonwealth, OPEC, BRICS, Mercosur, the USMCA, APEC, CARICOM, the Pacific Islands Forum, the Nordic Council and Benelux) with the days members joined and left; 16 informal groupings (the Middle East, Latin America, the Caribbean, the Balkans, the Western Balkans, Scandinavia, the Nordic countries, the Baltic states, Central and Southeast Asia, the Maghreb, the Horn of Africa, the Sahel, the British Isles, Iberia, Asia-Pacific); and regions inside a country (Japan's eight 地方 and the nine-region variant, the US Census regions and divisions, Canada's five regions, the UK's four nations, Australia's states and territories). `groupings`, `grouping`, `groupingsOf` and `membersOf`, with `on` for a body's members on a past day.
+- Every public export has a doc comment, kept in the built `.d.ts` so an editor shows it, with `@param`, `@returns` and an example; the tests run every example. The API page shows each function's parameters, what it returns and its example, and each interface's fields.
+- Japan's Kinki region carries Kansai (関西地方) as its other name: `Grouping.otherNames`.
+- `docs/facts.md`, `docs/subdivision-facts.md` and `docs/groupings.md` say what was decided, how much is known, and why the rest is `null`.
+- The demo has views of its own, each at its own address: a page for each country (its outline from Chizu with the capital marked, its facts with their years, neighbours and groupings as links, furigana, the time now in each of its zones), two countries compared, every country in a table to filter, sort and narrow by grouping, a groupings explorer with a body's members on any day, three seeded quizzes (capitals, which country a region is in, calling codes) whose link gives the same questions, a country and region form widget in English or Japanese with its code to copy, search by calling code, currency or domain, and the data's quality in the open. Tables and lists download as CSV, JSON or text. Chizu is a development dependency for the demo's outlines only.
+
+### Changed
+
+- Equatorial Guinea's capital is Ciudad de la Paz (シウダ・デ・ラ・パス), where it moved in January 2026; it was Malabo.
+- **Continents follow UN M49** (from CLDR): Russia is in Europe, Cyprus in Asia, Timor-Leste in Asia, Christmas Island and the Cocos Islands in Oceania, the British Indian Ocean Territory in Africa, and the sub-Antarctic islands where M49 puts them (Bouvet Island and South Georgia in South America, Heard and McDonald in Oceania, the French Southern Lands in Africa). Antarctica is the one continent named by hand. 1.0.0 took the continent from countries-list.
+- **Norway's counties are those of 2024**, when Viken, Vestfold og Telemark and Troms og Finnmark were divided again: NO-31 Østfold, NO-32 Akershus, NO-33 Buskerud, NO-39 Vestfold, NO-40 Telemark, NO-55 Troms and NO-56 Finnmark are added and NO-30, NO-38 and NO-54 are gone, as in ISO 3166-2, which CLDR 48.2 has not caught up with. There are now 5,050 subdivisions.
+- Short names where CLDR's full name reads badly in a narrow space: DR Congo (コンゴ民主共和国) and Congo (コンゴ共和国) for "Congo - Kinshasa" and "Congo - Brazzaville", ミャンマー for ミャンマー (ビルマ), ココス諸島. Hong Kong, Macao and Myanmar already had CLDR's.
+- Each capital's Japanese name is the usual one (東京, 北京, ソウル), not a municipality's formal name, after a review.
+
+### Fixed
+
+- English subdivision names that were wrong in 1.0.0: Peterborough and Marlborough were cut short ("Peter", "Marl"); Chiayi City and Chiayi County were swapped, in Japanese too (嘉義市, 嘉義県); Bogotá was "Capital District"; Davao de Oro (ダバオ・デ・オロ州), Csongrád-Csanád and Nicaragua's two Caribbean Coast regions had their old names; Russia's republics Buryatia, Chechnya, Chuvashia, Kabardino-Balkaria, Karachay-Cherkessia and Udmurtia were adjectives, and Altai Republic and Komi Republic are told from their neighbours; Cần Thơ had lost its marks; Barisal Division and Barisal District had each other's names; and Morocco's twelve regions carried the names of the regions that held their codes before 2019 (MA-04 is Rabat-Salé-Kénitra, not Oriental), in Japanese too, where MA-11's came from a Wikidata label that was not a name. Every English name is now checked for each of these faults against Wikidata's English label, and the build stops on one nobody has decided (`docs/disagreements.md`).
+
 ## [1.0.0] - 2026-10-09
 
 The first version: every country and its subdivisions, with ISO 3166 codes and names in English and Japanese.

package/NOTICE.md

@@ -10,7 +10,11 @@ address, the day it was read and its SHA-256.
 | Country names in English and Japanese, their short and variant forms, alpha-3 and numeric codes, currencies, UN M49 continents and subregions | Unicode CLDR 48.2 (`cldr-localenames-full` and `cldr-core` 48.2.0 on npm) | Unicode-3.0, below |
 | Subdivision codes, English and Japanese names, the levels they are at and what they are inside | Unicode CLDR 48.2 (`common/subdivisions/en.xml`, `ja.xml`, `common/validity/subdivision.xml` at the tag `release-48-2`, and `cldr-core`'s `subdivisionContainment.json` and `aliases.json`) | Unicode-3.0, below |
 | Japanese names of the subdivisions CLDR has none for, the kana readings of Japan's prefectures, calling codes, and what kind of place each subdivision is | Wikidata, the snapshot `data-sources/wikidata-2026-10-09.json` | CC0, below |
-| Each country's own name, capital, continent and languages, and the calling code where Wikidata has none | countries-list 3.4.1 by Annexare Studio | MIT, below |
+| Each country's own name, capital and languages, and the calling code where Wikidata has none | countries-list 3.4.1 by Annexare Studio | MIT, below |
+| Each country's capital in Japanese and its coordinates, population, area (with the year each is for), coordinates, driving side and the countries it shares a border with; each subdivision's capital, population, area and coordinates; the days members joined and left international bodies | Wikidata, the snapshot `data-sources/wikidata-facts-2026-10-09.json` | CC0, below |
+| Which land borders are real (two outlines touch) | Natural Earth 5.1.2 admin-0 countries at 1:50m, as drawn by `@johnmorrisdotca/chizu` 1.0.2 (a development dependency of the build; the package does not depend on it) | Public domain (Natural Earth); MIT (Chizu), below |
+| The first day of the week, the measurement system, the paper size and the clock; the UN M49 areas and their members; the members of the United Nations | Unicode CLDR 48.2 (`cldr-core` 48.2.0: weekData, measurementData, timeData, territoryContainment) | Unicode-3.0, below |
+| The members of each international body as the body lists them, the informal groupings with their definitions, the regions inside a country, the readings of the groupings' Japanese names, and the choices in `scripts/facts-config.ts` and `scripts/groupings-config.ts` | Written for this package, from the sources named beside each, read on 2026-10-09 | MIT; lists of facts |
 | Time zones | IANA time zone database 2026e, `zone.tab` | Public domain |
 | Country-code top-level domains | IANA's list of top-level domains (version 2026100900) | A list of facts, published by IANA |
 | The aliases ("Holland", "UK", 米国), the readings of country names written in kanji, Hokkaido's and Fukuoka's readings, and the Japanese words for kinds of place the build looks for | Written for this package, in `scripts/data-config.ts` | MIT |
@@ -80,6 +84,22 @@ is used only when CLDR has no Japanese name, when every current item for the cod
 written in Japanese with no bracketed explanation; a reading only when Wikidata gives exactly one for the same
 name. Kinds of place are read from the English labels of the classes an item is an instance of.
 
+The facts snapshot (`data-sources/wikidata-facts-2026-10-09.json`) holds the answers to the queries written in it:
+for every country and every subdivision, its capital with the capital's English and Japanese labels, kana name and
+coordinates; its best-ranked population and area with the day each is for; its coordinates; and, for countries, the
+side of the road it drives on, the countries it shares a border with and the international bodies it is a member
+of. `scripts/facts.ts`, `scripts/subdivision-facts.ts` and `scripts/groupings.ts` say how each is chosen. Figures are
+kept as Wikidata gives them, rounded only for coordinates (two decimal places).
+
+## Natural Earth, through Chizu
+
+Natural Earth (https://www.naturalearthdata.com/) is in the public domain: "No permission is needed to use Natural
+Earth. Crediting the authors is unnecessary." It is credited here anyway. Kuni ships no geometry. The build reads
+which countries' outlines touch from the country maps of `@johnmorrisdotca/chizu` 1.0.2 (MIT, © John Morris), drawn
+from Natural Earth 5.1.2 admin-0 countries at 1:50m, and keeps a border Wikidata states only where the outlines touch
+(or where `BORDERS_ADDED` in `scripts/facts-config.ts` says why it is a border on land). Chizu is a development
+dependency of the build and the demo; the published package depends on nothing.
+
 ## countries-list
 
 ```text
@@ -105,8 +125,8 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.```
 
-From https://github.com/annexare/Countries, version 3.4.1 on npm. Its own name (`native`), capital, continent and
-languages are used as they are; its calling code only where Wikidata has none.
+From https://github.com/annexare/Countries, version 3.4.1 on npm. Its own name (`native`), capital and languages
+are used as they are (from 1.1.0 the continent is UN M49's, from CLDR); its calling code only where Wikidata has none.
 
 ## IANA
 
@@ -116,12 +136,14 @@ read from it.
 
 ## Not carried
 
-No geometry, population, area or other figure, so no database with a share-alike condition is carried: the
-richer country datasets under ODbL (mledoze/countries, REST Countries) and the GPL `country-state-city` were
-looked at and deliberately not used. GeoNames was not used either: its codes are not ISO 3166-2, and its licence
+No geometry, and no database with a share-alike condition: the richer country datasets under ODbL
+(mledoze/countries, REST Countries) and the GPL `country-state-city` were looked at and deliberately not used; the
+figures in `/facts` and `/subdivision-facts` are Wikidata's (CC0), and the land borders are checked against Natural
+Earth (public domain). GeoNames was not used either: its codes are not ISO 3166-2, and its licence
 asks for attribution on every use.
 
 ## Made with
 
-`scripts/build-data.ts` reads the inputs with Node alone. `cldr-core`, `cldr-localenames-full` and
-`countries-list` are development dependencies of the build only: the package depends on nothing at run time.
+`scripts/build-data.ts` reads the inputs with Node alone. `cldr-core`, `cldr-localenames-full`, `countries-list`
+and `@johnmorrisdotca/chizu` are development dependencies of the build (and Chizu of the demo) only: the package
+depends on nothing at run time.

package/README.md

@@ -20,21 +20,21 @@ A typed, zero-dependency dataset from Unicode CLDR and Wikidata, loaded one coun
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the header with its language chooser, the API reference link, five cloth patches and the Help switch, then three panels. Find a country shows ドイツ typed in and its answer: the German flag, DE, DEU and 276, Germany, ドイツ, Deutschland, Europe, Berlin, +49, EUR, .de, two time zones, and 16 states. Subdivisions of a country shows Japan picked and a table of its prefectures with code, English and Japanese name, from JP-01 Hokkaidō 北海道, and the line 47 subdivisions; the main kind is prefecture. Look up a code begins below with JP-13 typed in." width="600">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the header with its language chooser, the API reference link, five cloth patches and the Help switch, then a row of views (Look up, Country, Compare, All countries, Groupings, Quiz, Form widget, Data quality) and the Look up view's panels. Find a country shows ドイツ typed in and its answer: the German flag, DE, DEU and 276, Germany, ドイツ, Deutschland, Europe, Berlin, +49, EUR, .de, two time zones, and 16 states. Subdivisions of a country shows Japan picked and a table of its prefectures with code, English and Japanese name, from JP-01 Hokkaidō 北海道, and the line 47 subdivisions; the main kind is prefecture. Look up a code begins below with JP-13 typed in." width="600">
 </picture>
 <br><em>The demo on a desk: a country found by its Japanese name, and Japan's prefectures loaded on demand.</em>
 </td>
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: the header, its language chooser, patches and buttons, then the first panel, 国を探す, with ドイツ typed in, its row of examples, and the start of its answer, the German flag and DE, DEU, 276" width="190">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: the header, its language chooser, patches and buttons, then the first panel, 国を探す, with ドイツ typed in, its row of examples, and the start of its answer, the German flag and DE, DEU, 276, under the row of views" width="190">
 </picture>
 <br><em>On a phone, in Japanese, in the device's light or dark.</em>
 </td>
 </tr>
 </table>
 
-Kuni is the country list every site ends up keeping for itself, kept once, with what a form, a profile page or a map quiz asks of it: the 250 countries with their ISO 3166-1 codes, and their 5,046 ISO 3166-2 subdivisions (Japan's prefectures, the American states, Canada's provinces and territories, France's regions and departments), each named in English and in Japanese. The names are Unicode CLDR's, with Wikidata filling the gaps, so they are the same on a server and in a browser, which `Intl.DisplayNames` is not. It looks a country up by what somebody typed (Holland, ＵＳＡ, どいつ, 米国) and a region by its code or its name. It works in [the demo](https://johnmorrisdotca.github.io/kuni/) with nothing to install.
+Kuni is the country list every site ends up keeping for itself, kept once, with what a form, a profile page or a map quiz asks of it: the 250 countries with their ISO 3166-1 codes, and their 5,050 ISO 3166-2 subdivisions (Japan's prefectures, the American states, Canada's provinces and territories, France's regions and departments), each named in English and in Japanese. Beside the names, in entries of their own so a page that only names countries does not carry them: each country's capital, population and area with the year each is for, coordinates, land borders, driving side and calendar conventions; each subdivision's capital, population and area; and 107 groupings, from the continents and the EU to Japan's eight regions. The names are Unicode CLDR's, with Wikidata filling the gaps, so they are the same on a server and in a browser, which `Intl.DisplayNames` is not. It looks a country up by what somebody typed (Holland, ＵＳＡ, にほん, 米国) and a region by its code or its name. It works in [the demo](https://johnmorrisdotca.github.io/kuni/) with nothing to install.
 
 ## In 30 seconds
 
@@ -45,12 +45,23 @@ npm install @johnmorrisdotca/kuni
 ```ts
 import { country, countryByName, countryName } from "@johnmorrisdotca/kuni";
 
-countryByName("ドイツ")?.alpha2;          // "DE"; "Germany", "どいつ" and "Deutschland" find it too
+countryByName("ドイツ")?.alpha2;          // "DE"; "Germany" and "Deutschland" find it too
 countryByName("Holland")?.name.ja;        // "オランダ"
 countryName("US", "ja", { short: true }); // "アメリカ"
 country("JP")?.callingCode;               // "+81"
 ```
 
+The figures and the groupings are entries of their own:
+
+```ts
+import { facts } from "@johnmorrisdotca/kuni/facts";
+import { membersOf } from "@johnmorrisdotca/kuni/groupings";
+
+facts("JP")?.population;                 // 123802000, for 2024
+facts("FR")?.borders;                    // ["AD", "BE", "BR", "CH", "DE", "ES", "IT", "LU", "MC", "SR"]
+membersOf("eu", { on: "2019-06-30" });   // the 28, the United Kingdom among them
+```
+
 One country's subdivisions are an entry of their own, so a page that needs Japan's prefectures carries Japan's and no other:
 
 ```ts
@@ -67,17 +78,24 @@ Install the scoped name: the unscoped `kuni` on npm is somebody else's package.
 - **Forms and profiles** that ask where somebody lives: a country select in either language, a state or prefecture select under it, and a free-text box whose "UK" or "Holland" still resolves to a code.
 - **Sites rendered on a server and hydrated in a browser**, where `Intl.DisplayNames` spells some countries differently in Node and in Chromium and the page does not match itself.
 - **Japanese-language pages** that need アメリカ合衆国 and オンタリオ州, the four kinds of Japanese prefecture (都道府県), and prefecture readings in kana.
-- **Maps, quizzes and data pipelines** that join their own figures to a country or a region by its ISO code.
+- **Maps, quizzes and data pipelines** that join their own figures to a country or a region by its ISO code, or want the capital, the population, the neighbours and the groupings a quiz asks about.
+- **Build scripts** in sister packages (a map that draws any grouping, a site with a page per prefecture) that read plain numbers, stable codes and as-of dates.
 
 ## Features
 
 - **Every country.** The 249 ISO 3166-1 codes and Kosovo (XK, user-assigned), each with alpha-2, alpha-3 and numeric codes, its flag, continent, UN M49 subregion, calling code, currencies, top-level domain, capital, time zones and languages.
-- **Every subdivision.** 5,046 ISO 3166-2 codes in 200 countries: 3,590 at the first level and 1,456 below it (France's departments in its regions, England's councils in England), each with its level and parent.
-- **English and Japanese names** from Unicode CLDR 48.2, with CLDR's short forms (UK, アメリカ) and variants (Ivory Coast, 象牙海岸). Japanese names for 3,523 of the 3,590 first-level subdivisions, and `null` for the rest, never a guess.
+- **Every subdivision.** 5,050 ISO 3166-2 codes in 200 countries: 3,594 at the first level and 1,456 below it (France's departments in its regions, England's councils in England), each with its level and parent.
+- **English and Japanese names** from Unicode CLDR 48.2, with CLDR's short forms (UK, アメリカ) and variants (Ivory Coast, 象牙海岸). Japanese names for 3,527 of the 3,594 first-level subdivisions, and `null` for the rest, never a guess.
 - **Found by what somebody typed.** Case, accents, full-width letters, half-width kana and hiragana or katakana are folded away, and the aliases people use (Holland, UK, Burma, 米国) are known.
 - **Kinds of place**: prefecture, state, province, region and some thirty more, read from Wikidata, with the Japanese word for each (県, 州, 省) where a country's names agree on one.
+- **Capitals in both languages.** Every country's capital in English and Japanese (東京, キーウ), and every subdivision's capital Wikidata names (3,968 of 5,050), with readings in kana for Japan's prefectural capitals (さっぽろし).
+- **Facts with their dates** (`/facts`): population and area with the year each is for, coordinates of the country and its capital, land borders (confirmed by Natural Earth's outlines, so islands have none), the side of the road it drives on, and CLDR's first day of the week, measurement system, paper size and clock. `distanceKm` between two points.
+- **Facts about subdivisions** (`/subdivision-facts`): each one's capital, population, area and coordinates, one country at a time; complete for Japan's 47 prefectures.
+- **Groupings** (`/groupings`): the seven continents, the 30 UN M49 areas, 23 international bodies (the UN, the EU, the euro area, Schengen, NATO, the G7 and G20, ASEAN and more) with the days members joined and left, 16 informal groupings (the Middle East, the Balkans, Scandinavia, the Sahel) each with the definition it follows, and regions inside a country (Japan's 地方, the US Census regions, Canada's regions).
 - **Small where it matters.** The countries and lookups are about 57 KB (19 KB gzipped); one country's subdivisions are their own entry (Japan's 47, 2.9 KB) or a dynamic import.
-- **Typed, frozen, pure and the same everywhere.** ESM and CommonJS, types for both, no dependencies, no network and no `Intl`.
+- **Typed, frozen, pure and the same everywhere.** ESM and CommonJS, types for both, no dependencies, no network and no `Intl`. Every export carries a doc comment with a runnable example, which an editor shows on hover and the tests run.
+- **A demo to use, not just to read.** A page for each country, two countries compared, every country in a sortable table, the groupings explorer, three seeded quizzes, a country and region form widget with its code to copy, and the data's quality in the open, each at an address of its own and downloadable as CSV, JSON or text: [the demo](https://johnmorrisdotca.github.io/kuni/).
+- **Never a guess.** A value no source gives is `null`, with the reason written down (`docs/facts.md`, `docs/subdivision-facts.md`, `docs/ja-gaps.md`), never a plausible filler.
 
 ## Use it in your project
 
@@ -99,7 +117,11 @@ It ships ES modules and CommonJS, with types for both and `sideEffects: false`.
 | `@johnmorrisdotca/kuni/codes` | The 250 codes and `isCountryCode`, nothing else | 2 KB |
 | `@johnmorrisdotca/kuni/subdivisions/<code>` | One country's subdivisions, every level (`/subdivisions/jp`, `/subdivisions/us`, lower case) | 1 to 13 KB; Japan 2.9 KB |
 | `@johnmorrisdotca/kuni/load` | `loadSubdivisions(code)`, one dynamic import per country | 11 KB, then the country's own file |
-| `@johnmorrisdotca/kuni/subdivisions` | All 5,046 subdivisions and the subdivision lookups | 216 KB, 85 KB gzipped |
+| `@johnmorrisdotca/kuni/subdivisions` | All 5,050 subdivisions and the subdivision lookups | 216 KB, 85 KB gzipped |
+| `@johnmorrisdotca/kuni/facts` | Every country's population, area, coordinates, borders, driving side and conventions | 25 KB, 9 KB gzipped |
+| `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts(code)`, one dynamic import per country | 12 KB, then the country's own file |
+| `@johnmorrisdotca/kuni/subdivision-facts/<code>` | One country's subdivision facts (`/subdivision-facts/jp`) | 1 to 16 KB; Japan 4.9 KB |
+| `@johnmorrisdotca/kuni/groupings` | The 107 groupings and their lookups | 84 KB, 16 KB gzipped |
 
 ### 1. The countries
 
@@ -139,6 +161,51 @@ subdivisions("FR", { level: "all" })?.length;                // 124, with the de
 subdivisionTypeLabel("JP-13", "ja");                         // "都"
 ```
 
+### 5. The facts about a country
+
+```ts
+import { allFacts, distanceKm, facts, FACTS_READ } from "@johnmorrisdotca/kuni/facts";
+
+const japan = facts("JP")!;
+japan.population;     // 123802000
+japan.populationYear; // 2024
+japan.areaKm2;        // 377973.68
+japan.capitalPoint;   // { lat: 35.69, lon: 139.69 }
+japan.borders;        // [], an island
+japan.drivingSide;    // "left"
+japan.weekStart;      // "sun"
+Math.round(distanceKm(japan.capitalPoint!, facts("GB")!.capitalPoint!)); // 9558
+FACTS_READ;           // "2026-10-09", the day Wikidata was read
+```
+
+Every figure is Wikidata's, as it stood on the day in `FACTS_READ`. A country with no permanent population (Antarctica) has `population: null`, and an island `borders: []`; `docs/facts.md` lists every gap with its reason.
+
+### 6. The facts about subdivisions
+
+```ts
+import { loadSubdivisionFacts } from "@johnmorrisdotca/kuni/subdivision-facts";
+import prefectures from "@johnmorrisdotca/kuni/subdivision-facts/jp";
+
+prefectures[0].capital;     // { en: "Sapporo", ja: "札幌市", reading: "さっぽろし" }
+prefectures[12].population; // 14264798, for 2022
+(await loadSubdivisionFacts("US"))?.find((one) => one.code === "US-CA")?.capital?.en; // "Sacramento"
+```
+
+### 7. Groupings
+
+```ts
+import { grouping, groupings, groupingsOf, membersOf } from "@johnmorrisdotca/kuni/groupings";
+
+grouping("eu")?.name.ja;                                  // "欧州連合"
+grouping("eu")?.others?.filter((one) => one.status === "candidate").length; // 9
+membersOf("eu", { on: "2019-06-30" })?.includes("GB");     // true
+groupingsOf("NO", { kind: "membership" }).map((one) => one.id); // ["un", "schengen", "eea", "nato", "oecd", "nordic-council"]
+membersOf("jp-kanto");                                    // ["JP-08", ..., "JP-14"]
+groupings({ kind: "informal" }).map((one) => one.id);     // ["middle-east", "latin-america", ...]
+```
+
+Each grouping has `definition`, `source` (name, address and licence) and `asOf`; an informal one has `informal: true` and, where definitions disagree, a `note`. `docs/groupings.md` cross-checks the bodies' lists against Wikidata and says what each grouping follows.
+
 ### In a page, with no bundler
 
 ```html
@@ -177,10 +244,10 @@ The Japanese name is `null` where no source has one, so the fallback to English
 ```ts
 import { countryByName } from "@johnmorrisdotca/kuni";
 
-for (const typed of ["UK", "the Netherlands", "ＵＳＡ", "どいつ", "Burma", "Narnia"]) {
+for (const typed of ["UK", "the Netherlands", "ＵＳＡ", "にほん", "Burma", "Narnia"]) {
   console.log(typed, countryByName(typed)?.alpha2 ?? "(keep their words, no flag)");
 }
-// UK GB · the Netherlands NL · ＵＳＡ US · どいつ DE · Burma MM · Narnia (keep their words, no flag)
+// UK GB · the Netherlands NL · ＵＳＡ US · にほん JP · Burma MM · Narnia (keep their words, no flag)
 ```
 
 ### A name that is two places
@@ -204,6 +271,10 @@ The [API reference](https://johnmorrisdotca.github.io/kuni/api.html) lists every
 | `@johnmorrisdotca/kuni/subdivisions` | `subdivisions`, `allSubdivisions`, `subdivision`, `subdivisionByShortCode`, `subdivisionByName`, `subdivisionsByName`, `subdivisionTypeLabel`, `SUBDIVISION_TYPES`, and the types `Subdivision`, `SubdivisionType`, `Level`, `SubdivisionsOptions` and `SubdivisionByNameOptions` |
 | `@johnmorrisdotca/kuni/subdivisions/<code>` | the country's list as the default export and as `SUBDIVISIONS` |
 | `@johnmorrisdotca/kuni/load` | `loadSubdivisions` and the type `Subdivision` |
+| `@johnmorrisdotca/kuni/facts` | `facts`, `allFacts`, `distanceKm`, `FACTS_READ`, and the types `CountryFacts`, `LatLon`, `DrivingSide`, `WeekStart`, `MeasurementSystem`, `PaperSize` and `HourCycle` |
+| `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts`, and the types `SubdivisionFacts` and `LatLon` |
+| `@johnmorrisdotca/kuni/subdivision-facts/<code>` | the country's subdivision facts as the default export and as `SUBDIVISION_FACTS` |
+| `@johnmorrisdotca/kuni/groupings` | `groupings`, `grouping`, `groupingsOf`, `membersOf`, `GROUPING_KINDS`, and the types `Grouping`, `GroupingKind`, `GroupingMember`, `GroupingName`, `GroupingOther`, `GroupingSource`, `GroupingStatus`, `GroupingsOptions` and `GroupingDateOptions` |
 
 A country:
 
@@ -217,12 +288,12 @@ interface Country {
   shortName?: { en?: string; ja?: string };           // "UK", アメリカ
   reading?: string;               // hiragana, where the Japanese name is in kanji: "にほん"
   flag: string;                   // the flag emoji
-  continent: "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
+  continent: "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";   // from UN M49; Antarctica by hand
   subregion?: string;             // UN M49: "030", Eastern Asia
   callingCode?: string;           // "+81"; "+1" for every member of the North American plan
   currency?: string[];            // ["JPY"]
   tld?: string;                   // "jp"; "uk" for GB
-  capital?: { en: string };
+  capital?: { en: string; ja: string };   // "Tokyo", 東京
   zones?: string[];               // ["Asia/Tokyo"]
   languages?: string[];           // ["ja"]
   subdivisionType?: SubdivisionType;   // "prefecture"
@@ -245,6 +316,51 @@ interface Subdivision {
 }
 ```
 
+The facts about a country:
+
+```ts
+interface CountryFacts {
+  alpha2: string;                 // "JP"
+  population: number | null;      // 123802000; null with no permanent population
+  populationYear: number | null;  // 2024
+  areaKm2: number | null;         // 377973.68
+  areaYear: number | null;        // where Wikidata gives one
+  areaOf: "whole" | "land" | null;
+  point: { lat: number; lon: number } | null;         // Wikidata's point for the country, not a computed centroid
+  capitalPoint: { lat: number; lon: number } | null;
+  borders: readonly string[];     // land borders, alpha-2; [] for an island
+  drivingSide: "left" | "right" | null;
+  weekStart: "mon" | "sun" | "sat" | "fri";
+  measurement: "metric" | "US" | "UK";
+  paper: "A4" | "US-Letter";
+  hourCycle: "h12" | "h23";
+}
+```
+
+A grouping:
+
+```ts
+interface Grouping {
+  id: string;                     // "eu", "m49-030", "continent-as", "middle-east", "jp-kanto"
+  kind: "continent" | "m49" | "membership" | "informal" | "subdivision";
+  name: { en: string; ja: string };
+  shortName?: { en?: string; ja?: string };   // "EU"
+  reading?: string;               // "おうしゅうれんごう"
+  otherNames?: readonly { en: string; ja: string; reading?: string }[];   // Kansai (関西地方) for the Kinki region
+  informal: boolean;
+  country?: string;               // for regions inside a country: "JP"
+  parent?: string;                // for UN M49: "m49-142"
+  sets?: readonly string[];       // for regions inside a country: the divisions it is part of
+  members: readonly string[];     // alpha-2 codes, or ISO 3166-2 inside a country
+  periods?: readonly { code: string; since: string | null; until: string | null }[];   // bodies only
+  others?: readonly { code: string; status: "candidate" | "associate" | "observer" | "suspended" }[];
+  definition: string;
+  note?: string;
+  source: { name: string; url: string; licence: string };
+  asOf: string;                   // "2026-10-09"
+}
+```
+
 Every function is pure and every object it hands out is frozen. A code or a name that is not one gives `null` (or an empty list), never a near miss.
 
 ## Theming
@@ -256,13 +372,19 @@ None, on purpose: Kuni is data and lookups, with no colours, markup or styles, s
 | Limit | Value | Where |
 | --- | --- | --- |
 | Countries | 250: the 249 ISO 3166-1 codes and XK | `COUNTRY_CODES` |
-| Subdivisions | 5,046 in 200 countries; 3,590 at level 1, 1,456 at level 2, none at level 3 | `allSubdivisions` |
-| Japanese names of subdivisions | 3,523 of 3,590 at level 1 (3,387 from CLDR, 41 written by hand, 95 from Wikidata); 4,747 of all 5,046 | `name.ja`, [docs/ja-gaps.md](./docs/ja-gaps.md) |
-| Kinds of place | known for 4,739 of 5,046; the rest are `null` | `type` |
+| Subdivisions | 5,050 in 200 countries; 3,594 at level 1, 1,456 at level 2, none at level 3 | `allSubdivisions` |
+| Japanese names of subdivisions | 3,527 of 3,594 at level 1 (3,376 from CLDR, 50 written by hand, 101 from Wikidata); 4,751 of all 5,050 | `name.ja`, [docs/ja-gaps.md](./docs/ja-gaps.md) |
+| Kinds of place | known for 4,745 of 5,050; the rest are `null` | `type` |
 | Readings in kana | Japan's 47 prefectures, and the 53 country names written with kanji | `reading` |
+| Capitals | 245 of 250 countries, each in English and Japanese; 3,968 of 5,050 subdivisions (2,856 of 3,594 at the first level), Japan's 47 with readings | `capital`, `SubdivisionFacts.capital` |
+| Population | 249 of 250 countries, with the year; 4,244 of 5,050 subdivisions | `/facts`, `/subdivision-facts` |
+| Area | 250 of 250 countries; 4,371 of 5,050 subdivisions | `areaKm2` |
+| Coordinates | 250 of 250 countries, 245 capitals; 4,780 of 5,050 subdivisions | `point`, `capitalPoint` |
+| Land borders | 327 pairs; 166 countries have one or more, 84 (islands, and Antarctica) none | `borders` |
+| Groupings | 7 continents, 30 UN M49 areas, 23 bodies, 16 informal, 31 inside a country | `/groupings` |
 | Languages | English and Japanese | `LANGUAGES` |
 
-Not here: cities, postal codes, coordinates, outlines, populations, and names in other languages. CLDR marks nearly all of its Japanese subdivision names "provisional"; where Wikidata names a place differently, CLDR's name is kept and the difference listed in [docs/disagreements.md](./docs/disagreements.md) (234 of 4,322 compared) for review. CLDR's trailing brackets (セント・ポール (ドミニカ国), バリンゴ (カウンティ)) are taken off by a rule listed in [docs/name-rules.md](./docs/name-rules.md), and 46 names a reviewer found wrong or out of date are written by hand, with their reasons, in [docs/disagreements.md](./docs/disagreements.md).
+Not here: cities, postal codes, outlines, and names in other languages. CLDR marks nearly all of its Japanese subdivision names "provisional"; where Wikidata names a place differently, CLDR's name is kept and the difference listed in [docs/disagreements.md](./docs/disagreements.md) (226 of 4,313 compared) for review. CLDR's trailing brackets (セント・ポール (ドミニカ国), バリンゴ (カウンティ)) are taken off by a rule listed in [docs/name-rules.md](./docs/name-rules.md), and 56 Japanese names a reviewer found wrong or out of date are written by hand, with their reasons, in [docs/disagreements.md](./docs/disagreements.md). Every English name is checked against Wikidata's English label for the patterns that were found wrong in 1.0.0 (a name cut short, an adjective for a name, marks stripped, a name swapped with a neighbour's, an old place's name on a reused code); 32 are corrected by hand, with their reasons, in the same file. Where ISO 3166-2 has changed since CLDR's release (Norway's counties of 2024), the codes follow ISO.
 
 ## Accessibility
 
@@ -271,6 +393,7 @@ Kuni draws nothing: it gives a page names, codes and readings, so what it can do
 - **Names in the reader's language.** Every country and nearly every first-level subdivision has a Japanese name, and Japan's prefectures and the kanji country names have readings in hiragana, for furigana or for a screen reader.
 - **Forgiving search.** A person who types in kana, in full-width letters or without accents still finds the place.
 - **Flags are never the only label.** A flag is an emoji that many screen readers say only as two letters; the demo always writes the name beside it.
+- **In the demo's views**, the country page's outline has a label naming the country, every table has column headers (the table of every country sorts from its headers, which are buttons and say which way they sort), a quiz's answer is said in words as well as colour, and the time in each zone is text, not a moving picture.
 - **In the demo**, every panel is a labelled region, each box has a label, the answers are `aria-live`, the list of subdivisions is a real table with column headers, every control is at least 44 pixels square, and the page fits a phone at 390 pixels.
 - **Not yet.** The demo's colours have not been measured against WCAG contrast ratios, and its Japanese has not been read by a native reader (see [Languages](#languages)).
 
@@ -290,7 +413,10 @@ Not here yet, and each welcome as an [issue](https://github.com/johnmorrisdotca/
 - Each subdivision's name in its own language and script (Wikidata P1705).
 - The Japanese names CLDR and Wikidata both lack (listed in [docs/ja-gaps.md](./docs/ja-gaps.md)), when a source has them.
 
-Left out on purpose: geometry and coordinates (see [Chizu](https://github.com/johnmorrisdotca/chizu)), and any data under a share-alike or GPL licence.
+- Flags as pictures. `flag` is an emoji, which Windows draws as two letters; a flags package of the family (Hata, 旗) is being made, and a page can swap the emoji for its picture by the same alpha-2 code.
+- La Francophonie among the groupings, once its tiers and its 2025 withdrawals can be checked against its own list.
+
+Left out on purpose: geometry (see [Chizu](https://github.com/johnmorrisdotca/chizu), which draws the outlines), and any data under a share-alike or GPL licence.
 
 ## Architecture
 
@@ -300,25 +426,33 @@ src/
 ├── codes.ts            the "/codes" entry: the codes alone
 ├── subdivisions.ts     the "/subdivisions" entry: every subdivision and its lookups
 ├── load.ts             the "/load" entry: one country's subdivisions by dynamic import
+├── facts.ts            the "/facts" entry: population, area, coordinates, borders and conventions
+├── subdivision-facts.ts  the "/subdivision-facts" entry: one country's subdivision facts by dynamic import
+├── groupings.ts        the "/groupings" entry: continents, UN M49, bodies, informal groupings, regions
 ├── fold.ts             folding what somebody typed: case, accents, width, kana
 ├── rows.ts             turning the data's compact rows into objects
 ├── types.ts            the shapes of a country and a subdivision, and the kinds of place
 ├── version.ts          the package's version
-├── data/               written by scripts/build-data.ts: countries, codes, and a file per country
-└── subdivisions/       written by scripts/build-data.ts: the "/subdivisions/<code>" entries
+├── data/               written by scripts/build-data.ts: countries, codes, facts, groupings, and files per country
+├── subdivisions/       written by scripts/build-data.ts: the "/subdivisions/<code>" entries
+└── subdivision-facts/  written by scripts/build-data.ts: the "/subdivision-facts/<code>" entries
 ```
 
-`scripts/build-data.ts` (`pnpm data`) makes `src/data/` from the inputs in `data-sources/` and three npm packages, with no network, and checks every input's SHA-256 first; run twice, it leaves the tree as it was. `scripts/data-config.ts` holds the few things written by hand. Tests sit beside the code (`*.test.ts`). `scripts/` also builds the demo and its API page and checks the package as npm packs it; `demo/` is the page and `e2e/` its browser tests.
+`scripts/build-data.ts` (`pnpm data`) makes `src/data/` from the inputs in `data-sources/` and three npm packages, with no network, and checks every input's SHA-256 first; run twice, it leaves the tree as it was. `scripts/data-config.ts`, `scripts/facts-config.ts` and `scripts/groupings-config.ts` hold the few things written by hand, each with its reason; `scripts/facts.ts`, `scripts/subdivision-facts.ts` and `scripts/groupings.ts` apply the rules written at their tops. Tests sit beside the code (`*.test.ts`). `scripts/` also builds the demo and its API page and checks the package as npm packs it; `demo/` is the page and `e2e/` its browser tests.
 
 ## Data and licences
 
 | What | From | Licence |
 | --- | --- | --- |
-| Country names, short and variant forms, codes, currencies, continents and subregions | Unicode CLDR 48.2 (`cldr-core`, `cldr-localenames-full`) | Unicode-3.0 |
+| Country names, short and variant forms, codes, currencies, continents (UN M49) and subregions | Unicode CLDR 48.2 (`cldr-core`, `cldr-localenames-full`) | Unicode-3.0 |
 | Subdivision codes, names, levels and parents | Unicode CLDR 48.2 (`common/subdivisions`, validity and containment) | Unicode-3.0 |
 | Japanese names CLDR lacks, prefecture readings, calling codes, kinds of place | Wikidata, a snapshot of 2026-10-09 | CC0 |
-| Own names, capitals, continents, languages | countries-list 3.4.1 | MIT |
+| Own names, capitals, languages | countries-list 3.4.1 | MIT |
 | Time zones and top-level domains | IANA tzdb 2026e `zone.tab`, IANA's TLD list | Public domain; a list of facts |
+| Capitals in Japanese, coordinates, population, area, driving side, borders, subdivisions' capitals and figures, and the dates members joined bodies | Wikidata, a snapshot of 2026-10-09 (`data-sources/wikidata-facts-2026-10-09.json`) | CC0 |
+| Land borders, confirmed | Natural Earth 5.1.2 admin-0 at 1:50m, as drawn by Chizu 1.0.2 (a development dependency of the build, never of the package) | Public domain (Natural Earth); MIT (Chizu) |
+| First day of the week, measurement system, paper size, clock; UN M49; the UN's members | Unicode CLDR 48.2 (`cldr-core`) | Unicode-3.0 |
+| The bodies' members, the informal groupings and the regions inside a country | written for this package from each body's own list, on 2026-10-09 (`scripts/groupings-config.ts`) | MIT; lists of facts |
 | Aliases, a few readings and 46 corrected Japanese subdivision names | written for this package | MIT |
 
 [NOTICE.md](./NOTICE.md) carries the Unicode licence text and says what was changed, and [data-sources/README.md](./data-sources/README.md) says where every input came from and how to refresh it. Nothing under ODbL, CC BY-SA or the GPL is used, so the dataset is shipped under MIT with those notices.
@@ -380,6 +514,7 @@ pnpm test:demo            # build the demo and play it in a real browser, at a p
 pnpm site                 # build the demo into site/, as the Pages workflow publishes it
 pnpm screenshots:readme   # take the README's pictures from the built demo, in light and dark
 pnpm data                 # rebuild src/data/ from data-sources/ (no network)
+pnpm data:facts           # a new Wikidata snapshot of the facts and the dates (network)
 pnpm data:report          # the coverage, and docs/ja-gaps.md
 pnpm docs:make            # rewrite docs/strings-ja.md after changing a word of the demo
 ```
@@ -390,8 +525,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md); the commands are under [Development](#
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). The first version is 1.0.0.
+See [CHANGELOG.md](./CHANGELOG.md). The latest release, 1.1.0, adds country and subdivision facts, 107 groupings, corrected names and continents, documentation on every export, and a demo with a country page, compare, a table, quizzes and a form widget.
 
 ## Licence
 
-MIT, © John Morris. The data is made from Unicode CLDR (Unicode-3.0), Wikidata (CC0), countries-list (MIT) and IANA (public domain), credited with their terms in [NOTICE.md](./NOTICE.md), which ships with the package.
+MIT, © John Morris. The data is made from Unicode CLDR (Unicode-3.0), Wikidata (CC0), countries-list (MIT), IANA (public domain) and, for confirming land borders, Natural Earth (public domain), credited with their terms in [NOTICE.md](./NOTICE.md), which ships with the package.

package/dist/codes.d.cts

@@ -1,6 +1,33 @@
+/**
+ * The 250 country codes: the 249 ISO 3166-1 alpha-2 codes and XK for Kosovo, in alphabetical order.
+ *
+ * @example
+ * ```ts
+ * import { COUNTRY_CODES } from "@johnmorrisdotca/kuni/codes";
+ *
+ * COUNTRY_CODES.length;   // 250
+ * COUNTRY_CODES[0];       // "AD"
+ * ```
+ */
 declare const COUNTRY_CODES: readonly ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW"];
+/** One of the 250 country codes, as a type: "JP" | "US" | ... */
 type CountryCode = (typeof COUNTRY_CODES)[number];
 
+/**
+ * Whether a value is one of the 250 codes exactly as ISO writes it: two capital letters ("JP", and "XK" for
+ * Kosovo). Lower case is not a code here; `country()` in the main entry is the forgiving one.
+ *
+ * @param value - Anything.
+ * @returns True for one of the 250 codes; false for anything else, a lower-case code included.
+ * @example
+ * ```ts
+ * import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
+ *
+ * isCountryCode("JP");   // true
+ * isCountryCode("jp");   // false
+ * isCountryCode("XX");   // false
+ * ```
+ */
 declare const isCountryCode: (value: unknown) => value is CountryCode;
 
 export { COUNTRY_CODES, type CountryCode, isCountryCode };

package/dist/codes.d.ts

@@ -1,6 +1,33 @@
+/**
+ * The 250 country codes: the 249 ISO 3166-1 alpha-2 codes and XK for Kosovo, in alphabetical order.
+ *
+ * @example
+ * ```ts
+ * import { COUNTRY_CODES } from "@johnmorrisdotca/kuni/codes";
+ *
+ * COUNTRY_CODES.length;   // 250
+ * COUNTRY_CODES[0];       // "AD"
+ * ```
+ */
 declare const COUNTRY_CODES: readonly ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW"];
+/** One of the 250 country codes, as a type: "JP" | "US" | ... */
 type CountryCode = (typeof COUNTRY_CODES)[number];
 
+/**
+ * Whether a value is one of the 250 codes exactly as ISO writes it: two capital letters ("JP", and "XK" for
+ * Kosovo). Lower case is not a code here; `country()` in the main entry is the forgiving one.
+ *
+ * @param value - Anything.
+ * @returns True for one of the 250 codes; false for anything else, a lower-case code included.
+ * @example
+ * ```ts
+ * import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
+ *
+ * isCountryCode("JP");   // true
+ * isCountryCode("jp");   // false
+ * isCountryCode("XX");   // false
+ * ```
+ */
 declare const isCountryCode: (value: unknown) => value is CountryCode;
 
 export { COUNTRY_CODES, type CountryCode, isCountryCode };