@innovayse/geo-atlas 2.0.0 → 2.0.2

package/README.md

@@ -9,12 +9,14 @@ Zero API calls — all data is bundled locally.
 
 ## Features
 
-- **250 countries** with ISO2 codes, flags, phone codes, capitals, coordinates
+- **250 countries** with ISO2/ISO3 codes, flags, phone codes, capitals, coordinates
 - **147,000+ cities** across all countries with coordinates
 - **Complete multilingual city names**: English, Russian (ru), Armenian (hy) + 15 more languages
-- **Native script** support for each city/country
+- **Country translations**: all 250 countries translated to Russian and Armenian
+- **Native script** support for each city and country
+- **Dual ESM + CJS build** — works in browsers, Node.js, Nuxt 3, Vite
 - **TypeScript** — full type declarations included
-- **Zero dependencies** — fully offline, no API calls
+- **Zero runtime dependencies** — fully offline, no API calls
 
 ## Installation
 
@@ -33,13 +35,29 @@ const countries = CountriesAtlas.getCountries()
 // [{ iso2: 'AM', name: 'Armenia', native: 'Հայաստան', emoji: '🇦🇲', phone: 374, ... }]
 ```
 
-### Get states/regions of a country
+### Find a country by ISO2
+
+```ts
+const armenia = CountriesAtlas.find('AM')
+// { iso2: 'AM', name: 'Armenia', translations: { hy: 'Հայաստան', ru: 'Армения' }, ... }
+```
+
+### Get states/regions — sync (Node.js / CJS)
 
 ```ts
 const states = CountriesAtlas.getStates('AM')
 // [{ name: 'Yerevan', cities: [...] }, ...]
 ```
 
+### Get states/regions — async (Browser / ESM)
+
+`getStatesAsync` uses dynamic `import()` and works in all environments including browsers:
+
+```ts
+const states = await CountriesAtlas.getStatesAsync('AM')
+// [{ name: 'Yerevan', cities: [...] }, ...]
+```
+
 ### Get cities
 
 ```ts
@@ -69,6 +87,7 @@ Each city includes:
 ```ts
 type Country = {
   iso2: string        // 'AM'
+  iso3: string        // 'ARM'
   name: string        // 'Armenia'
   native: string      // 'Հայաստան'
   emoji: string       // '🇦🇲'
@@ -76,39 +95,59 @@ type Country = {
   phone: number       // 374
   latitude: string    // '40.0'
   longitude: string   // '45.0'
-  translations: Record<string, string>
+  translations: {
+    hy: string        // 'Հայաստան'
+    ru: string        // 'Армения'
+    // + 15 more languages
+  }
   currency: string    // 'AMD'
   timezones: Timezone[]
 }
 ```
 
-## Multilingual Helper (Nuxt/Vue)
+## 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
-type GeoLocale = 'en' | 'ru' | 'hy'
+// nuxt.config.ts
+export default defineNuxtConfig({
+  vite: {
+    optimizeDeps: {
+      exclude: ['@innovayse/geo-atlas']
+    }
+  }
+})
+```
 
-/** Get localized city name with fallback */
-function getCityName(city: CityItem, locale: GeoLocale): string {
-  if (locale === 'en') return city.name
-  return city.translations[locale] ?? city.native ?? city.name
-}
+Then use `getStatesAsync` for browser-side city loading:
 
-/** Get localized country name with fallback */
-function getCountryName(country: CountryItem, locale: GeoLocale): string {
-  if (locale === 'en') return country.name
-  return country.translations[locale] ?? country.native ?? country.name
-}
-```
+```ts
+// composables/useCountries.ts
+import { CountriesAtlas } from '@innovayse/geo-atlas'
 
-## Nuxt 3 / SSR Setup
+// Async — works in browser (ESM dynamic import)
+const cities = await CountriesAtlas.getStatesAsync('AM')
+
+// Sync — works in Node.js / SSR only
+const cities = CountriesAtlas.getStates('AM')
+```
 
