regions-config 1.7.0 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +132 -4
- package/dist/index.d.mts +3137 -1672
- package/dist/index.d.ts +3137 -1672
- package/dist/index.js +3096 -1353
- package/dist/index.mjs +3055 -1298
- package/package.json +9 -8
package/README.md
CHANGED
|
@@ -153,6 +153,117 @@ Si `documentTypeOptionsByOrigin` no está definido, devuelve el array `documentT
|
|
|
153
153
|
|
|
154
154
|
---
|
|
155
155
|
|
|
156
|
+
### Catálogo de países (ISO 3166-1 alpha-2 ↔ `countryId` IATI)
|
|
157
|
+
|
|
158
|
+
Tabla maestra para traducir entre los `countryId` IATI (`1` España, `124` Italia, `127` Japón…) y códigos ISO 3166-1 alpha-2.
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
import {
|
|
162
|
+
COUNTRIES,
|
|
163
|
+
COUNTRY_CATALOG,
|
|
164
|
+
ISO_COUNTRY_CODES,
|
|
165
|
+
CUSTOM_ISO_COUNTRIES,
|
|
166
|
+
getCountryIdByIso,
|
|
167
|
+
getIsoByCountryId,
|
|
168
|
+
isIsoCountryCode,
|
|
169
|
+
type IsoCountryCode,
|
|
170
|
+
} from 'regions-config';
|
|
171
|
+
|
|
172
|
+
COUNTRIES.IT; // 124 (tipo literal `124`)
|
|
173
|
+
getCountryIdByIso('IT'); // 124
|
|
174
|
+
getCountryIdByIso('it'); // 124 (ignora mayúsculas y espacios)
|
|
175
|
+
getCountryIdByIso('XX'); // undefined
|
|
176
|
+
getIsoByCountryId(124); // 'IT'
|
|
177
|
+
getIsoByCountryId('190'); // 'PT' (acepta el id como string, como en `countriesToRedirect`)
|
|
178
|
+
getIsoByCountryId(9999); // undefined (no existe)
|
|
179
|
+
|
|
180
|
+
// Filas sin ISO oficial propio: código propio (ver CUSTOM_ISO_COUNTRIES)
|
|
181
|
+
getCountryIdByIso('XM'); // 202 Rusia (Moscú y San Petersburgo)
|
|
182
|
+
getCountryIdByIso('QW'); // 254 Mundo
|
|
183
|
+
getIsoByCountryId(202); // 'XM'
|
|
184
|
+
|
|
185
|
+
// También aceptan listas
|
|
186
|
+
getCountryIdByIso(['IT', 'JP']); // [124, 127]
|
|
187
|
+
getIsoByCountryId([124, '127']); // ['IT', 'JP']
|
|
188
|
+
|
|
189
|
+
// Enum tipado en compilación:
|
|
190
|
+
const CountrySchema = z.enum(ISO_COUNTRY_CODES); // z.ZodEnum<'AD' | 'AE' | … | 'ZZ'>, los 266 códigos
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
| Export | Descripción |
|
|
194
|
+
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| `COUNTRIES` | `as const` código → `countryId` para las 266 filas (ISO oficiales + códigos propios). Biyectivo. |
|
|
196
|
+
| `IsoCountryCode` | `keyof typeof COUNTRIES` |
|
|
197
|
+
| `ISO_COUNTRY_CODES` | Tupla con todos los ISO, lista para `z.enum(...)` |
|
|
198
|
+
| `COUNTRY_CATALOG` | Listado completo (`{ id, iso, name }`); todas las filas tienen código |
|
|
199
|
+
| `getCountryIdByIso(iso)` | ISO → `countryId`, o `undefined`. También acepta una lista. Con `IsoCountryCode` devuelve `number` |
|
|
200
|
+
| `getIsoByCountryId(id)` | `countryId` (number o string) → ISO, o `undefined`. También acepta una lista |
|
|
201
|
+
| `getDestinationCountryId(countryIds, regionName)` | `countryId` de destino: el país si es uno, o su agrupación si son varios (ver abajo) |
|
|
202
|
+
| `isIsoCountryCode(value)` | Type guard |
|
|
203
|
+
| `CUSTOM_ISO_COUNTRIES` | Las 20 filas con código propio (`{ id, iso, kind, name }`) |
|
|
204
|
+
| `CustomIsoCountryCode` | Unión de esos códigos propios |
|
|
205
|
+
|
|
206
|
+
#### Destino: `getDestinationCountryId(countryIds, regionName)`
|
|
207
|
+
|
|
208
|
+
Resuelve el `countryId` de destino (`destiny_country`) a partir de los destinos seleccionados:
|
|
209
|
+
|
|
210
|
+
- **Un destino** (tras quitar repetidos): ese mismo `countryId`.
|
|
211
|
+
- **Varios destinos**: el `regionId` de la agrupación de `regionsToGroup` de la región con mayor prioridad (`high` → `medium` → `low`) que contenga alguno de ellos.
|
|
212
|
+
|
|
213
|
+
Devuelve `undefined` si no hay destinos, algún id no existe en el catálogo, la región no existe o ninguna agrupación contiene los destinos.
|
|
214
|
+
|
|
215
|
+
```ts
|
|
216
|
+
import { getCountryIdByIso, getDestinationCountryId } from 'regions-config';
|
|
217
|
+
|
|
218
|
+
getDestinationCountryId([124], 'es'); // 124 Italia
|
|
219
|
+
getDestinationCountryId(getCountryIdByIso(['FR', 'IT']), 'es'); // 259 Europa
|
|
220
|
+
getDestinationCountryId(getCountryIdByIso(['FR', 'TH']), 'es'); // 273 Mundo (excluido EEUU/Canadá/Japón)
|
|
221
|
+
getDestinationCountryId(getCountryIdByIso(['FR', 'JP']), 'es'); // 272 Mundo (incluido EEUU/Canadá/Japón)
|
|
222
|
+
getDestinationCountryId(getCountryIdByIso(['FR', 'US']), 'com/mx'); // 274 Estados Unidos, Canadá
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Las agrupaciones y sus prioridades dependen de la región (`regionsToGroup` de cada una), así que el mismo par de destinos puede dar ámbitos distintos según el site.
|
|
226
|
+
|
|
227
|
+
#### Códigos propios (`CUSTOM_ISO_COUNTRIES`)
|
|
228
|
+
|
|
229
|
+
Todas las filas del catálogo tienen código y `COUNTRIES` es biyectivo (266 códigos ↔ 266 ids), así que `getIsoByCountryId` y `getCountryIdByIso` son exactamente inversas.
|
|
230
|
+
|
|
231
|
+
Las 20 filas sin ISO 3166-1 oficial propio usan un código de los rangos que ISO reserva para uso privado (`QM`–`QZ`, `XA`–`XZ`, `ZZ`), salvo `CP`, que ISO reserva para Clipperton. **No cambiarlos una vez publicados.**
|
|
232
|
+
|
|
233
|
+
| Código | id | Nombre | `kind` |
|
|
234
|
+
| ------ | --- | ----------------------------------------- | ----------- |
|
|
235
|
+
| `XA` | 3 | Akrotiri (Santorini) | `territory` |
|
|
236
|
+
| `XD` | 62 | Dekelia | `territory` |
|
|
237
|
+
| `XH` | 18 | Islas Ashmore y Cartier | `territory` |
|
|
238
|
+
| `XC` | 55 | Territorio de las Islas del Mar del Coral | `territory` |
|
|
239
|
+
| `CP` | 51 | Isla Clipperton | `territory` |
|
|
240
|
+
| `XS` | 220 | Islas Spratly | `territory` |
|
|
241
|
+
| `XG` | 81 | Franja de Gaza | `territory` |
|
|
242
|
+
| `XB` | 253 | Cisjordania | `territory` |
|
|
243
|
+
| `XM` | 202 | Rusia (Moscú y San Petersburgo) | `territory` |
|
|
244
|
+
| `XJ` | 126 | Jan Mayen | `territory` |
|
|
245
|
+
| `XN` | 168 | Isla de Navaza | `territory` |
|
|
246
|
+
| `XW` | 251 | Isla Wake | `territory` |
|
|
247
|
+
| `XK` | 134 | Kosovo | `territory` |
|
|
248
|
+
| `XP` | 185 | Islas Paracelso | `territory` |
|
|
249
|
+
| `QW` | 254 | Mundo | `region` |
|
|
250
|
+
| `QU` | 259 | Europa | `region` |
|
|
251
|
+
| `QT` | 272 | Mundo (incluido EEUU/Canadá/Japón) | `region` |
|
|
252
|
+
| `QR` | 273 | Mundo (excluido EEUU/Canadá/Japón) | `region` |
|
|
253
|
+
| `QN` | 274 | Estados Unidos, Canadá | `region` |
|
|
254
|
+
| `ZZ` | 260 | Unknown | `unknown` |
|
|
255
|
+
|
|
256
|
+
#### Mantenimiento
|
|
257
|
+
|
|
258
|
+
`src/countries/countryCatalog.ts` se mantiene a mano. Para añadir un país, añade su fila a `COUNTRY_CATALOG` y:
|
|
259
|
+
|
|
260
|
+
- añade su entrada en `COUNTRIES`;
|
|
261
|
+
- si no tiene un ISO oficial propio (que no use otra fila), asígnale un código propio libre de los rangos de uso privado y añádelo también a `CUSTOM_ISO_COUNTRIES` con el `kind` que corresponda (una nueva agrupación de regiones va también en `GROUP_REGIONS`).
|
|
262
|
+
|
|
263
|
+
`pnpm validate` comprueba que todo sea coherente: ids y códigos sin repetir, `COUNTRIES` igual al catálogo, códigos de uso privado solo en `CUSTOM_ISO_COUNTRIES` y sus agrupaciones iguales a `GROUP_REGIONS`.
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
156
267
|
## Tipos principales
|
|
157
268
|
|
|
158
269
|
```ts
|
|
@@ -186,16 +297,23 @@ type RegionConfig = {
|
|
|
186
297
|
| `US_CANADA_COUNTRIES` | Array de IDs de EE.UU. y Canadá |
|
|
187
298
|
| `US_CANADA_JAPAN_COUNTRIES` | Array de IDs de EE.UU., Canadá y Japón |
|
|
188
299
|
| `WORLD_COUNTRIES` | Array de IDs del resto del mundo |
|
|
300
|
+
| `COUNTRIES` | ISO 3166-1 alpha-2 → `countryId` IATI |
|
|
301
|
+
| `COUNTRY_CATALOG` | Listado completo de países y zonas |
|
|
302
|
+
| `ISO_COUNTRY_CODES` | Todos los ISO del catálogo |
|
|
189
303
|
|
|
190
304
|
## Estructura del paquete
|
|
191
305
|
|
|
192
306
|
```
|
|
193
307
|
src/
|
|
194
308
|
├── const.ts # Constantes de países y grupos de regiones
|
|
309
|
+
├── countries/
|
|
310
|
+
│ ├── countryCatalog.ts # COUNTRY_CATALOG + COUNTRIES
|
|
311
|
+
│ └── index.ts
|
|
195
312
|
├── index.ts # Punto de entrada y re-exports
|
|
196
313
|
├── regionsConfig.ts # Construcción del objeto de configuración
|
|
197
314
|
├── domain/
|
|
198
|
-
│
|
|
315
|
+
│ ├── RegionConfigSchema.ts # Schema Zod y tipos TypeScript
|
|
316
|
+
│ └── CountryCatalogSchema.ts # Schemas Zod y tipos del catálogo de países
|
|
199
317
|
├── regions/
|
|
200
318
|
│ ├── es.json # Config España
|
|
201
319
|
│ ├── commx.json # Config México
|
|
@@ -207,6 +325,9 @@ src/
|
|
|
207
325
|
│ ├── compe.json # Config Perú
|
|
208
326
|
│ └── index.ts
|
|
209
327
|
├── utils/
|
|
328
|
+
│ ├── getCountryIdByIso.ts
|
|
329
|
+
│ ├── getDestinationCountryId.ts
|
|
330
|
+
│ ├── getIsoByCountryId.ts
|
|
210
331
|
│ ├── getRegionConfig.ts
|
|
211
332
|
│ ├── getRegionConfigById.ts
|
|
212
333
|
│ ├── getRegionConfigByRegionCode.ts
|
|
@@ -215,6 +336,8 @@ src/
|
|
|
215
336
|
│ └── resolveDocumentTypeOptions.ts
|
|
216
337
|
└── validators/
|
|
217
338
|
└── validateRegion.ts
|
|
339
|
+
scripts/
|
|
340
|
+
└── validate.ts # `pnpm validate`: regiones + catálogo de países
|
|
218
341
|
```
|
|
219
342
|
|
|
220
343
|
## Scripts
|
|
@@ -223,7 +346,7 @@ src/
|
|
|
223
346
|
# Compilar el paquete
|
|
224
347
|
pnpm build
|
|
225
348
|
|
|
226
|
-
# Validar la configuración de todas las regiones sin compilar
|
|
349
|
+
# Validar la configuración de todas las regiones y el catálogo de países sin compilar
|
|
227
350
|
pnpm validate
|
|
228
351
|
|
|
229
352
|
# Modo watch (desarrollo)
|
|
@@ -241,6 +364,11 @@ La configuración de cada región se valida con **Zod** (`RegionConfigSchema`) a
|
|
|
241
364
|
pnpm validate
|
|
242
365
|
```
|
|
243
366
|
|
|
244
|
-
Este script ejecuta `tsx
|
|
367
|
+
Este script ejecuta `tsx scripts/validate.ts`, que:
|
|
368
|
+
|
|
369
|
+
1. Recorre todas las regiones, las resuelve (reemplazando referencias a constantes de países) y las parsea contra `RegionConfigSchema`.
|
|
370
|
+
2. Valida el catálogo de países: forma de cada fila, ids y códigos sin repetir, `COUNTRIES` igual al catálogo, `CUSTOM_ISO_COUNTRIES` coherente y **todos** los `countryId` usados en la configuración (`GROUP_REGIONS`, `EUROPE_COUNTRIES`, `WORLD_COUNTRIES`…, `COUNTRIES_TO_REDIRECT`, y en cada región `countriesToRedirect`, `residenceCountries` y `regionsToGroup`) presentes en el catálogo.
|
|
371
|
+
|
|
372
|
+
Si algo falla, el proceso termina con un error que lista todos los problemas encontrados.
|
|
245
373
|
|
|
246
|
-
El script se ejecuta automáticamente antes de cada compilación (`pnpm build` internamente corre `pnpm validate &&
|
|
374
|
+
El script se ejecuta automáticamente antes de cada compilación (`pnpm build` internamente corre `pnpm validate && tsdown`), por lo que un build exitoso garantiza que toda la configuración es válida.
|