@innovayse/geo-atlas 2.1.0 → 2.2.0

package/README.md

@@ -43,6 +43,41 @@ const armenia = CountriesAtlas.find('AM')
 // { iso2: 'AM', name: 'Armenia', translations: { hy: 'Հայաստան', ru: 'Армения' }, ... }
 ```
 
+### Lightweight entry — country list without the city dataset (`/lite`)
+
+`CountriesAtlas` bundles the per-country state/city dataset (~171 MB across ~250
+code-split chunks) because of its `getStates*` methods. If you only need the
+**country list** (names, translations, phone codes, currencies, timezones) —
+which is the common case on server-rendered pages — import from `/lite`. It loads
+only the small `atlas.json` and never references the per-country dataset, so
+bundlers don't have to process (or run out of memory on) the 171 MB:
+
+```ts
+import CountriesData from '@innovayse/geo-atlas/lite'
+
+const countries = CountriesData.getCountries()
+const armenia = CountriesData.find('AM')
+const dialCode = CountriesData.callingCode('AM')
+```
+
+`CountriesData` exposes every country-level method — `getCountries`, `find`,
+`findByIso3`, `getTimezones`, `timezone`, `getCallingCodes`, `callingCode`,
+`getCurrencies`, `currency`. `CountriesAtlas` extends it and adds `getStates`,
+`getStatesAsync` and `state`.
+
+### Cities on demand (`/cities`)
+
+When you actually need cities (typically a client-side interaction), load them
+through the dedicated `/cities` entry. Import it **dynamically** so the 171 MB
+dataset stays out of any server bundle:
+
+```ts
+// e.g. inside onMounted / a click handler — browser only
+const { getStatesForCountry } = await import('@innovayse/geo-atlas/cities')
+const states = await getStatesForCountry('AM')
+const cities = states.flatMap(s => s.cities ?? [])
+```
+
 ### Get states/regions — sync (Node.js / CJS)
 
 ```ts
@@ -135,34 +170,36 @@ const am = CountriesAtlas.callingCode('AM')
 | France (FR) | `+33 X XX XX XX XX` |
 | UK (GB) | `+44 XXXX XXXXXX` |
 
-## Nuxt 3 / Vite Setup
-
-To prevent esbuild from processing the large JSON data files (which causes OOM crashes), exclude the package from Vite's dependency optimization:
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  vite: {
-    optimizeDeps: {
-      exclude: ['@innovayse/geo-atlas']
-    }
-  }
-})
-```
+## Nuxt 3 / Vite / SSR Setup
 
-Then use `getStatesAsync` for browser-side city loading:
+The per-country dataset (~171 MB) is only reachable through the city/state
+methods. On an SSR build, importing the full `CountriesAtlas` drags that dataset
+into the **server** bundle, where rollup can run out of memory (SIGKILL / OOM).
+Avoid it by splitting your imports by need:
 
 ```ts
 // composables/useCountries.ts
-import { CountriesAtlas } from '@innovayse/geo-atlas'
 
-// Async — works in browser (ESM dynamic import)
-const cities = await CountriesAtlas.getStatesAsync('AM')
+// Server-safe: country list only — never bundles the 171 MB dataset.
+import CountriesData from '@innovayse/geo-atlas/lite'
+
+const countries = CountriesData.getCountries()
+const armenia = CountriesData.find('AM')
 
-// Sync — works in Node.js / SSR only
-const cities = CountriesAtlas.getStates('AM')
+// Cities: load on demand, browser side, via a dynamic import so the dataset
+// stays out of the server bundle entirely.
+async function loadCities(iso2: string) {
+  const { getStatesForCountry } = await import('@innovayse/geo-atlas/cities')
+  const states = await getStatesForCountry(iso2)
+  return states.flatMap(s => s.cities ?? [])
+}
 ```
 
+Keep server-rendered paths (`useAsyncData`, SSR templates) on `/lite`, and reach
+for `/cities` only where the user actually opens a city selector. With this split
+you no longer need any `optimizeDeps.exclude` / `nitro.externals` workaround for
+the package.
+
 ## Multilingual Country/City Names
 
 ```ts

