@destinatlon/state-resolve

Always resolve a valid province/state code for an address, so orders never get rejected or mis-shipped because of a missing or free-text state field.

No third-party dependencies — plain Node (CommonJS), built-in path only.

Install

npm install @destinatlon/state-resolve

Usage

const { resolveStateCode } = require('@destinatlon/state-resolve');

const stateCode = resolveStateCode({
  country: 'DE',          // ISO-ish code or internal alias (UK, EN, CH-DE, BE-FR…)
  postalCode: '80331',    // used for derivation when state is missing/invalid
  city: 'München',        // only used in fallback log messages
  state: 'Bayern',        // raw state name OR code; may be empty
});
// → 'BY'

How it resolves

Given { country, postalCode, city, state }, the code is resolved via this waterfall:

1. state is already a valid code → return it uppercased
2. state matches a known region name/alias → return that code
3. derive the code from postalCode (per-country logic)
4. fall back to a per-country default (logs a warning)

Unsupported countries pass the given state through unchanged.

API

| Export | Signature | Description | |--------|-----------|-------------| | resolveStateCode | ({ country, postalCode, city, state }) => string | Main entry point. Always returns a valid code for supported countries. | | isValidCode | (country, code) => boolean | True if code is a valid province/state code for country. | | normCountry | (country) => string | Normalize a country alias to its vocabulary key. | | deriveByPostcode | (country, postalCode) => string \| null | Derive a region code from a postcode, or null. |

Behaviour notes

• Country aliases are handled internally (UK→GB, EN→NL, CH-DE→CH, BE-FR/BE-NL→BE) via normCountry, so locale/language codes can be passed directly.
• For an unsupported country it returns whatever state you passed, untouched (and warns if empty).
• For a supported country it never returns empty — worst case it logs a [stateResolver] fell back to default… warning and returns the country default. Watch your logs for those; they flag addresses that may mis-ship.
• Supported derivation countries: DE, FR, AU, BE, AT, CH, SE, NO, FI, GB. To add another, add its vocabulary to data/state-codes.json and (optionally) a deriver function in src/postcodeRegion.js.

Data

• data/state-codes.json — province/state vocabulary per country.
• data/uk-outcodes.json — UK outcode → region lookup table.

Test

npm test

License

MIT © Destinatlon