@johnmorrisdotca/kuni 0.0.0-stage → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+export { COUNTRY_CODES, CountryCode, isCountryCode } from './codes.cjs';
+import { c as Continent, d as Language, e as Country } from './types-ChquRAZM.cjs';
+export { f as CONTINENTS, g as LANGUAGES, S as Subdivision, h as SubdivisionType } from './types-ChquRAZM.cjs';
+
+/**
+ * What two ways of typing a name have in common: width (full-width letters to ASCII, half-width katakana to full),
+ * case, accents (except the two marks that make が and ぱ), katakana to hiragana, apostrophes dropped, and every
+ * other run of punctuation or space to one space. The lookups compare names folded, and so can a page.
+ *
+ * @param text - Any text.
+ * @returns The text folded; "" for text that is only punctuation or space.
+ * @example
+ * ```ts
+ * import { fold } from "@johnmorrisdotca/kuni";
+ *
+ * fold("Côte d'Ivoire");   // "cote divoire"
+ * fold("ＵＳＡ");           // "usa"
+ * fold("ドイツ");           // "どいつ"
+ * ```
+ */
+declare const fold: (text: string) => string;
+
+/**
+ * The package's version, the same as package.json's.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "@johnmorrisdotca/kuni";
+ *
+ * console.log(`kuni ${VERSION}`);
+ * ```
+ */
+declare const VERSION = "1.1.0";
+
+/** The order `countries()` lists them in: "code" (alpha-2), "en" (by English name) or "ja" (by Japanese name, in kana). */
+type CountryOrder = "code" | "en" | "ja";
+/** What `countries()` may be asked. */
+interface CountriesOptions {
+    /** "code" (the default) is alpha-2 order; "en" and "ja" are by name, as `countries` says. */
+    order?: CountryOrder;
+}
+/** What `countryName()` may be asked. */
+interface CountryNameOptions {
+    /** The short form where CLDR has one ("UK", アメリカ), the full name otherwise. */
+    short?: boolean;
+}
+/**
+ * One country by its code.
+ *
+ * @param code - Alpha-2 ("JP", "jp"), alpha-3 ("JPN") or numeric ("392").
+ * @returns The country, frozen; `null` for anything that is not one of the 250 codes.
+ * @example
+ * ```ts
+ * import { country } from "@johnmorrisdotca/kuni";
+ *
+ * country("JP")?.name.en;     // "Japan"
+ * country("jpn")?.alpha2;     // "JP"
+ * country("392")?.name.ja;    // "日本"
+ * country("JP")?.capital;     // { "en": "Tokyo", "ja": "東京" }
+ * country("XX");              // null
+ * ```
+ */
+declare const country: (code: string) => Country | null;
+/**
+ * Every country: the 249 ISO 3166-1 codes and Kosovo (XK). `order: "en"` sorts by the English name folded
+ * (accents and case set aside); `order: "ja"` by the Japanese name in kana, its reading where it is written in
+ * kanji, in plain kana order (not a full Japanese collation).
+ *
+ * @param options - `order`: "code" (the default), "en" or "ja".
+ * @returns The 250 countries, the list and its objects frozen and shared.
+ * @example
+ * ```ts
+ * import { countries } from "@johnmorrisdotca/kuni";
+ *
+ * countries().length;                          // 250
+ * countries({ order: "en" })[0].name.en;       // "Afghanistan"
+ * countries({ order: "ja" })[0].name.ja;       // "アイスランド"
+ * ```
+ */
+declare const countries: (options?: CountriesOptions) => readonly Country[];
+/**
+ * A country from what somebody typed: its name or short name in English or Japanese ("Germany", ドイツ, どいつ),
+ * its own name ("Deutschland"), a name it is also known by ("Holland", "UK", 米国), or a code. Case, accents,
+ * width, kana and punctuation do not matter.
+ *
+ * @param text - What was typed.
+ * @returns The country, frozen; `null` when nothing matches, never a near miss.
+ * @example
+ * ```ts
+ * import { countryByName } from "@johnmorrisdotca/kuni";
+ *
+ * countryByName("ドイツ")?.alpha2;          // "DE"
+ * countryByName("Holland")?.name.ja;        // "オランダ"
+ * countryByName("ＵＳＡ")?.alpha2;           // "US"
+ * countryByName("cote d'ivoire")?.alpha2;   // "CI"
+ * countryByName("Narnia");                  // null
+ * ```
+ */
+declare const countryByName: (text: string) => Country | null;
+/**
+ * A country's name in English or Japanese.
+ *
+ * @param code - Any code `country()` takes.
+ * @param language - "en" (the default) or "ja".
+ * @param options - `short: true` for the short form where CLDR has one ("UK", アメリカ).
+ * @returns The name; `null` for a code that is not a country, or a language that is not one of the two.
+ * @example
+ * ```ts
+ * import { countryName } from "@johnmorrisdotca/kuni";
+ *
+ * countryName("US");                         // "United States"
+ * countryName("US", "ja", { short: true });  // "アメリカ"
+ * countryName("GB", "en", { short: true });  // "UK"
+ * countryName("XX");                         // null
+ * ```
+ */
+declare const countryName: (code: string, language?: Language, options?: CountryNameOptions) => string | null;
+/**
+ * The flag of a country as an emoji: two regional-indicator letters, which most systems draw as the flag and some
+ * (Windows) as the two letters. Write the country's name beside it.
+ *
+ * @param code - Any code `country()` takes.
+ * @returns The emoji; `null` for a code that is not a country.
+ * @example
+ * ```ts
+ * import { flag } from "@johnmorrisdotca/kuni";
+ *
+ * flag("JP");   // "🇯🇵"
+ * flag("XX");   // null
+ * ```
+ */
+declare const flag: (code: string) => string | null;
+/**
+ * A continent's name, from CLDR.
+ *
+ * @param continent - One of the seven two-letter continents.
+ * @param language - "en" (the default) or "ja".
+ * @returns The name; `null` for anything that is not one of the seven.
+ * @example
+ * ```ts
+ * import { continentName } from "@johnmorrisdotca/kuni";
+ *
+ * continentName("AS");         // "Asia"
+ * continentName("AS", "ja");   // "アジア"
+ * ```
+ */
+declare const continentName: (continent: Continent, language?: Language) => string | null;
+/**
+ * A UN M49 subregion's name, from CLDR.
+ *
+ * @param subregion - Three digits, as `Country.subregion` gives it: "030".
+ * @param language - "en" (the default) or "ja".
+ * @returns The name; `null` for a code no country is in.
+ * @example
+ * ```ts
+ * import { subregionName } from "@johnmorrisdotca/kuni";
+ *
+ * subregionName("030");         // "Eastern Asia"
+ * subregionName("030", "ja");   // "東アジア"
+ * ```
+ */
+declare const subregionName: (subregion: string, language?: Language) => string | null;
+
+export { Continent, type CountriesOptions, Country, type CountryNameOptions, type CountryOrder, Language, VERSION, continentName, countries, country, countryByName, countryName, flag, fold, subregionName };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+export { COUNTRY_CODES, CountryCode, isCountryCode } from './codes.js';
+import { c as Continent, d as Language, e as Country } from './types-ChquRAZM.js';
+export { f as CONTINENTS, g as LANGUAGES, S as Subdivision, h as SubdivisionType } from './types-ChquRAZM.js';
+
+/**
+ * What two ways of typing a name have in common: width (full-width letters to ASCII, half-width katakana to full),
+ * case, accents (except the two marks that make が and ぱ), katakana to hiragana, apostrophes dropped, and every
+ * other run of punctuation or space to one space. The lookups compare names folded, and so can a page.
+ *
+ * @param text - Any text.
+ * @returns The text folded; "" for text that is only punctuation or space.
+ * @example
+ * ```ts
+ * import { fold } from "@johnmorrisdotca/kuni";
+ *
+ * fold("Côte d'Ivoire");   // "cote divoire"
+ * fold("ＵＳＡ");           // "usa"
+ * fold("ドイツ");           // "どいつ"
+ * ```
+ */
+declare const fold: (text: string) => string;
+
+/**
+ * The package's version, the same as package.json's.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "@johnmorrisdotca/kuni";
+ *
+ * console.log(`kuni ${VERSION}`);
+ * ```
+ */
+declare const VERSION = "1.1.0";
+
+/** The order `countries()` lists them in: "code" (alpha-2), "en" (by English name) or "ja" (by Japanese name, in kana). */
+type CountryOrder = "code" | "en" | "ja";
+/** What `countries()` may be asked. */
+interface CountriesOptions {
+    /** "code" (the default) is alpha-2 order; "en" and "ja" are by name, as `countries` says. */
+    order?: CountryOrder;
+}
+/** What `countryName()` may be asked. */
+interface CountryNameOptions {
+    /** The short form where CLDR has one ("UK", アメリカ), the full name otherwise. */
+    short?: boolean;
+}
+/**
+ * One country by its code.
+ *
+ * @param code - Alpha-2 ("JP", "jp"), alpha-3 ("JPN") or numeric ("392").
+ * @returns The country, frozen; `null` for anything that is not one of the 250 codes.
+ * @example
+ * ```ts
+ * import { country } from "@johnmorrisdotca/kuni";
+ *
+ * country("JP")?.name.en;     // "Japan"
+ * country("jpn")?.alpha2;     // "JP"
+ * country("392")?.name.ja;    // "日本"
+ * country("JP")?.capital;     // { "en": "Tokyo", "ja": "東京" }
+ * country("XX");              // null
+ * ```
+ */
+declare const country: (code: string) => Country | null;
+/**
+ * Every country: the 249 ISO 3166-1 codes and Kosovo (XK). `order: "en"` sorts by the English name folded
+ * (accents and case set aside); `order: "ja"` by the Japanese name in kana, its reading where it is written in
+ * kanji, in plain kana order (not a full Japanese collation).
+ *
+ * @param options - `order`: "code" (the default), "en" or "ja".
+ * @returns The 250 countries, the list and its objects frozen and shared.
+ * @example
+ * ```ts
+ * import { countries } from "@johnmorrisdotca/kuni";
+ *
+ * countries().length;                          // 250
+ * countries({ order: "en" })[0].name.en;       // "Afghanistan"
+ * countries({ order: "ja" })[0].name.ja;       // "アイスランド"
+ * ```
+ */
+declare const countries: (options?: CountriesOptions) => readonly Country[];
+/**
+ * A country from what somebody typed: its name or short name in English or Japanese ("Germany", ドイツ, どいつ),
+ * its own name ("Deutschland"), a name it is also known by ("Holland", "UK", 米国), or a code. Case, accents,
+ * width, kana and punctuation do not matter.
+ *
+ * @param text - What was typed.
+ * @returns The country, frozen; `null` when nothing matches, never a near miss.
+ * @example
+ * ```ts
+ * import { countryByName } from "@johnmorrisdotca/kuni";
+ *
+ * countryByName("ドイツ")?.alpha2;          // "DE"
+ * countryByName("Holland")?.name.ja;        // "オランダ"
+ * countryByName("ＵＳＡ")?.alpha2;           // "US"
+ * countryByName("cote d'ivoire")?.alpha2;   // "CI"
+ * countryByName("Narnia");                  // null
+ * ```
+ */
+declare const countryByName: (text: string) => Country | null;
+/**
+ * A country's name in English or Japanese.
+ *
+ * @param code - Any code `country()` takes.
+ * @param language - "en" (the default) or "ja".
+ * @param options - `short: true` for the short form where CLDR has one ("UK", アメリカ).
+ * @returns The name; `null` for a code that is not a country, or a language that is not one of the two.
+ * @example
+ * ```ts
+ * import { countryName } from "@johnmorrisdotca/kuni";
+ *
+ * countryName("US");                         // "United States"
+ * countryName("US", "ja", { short: true });  // "アメリカ"
+ * countryName("GB", "en", { short: true });  // "UK"
+ * countryName("XX");                         // null
+ * ```
+ */
+declare const countryName: (code: string, language?: Language, options?: CountryNameOptions) => string | null;
+/**
+ * The flag of a country as an emoji: two regional-indicator letters, which most systems draw as the flag and some
+ * (Windows) as the two letters. Write the country's name beside it.
+ *
+ * @param code - Any code `country()` takes.
+ * @returns The emoji; `null` for a code that is not a country.
+ * @example
+ * ```ts
+ * import { flag } from "@johnmorrisdotca/kuni";
+ *
+ * flag("JP");   // "🇯🇵"
+ * flag("XX");   // null
+ * ```
+ */
+declare const flag: (code: string) => string | null;
+/**
+ * A continent's name, from CLDR.
+ *
+ * @param continent - One of the seven two-letter continents.
+ * @param language - "en" (the default) or "ja".
+ * @returns The name; `null` for anything that is not one of the seven.
+ * @example
+ * ```ts
+ * import { continentName } from "@johnmorrisdotca/kuni";
+ *
+ * continentName("AS");         // "Asia"
+ * continentName("AS", "ja");   // "アジア"
+ * ```
+ */
+declare const continentName: (continent: Continent, language?: Language) => string | null;
+/**
+ * A UN M49 subregion's name, from CLDR.
+ *
+ * @param subregion - Three digits, as `Country.subregion` gives it: "030".
+ * @param language - "en" (the default) or "ja".
+ * @returns The name; `null` for a code no country is in.
+ * @example
+ * ```ts
+ * import { subregionName } from "@johnmorrisdotca/kuni";
+ *
+ * subregionName("030");         // "Eastern Asia"
+ * subregionName("030", "ja");   // "東アジア"
+ * ```
+ */
+declare const subregionName: (subregion: string, language?: Language) => string | null;
+
+export { Continent, type CountriesOptions, Country, type CountryNameOptions, type CountryOrder, Language, VERSION, continentName, countries, country, countryByName, countryName, flag, fold, subregionName };