package/dist/cjs/cities.d.ts

@@ -0,0 +1,12 @@
+import type { State } from './types/state.interface';
+/**
+ * Load the states (with their cities) for a country by ISO2 code.
+ *
+ * Resolves the per-country data chunk via the code-split `countryLoaders`
+ * registry, so only the requested country's JSON is fetched at runtime.
+ *
+ * @param {string} iso2 - ISO2 code of the country (case-insensitive).
+ * @returns {Promise<State[]>} - Promise resolving to the country's states, or an empty array if unavailable.
+ */
+export declare function getStatesForCountry(iso2: string): Promise<State[]>;
+export type { State } from './types/state.interface';

package/dist/cjs/cities.js

@@ -0,0 +1,58 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStatesForCountry = void 0;
+/**
+ * @packageDocumentation
+ * @module touchestate/geo-atlas/cities
+ *
+ * @description On-demand per-country state/city loader. This entry point
+ * references `countryLoaders`, which pulls in the per-country JSON dataset
+ * (~171 MB across ~250 code-split chunks). Import it only from client/browser
+ * paths where the data is actually needed — keep it out of server-rendered
+ * bundles by importing it dynamically (e.g. `await import('...cities')`).
+ *
+ * @license MIT
+ *
+ * @example
+ * const { getStatesForCountry } = await import('@touchestate/geo-atlas/cities');
+ * const states = await getStatesForCountry('AM');
+ */
+const countryLoaders_1 = __importDefault(require("./helpers/countryLoaders"));
+/**
+ * Load the states (with their cities) for a country by ISO2 code.
+ *
+ * Resolves the per-country data chunk via the code-split `countryLoaders`
+ * registry, so only the requested country's JSON is fetched at runtime.
+ *
+ * @param {string} iso2 - ISO2 code of the country (case-insensitive).
+ * @returns {Promise<State[]>} - Promise resolving to the country's states, or an empty array if unavailable.
+ */
+function getStatesForCountry(iso2) {
+    var _a, _b;
+    return __awaiter(this, void 0, void 0, function* () {
+        const loader = countryLoaders_1.default[iso2.toLowerCase()];
+        if (!loader)
+            return [];
+        try {
+            const mod = yield loader();
+            const data = (_a = mod.default) !== null && _a !== void 0 ? _a : mod;
+            return (_b = data.states) !== null && _b !== void 0 ? _b : [];
+        }
+        catch (_c) {
+            return [];
+        }
+    });
+}
+exports.getStatesForCountry = getStatesForCountry;

package/dist/cjs/helpers/CountriesAtlas.d.ts

@@ -1,38 +1,17 @@
-import { Country } from '../types/country.interface';
-import { Currency } from '../types/currency.type';
-import { PhoneCode } from '../types/phone-code.interface';
+import { CountriesData } from './CountriesData';
 import { State } from '../types/state.interface';
-import { Timezone } from '../types/timezone.type';
 /**
- * Main helper class for querying countries, states, cities, timezones,
- * calling codes and currencies from the offline geo-atlas dataset.
+ * Full offline geo-atlas helper.
+ *
+ * Extends {@link CountriesData} (country list / phone / currency / timezone —
+ * all from the small bundled `atlas.json`) and adds per-country state & city
+ * access. The state/city methods pull data through `countryLoaders`, which
+ * references every per-country JSON file (~171 MB total). Because that import
+ * lives here and NOT in `CountriesData`, consumers that only need the country
+ * list can import `CountriesData` (or the `/lite` entry) and avoid bundling the
+ * per-country dataset entirely.
  */
