{"_id":"@destinatlon/state-resolve","_rev":"4-1c26b4fe04c838555a6d9f4b9aa6ec92","name":"@destinatlon/state-resolve","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@destinatlon/state-resolve","version":"1.0.0","keywords":["state","province","postcode","postal-code","region","address","geocoding"],"author":{"name":"Destinatlon"},"license":"MIT","_id":"@destinatlon/state-resolve@1.0.0","maintainers":[{"name":"destinatlon","email":"jekanotevgeny@gmail.com"}],"homepage":"https://github.com/Destinatlon/state-resolve#readme","bugs":{"url":"https://github.com/Destinatlon/state-resolve/issues"},"dist":{"shasum":"499ee10da62892983c5f5b5fc2b510481b830a8e","tarball":"https://registry.npmjs.org/@destinatlon/state-resolve/-/state-resolve-1.0.0.tgz","fileCount":9,"integrity":"sha512-jm6Wlspqr3lTiq1pI2ZxBis0uXCoFn7d0KrNWKSjZgtEZ4Ot5Fsvm/CbXJrANOm3x+vO73vNh/cKeRq6w/ibDQ==","signatures":[{"sig":"MEUCIFVbd0OyZjjL/yzQKbEQ69kgkrT23a955welyKut0RQLAiEAt0uKSfVjDQ0AYKwbFsRqxH+BoGuFhvNl8tqhYg14hTU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66706},"main":"index.js","types":"index.d.ts","engines":{"node":">=14"},"gitHead":"766c5cfa1e6d0f96b7ecbe5aeacfc3c81097b670","scripts":{"test":"node test/state-resolve.test.js"},"_npmUser":{"name":"destinatlon","email":"jekanotevgeny@gmail.com"},"repository":{"url":"git+https://github.com/Destinatlon/state-resolve.git","type":"git"},"_npmVersion":"11.8.0","description":"Always resolve a valid province/state code for an address. Waterfall: valid code → region name/alias → postcode derivation → country default. Supports DE, FR, AU, BE, AT, CH, SE, NO, FI, GB.","directories":{},"_nodeVersion":"24.13.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/state-resolve_1.0.0_1782142318639_0.2587383179814362","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@destinatlon/state-resolve","version":"1.0.1","keywords":["state","province","postcode","postal-code","region","address","geocoding"],"author":{"name":"Destinatlon"},"license":"MIT","_id":"@destinatlon/state-resolve@1.0.1","maintainers":[{"name":"destinatlon","email":"jekanotevgeny@gmail.com"}],"homepage":"https://github.com/Destinatlon/state-resolve#readme","bugs":{"url":"https://github.com/Destinatlon/state-resolve/issues"},"dist":{"shasum":"201b9410dd99f0b100485747a2aac176f2da8532","tarball":"https://registry.npmjs.org/@destinatlon/state-resolve/-/state-resolve-1.0.1.tgz","fileCount":9,"integrity":"sha512-OPOxkiVplrdn5uAOdvK+bscTTN4Ip6vlQ0K45Q4jKipXnBtSSr7vY9q993X/pEEB9PADB4Xbrxipa/YF5Kuc5g==","signatures":[{"sig":"MEUCIQDqHNRRMSbdkEnpmT2ttEhVXwkJ0cqNjqT4tMM3apKVHQIgGvgMzq9VQMWaRPRkEOWkz0mgGm2+MoxVOzQuVFPpcL4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68099},"main":"index.js","types":"index.d.ts","engines":{"node":">=14"},"gitHead":"766c5cfa1e6d0f96b7ecbe5aeacfc3c81097b670","scripts":{"test":"node test/state-resolve.test.js"},"_npmUser":{"name":"destinatlon","email":"jekanotevgeny@gmail.com"},"repository":{"url":"git+https://github.com/Destinatlon/state-resolve.git","type":"git"},"_npmVersion":"11.8.0","description":"Always resolve a valid province/state code for an address. Waterfall: valid code → region name/alias → postcode derivation → country default. Supports DE, FR, AU, BE, AT, CH, SE, NO, FI, GB.","directories":{},"_nodeVersion":"24.13.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/state-resolve_1.0.1_1782152224145_0.9595142836714168","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@destinatlon/state-resolve","version":"1.0.2","keywords":["state","province","postcode","postal-code","region","address","geocoding"],"author":{"name":"Destinatlon"},"license":"MIT","_id":"@destinatlon/state-resolve@1.0.2","maintainers":[{"name":"destinatlon","email":"jekanotevgeny@gmail.com"}],"homepage":"https://github.com/Destinatlon/state-resolve#readme","bugs":{"url":"https://github.com/Destinatlon/state-resolve/issues"},"dist":{"shasum":"b522c7ba178fe77b85431ad79ab52ddacc835e47","tarball":"https://registry.npmjs.org/@destinatlon/state-resolve/-/state-resolve-1.0.2.tgz","fileCount":9,"integrity":"sha512-pzEOkN8x1Ey34GBtOTwraKBZv6fCd3sZTl8pBtMUY9Y8xVCjtm5IH3zwMG0F7dFJqJELrT6A1fwAjwAm7mDkUQ==","signatures":[{"sig":"MEUCIQDtju4EncSxdTemjfsI3K7eQg8p/HMAzbyiqoXENLO9+gIgRLrIH15dFN022E3/DQteRm7i9uD/cCJ9nKYXOsIFAMY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73198},"main":"index.js","types":"index.d.ts","engines":{"node":">=14"},"gitHead":"766c5cfa1e6d0f96b7ecbe5aeacfc3c81097b670","scripts":{"test":"node test/state-resolve.test.js","test:locales":"node test/new-locales.test.js"},"_npmUser":{"name":"destinatlon","email":"jekanotevgeny@gmail.com"},"repository":{"url":"git+https://github.com/Destinatlon/state-resolve.git","type":"git"},"_npmVersion":"11.8.0","description":"Always resolve a valid province/state code for an address. Waterfall: valid code → region name/alias → postcode derivation → country default. Supports DE, FR, AU, BE, AT, CH, SE, NO, FI, GB.","directories":{},"_nodeVersion":"24.13.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/state-resolve_1.0.2_1782158061416_0.6459823591895806","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@destinatlon/state-resolve","version":"1.0.3","description":"Always resolve a valid province/state code for an address. Waterfall: valid code → region name/alias → postcode derivation → country default. Supports DE, FR, AU, BE, AT, CH, SE, NO, FI, GB.","main":"index.js","types":"index.d.ts","scripts":{"test":"node test/state-resolve.test.js","test:locales":"node test/new-locales.test.js"},"keywords":["state","province","postcode","postal-code","region","address","geocoding"],"repository":{"type":"git","url":"git+https://github.com/Destinatlon/state-resolve.git"},"homepage":"https://github.com/Destinatlon/state-resolve#readme","bugs":{"url":"https://github.com/Destinatlon/state-resolve/issues"},"author":{"name":"Destinatlon"},"license":"MIT","engines":{"node":">=14"},"publishConfig":{"access":"public"},"gitHead":"1ace6d4edc54ee5561628cce50b1fd000aab0ba1","_id":"@destinatlon/state-resolve@1.0.3","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-ffvRbpQBq8NAyGmJfca0tgsi/luBxM0l+jYsKZ6ab7vep1JI94ek6cTt63HAKvSJaLR76nHwvWH0L7lNEI1dZw==","shasum":"e61057e07459e7fc0346efc008dcc7eeef4b8264","tarball":"https://registry.npmjs.org/@destinatlon/state-resolve/-/state-resolve-1.0.3.tgz","fileCount":9,"unpackedSize":73774,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID5rUvImk+MFX57BgNqcBtyT5SEgo6oITWX2I+ZCEybGAiEApM9Bgd+C/W0Tw3uY5Z2wfmR2L9PlUW5wkb+dfBas9TM="}]},"_npmUser":{"name":"destinatlon","email":"jekanotevgeny@gmail.com"},"directories":{},"maintainers":[{"name":"destinatlon","email":"jekanotevgeny@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/state-resolve_1.0.3_1782208786067_0.8245276213296859"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T15:31:58.382Z","modified":"2026-06-23T09:59:46.333Z","1.0.0":"2026-06-22T15:31:58.800Z","1.0.1":"2026-06-22T18:17:04.281Z","1.0.2":"2026-06-22T19:54:21.563Z","1.0.3":"2026-06-23T09:59:46.223Z"},"bugs":{"url":"https://github.com/Destinatlon/state-resolve/issues"},"author":{"name":"Destinatlon"},"license":"MIT","homepage":"https://github.com/Destinatlon/state-resolve#readme","keywords":["state","province","postcode","postal-code","region","address","geocoding"],"repository":{"type":"git","url":"git+https://github.com/Destinatlon/state-resolve.git"},"description":"Always resolve a valid province/state code for an address. Waterfall: valid code → region name/alias → postcode derivation → country default. Supports DE, FR, AU, BE, AT, CH, SE, NO, FI, GB.","maintainers":[{"name":"destinatlon","email":"jekanotevgeny@gmail.com"}],"readme":"# @destinatlon/state-resolve\n\nAlways resolve a **valid province/state code** for an address, so orders\nnever get rejected or mis-shipped because of a missing or free-text state field.\n\nNo third-party dependencies — plain Node (CommonJS), built-in `path` only.\n\n## Install\n\n```sh\nnpm install @destinatlon/state-resolve\n```\n\n## Usage\n\n```js\nconst { resolveStateCode } = require('@destinatlon/state-resolve');\n\nconst stateCode = resolveStateCode({\n  country: 'DE',          // ISO-ish code or internal alias (UK, EN, CH-DE, BE-FR…)\n  postalCode: '80331',    // used for derivation when state is missing/invalid\n  city: 'München',        // only used in fallback log messages\n  state: 'Bayern',        // raw state name OR code; may be empty\n});\n// → 'BY'\n```\n\n## How it resolves\n\nGiven `{ country, postalCode, city, state }`, the code is resolved via this waterfall:\n\n1. `state` is already a valid code → return it uppercased\n2. `state` matches a known region name/alias → return that code\n3. derive the code from `postalCode` (per-country logic)\n4. fall back to a per-country default (logs a warning)\n\nUnsupported countries pass the given `state` through unchanged.\n\n## API\n\n| Export | Signature | Description |\n|--------|-----------|-------------|\n| `resolveStateCode` | `({ country, postalCode, city, state }) => string` | Main entry point. Always returns a valid code for supported countries. |\n| `isValidCode` | `(country, code) => boolean` | True if `code` is a valid province/state code for `country`. |\n| `normCountry` | `(country) => string` | Normalize a country alias to its vocabulary key. |\n| `deriveByPostcode` | `(country, postalCode) => string \\| null` | Derive a region code from a postcode, or `null`. |\n\n## Behaviour notes\n\n- **Country aliases** are handled internally (`UK`→`GB`, `EN`→`NL`, `CH-DE`→`CH`,\n  `BE-FR`/`BE-NL`→`BE`) via `normCountry`, so locale/language codes can be passed directly.\n- For an **unsupported country** it returns whatever `state` you passed, untouched\n  (and warns if empty).\n- For a **supported country** it never returns empty — worst case it logs a\n  `[stateResolver] fell back to default…` warning and returns the country default.\n  Watch your logs for those; they flag addresses that may mis-ship.\n- **Supported derivation countries:** DE, FR, AU, BE, AT, CH, SE, NO, FI, GB.\n  To add another, add its vocabulary to `data/state-codes.json` and (optionally) a\n  deriver function in `src/postcodeRegion.js`.\n\n## Data\n\n- `data/state-codes.json` — province/state vocabulary per country.\n- `data/uk-outcodes.json` — UK outcode → region lookup table.\n\n## Test\n\n```sh\nnpm test\n```\n\n## License\n\nMIT © Destinatlon\n","readmeFilename":"README.md"}