-Add to `nuxt.config.ts`:
+## Multilingual Country/City Names
 
 ```ts
-vite: {
-  ssr: {
-    noExternal: ['@innovayse/geo-atlas']
-  }
+type GeoLocale = 'en' | 'ru' | 'hy'
+
+/** Get localized country name with fallback chain */
+function getCountryName(country: Country, locale: GeoLocale): string {
+  if (locale === 'en') return country.name
+  return country.translations?.[locale] ?? country.native ?? country.name
+}
+
+/** Get localized city name with fallback chain */
+function getCityName(city: City, locale: GeoLocale): string {
+  if (locale === 'en') return city.name
+  return city.translations?.[locale] ?? city.native ?? city.name
 }
 ```
 
@@ -117,8 +156,9 @@ vite: {
 ```ts
 import { ValidatorAtlas } from '@innovayse/geo-atlas'
 
-ValidatorAtlas.isValidCountry('AM')   // true
-ValidatorAtlas.isValidState('AM', 'Yerevan')  // true
+ValidatorAtlas.isValidCountry('AM')            // true
+ValidatorAtlas.isValidCountry('XX')            // false
+ValidatorAtlas.isValidState('AM', 'Yerevan')   // true
 ```
 
 ## License

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

@@ -40,6 +40,13 @@ export declare class CountriesAtlas {
      * @returns {State[] | undefined} - Array of state objects or undefined if not found.
      */
     getStates(iso2: string): State[] | undefined;
+    /**
+     * Retrieve all states of a country by its ISO2 code using dynamic import (browser-compatible).
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {Promise<State[]>} - Promise resolving to array of state objects.
+     */
+    getStatesAsync(iso2: string): Promise<State[]>;
     /**
      * Find a state by its state code and country ISO2 code.
      *

package/dist/cjs/helpers/CountriesAtlas.js

@@ -1,4 +1,36 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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 };
 };
@@ -83,6 +115,29 @@ class CountriesAtlas {
         }
         return undefined;
     }
+    /**
+     * Retrieve all states of a country by its ISO2 code using dynamic import (browser-compatible).
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {Promise<State[]>} - Promise resolving to array of state objects.
+     */
+    getStatesAsync(iso2) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            var _c;
+            const country = this.find(iso2);
+            if (!country || !country.iso2)
+                return [];
+            try {
+                const mod = yield (_c = `../data/countries/${country.iso2.toLowerCase()}.json`, Promise.resolve().then(() => __importStar(require(_c))));
+                const data = (_a = mod.default) !== null && _a !== void 0 ? _a : mod;
+                return (_b = data.states) !== null && _b !== void 0 ? _b : [];
+            }
+            catch (_d) {
+                return [];
+            }
+        });
+    }
     // state(iso2: string, stateCode: string): Promise<State | undefined> | undefined {
     //     const country = this.find(iso2);
     //     if (country) {

package/dist/cjs/index.d.ts

@@ -14,3 +14,11 @@
  */
 export { default as CountriesAtlas } from './helpers/CountriesAtlas';
 export { default as ValidatorAtlas } from './helpers/ValidatorAtlas';
+export type { Country } from './types/country.interface';
+export type { State } from './types/state.interface';
+export type { City } from './types/city.type';
+export type { Timezone } from './types/timezone.type';
+export type { Translations } from './types/translation.type';
+export type { Currency } from './types/currency.type';
+export type { PhoneCode } from './types/phone-code.interface';
+export type { StateData } from './types/state-data.type';

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

