es-regional-holidays 0.1.2 → 0.2.0

package/README.es.md

@@ -0,0 +1,156 @@
+# es-regional-holidays
+
+es-regional-holidays es una librería ligera, TypeScript-first, que proporciona los festivos oficiales en España por año y comunidad autónoma, con soporte opcional para festivos locales (municipales).
+
+Es agnóstica al framework y funciona con React, Angular, Vue y Node.js puro.
+
+## Características
+
+- Festivos nacionales, autonómicos y locales (municipales)
+- Un único dataset normalizado por año
+- Datos opcionales a nivel de provincia y municipio
+- Totalmente tipada con TypeScript
+- Compatible con bundlers modernos (ESM y CJS)
+- Cero dependencias en tiempo de ejecución
+
+## Instalación
+
+El paquete está disponible en npm.
+
+Usando npm:
+npm install es-regional-holidays
+
+Usando yarn:
+yarn add es-regional-holidays
+
+Usando pnpm:
+pnpm add es-regional-holidays
+
+## Uso
+
+### Obtener todos los festivos de una comunidad
+
+Devuelve los festivos **nacionales + autonómicos + locales** para una comunidad y un año.
+
+```ts
+import { getAllHolidaysByRegionCode } from "es-regional-holidays";
+
+const holidays = getAllHolidaysByRegionCode("CN", 2026);
+```
+
+Ejemplo de resultado:
+
+```ts
+[
+  { date: "2026-01-01", name: "Año Nuevo", scope: "national" },
+  { date: "2026-01-06", name: "Epifanía del Señor", scope: "regional", region: "CN" },
+  { date: "2026-05-30", name: "Día de Canarias", scope: "regional", region: "CN" }
+]
+```
+
+### Solo festivos nacionales
+
+```ts
+import { getNationalHolidays } from "es-regional-holidays";
+
+const national = getNationalHolidays(2026);
+```
+
+### Solo festivos autonómicos
+
+```ts
+import { getRegionalHolidaysByRegionCode } from "es-regional-holidays";
+
+const regional = getRegionalHolidaysByRegionCode("MD", 2026);
+```
+
+### Festivos locales (municipales)
+
+```ts
+import { getLocalHolidaysByProvince } from "es-regional-holidays";
+
+const valenciaLocal = getLocalHolidaysByProvince("VC", "Valencia", 2026);
+```
+
+### Comprobar si una fecha es festivo
+
+```ts
+import { isHoliday } from "es-regional-holidays";
+
+isHoliday("2026-01-01");           // true (nacional)
+isHoliday("2026-05-30", "CN");     // true (autonómico)
+isHoliday("2026-05-30", "MD");     // false
+```
+
+Acepta tanto strings `YYYY-MM-DD` como objetos `Date`.
+
+### Comprobar solo festivos locales
+
+```ts
+import { isLocalHoliday } from "es-regional-holidays";
+
+isLocalHoliday("2026-01-22", "VC", "Valencia", "VALENCIA");
+```
+
+### Listar comunidades soportadas
+
+```ts
+import { getAllRegions } from "es-regional-holidays";
+
+const regions = getAllRegions(2026);
+```
+
+Los códigos de comunidad siguen las abreviaturas oficiales del BOE.
+
+## Modelo de datos
+
+```ts
+export interface Holiday {
+  date: string;
+  name: string;
+  scope: "national" | "regional" | "local";
+  region?: string;
+  regionName?: string;
+  province?: string;
+  locality?: string;
+}
+```
+
+## Clasificación nacional vs autonómica
+
+La clasificación de festivos sigue la práctica administrativa real, no solo el origen legal.
+
+En el BOE, los festivos se marcan como:
+- `*` -> Festivo nacional no sustituible
+- `**` -> Festivo nacional sustituible por la comunidad autónoma
+- `***` -> Festivo autonómico
+
+En esta librería se exponen como:
+- `*` -> Nacional
+- `**` -> Autonómico
+- `***` -> Autonómico
+
+Algunos festivos son de origen nacional pero están gestionados por las comunidades autónomas. Para reflejar los calendarios reales, estos festivos se exponen como autonómicos en la API.
+
+## Fuente de datos
+
+Los datos se obtienen principalmente del calendario oficial de la Seguridad Social y se contrastan con la resolución anual publicada en el BOE.
+Por ejemplo, BOE-A-2025-21667 para el año 2026.
+
+Los datos en bruto se conservan internamente para trazabilidad y reproducibilidad.
+
+## Años soportados
+
+- 2026
+
+Se añadirán más años de forma incremental.
+
+## Licencia
+
+MIT License  
+Copyright (c) Juan Melo
+
+## Contribuir
+
+Issues y pull requests son bienvenidos.  
+El objetivo del proyecto es mantenerse pequeño, predecible y sin dependencias.

