@temboplus/frontend-core 0.2.5 → 0.2.6

package/esm/src/models/country/country.js

@@ -1,4 +1,31 @@
-import { CountryService } from "./service.js";
+/**
+ * @fileoverview This file contains both the Country class and CountryService class.
+ *
+ * ARCHITECTURE NOTE: Country and CountryService Classes
+ * ======================================================
+ *
+ * These two classes have been intentionally placed in the same file to resolve
+ * a circular dependency issue. The original implementation had these in separate files:
+ *
+ * - Country class: Defines country properties and static accessors
+ * - CountryService class: Loads country data and provides instance methods
+ *
+ * The circular dependency occurred because:
+ * 1. Country needed CountryService to initialize its static properties
+ * 2. CountryService needed Country to create Country instances
+ *
+ * By combining both classes in a single file:
+ * - We ensure proper initialization order
+ * - All static properties are immediately available after import
+ * - The public API remains unchanged
+ *
+ * This approach also better encapsulates related functionality in a single module,
+ * making it easier to understand and maintain the country-related domain model.
+ * The addition of currency support through the getCurrency() method leverages
+ * the Currency model while maintaining a clean separation of concerns.
+ */
+import { Currency } from "../currency/currency.js";
+import file from "../../data/countries.js";
 /**
  * Enum for continents
  */
