cf-emoji

A small, zero-dependency converter from two-letter country codes or locale suffixes to Unicode flag emoji.

Highlights

• Constant-time suffix parsing with no split, regular expressions, or case-conversion allocation
• Two-tier bounded caching for exact hot inputs and canonical country pairs
• Case-insensitive ASCII input
• Exhaustive tests for all 676 letter pairs and 100% source coverage
• Native ESM with bundled TypeScript declarations
• Node.js 14+ and Bun support

Installation

npm install cf-emoji

The package is also available through Yarn, pnpm, and Bun.

Usage

import { toFlag } from 'cf-emoji';

toFlag('US');         // 🇺🇸
toFlag('gb');         // 🇬🇧
toFlag('en-US');      // 🇺🇸
toFlag('zh-Hant-TW'); // 🇹🇼

API

toFlag(code: string): string

Converts the final two-letter region component to a pair of Unicode regional-indicator symbols.

Accepted inputs are either:

• exactly two ASCII letters, such as US; or
• a string ending in a hyphen and two ASCII letters, such as en-US or zh-Hant-TW.

Letter matching is case-insensitive. Invalid lengths, separators, non-ASCII letters, and non-string runtime values throw Error('Invalid code').

toFlag performs a syntactic conversion. It does not verify that a letter pair is an officially assigned ISO 3166-1 code, and flag rendering depends on the platform and font.

Performance

The implementation uses a fast exact-input path for common country and language-region strings. Cache misses are parsed without substrings, and all aliases for the same country share one canonical flag string.

Reference throughput on Bun 1.4.0 and an AMD Ryzen 5 3500U:

| Workload | cf-emoji 1.0.6 | cf-emoji 1.0.5 | Allocation-heavy baseline | | --- | ---: | ---: | ---: | | Single hot input | 95.74 M ops/s | 70.39 M ops/s | 3.19 M ops/s | | Mixed hot set | 72.97 M ops/s | 50.33 M ops/s | 3.00 M ops/s | | 4,096 locale prefixes | 98.30 M ops/s | 8.41 M ops/s | 1.70 M ops/s |

These are microbenchmark results, not application-level latency guarantees. See BENCHMARKS.md for the complete methodology, timings, environment, caveats, and reproduction steps.

Development

bun install --frozen-lockfile
bun test
bun run build
bun run bench

The build emits one minified ESM implementation file and one declaration file in dist/.

License

MIT © Dalist