package/README.md

@@ -1,16 +1,17 @@
 # es-regional-holidays
 
-es-regional-holidays is a lightweight, TypeScript-first library that provides official public holidays in Spain by year and autonomous community, based on data published in the Boletín Oficial del Estado (BOE).
+es-regional-holidays is a lightweight, TypeScript-first library that provides official public holidays in Spain by year and autonomous community, with optional support for local (municipal) holidays.
 
-The library is framework-agnostic and can be used with React, Angular, Vue, or plain Node.js projects.
+It is framework-agnostic and works with React, Angular, Vue, and plain Node.js.
 
 ## Features
 
-- Official holiday data sourced from the BOE
-- Clear distinction between national and regional holidays
-- Zero runtime dependencies
+- National, regional, and local (municipal) holidays
+- Single normalized dataset per year
+- Optional province and locality-level data
 - Fully typed with TypeScript
 - Compatible with modern bundlers (ESM and CJS)
+- Zero runtime dependencies
 
 ## Installation
 
@@ -25,11 +26,11 @@ yarn add es-regional-holidays
 Using pnpm:
 pnpm add es-regional-holidays
 
-## Basic usage
+## Usage
 
 ### Get all holidays for a region
 
-Returns all applicable holidays for a given region and year, including national common holidays and region-managed holidays.
+Returns **national + regional + local** holidays for a region and year.
 
 ```ts
 import { getAllHolidaysByRegionCode } from "es-regional-holidays";
@@ -47,53 +48,71 @@ Example result:
 ]
 ```
 
-## Check if a date is a holiday
+### National holidays only
 
 ```ts
-import { isHoliday } from "es-regional-holidays";
+import { getNationalHolidays } from "es-regional-holidays";
+
+const national = getNationalHolidays(2026);
+```
+
+### Regional holidays only
+
+```ts
+import { getRegionalHolidaysByRegionCode } from "es-regional-holidays";
 
-isHoliday("2026-05-30", "CN");
-isHoliday("2026-05-30", "MD");
+const regional = getRegionalHolidaysByRegionCode("MD", 2026);
 ```
 
-The function accepts both YYYY-MM-DD strings and Date objects.
+### Local (municipal) holidays
+
+```ts
+import { getLocalHolidaysByProvince } from "es-regional-holidays";
+
+const valenciaLocal = getLocalHolidaysByProvince("VC", "Valencia", 2026);
+```
 
-## National holidays only
+### Check if a date is a holiday
 
 ```ts
-import { getNationalHolidays } from "es-regional-holidays";
+import { isHoliday } from "es-regional-holidays";
 
-const nationalHolidays = getNationalHolidays(2026);
+isHoliday("2026-01-01");           // true (national)
+isHoliday("2026-05-30", "CN");     // true (regional)
+isHoliday("2026-05-30", "MD");     // false
 ```
 
-## Regional holidays only
+Accepts both `YYYY-MM-DD` strings and `Date` objects.
+
+### Check local holidays only
 
 ```ts
-import { getRegionalHolidaysByRegionCode } from "es-regional-holidays";
+import { isLocalHoliday } from "es-regional-holidays";
 
-const regionalHolidays = getRegionalHolidaysByRegionCode("MD", 2026);
+isLocalHoliday("2026-01-22", "VC", "Valencia", "VALENCIA");
 ```
 
