@resquash/country-state

Country, state/province, and postal metadata for address forms.

API shape follows country-state-city (Country / State namespaces). Currently supports United States and Canada only.

Install

npm install @resquash/country-state
# or
yarn add @resquash/country-state

"@resquash/country-state": "^1.0.1"

Usage

import {
  Country,
  State,
  validatePostalCode,
  validateSubdivisionCode,
  type ICountry,
  type IState,
} from '@resquash/country-state';

Countries

// All supported countries
const countries = Country.getAllCountries();
// [
//   { isoCode: 'US', name: 'United States', phonecode: '1', flag: '🇺🇸', metadata: {...} },
//   { isoCode: 'CA', name: 'Canada', phonecode: '1', flag: '🇨🇦', metadata: {...} },
// ]

// Lookup by ISO2 code (input is case-insensitive)
const us = Country.getCountryByCode('us');
// {
//   isoCode: 'US',
//   name: 'United States',
//   phonecode: '1',
//   flag: '🇺🇸',
//   metadata: {
//     hasSubdivisions: true,
//     subdivisionLabel: 'State',
//     postalLabel: 'ZIP code',
//     postalPattern: '^\\d{5}(-\\d{4})?$',
//   },
// }

States / provinces

// All states and provinces (US + CA)
const allStates = State.getAllStates();
// [{ name: 'Alabama', isoCode: 'AL', countryCode: 'US' }, ...]

// States for one country
const usStates = State.getStatesOfCountry('US');
// [{ name: 'California', isoCode: 'CA', countryCode: 'US' }, ...]

const caProvinces = State.getStatesOfCountry('CA');
// [{ name: 'Ontario', isoCode: 'ON', countryCode: 'CA' }, ...]

// Single lookup (codes are case-insensitive on input)
const california = State.getStateByCodeAndCountry('ca', 'US');
// { name: 'California', isoCode: 'CA', countryCode: 'US' }

Postal validation

validatePostalCode('US', '90001');      // true
validatePostalCode('US', '90001-1234'); // true
validatePostalCode('CA', 'M5V 3L9');    // true
validatePostalCode('CA', '12345');      // false

validateSubdivisionCode('US', 'NY'); // true
validateSubdivisionCode('US', 'ZZ'); // false

Address form example

const countryCode = 'US'; // from country picker
const country = Country.getCountryByCode(countryCode);

// Drive labels from metadata
const stateLabel = country?.metadata.subdivisionLabel; // "State" or "Province"
const postalLabel = country?.metadata.postalLabel;     // "ZIP code" or "Postal code"

// Populate state/province picker
const subdivisions = State.getStatesOfCountry(countryCode);

// On save — public API returns uppercase; you may store lowercase in your DB
const selectedState = State.getStateByCodeAndCountry('CA', countryCode);
const address = {
  street: '123 Main St',
  city: 'Los Angeles',
  state: selectedState?.name ?? '',
  stateCode: selectedState?.isoCode.toLowerCase() ?? '',
  zipCode: '90001',
  country: country?.name ?? '',
  countryCode: country?.isoCode.toLowerCase() ?? '',
};

Code conventions

| Layer | Case | Example | |-------|------|---------| | Public API (isoCode, countryCode) | UPPERCASE | US, CA, ON | | Seed data / internal storage | lowercase | us, ca, on | | Typical DB storage (countryCode, stateCode) | lowercase | us, ca |

Input to lookup methods accepts any case ('us', 'US', ' Ca ').

API reference

Country

| Method | Returns | |--------|---------| | getAllCountries() | ICountry[] | | getCountryByCode(countryCode) | ICountry \| undefined |

State

| Method | Returns | |--------|---------| | getAllStates() | IState[] | | getStatesOfCountry(countryCode) | IState[] | | getStateByCodeAndCountry(stateCode, countryCode) | IState \| undefined |

Address helpers

| Function | Description | |----------|-------------| | validatePostalCode(countryCode, postalCode) | Validate zip/postal format for country | | validateSubdivisionCode(countryCode, subdivisionCode) | Validate state/province code | | getPostalPattern(countryCode) | RegExp for country postal format |

Development

npm install
npm run build   # typecheck
npm test