@@ -47,25 +74,26 @@ export class Country {
     /**
      * Creates a new Country instance.
      * @param {string} _name - The common name of the country
-     * @param {string} _code - The ISO-2 country code
+     * @param {string} _iso2 - The ISO-2 country code
      * @param {string} _nameOfficial - The official name of the country
      * @param {string} _iso3 - The ISO-3 country code
      * @param {string} _flagEmoji - The flag emoji of the country
      * @param {CONTINENT} _continent - The continent where the country is located
      * @param {SUB_REGION} _region - The region within the continent where the country is located
+     * @param {string | null} _currencyCode - The ISO currency code used in the country
      */
-    constructor(_name, _code, _nameOfficial = "", _iso3 = "", _flagEmoji = "", _continent = CONTINENT.EUROPE, _region = SUB_REGION.NORTHERN_EUROPE) {
+    constructor(_name, _iso2, _nameOfficial = "", _iso3, _flagEmoji = "", _continent = CONTINENT.EUROPE, _region = SUB_REGION.NORTHERN_EUROPE, _currencyCode = null) {
         Object.defineProperty(this, "_name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: _name
         });
-        Object.defineProperty(this, "_code", {
+        Object.defineProperty(this, "_iso2", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: _code
+            value: _iso2
         });
         Object.defineProperty(this, "_nameOfficial", {
             enumerable: true,
@@ -97,6 +125,12 @@ export class Country {
             writable: true,
             value: _region
         });
+        Object.defineProperty(this, "_currencyCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: _currencyCode
+        });
     }
     /**
      * Gets the common name of the country.
@@ -107,10 +141,10 @@ export class Country {
     }
     /**
      * Gets the ISO-2 code of the country.
-     * @returns {string} The ISO-2 code of the country
+     * @returns {ISO2CountryCode} The ISO-2 code of the country
      */
     get code() {
-        return this._code;
+        return this._iso2;
     }
     /**
      * Gets the official name of the country.
@@ -121,7 +155,7 @@ export class Country {
     }
     /**
      * Gets the ISO-3 code of the country.
-     * @returns {string} The ISO-3 code of the country
+     * @returns {ISO3CountryCode} The ISO-3 code of the country
      */
     get iso3() {
         return this._iso3;
@@ -147,6 +181,23 @@ export class Country {
     get region() {
         return this._region;
     }
+    /**
+     * Gets the ISO currency code used in the country.
+     * @returns {string | null} The ISO currency code of the country, or null if not available
+     */
+    get currencyCode() {
+        return this._currencyCode;
+    }
+    /**
+     * Gets the Currency instance for this country.
+     * @returns {Currency | undefined} The Currency instance or undefined if no currency is assigned
+     */
+    getCurrency() {
+        if (!this._currencyCode) {
+            return undefined;
+        }
+        return Currency.fromCode(this._currencyCode);
+    }
     /**
      * Creates a string representation of the country.
      * @returns {string} String representation of the country
@@ -162,8 +213,8 @@ export class Country {
         return `${this.flagEmoji} ${this.name} (${this.code}, ${this.iso3})`;
     }
     /**
-     * Retrieves a country by its ISO-2 code.
-     * @param {string} code The ISO-2 code of the country.
+     * Retrieves a country by its ISO-2 or ISO-3 code.
+     * @param {CountryCode} code The ISO-2 or ISO-3 code of the country.
      * @returns {Country | undefined} The country corresponding to the ISO code or `undefined` if not found.
      */
     static fromCode(code) {
@@ -171,7 +222,7 @@ export class Country {
     }
     /**
      * Retrieves a country by its ISO-3 code.
-     * @param {string} iso3 The ISO-3 code of the country.
+     * @param {ISO3CountryCode} iso3 The ISO-3 code of the country.
      * @returns {Country | undefined} The country corresponding to the ISO-3 code or `undefined` if not found.
      */
     static fromIso3(iso3) {
@@ -222,28 +273,6 @@ export class Country {
     static getRegions() {
         return Object.values(SUB_REGION);
     }
-    /**
-     * Validates if a given ISO-2 country code is valid
-     * @param code The country code to validate
-     * @returns True if the country code is valid
-     */
-    static isValidCode(code) {
-        if (!code)
-            return false;
-        const country = Country.fromCode(code);
-        return !!country;
-    }
-    /**
-     * Validates if a given ISO-3 country code is valid
-     * @param iso3 The ISO-3 country code to validate
-     * @returns True if the ISO-3 country code is valid
-     */
-    static isValidIso3(iso3) {
-        if (!iso3)
-            return false;
-        const country = Country.fromIso3(iso3);
-        return !!country;
-    }
     /**
      * Validates if a given country name is valid
      * @param countryName The country name to validate
@@ -262,7 +291,7 @@ export class Country {
     validate() {
         try {
             return (Country.fromName(this._name) !== undefined &&
-                Country.fromCode(this._code) !== undefined);
+                Country.fromCode(this._iso2) !== undefined);
         }
         catch (_) {
             return false;
@@ -278,9 +307,11 @@ export class Country {
             const country1 = Country.fromName(input);
             if (country1)
                 return country1;
+            // deno-lint-ignore no-explicit-any
             const country2 = Country.fromCode(input);
             if (country2)
                 return country2;
+            // deno-lint-ignore no-explicit-any
             const country3 = Country.fromIso3(input);
             if (country3)
                 return country3;
@@ -298,8 +329,10 @@ export class Country {
         const text = input.trim();
         if (text.length === 0)
             return false;
-        const countryFromCode = Country.fromCode(text);
         const countryFromName = Country.fromName(text);
+        // deno-lint-ignore no-explicit-any
+        const countryFromCode = Country.fromCode(text);
+        // deno-lint-ignore no-explicit-any
         const countryFromIso3 = Country.fromIso3(text);
         return countryFromCode !== undefined ||
             countryFromName !== undefined ||
@@ -314,24 +347,391 @@ export class Country {
         if (!obj || typeof obj !== "object")
             return false;
         const maybeCountry = obj;
+        console.log(maybeCountry);
         // Check private properties exist with correct types
         if (typeof maybeCountry._name !== "string")
             return false;
-        if (typeof maybeCountry._code !== "string")
+        if (typeof maybeCountry._iso2 !== "string")
             return false;
         // Validate against known countries
-        const countryFromCode = Country.from(maybeCountry._code);
+        const countryFromCode = Country.from(maybeCountry._iso2);
         const countryFromName = Country.from(maybeCountry._name);
         return Boolean(countryFromCode &&
             countryFromName &&
             countryFromCode.code === countryFromName.code);
     }
 }
+/**
+ * Service for managing country data.
+ * @class CountryService
+ */
+export class CountryService {
+    constructor() {
+        Object.defineProperty(this, "countryList", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "codeRecord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "iso3Record", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "nameRecord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "continentRecord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "regionRecord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        // Static references for direct access through Country class
+        Object.defineProperty(this, "staticReferences", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Gets the singleton instance of CountryService.
+     * Creates the instance if it doesn't exist.
+     * @static
+     * @returns {CountryService} The singleton instance
+     */
+    static getInstance() {
+        if (!CountryService.instance) {
+            CountryService.instance = new CountryService();
+            CountryService.instance.initialize();
+        }
+        return CountryService.instance;
+    }
+    /**
+     * Maps a string continent name to the CONTINENT enum
+     * @param continentName String continent name from JSON
+     * @returns The corresponding CONTINENT enum value
+     */
+    mapContinent(continentName) {
+        switch (continentName) {
+            case "Africa":
+                return CONTINENT.AFRICA;
+            case "Antarctica":
+                return CONTINENT.ANTARCTICA;
+            case "Asia":
+                return CONTINENT.ASIA;
+            case "Europe":
+                return CONTINENT.EUROPE;
+            case "North America":
+                return CONTINENT.NORTH_AMERICA;
+            case "Oceania":
+                return CONTINENT.OCEANIA;
+            case "South America":
+                return CONTINENT.SOUTH_AMERICA;
+            default:
+                return CONTINENT.EUROPE; // Default value
+        }
+    }
+    /**
+     * Maps a string region name to the SUB_REGION enum
+     * @param regionName String region name from JSON
+     * @returns The corresponding SUB_REGION enum value
+     */
+    mapRegion(regionName) {
+        switch (regionName) {
+            case "Australia and New Zealand":
+                return SUB_REGION.AUSTRALIA_AND_NEW_ZEALAND;
+            case "Caribbean":
+                return SUB_REGION.CARIBBEAN;
+            case "Central America":
+                return SUB_REGION.CENTRAL_AMERICA;
+            case "Central Asia":
+                return SUB_REGION.CENTRAL_ASIA;
+            case "Eastern Africa":
+                return SUB_REGION.EASTERN_AFRICA;
+            case "Eastern Asia":
+                return SUB_REGION.EASTERN_ASIA;
+            case "Eastern Europe":
+                return SUB_REGION.EASTERN_EUROPE;
+            case "Melanesia":
+                return SUB_REGION.MELANESIA;
+            case "Micronesia":
+                return SUB_REGION.MICRONESIA;
+            case "Middle Africa":
+                return SUB_REGION.MIDDLE_AFRICA;
+            case "Northern Africa":
+                return SUB_REGION.NORTHERN_AFRICA;
+            case "Northern America":
+                return SUB_REGION.NORTHERN_AMERICA;
+            case "Northern Europe":
+                return SUB_REGION.NORTHERN_EUROPE;
+            case "Polynesia":
+                return SUB_REGION.POLYNESIA;
+            case "South-eastern Asia":
+                return SUB_REGION.SOUTH_EASTERN_ASIA;
+            case "Southern Africa":
+                return SUB_REGION.SOUTHERN_AFRICA;
+            case "Southern Asia":
+                return SUB_REGION.SOUTHERN_ASIA;
+            case "Southern Europe":
+                return SUB_REGION.SOUTHERN_EUROPE;
+            case "Western Africa":
+                return SUB_REGION.WESTERN_AFRICA;
+            case "Western Asia":
+                return SUB_REGION.WESTERN_ASIA;
+            case "Western Europe":
+                return SUB_REGION.WESTERN_EUROPE;
+            default:
+                return SUB_REGION.NORTHERN_EUROPE; // Default value
+        }
+    }
+    /**
+     * Initializes the service with country data.
+     * Should be called once when your application starts.
+     */
+    initialize() {
+        try {
+            // Parse the JSON data
+            const data = JSON.parse(JSON.stringify(file));
+            // deno-lint-ignore no-explicit-any
+            const countriesData = data.countries || [];
+            // Initialize continent and region records
+            Object.values(CONTINENT).forEach((continent) => {
+                this.continentRecord[continent] = [];
+            });
+            Object.values(SUB_REGION).forEach((region) => {
+                this.regionRecord[region] = [];
+            });
+            // Create Country instances from the data
+            const countries = countriesData.map((c) => {
+                const continent = this.mapContinent(c.continent);
+                const region = this.mapRegion(c.region);
+                return new Country(c.name, c.iso_2, c.name_official, c.iso_3, c.flag_emoji, continent, region, c.currency_iso_iso2);
+            });
+            const code_record = {};
+            const iso3_record = {};
+            const name_record = {};
+            countries.forEach((country) => {
+                // Populate code records
+                code_record[country.code] = country;
+                iso3_record[country.iso3] = country;
+                // Add to record by name
+                // Generate uppercase full name with underscores
+                const nameKey = country.name
+                    .toUpperCase()
+                    .replace(/\s+/g, "_")
+                    .replace(/[-(),.']/g, "")
+                    .replace(/&/g, "AND");
+                name_record[nameKey] = country;
+                // Group countries by continent
+                this.continentRecord[country.continent].push(country);
+                // Group countries by region
+                this.regionRecord[country.region].push(country);
+                this.staticReferences.set(country.code, country);
+                this.staticReferences.set(nameKey, country);
+            });
+            // Add specific country mappings for special cases
+            // Cocos Islands
+            if (code_record["CC"]) {
+                name_record["COCOS_ISLANDS"] = code_record["CC"];
+                this.staticReferences.set("COCOS_ISLANDS", code_record["CC"]);
+            }
+            // Cote d'Ivoire
+            if (code_record["CI"]) {
+                name_record["COTE_DIVOIRE"] = code_record["CI"];
+                this.staticReferences.set("COTE_DIVOIRE", code_record["CI"]);
+            }
+            // Macedonia (North Macedonia)
+            if (code_record["MK"]) {
+                name_record["MACEDONIA"] = code_record["MK"];
+                this.staticReferences.set("MACEDONIA", code_record["MK"]);
+            }
+            // US Virgin Islands
+            if (code_record["VI"]) {
+                name_record["VIRGIN_ISLANDS_US"] = code_record["VI"];
+                this.staticReferences.set("VIRGIN_ISLANDS_US", code_record["VI"]);
+            }
+            // British Virgin Islands
+            if (code_record["VG"]) {
+                name_record["VIRGIN_ISLANDS_BRITISH"] = code_record["VG"];
+                this.staticReferences.set("VIRGIN_ISLANDS_BRITISH", code_record["VG"]);
+            }
+            // Democratic Republic of the Congo
+            if (code_record["CD"]) {
+                name_record["DEMOCRATIC_REPUBLIC_OF_CONGO"] = code_record["CD"];
+                this.staticReferences.set("DEMOCRATIC_REPUBLIC_OF_CONGO", code_record["CD"]);
+            }
+            // Falkland Islands (Malvinas)
+            if (code_record["FK"]) {
+                name_record["FALKLAND_ISLANDS"] = code_record["FK"];
+                this.staticReferences.set("FALKLAND_ISLANDS", code_record["FK"]);
+            }
+            // Lao
+            if (code_record["LA"]) {
+                name_record["LAO"] = code_record["LA"];
+                this.staticReferences.set("LAO", code_record["LA"]);
+            }
+            this.codeRecord = code_record;
+            this.iso3Record = iso3_record;
+            this.nameRecord = name_record;
+            this.countryList = countries;
+            // Initialize static properties on Country class
+            this.initializeCountryStatics();
+        }
+        catch (error) {
+            console.error("Failed to initialize CountryService:", error);
+        }
+    }
+    /**
+     * Initialize the static properties on the Country class
+     */
+    initializeCountryStatics() {
+        // Initialize ISO-2 code properties
+        Object.entries(this.codeRecord).forEach(([code, country]) => {
+            // deno-lint-ignore no-explicit-any
+            Country[code.toUpperCase()] = country;
+        });
+        // Initialize full name properties
+        Object.entries(this.nameRecord).forEach(([fullName, country]) => {
+            // deno-lint-ignore no-explicit-any
+            Country[fullName] = country;
+        });
+    }
+    /**
+     * Gets all countries.
+     * @returns {Country[]} Array of all countries
+     */
+    getAll() {
+        return this.countryList;
+    }
+    /**
+     * Gets static country references to be used by the Country class.
+     * @returns {Map<string, Country>} Map of static references
+     */
+    getStaticReferences() {
+        return this.staticReferences;
+    }
+    /**
+     * Gets all countries as a record.
+     * @returns {Record<string, Country>} Record of country codes and country objects
+     */
+    getAllAsRecord() {
+        return this.codeRecord;
+    }
+    /**
+     * Gets all countries from a specific continent.
+     * @param {CONTINENT} continent The continent enum value
+     * @returns {Country[]} Array of countries in the specified continent
+     */
+    getByContinent(continent) {
+        return this.continentRecord[continent] || [];
+    }
+    /**
+     * Gets all countries from a specific region.
+     * @param {SUB_REGION} region The region enum value
+     * @returns {Country[]} Array of countries in the specified region
+     */
+    getByRegion(region) {
+        return this.regionRecord[region] || [];
+    }
+    /**
+     * Gets the full name record mapping.
+     * @returns {Record<string, Country>} Record of uppercase full name keys to country objects
+     */
+    getFullNameRecord() {
+        return this.nameRecord;
+    }
+    /**
+     * Retrieves a country by its ISO-2 code.
+     * @param {string} code The ISO-2 code of the country.
+     * @returns {Country | undefined} The country corresponding to the ISO code or `undefined` if not found.
+     */
+    fromCode(code) {
+        return this.codeRecord[code.toUpperCase()];
+    }
+    /**
+     * Retrieves a country by its ISO-3 code.
+     * @param {ISO3CountryCode} iso3 The ISO-3 code of the country.
+     * @returns {Country | undefined} The country corresponding to the ISO-3 code or `undefined` if not found.
+     */
+    fromIso3(iso3) {
+        return this.iso3Record[iso3.toUpperCase()];
+    }
+    /**
+     * Retrieves a country by its name.
+     * @param {string} countryName The name of the country.
+     * @returns {Country | undefined} The country corresponding to the name or `undefined` if not found.
+     */
+    fromName(countryName) {
+        const fullNameKey = countryName
+            .toUpperCase()
+            .replace(/\s+/g, "_")
+            .replace(/[-(),.']/g, "")
+            .replace(/&/g, "AND");
+        const fullNameMatch = this.nameRecord[fullNameKey];
+        if (fullNameMatch)
+            return fullNameMatch;
+        // If not found, try more lenient matching
+        return this.countryList.find((country) => country.name.toLowerCase() === countryName.toLowerCase());
+    }
+    /**
+     * Searches for countries that match the given search term.
+     * @param {string} searchTerm - The partial name or code to search for.
+     * @param {number} [limit=10] - Maximum number of results to return.
+     * @returns {Country[]} Array of matching countries, limited to specified count.
+     */
+    search(searchTerm, limit = 10) {
+        if (!searchTerm || typeof searchTerm !== "string")
+            return [];
+        const term = searchTerm.toLowerCase().trim();
+        if (term.length === 0)
+            return [];
+        const results = this.countryList.filter((country) => country.name.toLowerCase().includes(term) ||
+            country.nameOfficial.toLowerCase().includes(term) ||
+            country.code.toLowerCase().includes(term) ||
+            country.iso3.toLowerCase().includes(term));
+        return results.slice(0, limit);
+    }
+    /**
+     * Compares two Country instances for equality by checking their name and code
+     *
+     * @param {Country} country1 - First country to compare
+     * @param {Country} country2 - Second country to compare
+     * @returns {boolean} True if countries are equal, false otherwise
+     * @private
+     */
+    compare(country1, country2) {
+        return (country1.name === country2.name &&
+            country1.code === country2.code);
+    }
+}
 // Initialize static properties by applying the references from CountryService
 (function setupStaticReferences() {
-    const staticRefs = CountryService.getInstance().getAll();
-    staticRefs.forEach((country, key) => {
-        // deno-lint-ignore no-explicit-any
-        Country[key] = country;
-    });
+    try {
+        const refs = CountryService.getInstance().getStaticReferences();
+        refs.forEach((country, key) => {
+            // deno-lint-ignore no-explicit-any
+            Country[key] = country;
+        });
+    }
+    catch (error) {
+        console.log("Failed to set up static references: ", error);
+    }
 })();

package/esm/src/models/country/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./country.js";
-export * from "./service.js";
+export * from "./index.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/src/models/country/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/models/country/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/models/country/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/esm/src/models/country/index.js

@@ -1,2 +1,2 @@
 export * from "./country.js";
-export * from "./service.js";
+export * from "./index.js";

package/esm/src/models/country/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Type definitions for ISO country codes
+ *
+ * These types provide type-safe representations of standard ISO codes:
+ * - CountryCode: ISO 3166-1 alpha-2 country codes
+ * - CountryCodeISO3: ISO 3166-1 alpha-3 country codes (three letters)
+ *
+ * Benefits:
+ * - Type-safety at compile time
+ * - Zero runtime overhead (compile away to strings)
+ * - Autocompletion in modern IDEs
+ * - Protection against typos and invalid values
+ */
+/**
+ * ISO 3166-1 alpha-2 country codes
+ *
+ * These two-letter codes represent countries and territories based on the ISO 3166 standard.
+ * Example: "US" for United States, "JP" for Japan, "DE" for Germany
+ */
+export type ISO2CountryCode = "AF" | "AX" | "AL" | "DZ" | "AS" | "AD" | "AO" | "AI" | "AQ" | "AG" | "AR" | "AM" | "AW" | "AU" | "AT" | "AZ" | "BS" | "BH" | "BD" | "BB" | "BY" | "BE" | "BZ" | "BJ" | "BM" | "BT" | "BO" | "BA" | "BW" | "BV" | "BR" | "IO" | "VG" | "BN" | "BG" | "BF" | "BI" | "CV" | "KH" | "CM" | "CA" | "KY" | "CF" | "TD" | "CL" | "CN" | "CX" | "CC" | "CO" | "KM" | "CG" | "CK" | "CR" | "CI" | "HR" | "CU" | "CY" | "CZ" | "CD" | "DK" | "DJ" | "DM" | "DO" | "EC" | "EG" | "SV" | "GQ" | "ER" | "EE" | "SZ" | "ET" | "FK" | "FO" | "FJ" | "FI" | "FR" | "GF" | "PF" | "TF" | "GA" | "GM" | "GE" | "DE" | "GH" | "GI" | "GR" | "GL" | "GD" | "GP" | "GU" | "GT" | "GG" | "GN" | "GW" | "GY" | "HT" | "HM" | "VA" | "HN" | "HK" | "HU" | "IS" | "IN" | "ID" | "IR" | "IQ" | "IE" | "IM" | "IL" | "IT" | "JM" | "JP" | "JE" | "JO" | "KZ" | "KE" | "KI" | "KP" | "KR" | "KW" | "KG" | "LA" | "LV" | "LB" | "LS" | "LR" | "LY" | "LI" | "LT" | "LU" | "MO" | "MG" | "MW" | "MY" | "MV" | "ML" | "MT" | "MH" | "MQ" | "MR" | "MU" | "YT" | "MX" | "FM" | "MD" | "MC" | "MN" | "ME" | "MS" | "MA" | "MZ" | "MM" | "NA" | "NR" | "NP" | "NL" | "NC" | "NZ" | "NI" | "NE" | "NG" | "NU" | "NF" | "MK" | "MP" | "NO" | "OM" | "PK" | "PW" | "PS" | "PA" | "PG" | "PY" | "PE" | "PH" | "PN" | "PL" | "PT" | "PR" | "QA" | "RE" | "RO" | "RU" | "RW" | "SH" | "KN" | "LC" | "PM" | "VC" | "WS" | "SM" | "ST" | "SA" | "SN" | "RS" | "SC" | "SL" | "SG" | "SK" | "SI" | "SB" | "SO" | "ZA" | "GS" | "SS" | "ES" | "LK" | "SD" | "SR" | "SJ" | "SE" | "CH" | "SY" | "TW" | "TJ" | "TZ" | "TH" | "TL" | "TG" | "TK" | "TO" | "TT" | "TN" | "TR" | "TM" | "TC" | "TV" | "VI" | "UG" | "UA" | "AE" | "GB" | "US" | "UM" | "UY" | "UZ" | "VU" | "VE" | "VN" | "WF" | "EH" | "YE" | "ZM" | "ZW";
+/**
+ * ISO 3166-1 alpha-3 country codes
+ *
+ * These three-letter codes represent countries and territories based on the ISO 3166 standard.
+ * Example: "USA" for United States, "JPN" for Japan, "DEU" for Germany
+ */
+export type ISO3CountryCode = "AFG" | "ALA" | "ALB" | "DZA" | "ASM" | "AND" | "AGO" | "AIA" | "ATA" | "ATG" | "ARG" | "ARM" | "ABW" | "AUS" | "AUT" | "AZE" | "BHS" | "BHR" | "BGD" | "BRB" | "BLR" | "BEL" | "BLZ" | "BEN" | "BMU" | "BTN" | "BOL" | "BIH" | "BWA" | "BVT" | "BRA" | "IOT" | "VGB" | "BRN" | "BGR" | "BFA" | "BDI" | "CPV" | "KHM" | "CMR" | "CAN" | "CYM" | "CAF" | "TCD" | "CHL" | "CHN" | "CXR" | "CCK" | "COL" | "COM" | "COG" | "COK" | "CRI" | "CIV" | "HRV" | "CUB" | "CYP" | "CZE" | "COD" | "DNK" | "DJI" | "DMA" | "DOM" | "ECU" | "EGY" | "SLV" | "GNQ" | "ERI" | "EST" | "SWZ" | "ETH" | "FLK" | "FRO" | "FJI" | "FIN" | "FRA" | "GUF" | "PYF" | "ATF" | "GAB" | "GMB" | "GEO" | "DEU" | "GHA" | "GIB" | "GRC" | "GRL" | "GRD" | "GLP" | "GUM" | "GTM" | "GGY" | "GIN" | "GNB" | "GUY" | "HTI" | "HMD" | "VAT" | "HND" | "HKG" | "HUN" | "ISL" | "IND" | "IDN" | "IRN" | "IRQ" | "IRL" | "IMN" | "ISR" | "ITA" | "JAM" | "JPN" | "JEY" | "JOR" | "KAZ" | "KEN" | "KIR" | "KWT" | "KGZ" | "LAO" | "LVA" | "LBN" | "LSO" | "LBR" | "LBY" | "LIE" | "LTU" | "LUX" | "MAC" | "MDG" | "MWI" | "MYS" | "MDV" | "MLI" | "MLT" | "MHL" | "MTQ" | "MRT" | "MUS" | "MYT" | "MEX" | "FSM" | "MDA" | "MCO" | "MNG" | "MNE" | "MSR" | "MAR" | "MOZ" | "MMR" | "NAM" | "NRU" | "NPL" | "NLD" | "NCL" | "NZL" | "NIC" | "NER" | "NGA" | "NIU" | "NFK" | "PRK" | "MKD" | "MNP" | "NOR" | "OMN" | "PAK" | "PLW" | "PSE" | "PAN" | "PNG" | "PRY" | "PER" | "PHL" | "PCN" | "POL" | "PRT" | "PRI" | "QAT" | "REU" | "ROU" | "RUS" | "RWA" | "SHN" | "KNA" | "LCA" | "SPM" | "VCT" | "WSM" | "SMR" | "STP" | "SAU" | "SEN" | "SRB" | "SYC" | "SLE" | "SGP" | "SVK" | "SVN" | "SLB" | "SOM" | "ZAF" | "SGS" | "KOR" | "SSD" | "ESP" | "LKA" | "SDN" | "SUR" | "SJM" | "SWE" | "CHE" | "SYR" | "TWN" | "TJK" | "TZA" | "THA" | "TLS" | "TGO" | "TKL" | "TON" | "TTO" | "TUN" | "TUR" | "TKM" | "TCA" | "TUV" | "VIR" | "UGA" | "UKR" | "ARE" | "GBR" | "USA" | "UMI" | "URY" | "UZB" | "VUT" | "VEN" | "VNM" | "WLF" | "ESH" | "YEM" | "ZMB" | "ZWE";
+/**
+ * Maps ISO-2 country codes to ISO-3 country codes
+ */
+export declare const ISO2_TO_ISO3_MAP: Record<ISO2CountryCode, ISO3CountryCode>;
+/**
+ * Represents an ISO country code, accepting either ISO 3166-1 alpha-2 (two-letter)
+ * or ISO 3166-1 alpha-3 (three-letter) formats.
+ *
+ * This union type allows functions to accept either format for flexibility,
+ * while still maintaining type safety and validation.
+ *
+ * @example
+ * // Valid uses:
+ * const usa1: CountryCode = "US";  // ISO2
+ * const usa2: CountryCode = "USA"; // ISO3
+ * const japan1: CountryCode = "JP";  // ISO2
+ * const japan2: CountryCode = "JPN"; // ISO3
+ *
+ * // Type checking will catch invalid codes:
+ * const invalid: CountryCode = "INVALID"; // Error
+ *
+ * @see ISO2CountryCode - For two-letter country codes only
+ * @see ISO3CountryCode - For three-letter country codes only
+ */
+export type CountryCode = ISO2CountryCode | ISO3CountryCode;
+//# sourceMappingURL=types.d.ts.map