-## List supported regions
+### List supported regions
 
 ```ts
-import { getRegions } from "es-regional-holidays";
+import { getAllRegions } from "es-regional-holidays";
 
-const regions = getRegions();
+const regions = getAllRegions(2026);
 ```
 
-Region codes follow the official BOE abbreviations.
+Region codes follow official BOE abbreviations.
 
-## Holiday data model
+## Data model
 
 ```ts
 export interface Holiday {
   date: string;
   name: string;
+  scope: "national" | "regional" | "local";
   region?: string;
   regionName?: string;
-  scope: "national" | "regional";
-  source?: string;
+  province?: string;
+  locality?: string;
 }
 ```
 

package/dist/index.d.mts

@@ -1,43 +1,61 @@
 type RegionCode = "AN" | "AR" | "AS" | "CB" | "CE" | "CL" | "CM" | "CN" | "CT" | "EX" | "GA" | "IB" | "MC" | "MD" | "ML" | "NC" | "PV" | "RI" | "VC";
-type HolidayScope = "national" | "regional";
+type HolidayScope = "national" | "regional" | "local";
+/** Entry as stored in the source dataset */
+interface HolidayEntry {
+    date: string;
+    name: string;
+}
+/** Resolved holiday returned by the API */
 interface Holiday {
-    /** ISO date: YYYY-MM-DD */
     date: string;
-    /** Holiday name in Spanish (as in BOE) */
     name: string;
-    /** Region code if scoped to a region (e.g. "CN"). */
+    scope: HolidayScope;
     region?: RegionCode;
-    /** Region name (e.g. "Canarias") */
     regionName?: string;
-    /** "national" = common to all regions. "regional" = chosen/managed by the region. */
-    scope: HolidayScope;
-    /** BOE id (useful for traceability) */
-    source?: string;
+    province?: string;
+    locality?: string;
 }
+/** Local holidays grouped by province */
+interface ProvinceSource {
+    localities: Record<string, HolidayEntry[]>;
+}
+/** Region source data */
+interface RegionSource {
+    regionName: string;
+    regional: HolidayEntry[];
+    provinces?: Record<string, ProvinceSource>;
+}
+/** Source dataset for a given year */
 interface HolidaysDataset {
-    source: string;
     year: number;
     generated_at?: string;
-    national: Array<{
-        date: string;
-        name: string;
-        scope: "national";
-    }>;
-    regions: Record<RegionCode, {
-        regionName: string;
-        regional: Array<{
-            date: string;
-            name: string;
-            scope: "regional";
-        }>;
-    }>;
+    national: HolidayEntry[];
+    regions: Record<RegionCode, RegionSource>;
 }
 
 declare function getAllHolidays(year?: number): Holiday[];
 declare function getNationalHolidays(year?: number): Holiday[];
 declare function getRegionalHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
-declare function getAllHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
+/**
+ * Local holidays for a region (resolved from provinces/localities)
+ */
+declare function getLocalHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
+/**
+ * Local holidays filtered by province (province key as stored in the dataset).
+ */
+declare function getLocalHolidaysByProvince(region: RegionCode, province: string, year?: number): Holiday[];
+/**
+ * Checks if a date is a holiday in Spain.
+ * - Without region: checks only national holidays.
+ * - With region: checks national + regional + local holidays for that region.
+ */
 declare function isHoliday(date: string | Date, region?: RegionCode, year?: number): boolean;
+/**
+ * Checks if a date is a LOCAL (municipal) holiday.
+ * Province and locality must match the dataset keys exactly.
+ */
+declare function isLocalHoliday(date: string | Date, region: RegionCode, province: string, locality: string, year?: number): boolean;
+declare function getAllHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
 declare function getAllRegions(year?: number): RegionCode[];
 
