@d4l/postalcodes

Offline postal-code validation for every country GeoNames covers — Node, browsers, and React Native. Sub-millisecond live validation as the user types, with no network calls and no API keys.

Why does this exist?

Validating a postal code is one of those small problems that gets nasty fast:

• A regex like /^\d{5}$/ rejects perfectly valid Canadian (K1A 0B1), Argentinian (C1419), or UK (SW1A 1AA) codes.
• Server-side APIs (Google, Smarty, etc.) send your users' addresses over the network, cost money, need keys, and break offline.
• Hand-rolled regex libraries are incomplete and go stale — postal authorities add codes constantly.

@d4l/postalcodes ships the GeoNames postal-code dataset as one gzipped, binary-packed index file per country, inside the npm tarball. The runtime is a few kilobytes and never touches the network. A scheduled GitHub Action refreshes the data and republishes monthly, so your users see new codes without you lifting a finger.

30 seconds

import { loadCountry } from '@d4l/postalcodes/node';
import { validatePostalCode } from '@d4l/postalcodes';

await loadCountry('US');

validatePostalCode('US', '');         // → verdict: 'partial'    (still typing)
validatePostalCode('US', '9');        // → verdict: 'partial'    (still typing)
validatePostalCode('US', '902');      // → verdict: 'partial'    (still typing)
validatePostalCode('US', '90210');    // → verdict: 'valid'      (Beverly Hills)
validatePostalCode('US', '99999');    // → verdict: 'unknown'    (well-formed but not in dataset)
validatePostalCode('US', '9XYZ0');    // → verdict: 'malformed'  (format violation)

The 'partial' verdict is the trick that makes input fields feel right: the field stays neutral while the user is still typing and only goes red when the input can no longer become a valid code. No more flickering green-then-red on every keystroke.

How it stacks up

	@d4l/postalcodes	regex-based libraries	online APIs (Google, Smarty, …)
Works offline	yes	yes	no
Validates against real codes	yes (GeoNames dataset)	format only	yes
Live "as you type" check	yes (prefix lookup)	partial (regex only)	usually no
Privacy	inputs never leave the device	inputs never leave	inputs sent to vendor
Cost	free, MIT	free	paid above free tier
React Native / Hermes	yes	yes	only with network
Country coverage	~100 (whatever GeoNames ships)	varies	~250
Stays current	monthly auto-publish	manual PRs	vendor-managed
API key / signup	none	none	required

When to reach for it

• Address forms in e-commerce checkouts — make the field forgiving while the user types, but reject typos before they become failed shipments.
• Patient or customer onboarding in regulated contexts where postal codes must not be sent to a third party.
• KYC / address-verification UIs that need to work behind a VPN, in the field, or in waiting-room kiosks without reliable connectivity.
• React Native apps where bundling means "must work offline by default."
• Forms in design systems — drop-in validator with a ValidationResult that maps cleanly to your existing idle / pending / valid / error states.

Install

npm install @d4l/postalcodes

Node 20+ for the convenience loader. The browser / React Native path has no Node-version requirement — everything runtime-side runs on ES2022.

Quick start — Node

import { loadCountry } from '@d4l/postalcodes/node';
import { validatePostalCode } from '@d4l/postalcodes';

await loadCountry('US');

validatePostalCode('US', '90210');
// → { verdict: 'valid', normalized: '90210' }

Quick start — React Native / browser

Two options, depending on how much country data you want to ship.

Cherry-pick — register only the countries you need. Bundlers (Metro, webpack, …) tree-shake the rest, so you only pay for what you import.

import US from '@d4l/postalcodes/data/US.json';
import DE from '@d4l/postalcodes/data/DE.json';
import { registerCountry, validatePostalCode } from '@d4l/postalcodes';

registerCountry(US);
registerCountry(DE);

validatePostalCode('DE', '10117').verdict; // 'valid' (Berlin)

Bulk — @d4l/postalcodes/bundled exposes every country with lazy, on-demand registration. Use this when you don't know which countries the user might pick at runtime.

import { validatePostalCode, SUPPORTED_COUNTRIES } from '@d4l/postalcodes/bundled';

validatePostalCode('DE', '10117').verdict; // 'valid' — DE registered automatically

There's a complete React Native example in examples/react-native-input.tsx and a runnable browser demo in examples/web-form.html.

API

validatePostalCode(country, raw): ValidationResult

type ValidationVerdict = 'valid' | 'unknown' | 'partial' | 'malformed';

