localized-regions 1.1.0 → 1.2.0

package/README.md

@@ -97,6 +97,8 @@ import { countryOptions } from 'localized-regions';
 | `countryOptions(locale?)` | `Option[]` (`{ value, label }`) |
 | `provinceOptions(countryCode)` | `Option[]` |
 | `cityOptions(countryCode, provinceCode?)` | `Option[]` |
+| `formatAddressLine1(countryCode, street, houseNumber)` | address line 1 in the country's own order |
+| `isHouseNumberFirst(countryCode)` | `boolean` - does this country write the number before the street |
 
 ## How the data is built
 
@@ -140,6 +142,23 @@ Maarten are separate constituent countries, and Bonaire, Saba and Sint Eustatius
 are Caribbean special municipalities; ISO 3166-2 lists all six under NL, but they
 are not provinces and have no cities, so they are excluded.
 
+## Address line 1 order
+
+Countries disagree on whether the house number comes before or after the
+street. `formatAddressLine1` builds line 1 from the separate street and number
+(for example Google Places `route` + `street_number`) in the country's order:
+
+```js
+import { formatAddressLine1 } from 'localized-regions';
+
+formatAddressLine1('NL', 'Boerendanserdijk', '43a'); // "Boerendanserdijk 43a"
+formatAddressLine1('ES', 'Calle Mayor', '12');       // "Calle Mayor 12"
+formatAddressLine1('GB', 'Downing Street', '10');    // "10 Downing Street"
+```
+
+GB, IE, LU, FR and US put the number first; every other country puts the street
+first. A missing street or number is simply left out.
+
 ## Notes and limitations
 
 - **Spain city cascade is community-level.** The source city data groups Spanish cities under autonomous communities, not the 50 provinces, so `getCities('ES', 'ES-MA')` returns the parent community's cities (best-effort). City is best treated as a free-text field.

package/dist/address.d.ts

@@ -0,0 +1,8 @@
+/** Does this country write the house number before the street? */
+export declare function isHouseNumberFirst(countryCode: string): boolean;
+/**
+ * Address line 1 in the order the country writes it. `houseNumber` keeps any
+ * addition as given ("43a"). A missing street or number is left out rather
+ * than leaving a stray space, so `formatAddressLine1('NL', 'Dam', '')` is "Dam".
+ */
+export declare function formatAddressLine1(countryCode: string, street: string, houseNumber: string): string;

package/dist/address.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHouseNumberFirst = isHouseNumberFirst;
+exports.formatAddressLine1 = formatAddressLine1;
+/**
+ * Countries whose postal address puts the house number before the street, e.g.
+ * "10 Downing Street". Every other country writes the street first, e.g.
+ * "Boerendanserdijk 43a" (NL) or "Calle Mayor 12" (ES).
+ *
+ * ISO 3166-1 alpha-2, as Google Places returns it - the UK is "GB" (RAT-2178).
+ */
+const HOUSE_NUMBER_FIRST_COUNTRIES = new Set(['GB', 'IE', 'LU', 'FR', 'US']);
+/** Does this country write the house number before the street? */
+function isHouseNumberFirst(countryCode) {
+    return HOUSE_NUMBER_FIRST_COUNTRIES.has((countryCode ?? '').trim().toUpperCase());
+}
+/**
+ * Address line 1 in the order the country writes it. `houseNumber` keeps any
+ * addition as given ("43a"). A missing street or number is left out rather
+ * than leaving a stray space, so `formatAddressLine1('NL', 'Dam', '')` is "Dam".
+ */
+function formatAddressLine1(countryCode, street, houseNumber) {
+    const parts = isHouseNumberFirst(countryCode) ? [houseNumber, street] : [street, houseNumber];
+    return parts
+        .map((part) => (part ?? '').trim())
+        .filter(Boolean)
+        .join(' ');
+}

package/dist/index.d.ts

@@ -41,4 +41,5 @@ export declare function countryOptions(locale?: string): Option[];
 export declare function provinceOptions(countryCode: string): Option[];
 /** City options. value = label = city name (cities have no stable code). */
 export declare function cityOptions(countryCode: string, provinceCode?: string): Option[];
+export { formatAddressLine1, isHouseNumberFirst } from './address';
 export * from './types';

package/dist/index.js

@@ -17,6 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHouseNumberFirst = exports.formatAddressLine1 = void 0;
 exports.getCountries = getCountries;
 exports.getCountry = getCountry;
 exports.formatCountryLabel = formatCountryLabel;
@@ -147,4 +148,7 @@ function provinceOptions(countryCode) {
 function cityOptions(countryCode, provinceCode) {
     return getCities(countryCode, provinceCode).map((c) => ({ value: c.name, label: c.name }));
 }
+var address_1 = require("./address");
+Object.defineProperty(exports, "formatAddressLine1", { enumerable: true, get: function () { return address_1.formatAddressLine1; } });
+Object.defineProperty(exports, "isHouseNumberFirst", { enumerable: true, get: function () { return address_1.isHouseNumberFirst; } });
 __exportStar(require("./types"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localized-regions",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Country, province and city data with bilingual localized labels (e.g. \"España (Spain)\") and ISO 3166-1 / ISO 3166-2 codes. Ships all 50 Spanish provinces. Framework-agnostic, drop-in options for react-select and MUI dropdowns.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",