-export { type Holiday, type HolidaysDataset, type RegionCode, getAllHolidays, getAllHolidaysByRegionCode, getAllRegions, getNationalHolidays, getRegionalHolidaysByRegionCode, isHoliday };
+export { type Holiday, type HolidaysDataset, type RegionCode, getAllHolidays, getAllHolidaysByRegionCode, getAllRegions, getLocalHolidaysByProvince, getLocalHolidaysByRegionCode, getNationalHolidays, getRegionalHolidaysByRegionCode, isHoliday, isLocalHoliday };

package/dist/index.d.ts

@@ -1,43 +1,61 @@
 type RegionCode = "AN" | "AR" | "AS" | "CB" | "CE" | "CL" | "CM" | "CN" | "CT" | "EX" | "GA" | "IB" | "MC" | "MD" | "ML" | "NC" | "PV" | "RI" | "VC";
-type HolidayScope = "national" | "regional";
+type HolidayScope = "national" | "regional" | "local";
+/** Entry as stored in the source dataset */
+interface HolidayEntry {
+    date: string;
+    name: string;
+}
+/** Resolved holiday returned by the API */
 interface Holiday {
-    /** ISO date: YYYY-MM-DD */
     date: string;
-    /** Holiday name in Spanish (as in BOE) */
     name: string;
-    /** Region code if scoped to a region (e.g. "CN"). */
+    scope: HolidayScope;
     region?: RegionCode;
-    /** Region name (e.g. "Canarias") */
     regionName?: string;
-    /** "national" = common to all regions. "regional" = chosen/managed by the region. */
-    scope: HolidayScope;
-    /** BOE id (useful for traceability) */
-    source?: string;
+    province?: string;
+    locality?: string;
 }
+/** Local holidays grouped by province */
+interface ProvinceSource {
+    localities: Record<string, HolidayEntry[]>;
+}
+/** Region source data */
+interface RegionSource {
+    regionName: string;
+    regional: HolidayEntry[];
+    provinces?: Record<string, ProvinceSource>;
+}
+/** Source dataset for a given year */
 interface HolidaysDataset {
-    source: string;
     year: number;
     generated_at?: string;
-    national: Array<{
-        date: string;
-        name: string;
-        scope: "national";
-    }>;
-    regions: Record<RegionCode, {
-        regionName: string;
-        regional: Array<{
-            date: string;
-            name: string;
-            scope: "regional";
-        }>;
-    }>;
+    national: HolidayEntry[];
+    regions: Record<RegionCode, RegionSource>;
 }
 
 declare function getAllHolidays(year?: number): Holiday[];
 declare function getNationalHolidays(year?: number): Holiday[];
 declare function getRegionalHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
-declare function getAllHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
+/**
+ * Local holidays for a region (resolved from provinces/localities)
+ */
+declare function getLocalHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
+/**
+ * Local holidays filtered by province (province key as stored in the dataset).
+ */
+declare function getLocalHolidaysByProvince(region: RegionCode, province: string, year?: number): Holiday[];
+/**
+ * Checks if a date is a holiday in Spain.
+ * - Without region: checks only national holidays.
+ * - With region: checks national + regional + local holidays for that region.
+ */
 declare function isHoliday(date: string | Date, region?: RegionCode, year?: number): boolean;
+/**
+ * Checks if a date is a LOCAL (municipal) holiday.
+ * Province and locality must match the dataset keys exactly.
+ */
+declare function isLocalHoliday(date: string | Date, region: RegionCode, province: string, locality: string, year?: number): boolean;
+declare function getAllHolidaysByRegionCode(region: RegionCode, year?: number): Holiday[];
 declare function getAllRegions(year?: number): RegionCode[];
 
-export { type Holiday, type HolidaysDataset, type RegionCode, getAllHolidays, getAllHolidaysByRegionCode, getAllRegions, getNationalHolidays, getRegionalHolidaysByRegionCode, isHoliday };
+export { type Holiday, type HolidaysDataset, type RegionCode, getAllHolidays, getAllHolidaysByRegionCode, getAllRegions, getLocalHolidaysByProvince, getLocalHolidaysByRegionCode, getNationalHolidays, getRegionalHolidaysByRegionCode, isHoliday, isLocalHoliday };