interface ValidationResult {
  verdict: ValidationVerdict;
  normalized: string; // uppercase, separators stripped
}

verdict	meaning	typical UI
'valid'	complete code, present in the country's index	green
'unknown'	well-formed but not in the dataset	soft warn
'partial'	could still grow into a valid code (still typing)	neutral
'malformed'	violates the country's structural pattern	red

Input is normalized internally — spaces and hyphens stripped, letters uppercased — so validatePostalCode('CA', 'k1a 0b1') and validatePostalCode('CA', 'K1A-0B1') behave identically.

Throws UnknownCountryError if you forgot to register that country (the main entry only; the ./bundled wrapper returns undefined instead of throwing).

Driving an <input> field

function uiState(country: string, raw: string) {
  if (!raw) return 'idle';
  switch (validatePostalCode(country, raw).verdict) {
    case 'valid':     return 'valid';   // green
    case 'unknown':   return 'warn';    // amber — accept, but flag for review
    case 'partial':   return 'typing';  // neutral
    case 'malformed': return 'invalid'; // red
  }
}

For a hard "can the user submit" gate, the simplest expression is the regex:

import { regexForCountry, normalizePostalCode } from '@d4l/postalcodes';
const ok = regexForCountry(country).test(normalizePostalCode(raw));

Other exports

• isValidPostalCode(country, raw): boolean — sugar for verdict === 'valid'
• isAcceptablePostalCode(country, raw): boolean — verdict !== 'malformed'
• getCountryFormat(country): CountryFormat | undefined — { minLen, maxLen, charsets, digitsOnly, lettersOnly, hasDigits, hasLetters }. Useful for configuring an <input> (numeric keyboard, maxLength, autocapitalize) without first running a validation.
• regexForCountry(code: string): RegExp — anchored structural regex (handy for <input pattern>)
• normalizePostalCode(raw: string): string
• registerCountry(data: CountryData): void
• unregisterCountry(code: string): boolean
• isCountryLoaded(code: string): boolean
• loadedCountries(): string[]

From @d4l/postalcodes/bundled (static-bundler-friendly, every country lazily registered):

• validatePostalCode, isValidPostalCode, isAcceptablePostalCode, getCountryFormat, regexForCountry, normalizePostalCode — same signatures as the main entry, but each lazily calls ensureCountry(...) and returns undefined (instead of throwing) when the country isn't bundled in this build
• ensureCountry(code: string): boolean — lazily register one country
• registerAllCountries(): readonly string[] — register every bundled country eagerly
• SUPPORTED_COUNTRIES: readonly string[] — every ISO code this build ships

From @d4l/postalcodes/node (Node-only convenience):

• loadCountry(code: string): Promise<boolean>
• loadAllCountries(): Promise<string[]>
• readManifest(): Promise<Manifest>

How it works

For each country we:

1. Parse the GeoNames TSV and keep only (country_code, postal_code) pairs.
2. Normalize codes to uppercase ASCII, strip spaces and hyphens, deduplicate.
3. Sort lexicographically and pack:
   • If every code has the same length: concatenate, no per-record overhead.
   • Otherwise: 1-byte length prefix + ASCII bytes per code.
4. Gzip the packed buffer, base64-encode it, wrap in a small JSON record with per-position character-class metadata.

At runtime, validation is:

• O(L) structural check against the per-position char-class (rejects garbage early)
• O(log N · L) binary search over the sorted buffer for exact match and prefix

N is the number of codes for the country (US ≈ 42k, DE ≈ 16k); L is the code length. Validation is well under a millisecond in practice.

Updating the data

A scheduled GitHub Action runs on the 1st of every month, regenerates the indexes from GeoNames, bumps the patch version, and republishes — so your ^0.1.0 range automatically picks up new codes. See .github/workflows/update-data.yml.

To regenerate locally:

npm run update-data   # downloads allCountries.zip and rebuilds data/

Coverage caveats

The dataset is whatever GeoNames distributes in allCountries.zip — typically around 100 countries with a mix of full and partial codes. Most notably:

• Great Britain ships outward codes only (e.g. SW1A), not full PAF postcodes. If you need full UK postcode validation, pair this package with a PAF-licensed source.
• A handful of small territories may be missing entirely.

Run await readManifest() (from @d4l/postalcodes/node) to see the exact country list shipped in your installed version.

Attribution

Postal-code data © GeoNames, CC BY 4.0. When redistributing the data, keep the attribution intact. See ATTRIBUTION.md.

License

MIT for the code. CC BY 4.0 for the bundled data in data/.