-export declare class CountriesAtlas {
-    /** Internal countries array loaded from the bundled atlas.json. */
-    private countries;
-    /** Initializes the atlas by loading the bundled country data. */
-    constructor();
-    /**
-     * Retrieve all countries with specified properties, or all countries if no properties are specified.
-     *
-     * @param {string[]} properties - Array of properties to retrieve.
-     * @return {Country[]} - Array of country objects with specified properties or all countries.
-     */
-    getCountries(properties?: string[]): Country[];
-    /**
-     * Find a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country to find.
-     * @return {Country | undefined} - Country object or undefined if not found.
-    */
-    find(iso2: string): Country | undefined;
-    /**
-     * Find a country by its ISO3 code.
-     *
-     * @param {string} iso3 - ISO3 code of the country to find.
-     * @return {Country | undefined} - Country object or undefined if not found.
-    */
-    findByIso3(iso3: string): Country | undefined;
+export declare class CountriesAtlas extends CountriesData {
     /**
      * Retrieve all states of a country by its ISO2 code.
      *
@@ -59,45 +38,6 @@ export declare class CountriesAtlas {
      * @returns {State | undefined} - State object or undefined if not found.
      */
     state(iso2: string, stateCode: string): State | undefined;
-    /**
-     * Retrieve all timezones of all available countries.
-     *
-     * @returns {Timezone[]} - Array of timezone objects.
-     */
-    getTimezones(): Timezone[];
-    /**
-     * Retrieve all timezones of a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country.
-     * @returns {Timezone[] | undefined} - Array of timezone objects or undefined if not found.
-     */
-    timezone(iso2: string): Timezone[] | undefined;
-    /**
-     * Retrieve all calling codes of all available countries.
-     *
-     * @returns {PhoneCode[]} - Array of phone code objects.
-     */
-    getCallingCodes(): PhoneCode[];
-    /**
-     * Retrieve calling codes of a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country.
-     * @returns {PhoneCode | undefined} - Phone code object or undefined if not found.
-     */
-    callingCode(iso2: string): PhoneCode | undefined;
-    /**
-     * Retrieve all currencies of all available countries.
-     *
-     * @returns {Currency[]} - Array of currency objects.
-     */
-    getCurrencies(): Currency[];
-    /**
-     * Retrieve currency of a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country.
-     * @returns {Currency | undefined} - Currency object or undefined if not found.
-     */
-    currency(iso2: string): Currency | undefined;
 }
 declare const _default: CountriesAtlas;
 export default _default;

package/dist/cjs/helpers/CountriesAtlas.js

@@ -13,66 +13,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CountriesAtlas = void 0;
-const atlas_json_1 = __importDefault(require("../data/atlas.json"));
+const CountriesData_1 = require("./CountriesData");
 const countryLoaders_1 = __importDefault(require("./countryLoaders"));
 /**
- * Main helper class for querying countries, states, cities, timezones,
- * calling codes and currencies from the offline geo-atlas dataset.
+ * Full offline geo-atlas helper.
+ *
+ * Extends {@link CountriesData} (country list / phone / currency / timezone —
+ * all from the small bundled `atlas.json`) and adds per-country state & city
+ * access. The state/city methods pull data through `countryLoaders`, which
+ * references every per-country JSON file (~171 MB total). Because that import
+ * lives here and NOT in `CountriesData`, consumers that only need the country
+ * list can import `CountriesData` (or the `/lite` entry) and avoid bundling the
+ * per-country dataset entirely.
  */
-class CountriesAtlas {
-    /** Initializes the atlas by loading the bundled country data. */
-    constructor() {
-        this.countries = atlas_json_1.default;
-    }
-    /**
-     * Retrieve all countries with specified properties, or all countries if no properties are specified.
-     *
-     * @param {string[]} properties - Array of properties to retrieve.
-     * @return {Country[]} - Array of country objects with specified properties or all countries.
-     */
-    getCountries(properties) {
-        if (properties) {
-            return this.countries.map(country => {
-                const newCountry = {};
-                properties.forEach(property => {
-                    newCountry[property] = country[property];
-                });
-                return newCountry;
-            });
-        }
-        return this.countries;
-    }
-    /**
-     * Find a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country to find.
-     * @return {Country | undefined} - Country object or undefined if not found.
-    */
-    find(iso2) {
-        return this.countries.find(country => { var _a; return ((_a = country.iso2) === null || _a === void 0 ? void 0 : _a.toUpperCase()) === iso2.toUpperCase(); });
-    }
-    /**
-     * Find a country by its ISO3 code.
-     *
-     * @param {string} iso3 - ISO3 code of the country to find.
-     * @return {Country | undefined} - Country object or undefined if not found.
-    */
-    findByIso3(iso3) {
-        return this.countries.find(country => { var _a; return ((_a = country.iso3) === null || _a === void 0 ? void 0 : _a.toUpperCase()) === iso3.toUpperCase(); });
-    }
-    // getStates(iso2: string): Promise<State[]> | undefined {
-    //     const country = this.find(iso2)
-    //     if (country) {
-    //         return import(`../data/countries/${country.iso2?.toLowerCase()}.json`)
-    //             .then(statesData => {
-    //                 return statesData.states
-    //             })
-    //             .catch(() => {
-    //                 return undefined
-    //             })
-    //     }
-    //     return undefined
-    // }
+class CountriesAtlas extends CountriesData_1.CountriesData {
     /**
      * Retrieve all states of a country by its ISO2 code.
      *
@@ -122,18 +76,6 @@ class CountriesAtlas {
             }
         });
     }
-    // state(iso2: string, stateCode: string): Promise<State | undefined> | undefined {
-    //     const country = this.find(iso2);
-    //     if (country) {
-    //         return import(`../data/countries/${country.iso2?.toLowerCase()}.json`)
-    //             .then((statesData: StateData) => {
-    //                 const state = statesData.states.find((s: State) => s.state_code?.toUpperCase() === stateCode);
-    //                 return state ? state : undefined;
-    //             })
-    //             .catch(() => undefined);
-    //     }
-    //     return undefined;
-    // }
     /**
      * Find a state by its state code and country ISO2 code.
      *
@@ -156,98 +98,6 @@ class CountriesAtlas {
         }
         return undefined;
     }
-    /**
-     * Retrieve all timezones of all available countries.
-     *
-     * @returns {Timezone[]} - Array of timezone objects.
-     */
-    getTimezones() {
-        const timezoneSet = new Set();
-        this.countries.forEach(country => {
-            var _a;
-            (_a = country.timezones) === null || _a === void 0 ? void 0 : _a.forEach(timezone => {
-                timezoneSet.add(timezone);
-            });
-        });
-        return Array.from(timezoneSet);
-    }
-    /**
-     * Retrieve all timezones of a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country.
-     * @returns {Timezone[] | undefined} - Array of timezone objects or undefined if not found.
-     */
-    timezone(iso2) {
-        const country = this.find(iso2);
-        if (country) {
-            return country.timezones;
-        }
-        return undefined;
-    }
-    /**
-     * Retrieve all calling codes of all available countries.
-     *
-     * @returns {PhoneCode[]} - Array of phone code objects.
-     */
-    getCallingCodes() {
-        return this.getCountries(['name', 'phone', 'iso2', 'phone_format']).map(country => {
-            var _a;
-            return Object.assign(Object.assign({}, country), { phone_code: `+${country.phone}`, flag: `flag flag-${(_a = country.iso2) === null || _a === void 0 ? void 0 : _a.toLowerCase()}` });
-        });
-    }
-    /**
-     * Retrieve calling codes of a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country.
-     * @returns {PhoneCode | undefined} - Phone code object or undefined if not found.
-     */
-    callingCode(iso2) {
-        var _a;
-        const country = this.find(iso2);
-        if (country) {
-            return {
-                name: country.name,
-                phone: country.phone,
-                iso2: country.iso2,
-                phone_code: `+${country.phone}`,
-                flag: `flag flag-${(_a = country.iso2) === null || _a === void 0 ? void 0 : _a.toLowerCase()}`,
-                phone_format: country.phone_format
-            };
-        }
-        return undefined;
-    }
-    /**
-     * Retrieve all currencies of all available countries.
-     *
-     * @returns {Currency[]} - Array of currency objects.
-     */
-    getCurrencies() {
-        return this.getCountries(['name', 'iso2', 'currency', 'currency_symbol', 'currency_name']).map(country => {
-            var _a;
-            return Object.assign(Object.assign({}, country), { flag: `flag flag-${(_a = country.iso2) === null || _a === void 0 ? void 0 : _a.toLowerCase()}` });
-        });
-    }
-    /**
-     * Retrieve currency of a country by its ISO2 code.
-     *
-     * @param {string} iso2 - ISO2 code of the country.
-     * @returns {Currency | undefined} - Currency object or undefined if not found.
-     */
-    currency(iso2) {
-        var _a;
-        const country = this.find(iso2);
-        if (country) {
-            return {
-                name: country.name,
-                iso2: country.iso2,
-                currency: country.currency,
-                currency_symbol: country.currency_symbol,
-                currency_name: country.currency_name,
-                flag: `flag flag-${(_a = country.iso2) === null || _a === void 0 ? void 0 : _a.toLowerCase()}`
-            };
-        }
-        return undefined;
-    }
 }
 exports.CountriesAtlas = CountriesAtlas;
 exports.default = new CountriesAtlas();

package/dist/cjs/helpers/CountriesData.d.ts

@@ -0,0 +1,86 @@
+import { Country } from '../types/country.interface';
+import { Currency } from '../types/currency.type';
+import { PhoneCode } from '../types/phone-code.interface';
+import { Timezone } from '../types/timezone.type';
+/**
+ * Lightweight country-list helper.
+ *
+ * Loads ONLY the bundled `atlas.json` (the country list plus per-country
+ * metadata: names, translations, phone, currency, timezones). It deliberately
+ * does NOT import the per-country state/city loaders (`countryLoaders`), so
+ * importing this class never drags the ~171 MB of per-country state/city JSON
+ * into a consumer's bundle.
+ *
+ * Use this when you only need countries, phone codes, currencies or timezones
+ * — e.g. on a server-rendered path. When you need states/cities, use
+ * `CountriesAtlas` (which extends this) or the `@touchestate/geo-atlas/cities`
+ * entry point.
+ */
+export declare class CountriesData {
+    /** Internal countries array loaded from the bundled atlas.json. */
+    protected countries: Country[];
+    /** Initializes the atlas by loading the bundled country data. */
+    constructor();
+    /**
+     * Retrieve all countries with specified properties, or all countries if no properties are specified.
+     *
+     * @param {string[]} properties - Array of properties to retrieve.
+     * @return {Country[]} - Array of country objects with specified properties or all countries.
+     */
+    getCountries(properties?: string[]): Country[];
+    /**
+     * Find a country by its ISO2 code.
+     *
+     * @param {string} iso2 - ISO2 code of the country to find.
+     * @return {Country | undefined} - Country object or undefined if not found.
+     */
+    find(iso2: string): Country | undefined;
+    /**
+     * Find a country by its ISO3 code.
+     *
+     * @param {string} iso3 - ISO3 code of the country to find.
+     * @return {Country | undefined} - Country object or undefined if not found.
+     */
+    findByIso3(iso3: string): Country | undefined;
+    /**
+     * Retrieve all timezones of all available countries.
+     *
+     * @returns {Timezone[]} - Array of timezone objects.
+     */
+    getTimezones(): Timezone[];
+    /**
+     * Retrieve all timezones of a country by its ISO2 code.
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {Timezone[] | undefined} - Array of timezone objects or undefined if not found.
+     */
+    timezone(iso2: string): Timezone[] | undefined;
+    /**
+     * Retrieve all calling codes of all available countries.
+     *
+     * @returns {PhoneCode[]} - Array of phone code objects.
+     */
+    getCallingCodes(): PhoneCode[];
+    /**
+     * Retrieve calling codes of a country by its ISO2 code.
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {PhoneCode | undefined} - Phone code object or undefined if not found.
+     */
+    callingCode(iso2: string): PhoneCode | undefined;
+    /**
+     * Retrieve all currencies of all available countries.
+     *
+     * @returns {Currency[]} - Array of currency objects.
+     */
+    getCurrencies(): Currency[];
+    /**
+     * Retrieve currency of a country by its ISO2 code.
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {Currency | undefined} - Currency object or undefined if not found.
+     */
+    currency(iso2: string): Currency | undefined;
+}
+declare const _default: CountriesData;
+export default _default;