🌍 Randstad Countries, States & Cities Library

Una librería en TypeScript para acceder a información sobre países, estados/provincias y ciudades de forma organizada y tipada.

npm install @randstad-uca/countries-states-cities

🧩 Características

• ✅ Soporte multilenguaje (ej: español, inglés).
• ✅ Archivos JSON separados por idioma.
• ✅ Fácil de mantener y expandir.
• ✅ Uso simple desde cualquier parte del proyecto.
• ✅ Compatible con sistemas offline (si se usa con .tgz o archivos locales).

🧩 Uso Básico

import location from '@randstad-uca/countries-states-cities';

🏁 Métodos Disponibles

1. getAllCountries(type?: Type): CountryResponse[]

Devuelve todos los países.

• Parámetros: type: 'base' | 'full' (opcional, por defecto es 'base')
• Ejemplo:

const allCountries = location.getAllCountries();
const baseCountries = location.getAllCountries('full');

2. getCountry(isoCode: string, type?: Type): CountryResponse | undefined Busca un país por su código ISO.

• Parámetros: isoCode: Código ISO del país (ej: "AR" para Argentina) type: 'base' | 'full' (opcional, por defecto es 'base')
• Ejemplo:

const argentina = location.getCountry("AR");
const argentinaBase = location.getCountry("AR", "base");

3. getAllStates(countryCode: string, type?: Type): StateResponse[] Devuelve todos los estados de un país.

• Parámetros: countryCode: Código ISO del país (ej: "AR") type: 'base' | 'full' (opcional, por defecto es 'base')
• Ejemplo:

const estadosDeARG = location.getAllStates("AR");
const estadosDeARGBase = location.getAllStates("AR", "base");

4. getCitiesByState(countryCode: string, stateCode: number | string): CityResponse[] Devuelve todas las ciudades de un estado de Argentina solo se usa este en las API habilitadas

• Parámetros: countryCode: Código ISO del país (ej: "AR") stateCode: Código del estado (puede ser número o string)
• Ejemplo:

const citiesOfArgentina = location.getCitiesByState("AR", 1);

5. getCityByLocCodLocSec(locCod: number, locSec: number): City[] Devuelve todas las ciudades de con locCod y locSec de Argentina solo se usa este en las API habilitadas

• Parámetros: locCod: Código númerico postal de la provincia (ej: 5539) locSec: Código númerico seccion de la provincia (ej: 1)
• Ejemplo:

const citiesOfArgentinaByLocCodLocSec = location.getCityByLocCodLocSec(1741, 8);

6. getState(stateCode: number): State[] Devuelve estado especificamente de Argentina correspodiente al stateCode

• Parámetros: stateCode: stateCode de la provincia (ej: 6)
• Ejemplo:

const stateByCodePRV = location.getState(6);

🧱 Tipos Soportados

type Type = 'base' | 'full';

Interfaces Base

CountryBase

{
  PaiCod: string;     // Nombre del país
  PaiNom: string;     // Nombre formal
  PaiAFICod: number;  // Código interno
  PaiIso: string;     // Código ISO
}

StateBase

{
  PrvCod: number;     // Código del estado
  PrvNom: string;     // Nombre del estado
}

CityBase

{
  LocCod: number;     // Código de la ciudad
  LocSec: number;     // Código secundario
  LocNom: string;     // Nombre de la ciudad
  PrvCod: number;     // Código del estado al que pertenece
}

📁 Estructura del Proyecto

country-state-cities/
├── src/
│   ├── assets              - Banderas .svg
│   ├── index.ts            - Funciones principales
│   ├── data/               # Archivos JSON con datos
│   ├── script/             # Copy data to build
│   ├── services/           # Servicio principal
│   ├── utils/              # Funciones auxiliares
│   ├── types/              # Tipos e interfaces globales
│   └── test/               # Scripts de prueba
├── dist/                   - Código compilado (build)
├── package.json
├── README.md
└── tsconfig.json