country-code-lookup

country-code-lookup is a lightweight Node.js module for resolving countries from any of five common code systems: FIPS 10-4, ISO 3166-1 alpha-2, ISO 3166-1 alpha-3, ISO 3166-1 numeric, and internet ccTLD codes. Each lookup returns a plain object with continent, region, capital, and every associated code variant, or null when nothing matches — making it a drop-in normalization layer for any pipeline that needs to reconcile country identifiers coming from different data sources.

The entire dataset — 250+ countries and territories — ships as a frozen, in-memory array with zero runtime dependencies, so lookups are synchronous and require no network or file I/O. The library bundles its own TypeScript type definitions and has a test suite that continues to track de-facto changes to national codes (Kosovo, Czechia, the Sudan/South Sudan split, Romania’s ISO3 change), and it is exercised by CI on every push.

What You Get

• Functions byFips, byIso, byInternet, and byCountry covering all five code standards with one call each
• A frozen countries array of full country records (continent, region, capital, all code variants) for iterating or building your own lookup indices
• Bundled TypeScript typings (index.d.ts) with Country and SearchOutput types, so no separate @types package is needed
• Zero runtime dependencies, keeping the package small and safe to use in serverless or edge environments

Common Use Cases

• Normalizing country codes across mismatched third-party APIs before storing them in your own schema
• Rendering full country, continent, and region names from a stored ISO code in a UI
• Validating user-submitted country codes during form or address validation
• Enriching e-commerce or logistics records with capital city or region data derived from a country code

Under The Hood

Architecture The library is a single flat CommonJS module (index.js) with no internal layering: four small functions (byFips, byIso, byInternet, byCountry) sit at the top of the file and delegate to one private linear-scan search() helper against a hardcoded countries array declared further down (relying on var hoisting so the functions can reference it before its literal declaration). There’s no build step, no external state, and no plausible “core abstraction” to break beyond the shape of the country records themselves, since every consumer touches the same flat, frozen data.

Tech Stack The package is plain, dependency-free JavaScript with no transpilation or bundling: package.json declares zero runtime dependencies and a single devDependency, Mocha, for tests. Type support comes from a hand-written index.d.ts rather than a TypeScript source compile. CI is a GitHub Actions workflow that installs, runs npm test on Node 20.x for every push, and attempts an npm publish gated by a repository secret when the push lands on master.

Code Quality The test suite (test.js, plain Node assert + Mocha) is unusually thorough for a small data library: beyond basic lookups by each code type, it pins down historical corrections (Romania’s ISO3 moving from ROM to ROU, Kosovo’s XKX code, the Sudan/South Sudan 729 split, Czechia’s rename), null/undefined input guards for every exported function, and an invariant check that every ISO numeric code is exactly three digits. There is no linter or formatter configured in the repository, and the module itself is untyped JavaScript, so type safety comes only from the bundled .d.ts file rather than from compiling the implementation.

API Design The public surface is deliberately small and requires no setup: require('country-code-lookup') and call one of four functions immediately, no instantiation or configuration. byIso in particular infers which ISO variant to use from the input’s type and length (numeric string of any padding, 2-char alpha-2, or 3-char alpha-3) rather than forcing the caller to pick a variant-specific function, which removes a step most comparable libraries push onto the consumer. The returned country object shape is consistent across all four entry points, and the frozen countries export gives direct access to the raw dataset for callers who want to build their own index or iterate.