@@ -40,6 +40,13 @@ export declare class CountriesAtlas {
      * @returns {State[] | undefined} - Array of state objects or undefined if not found.
      */
     getStates(iso2: string): State[] | undefined;
+    /**
+     * Retrieve all states of a country by its ISO2 code using dynamic import (browser-compatible).
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {Promise<State[]>} - Promise resolving to array of state objects.
+     */
+    getStatesAsync(iso2: string): Promise<State[]>;
     /**
      * Find a state by its state code and country ISO2 code.
      *

package/dist/esm/helpers/CountriesAtlas.js

@@ -1,3 +1,12 @@
+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());
+    });
+};
 import countriesData from '../data/atlas.json';
 /**
  * Main helper class for querying countries, states, cities, timezones,
@@ -77,6 +86,28 @@ export class CountriesAtlas {
         }
         return undefined;
     }
+    /**
+     * Retrieve all states of a country by its ISO2 code using dynamic import (browser-compatible).
+     *
+     * @param {string} iso2 - ISO2 code of the country.
+     * @returns {Promise<State[]>} - Promise resolving to array of state objects.
+     */
+    getStatesAsync(iso2) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const country = this.find(iso2);
+            if (!country || !country.iso2)
+                return [];
+            try {
+                const mod = yield import(`../data/countries/${country.iso2.toLowerCase()}.json`);
+                const data = (_a = mod.default) !== null && _a !== void 0 ? _a : mod;
+                return (_b = data.states) !== null && _b !== void 0 ? _b : [];
+            }
+            catch (_c) {
+                return [];
+            }
+        });
+    }
     // state(iso2: string, stateCode: string): Promise<State | undefined> | undefined {
     //     const country = this.find(iso2);
     //     if (country) {

package/dist/esm/index.d.ts

@@ -14,3 +14,11 @@
  */
 export { default as CountriesAtlas } from './helpers/CountriesAtlas';
 export { default as ValidatorAtlas } from './helpers/ValidatorAtlas';
+export type { Country } from './types/country.interface';
+export type { State } from './types/state.interface';
+export type { City } from './types/city.type';
+export type { Timezone } from './types/timezone.type';
+export type { Translations } from './types/translation.type';
+export type { Currency } from './types/currency.type';
+export type { PhoneCode } from './types/phone-code.interface';
+export type { StateData } from './types/state-data.type';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@innovayse/geo-atlas",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Offline countries, states and cities with multilingual support (EN/RU/HY + 15 languages).",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -10,10 +10,58 @@
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js",
       "types": "./dist/cjs/index.d.ts"
+    },
+    "./country": {
+      "import": "./dist/esm/types/country.interface.js",
+      "require": "./dist/cjs/types/country.interface.js",
+      "types": "./dist/cjs/types/country.interface.d.ts"
+    },
+    "./state": {
+      "import": "./dist/esm/types/state.interface.js",
+      "require": "./dist/cjs/types/state.interface.js",
+      "types": "./dist/cjs/types/state.interface.d.ts"
+    },
+    "./city": {
+      "import": "./dist/esm/types/city.type.js",
+      "require": "./dist/cjs/types/city.type.js",
+      "types": "./dist/cjs/types/city.type.d.ts"
+    },
+    "./timezone": {
+      "import": "./dist/esm/types/timezone.type.js",
+      "require": "./dist/cjs/types/timezone.type.js",
+      "types": "./dist/cjs/types/timezone.type.d.ts"
+    },
+    "./translations": {
+      "import": "./dist/esm/types/translation.type.js",
+      "require": "./dist/cjs/types/translation.type.js",
+      "types": "./dist/cjs/types/translation.type.d.ts"
+    },
+    "./currency": {
+      "import": "./dist/esm/types/currency.type.js",
+      "require": "./dist/cjs/types/currency.type.js",
+      "types": "./dist/cjs/types/currency.type.d.ts"
+    },
+    "./phone-code": {
+      "import": "./dist/esm/types/phone-code.interface.js",
+      "require": "./dist/cjs/types/phone-code.interface.js",
+      "types": "./dist/cjs/types/phone-code.interface.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "country": ["./dist/cjs/types/country.interface.d.ts"],
+      "state": ["./dist/cjs/types/state.interface.d.ts"],
+      "city": ["./dist/cjs/types/city.type.d.ts"],
+      "timezone": ["./dist/cjs/types/timezone.type.d.ts"],
+      "translations": ["./dist/cjs/types/translation.type.d.ts"],
+      "currency": ["./dist/cjs/types/currency.type.d.ts"],
+      "phone-code": ["./dist/cjs/types/phone-code.interface.d.ts"]
     }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json"
+    "build": "rm -rf dist && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "countries",
@@ -28,8 +76,10 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^18.19.0",
+    "ts-node": "^10.9.2",
     "typescript": "4.9.5",
-    "@types/node": "18.19.0"
+    "vitest": "^4.1.4"
   },
   "files": [
     "dist/**/*",