@innovayse/geo-atlas 2.0.2 → 2.2.0

package/README.md

@@ -9,11 +9,12 @@ Zero API calls — all data is bundled locally.
 
 ## Features
 
-- **250 countries** with ISO2/ISO3 codes, flags, phone codes, capitals, coordinates
+- **250 countries** with ISO2/ISO3 codes, flags, phone codes, phone format placeholders, capitals, coordinates
 - **147,000+ cities** across all countries with coordinates
 - **Complete multilingual city names**: English, Russian (ru), Armenian (hy) + 15 more languages
 - **Country translations**: all 250 countries translated to Russian and Armenian
 - **Native script** support for each city and country
+- **Phone format placeholders** for all 250 countries (e.g. `+374 9X XXX XXX` for Armenia)
 - **Dual ESM + CJS build** — works in browsers, Node.js, Nuxt 3, Vite
 - **TypeScript** — full type declarations included
 - **Zero runtime dependencies** — fully offline, no API calls
@@ -42,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
@@ -93,6 +129,7 @@ type Country = {
   emoji: string       // '🇦🇲'
   capital: string     // 'Yerevan'
   phone: number       // 374
+  phone_format: string // '+374 9X XXX XXX'
   latitude: string    // '40.0'
   longitude: string   // '45.0'
   translations: {
@@ -105,34 +142,64 @@ type Country = {
 }
 ```
 
-## Nuxt 3 / Vite Setup
+### Phone format placeholder
 
-To prevent esbuild from processing the large JSON data files (which causes OOM crashes), exclude the package from Vite's dependency optimization:
+`phone_format` contains the full international format with `X` for variable digits:
 
 ```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  vite: {
-    optimizeDeps: {
-      exclude: ['@innovayse/geo-atlas']
-    }
-  }
-})
+const am = CountriesAtlas.callingCode('AM')
+// {
+//   name: 'Armenia',
+//   phone: 374,
+//   iso2: 'AM',
+//   phone_code: '+374',
+//   phone_format: '+374 9X XXX XXX',
+//   flag: 'flag flag-am'
+// }
+
+// Use as input placeholder:
+// <input :placeholder="callingCode.phone_format" />
 ```
 
-Then use `getStatesAsync` for browser-side city loading:
+| Country | `phone_format` |
+|---------|---------------|
+| Armenia (AM) | `+374 9X XXX XXX` |
+| Russia (RU) | `+7 9XX XXX XXXX` |
+| USA (US) | `+1 XXX XXX XXXX` |
+| Germany (DE) | `+49 XXXX XXXXXXX` |
+| France (FR) | `+33 X XX XX XX XX` |
+| UK (GB) | `+44 XXXX XXXXXX` |
+
+## Nuxt 3 / Vite / SSR Setup
+
+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;