colombian-holidays
Version:
375 lines (309 loc) • 8.39 kB
Markdown
# Colombian Holidays 🎆
[](https://badge.fury.io/js/colombian-holidays)
[](https://codecov.io/gh/MauricioRobayo/colombian-holidays)
[](https://www.codefactor.io/repository/github/mauriciorobayo/colombian-holidays)
[](git@github.com:MauricioRobayo/colombian-holidays.git)
TypeScript module to calculate colombian holidays for any given year.
## Installation
To install as a dependency of your project:
```sh
npm install colombian-holidays
```
## Usage
The default export is a function to get all the holidays for a given year.
The `year` should be between 1583 and 4099 (see [Pascua](https://github.com/MauricioRobayo/pascua) package).
### CommonJS
```js
const colombianHolidays = require("colombian-holidays").default;
```
### ES6 Modules
```js
import colombianHolidays from "colombian-holidays";
```
You get a function that you can use to get the complete list of holidays for a given year:
```js
const colombianHolidays2015 = colombianHolidays({ year: 2015 });
```
# Examples
Get current year holidays
```sh
npm run ts-node examples/currentDate
```
Get next year holidays
```sh
npm run ts-node examples/nextYear
```
The content of the `colombianHolidays2015` variable will be the following array:
```js
[
{
date: "2015-01-01",
celebrationDate: "2015-01-01",
name: {
es: "Año Nuevo",
en: "New Year's day",
},
nextMonday: false,
},
{
date: "2015-01-06",
celebrationDate: "2015-01-12",
name: {
es: "Reyes Magos",
en: "Epiphany",
},
nextMonday: true,
},
{
date: "2015-03-19",
celebrationDate: "2015-03-23",
name: {
es: "San José",
en: "Saint Joseph's Day",
},
nextMonday: true,
},
{
date: "2015-04-02",
celebrationDate: "2015-04-02",
{ es: "Jueves Santo", en: "Maundy Thursday" },
nextMonday: false,
},
{
date: "2015-04-03",
celebrationDate: "2015-04-03",
{ es: "Viernes Santo", en: "Good Friday" },
nextMonday: false,
},
{
date: "2015-05-01",
celebrationDate: "2015-05-01",
name: {
es: "Día del Trabajo",
en: "Labour Day",
}
nextMonday: false,
},
{
date: "2015-05-14",
celebrationDate: "2015-05-18",
name: { es: "Ascensión del Señor", en: "Ascension of Jesus" },
nextMonday: true,
},
{
date: "2015-06-04",
celebrationDate: "2015-06-08",
name: { es: "Corpus Christi", en: "Corpus Christi" },
nextMonday: true,
},
{
date: "2015-06-12",
celebrationDate: "2015-06-15",
name: { es: "Sagrado Corazón de Jesús", en: "Sacred Heart" },
nextMonday: true,
},
{
date: "2015-06-29",
celebrationDate: "2015-06-29",
name: {
es: "San Pedro y San Pablo",
en: "Saint Peter and Saint Paul",
},
nextMonday: true,
},
{
date: "2015-07-20",
celebrationDate: "2015-07-20",
name: {
es: "Grito de la Independencia",
en: "Declaration of Independence",
},
nextMonday: false,
},
{
date: "2015-08-07",
celebrationDate: "2015-08-07",
name: {
es: "Batalla de Boyacá",
en: "Battle of Boyacá",
},
nextMonday: false,
},
{
date: "2015-08-15",
celebrationDate: "2015-08-17",
name: {
es: "Asunción de la Virgen",
en: "Assumption of Mary",
},
nextMonday: true,
},
{
date: "2015-10-12",
celebrationDate: "2015-10-12",
name: {
es: "Día de la Raza",
en: "Columbus Day",
},
nextMonday: true,
},
{
date: "2015-11-01",
celebrationDate: "2015-11-02",
name: {
es: "Todos los Santos",
en: "All Saints’ Day",
},
nextMonday: true,
},
{
date: "2015-11-11",
celebrationDate: "2015-11-16",
name: { es: "Independencia de Cartagena", en: "Independence of Cartagena" },
nextMonday: true,
},
{
date: "2015-12-08",
celebrationDate: "2015-12-08",
name: { es: "Inmaculada Concepción", en: "Immaculate Conception" },
nextMonday: false,
},
{
date: "2015-12-25",
celebrationDate: "2015-12-25",
name: { es: "Navidad", en: "Christmas" },
nextMonday: false,
},
];
```
Optionally, you can request the holidays for just a given month:
```js
const colombianHolidays2015 = colombianHolidays({
year: 2015,
month: 1 /* January */,
});
```
Returns:
```js
[
{
date: "2015-01-01",
celebrationDate: "2015-01-01",
name: {
es: "Año Nuevo",
en: "New Year's day",
},
nextMonday: false,
},
{
date: "2015-01-06",
celebrationDate: "2015-01-12",
name: {
es: "Reyes Magos",
en: "Epiphany",
},
nextMonday: true,
},
];
```
Run the previous example
```sh
npm run ts-node examples/monthHolidays
```
You can opt-in to have the function return native JavaScript dates instead of strings for the `date` and `celebrationDate` properties by using the `valueAsDate` option:
```js
const colombianHolidays2015 = colombianHolidays({
year: 2015,
valueAsDate: true,
});
```
If the year is omitted, by default the function will return the holidays for the current year:
```js
const currentYearHolidaysAsStrings = colombianHolidays();
const currentYearHolidaysAsDates = colombianHolidays({ valueAsDate: true });
```
## Utils
The package provides four helper functions:
### getHolidaysByYear
Returns the list of all Colombian holidays for a given year.
```js
import { getHolidaysByYear } from "colombian-holidays";
const holidays = getHolidaysByYear(2025);
```
You can also pass the `valueAsDate` option to return native JavaScript `Date` objects instead of ISO strings:
```js
const holidaysAsDates = getHolidaysByYear(2025, { valueAsDate: true });
```
This function is equivalent to calling:
```js
colombianHolidays({ year: 2025 });
```
But uses an in-memory cache.
> [!TIP]
> Use `getHolidaysByYear` instead of `colombianHolidays` when possible. It includes built-in caching, which improves performance and avoids redundant computations when accessing holidays by year. It is used under the hood by all other helpers, providing a shared in-memory cache.
### isHoliday
Returns `true` if the given date is a colombian holiday, otherwise returns `false`.
```js
import { isHoliday } from "colombian-holidays";
const date = new Date("2018-01-01");
if (isHoliday(date)) {
console.log("it is a colombian holiday");
} else {
console.log("it is NOT a colombian holiday");
}
```
### getHoliday
Similar to `isHoliday` but will return the corresponding holiday for a given date or `null` if there is no matching holiday.
```js
import { getHoliday } from "colombian-holidays";
const date = new Date("2018-01-01");
const newYear = getHoliday(date);
/*
{
celebrationDate: "2018-01-01",
date: "2018-01-01",
name: { en: "New Year's Day", es: "Año Nuevo" },
nextMonday: false,
}
*/
```
To get the values as date use the options argument:
```js
const newYearAsDate = getHoliday(date, { valueAsDate: true });
```
### holidaysWithinInterval
Returns an array with the colombian holidays within two dates:
```js
import { holidaysWithinInterval } from "colombian-holidays";
const start = new Date("2021-01-01");
const end = new Date("2021-01-11");
const holidays = holidaysWithinInterval({ start, end });
// const holidays = holidaysWithinInterval({ start, end, valueAsDate: true });
```
returns:
```js
[
{
celebrationDate: "2021-01-01",
date: "2021-01-01",
name: {
es: "Año Nuevo",
en: "New Year's day",
},
nextMonday: false,
},
{
celebrationDate: "2021-01-11",
date: "2021-01-06",
name: {
es: "Reyes Magos",
en: "Epiphany",
},
nextMonday: true,
},
];
```
### TypeScript
The module is written in TypeScript and type definitions files are included.
## License
[](https://app.fossa.com/projects/git%2Bgithub.com%2FMauricioRobayo%2Fcolombian-holidays?ref=badge_large)