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 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
- │ └── RegionConfigSchema.ts # Schema Zod y tipos TypeScript
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 src/regionsConfig.ts`, que recorre todos los JSONs de región, los resuelve (reemplazando referencias a constantes de países) y los parsea contra el schema. Si algún JSON está mal formado o le falta algún campo requerido, el proceso termina con un error descriptivo.
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 && tsup`), por lo que un build exitoso garantiza que toda la configuración es válida.
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.