Dates and holidays

Add business days

• JavaScript library
• Python library
• Go library
• Ruby library
• Rust library
• .NET library
• Erlang library

Adds a number of Brazilian business days (dias úteis) to a date. It walks one calendar day at a time and counts only the days date.isBusinessDay accepts with the same options.

• Returns a new date and keeps the time of day. The function never changes the input. When the result day does not have that time (a daylight saving jump), the result is the nearest instant of that day.
• An amount of 0 returns the same date, even on a non-business day. A negative amount walks backwards.
• options.includeOptional (default true) counts the optional holidays (Carnaval Monday and Tuesday, Corpus Christi) as non-business days. With false, only national and state holidays count, so Corpus Christi still counts in DF, in MA from 2024 and in RJ from 2026, where it is a state holiday.
• options.includeSaturday (default false) counts Saturday as a business day, the labor law count of the payroll deadline (CLT art. 459 § 1º, read through IN MTP nº 2/2021, art. 14, I). Sunday and holidays stay excluded, including a holiday on a Saturday (Finados 2024-11-02, Independência 2024-09-07).
• includeSaturday does not cover municipal holidays, which the IN also excludes. An exact count for a municipality has to remove them separately. The option name does not promise "CLT" for that reason.
• A truthy value that is not a boolean (for example "false") turns includeSaturday or includeOptional on.
• options.stateCode is read ignoring case and surrounding whitespace, as in every state util: "sp" and " SP " add the holidays of São Paulo. Only an omitted (undefined) stateCode means national holidays only.
• A stateCode that is present and is not a state code ("XX", "", "__proto__", a number, null, an object) is rejected: the function returns null without looking at the date. 2.4.0 silently fell back to the national holidays for an unknown or lowercase code, so "sp" counted 9 July as a business day in São Paulo.
• Returns null for an invalid date, an amount that is not a finite integer, or a start or result outside the years 1900 to 2099.
• The walk always ends. 2.4.0 could loop forever in time zones where a local day does not exist (Pacific/Apia and Pacific/Fakaofo on 2011-12-30, Pacific/Kiritimati and Pacific/Enderbury on 1994-12-31, Pacific/Kwajalein on 1993-08-21); the walk now skips that day. The half-hour shift of Australia/Lord_Howe was fixed too. Other results are unchanged.

Recipes (no dedicated helper exists):

• Next business day: addBusinessDays(d, 1).
• N-th business day of a month: addBusinessDays(new Date(y, m, 0), n), starting from the last day of the previous month. When n is larger than the month's business days, the result falls in the next month; check its month.
• Last business day of a month: subBusinessDays(new Date(y, m + 1, 1), 1), starting from the first day of the next month.
• Edges: the n-th business day of January 1900 and the last business day of December 2099 return null, because the starting day is outside 1900 to 2099.
• With { includeSaturday: true } the same recipe gives the labor law "quinto dia útil": addBusinessDays(new Date(2024, 2, 0), 5, { includeSaturday: true }) is Wednesday 2024-03-06, while the banking count without the option is Thursday 2024-03-07.

import { addBusinessDays } from '@brazilian-utils/brazilian-utils';

addBusinessDays(new Date(2024, 0, 2, 12), 1); // Date, 2024-01-03 12:00 (next day is already a business day)
addBusinessDays(new Date(2024, 11, 31, 12), 1); // Date, 2025-01-02 12:00 (2025-01-01 is Ano novo, skipped)
addBusinessDays(new Date(2024, 0, 5, 12), -1); // Date, 2024-01-04 12:00 (walks backwards)
addBusinessDays(new Date(2024, 0, 6, 12), 0); // Date, 2024-01-06 12:00 (unchanged, even though Saturday is not a business day)
addBusinessDays(new Date(2024, 0, 5, 12), 1, { includeSaturday: true }); // Date, 2024-01-06 12:00 (labour law count, Saturday counts)
addBusinessDays(new Date(2024, 10, 1, 12), 1, { includeSaturday: true }); // Date, 2024-11-04 12:00 (2024-11-02 is Finados, a holiday on a Saturday)
addBusinessDays(new Date(2024, 6, 8, 12), 1, { stateCode: 'SP' }); // Date, 2024-07-10 12:00 (2024-07-09 is Revolução Constitucionalista in SP, skipped)
addBusinessDays(new Date('not a date'), 1); // null
addBusinessDays(new Date(2024, 0, 2), 1.5); // null (not an integer)

Write out in words

• JavaScript library
• Python library32 cases fail
• Go library2 cases fail
• Ruby library4 cases fail
• Rust library
• .NET library1 case fails
• Erlang library

Writes a date in Brazilian Portuguese words ("por extenso"), such as "primeiro de janeiro de dois mil e vinte e quatro".

• value is a date (its local calendar date) or a string dd/mm/yyyy or ISO yyyy-mm-dd.
• options.style (default "full") spells out the day, the month and the year ("dois de março de dois mil e vinte e quatro"). "month" spells out only the month and leaves the day and the year as digits ("2 de março de 2024"), with day 1 as 1º ("1º de janeiro de 2024"). Any other value is ignored and "full" is used.
• options.weekday (default false) puts the weekday name in lowercase and a comma in front ("sábado, dois de março de dois mil e vinte e quatro"). The weekday comes from the resolved calendar date: the local date of a date value, or the parsed date of a string. It combines with either style.
• style and weekday are read strictly: only "month" and only true change the output. "true" or 1 for weekday do nothing.
• Day 1 is "primeiro" in the full style.
• In the full style the year is written as number.convertToWords writes it (1999 is "mil novecentos e noventa e nove", 2000 is "dois mil"). The result is always lowercase.
• February 29th is accepted only on leap years of the proleptic Gregorian calendar (divisible by 4, except centuries not divisible by 400). A string must match dd/mm/yyyy or yyyy-mm-dd exactly, with no other characters around it.

import { convertDateToWords } from '@brazilian-utils/brazilian-utils';

convertDateToWords('01/01/2024'); // "primeiro de janeiro de dois mil e vinte e quatro"
convertDateToWords('2024-01-02'); // "dois de janeiro de dois mil e vinte e quatro"
convertDateToWords(new Date(2024, 0, 1)); // "primeiro de janeiro de dois mil e vinte e quatro"
convertDateToWords('02/03/2024', { style: 'month' }); // "2 de março de 2024"
convertDateToWords('01/01/2024', { style: 'month' }); // "1º de janeiro de 2024"
convertDateToWords('02/03/2024', { weekday: true }); // "sábado, dois de março de dois mil e vinte e quatro"
convertDateToWords('10/05/1999'); // "dez de maio de mil novecentos e noventa e nove"
convertDateToWords('31/04/2024'); // "" (April has 30 days)
convertDateToWords('invalid'); // ""
convertDateToWords('29/02/1900'); // "" (1900 is not a leap year)

Difference in business days

• JavaScript library
• Python library
• Go library
• Ruby library
• Rust library
• .NET library
• Erlang library

Counts the Brazilian business days between two dates.

• Counts earlierDate when it is a business day, and every business day strictly between the two. It never counts laterDate. The time of day is ignored.
• The result is negative when laterDate is before earlierDate, and 0 on the same calendar day.
• options as in date.addBusinessDays: includeOptional, includeSaturday and stateCode. With { includeSaturday: true }, 2024-01-01 to 2024-01-08 gives 5 (1 January is a holiday, Sunday is excluded).
• Returns null when either date is invalid or outside the years 1900 to 2099, and when options.stateCode is present and is not a state code (2.4.0 fell back to national holidays).

import { differenceInBusinessDays } from '@brazilian-utils/brazilian-utils';

differenceInBusinessDays(new Date(2024, 0, 2), new Date(2024, 0, 1)); // 0 (Jan 1 is Ano novo, not counted)
differenceInBusinessDays(new Date(2024, 0, 3), new Date(2024, 0, 2)); // 1 (Jan 2 counted, a Tuesday; Jan 3 is not)
differenceInBusinessDays(new Date(2024, 0, 2), new Date(2024, 0, 3)); // -1 (the later date comes first, so the count is negative)
differenceInBusinessDays(new Date(2024, 0, 2), new Date(2024, 0, 2)); // 0 (same day)
differenceInBusinessDays(new Date(2024, 0, 8), new Date(2024, 0, 1)); // 4 (Monday to Friday count, 2024-01-02 to 2024-01-05)
differenceInBusinessDays(new Date(2024, 0, 8), new Date(2024, 0, 1), { includeSaturday: true }); // 5 (2024-01-06, a Saturday, also counts)
differenceInBusinessDays(new Date(2024, 10, 4), new Date(2024, 10, 1), { includeSaturday: true }); // 1 (2024-11-02 is Finados, a holiday on a Saturday)
differenceInBusinessDays(new Date(2024, 6, 10), new Date(2024, 6, 8), { stateCode: 'SP' }); // 1 (2024-07-09 is a state holiday in SP)
differenceInBusinessDays(new Date(), new Date('not a date')); // null

Get holidays

• JavaScript library
• Python library
• Go library8 cases fail
• Ruby library
• Rust library
• .NET library8 cases fail
• Erlang library

Returns the Brazilian holidays of a year, sorted by date: the national ones, plus those of one state when stateCode is given.

• options is { year, stateCode? }. JavaScript also accepts a bare year, getHolidays(2024), for the national holidays.
• Each holiday has a name, a date and a type: national, state, optional (ponto facultativo) or religious (Páscoa, listed for convenience; no norm declares it).
• stateCode is read ignoring case and surrounding whitespace, as in every state util. Only an omitted (undefined) stateCode means national holidays only.
• A stateCode that is present and is not a state code ("XX", "", "__proto__", a number, null, an object) returns an empty list. 2.4.0 returned the national holidays for it, so { year: 2024, stateCode: "sp" } left out the São Paulo holidays.
• Returns an empty list when year is not an integer from 1900 to 2099.
• Each holiday appears only in the years its norm was in force:
  • Fixed national holidays appear only in the years a federal norm declared them. Finados appears up to 1948 and from 2003 on, not from 1949 to 2002 (2.4.0 listed it every year). Nossa Senhora Aparecida appears from 1980. Dia da Consciência Negra (20 November) is national from 2024.
  • Natal appears from 1922, Dia do trabalhador from 1925, and Tiradentes up to 1930, from 1933 to 1948 and from 1951. Lei nº 662/1949 left Finados out of the national holidays Decreto-lei nº 486/1938 listed, and Lei nº 10.607/2002 put it back. The other national festivals of the first republican calendar (24 February, 3 May, 13 May, 14 July and 12 October) are listed up to 1930, and 3 May (1936 to 1938), 16 July and 12 October (1936 and 1937) again under Lei nº 108/1935.
  • State holidays appear from the year their law took effect, and up to the year it was revoked.
• Sexta-feira Santa is national every year. Carnaval Monday and Tuesday and Corpus Christi are optional, the pontos facultativos of the federal calendar (2.4.0 did not list the Monday).
• The optional entries are the whole-day pontos facultativos of the federal calendar (Portarias MGI nº 8.617/2023, 9.783/2024 and 11.460/2025, for 2024 to 2026): Carnaval Monday and Tuesday and Corpus Christi, the same three days the financial market skips (Resolução CMN nº 4.880/2020), plus the ones a state norm declares (AM's 8 December from 1999, PE's 6 March of 2008 and 2009). The partial ones are left out: Quarta-feira de Cinzas (until 14h), 28 October (Dia do Servidor Público) and the afternoons of 24 and 31 December.
• The first round of the elections is a national holiday: the first Sunday of October in even years from 1998 on (15 November in 2020), under art. 380 of the Código Eleitoral. The second round is not listed.
• Before 1998, Lei nº 1.266/1950 made the day of the general elections a national holiday, so the ones held on a weekday are listed too: 3 October of 1955 and 1958 (Eleições gerais) and of 1990 and 1994 (Eleições (primeiro turno)). 3 October 1960 and the municipal election of 3 October 1996 are not listed. Being a Sunday, the election day never changes a business day count.
• A state entry with the same name and date as a national one replaces it. Corpus Christi is typed state in DF, in MA from 2024 and in RJ from 2026, and stays an optional federal ponto facultativo elsewhere. The Carnaval Tuesday is a state holiday in RJ from 2009.
• Two observance shifts move a state date. Alagoas' 30 November goes back to Monday when it falls on a Tuesday and on to Friday when it falls on a Thursday (from 2014, Lei AL nº 7.530/2013). Santa Catarina's 11 August (from 2005) and 25 November (from 1999) each move to the following Sunday when they fall Monday to Saturday. Pernambuco's data magna falls on the first Sunday of March from 2010 to 2017 and on 6 March from 2018.
• A state law the STF struck down has no entry in any year: Rondônia's 18 June (ADI 3940) and Amapá's 25 July (ADI 4820).
• Goiás lists 26/07, 24/10 and 28/10 as the feriados estaduais of the state servants' statute, from 1986, and 2 November as a Goiás holiday from 1986 to 2002, the years Finados was not national. Alagoas' 16/09 is a state holiday from 2011 (2.4.0 typed it optional up to 2023).
• Changes in 2.5.0, each from the state norm cited in the JavaScript source:
  • RJ: Corpus Christi from 2026 (Lei RJ nº 11.002/2025, upheld by the STF in ADI 7898, final on 13/08/2026). 2.4.0 typed it optional, as in every other state.
  • AL: 20/11 from 1995 to 2023; 30/11 from 2014 (moved to Monday when it falls on a Tuesday and to Friday when it falls on a Thursday).
  • AC: 20/01 from 2017. AP: 20/11 from 2008 to 2023; 15/05 from 2018. AP's 25/07 has no entry in any year (see below).
  • MA: Corpus Christi from 2024; 08/03 from 2027. PB: 05/08 from 1968.
  • SE: 08/07 from 1990; 24/10 from 1989 to 1999. PR: 19/12 from 1963 to 2013 (Lei PR 4.658/1962, revoked by Lei PR 18.384/2014).
  • PE: 06/03 in 2008 and 2009 as optional (Lei PE 13.386/2007). AM: 08/12 as optional from 1999 (the state declares it a ponto facultativo in its offices by decree, DOE-AM of 02/12/2025; the earliest norm located is Lei Municipal de Manaus nº 496/1999). 2.4.0 listed it from 1900.
• Returns an empty list when the argument is neither a number nor an object.
• Municipal holidays are not covered.
• One-year moves made by decree are not applied; the table keeps the statutory date. Examples: Decreto GO nº 10.935/2026 moved 26/07/2026 to 20/07, and Goiás moved 28/10/2026 to 30/10.
• Also not applied: Acre's law that moves the holidays falling Tuesday to Thursday to the Friday (Lei AC nº 2.126/2009), because the state's own yearly decrees apply it unevenly (2026 moves 20/01 and leaves 17/11, a Tuesday, in place).

import { getHolidays } from '@brazilian-utils/brazilian-utils';

// Get the holidays of 2024, national and optional ones
getHolidays(2024);
// [
//   { name: 'Ano novo', date: Date('2024-01-01'), type: 'national' },
//   { name: 'Carnaval (segunda-feira)', date: Date('2024-02-12'), type: 'optional' },
//   { name: 'Carnaval (terça-feira)', date: Date('2024-02-13'), type: 'optional' },
//   { name: 'Sexta-feira Santa', date: Date('2024-03-29'), type: 'national' },
//   { name: 'Páscoa', date: Date('2024-03-31'), type: 'religious' },
//   { name: 'Tiradentes', date: Date('2024-04-21'), type: 'national' },
//   { name: 'Dia do trabalhador', date: Date('2024-05-01'), type: 'national' },
//   { name: 'Corpus Christi', date: Date('2024-05-30'), type: 'optional' },
//   { name: 'Independência do Brasil', date: Date('2024-09-07'), type: 'national' },
//   { name: 'Eleições (primeiro turno)', date: Date('2024-10-06'), type: 'national' },
//   { name: 'Nossa Senhora Aparecida', date: Date('2024-10-12'), type: 'national' },
//   { name: 'Finados', date: Date('2024-11-02'), type: 'national' },
//   { name: 'Proclamação da República', date: Date('2024-11-15'), type: 'national' },
//   { name: 'Dia da Consciência Negra', date: Date('2024-11-20'), type: 'national' },
//   { name: 'Natal', date: Date('2024-12-25'), type: 'national' },
// ]

// Get holidays for a specific state
getHolidays({ year: 2024, stateCode: 'SP' });
// Includes national holidays plus state-specific holidays (e.g., "Revolução Constitucionalista")

Is business day

• JavaScript library
• Python library
• Go library
• Ruby library
• Rust library
• .NET library
• Erlang library

Checks whether a date is a Brazilian business day (dia útil), by its local calendar date. A business day is not a Saturday, a Sunday or a holiday of date.getHolidays for the same state.

• options.includeOptional (default true) counts the optional holidays (Carnaval Monday and Tuesday, Corpus Christi, and the optional entries a state has, AM's 8 December and PE's 6 March of 2008 and 2009) as non-business days. With false, only national and state holidays count, so Corpus Christi still counts in DF, in MA from 2024 and in RJ from 2026, where it is a state holiday.
• options.includeSaturday (default false) counts Saturday as a business day, the labor law count of the payroll deadline (CLT art. 459 § 1º, read through IN MTP nº 2/2021, art. 14, I). Sunday and holidays stay excluded, including a holiday on a Saturday (Finados 2024-11-02, Independência 2024-09-07).
• includeSaturday does not cover municipal holidays, which the IN also excludes. An exact count for a municipality has to remove them separately. The option name does not promise "CLT" for that reason.
• A truthy value that is not a boolean (for example "false") turns includeSaturday or includeOptional on.
• An options that is not an object is ignored, as if it were omitted.
• options.stateCode is read ignoring case and surrounding whitespace, as in every state util: "sp" and " SP " add the holidays of São Paulo. Only an omitted (undefined) stateCode means national holidays only.
• A stateCode that is present and is not a state code ("XX", "", "__proto__", a number, null, an object) is rejected: the function returns false without looking at the date. 2.4.0 silently fell back to the national holidays for an unknown or lowercase code, so "sp" counted 9 July as a business day in São Paulo.
• This is not by itself a bank or court calendar: banks also close on their branch's local holidays, and courts follow their own calendars.
• Returns false for an invalid date or a year outside 1900 to 2099.

import { isBusinessDay } from '@brazilian-utils/brazilian-utils';

isBusinessDay(new Date(2024, 0, 2)); // true (Tuesday, not a holiday)
isBusinessDay(new Date(2024, 0, 1)); // false (Ano novo)
isBusinessDay(new Date(2024, 0, 6)); // false (Saturday)
isBusinessDay(new Date(2024, 0, 6), { includeSaturday: true }); // true (labour law count)
isBusinessDay(new Date(2024, 8, 7), { includeSaturday: true }); // false (Independência, a holiday on a Saturday)
isBusinessDay(new Date(2024, 0, 7), { includeSaturday: true }); // false (Sunday is never included)
isBusinessDay(new Date(2024, 1, 12)); // false (Carnaval Monday, optional holiday, counts by default)
isBusinessDay(new Date(2024, 1, 13)); // false (Carnaval Tuesday, optional holiday, counts by default)
isBusinessDay(new Date(2024, 1, 13), { includeOptional: false }); // true
isBusinessDay(new Date(2024, 6, 9), { stateCode: 'SP' }); // false (Revolução Constitucionalista)
isBusinessDay(new Date(2024, 6, 9)); // true (state holiday ignored without stateCode)
isBusinessDay(new Date('not a date')); // false

Is holiday

• JavaScript library
• Python library
• Go library
• Ruby library
• Rust library
• .NET library
• Erlang library

Checks whether a date is a Brazilian holiday, by its local calendar date.

• options carries the target date and, optionally, a state code whose holidays also count. Every holiday date.getHolidays lists counts, optional ones and the first round of the elections included.
• options.stateCode is read ignoring case and surrounding whitespace, as in every state util: "sp" and " SP " add the holidays of São Paulo. Only an omitted (undefined) stateCode means national holidays only.
• A stateCode that is present and is not a state code ("XX", "", "__proto__", a number, null, an object) is rejected: the function returns false without looking at the date. 2.4.0 silently fell back to the national holidays for an unknown or lowercase code, so "sp" did not find 9 July as a holiday in São Paulo.
• options.targetDate is the date to check. It is read by its local calendar day, not by its UTC instant. options.stateCode is optional.
• Returns false when targetDate is missing or is not a valid date, and when stateCode is present and is not a state code, even on a national holiday.
• Returns false for a year outside 1900 to 2099, where date.getHolidays lists nothing.
• The optional and religious entries of date.getHolidays count: Carnaval Monday and Tuesday, Corpus Christi and Páscoa make the function return true. There is no includeOptional here, unlike date.isBusinessDay.

import { isHoliday } from '@brazilian-utils/brazilian-utils';

isHoliday({ targetDate: new Date(2024, 0, 1) }); // true
isHoliday({ targetDate: new Date(2024, 6, 9), stateCode: 'SP' }); // true
isHoliday(); // false

Sub business days

• JavaScript library
• Python library
• Go library
• Ruby library
• Rust library
• .NET library
• Erlang library

Subtracts a number of Brazilian business days from a date. This is the same as date.addBusinessDays with the opposite amount.

• Same rules and options as date.addBusinessDays (includeOptional, includeSaturday, stateCode), including the same caveat on the time of day. A negative amount walks forwards.
• Last business day of a month: subBusinessDays(new Date(y, m + 1, 1), 1). For December 2099 this returns null, because the starting day is in 2100.

import { subBusinessDays } from '@brazilian-utils/brazilian-utils';

subBusinessDays(new Date(2024, 0, 5, 12), 1); // Date, 2024-01-04 12:00 (previous day is already a business day)
subBusinessDays(new Date(2024, 0, 8, 12), 1); // Date, 2024-01-05 12:00 (walks back over the weekend)
subBusinessDays(new Date(2025, 0, 2, 12), 1); // Date, 2024-12-31 12:00 (2025-01-01 is Ano novo, skipped)
subBusinessDays(new Date(2024, 0, 5, 12), -1); // Date, 2024-01-08 12:00 (walks forwards)
subBusinessDays(new Date(2024, 0, 6, 12), 0); // Date, 2024-01-06 12:00 (unchanged, even though Saturday is not a business day)
subBusinessDays(new Date(2024, 0, 8, 12), 1, { includeSaturday: true }); // Date, 2024-01-06 12:00 (labour law count, Saturday counts)
subBusinessDays(new Date(2024, 10, 4, 12), 1, { includeSaturday: true }); // Date, 2024-11-01 12:00 (2024-11-02 is Finados, a holiday on a Saturday)
subBusinessDays(new Date(2024, 6, 10, 12), 1, { stateCode: 'SP' }); // Date, 2024-07-08 12:00 (2024-07-09 is Revolução Constitucionalista in SP, skipped)
subBusinessDays(new Date('not a date'), 1); // null
subBusinessDays(new Date(2024, 0, 2), 1.5); // null (not an integer)

import { addBusinessDays, subBusinessDays } from '@brazilian-utils/brazilian-utils';

// n-th business day of the month: add n from the last day of the month before
addBusinessDays(new Date(2024, 0, 0), 5); // Date, 2024-01-08 00:00 (5th business day of January 2024)
addBusinessDays(new Date(2024, 1, 0), 10); // Date, 2024-02-16 00:00 (10th of February 2024, Carnaval Monday and Tuesday skipped)

// last business day of the month: subtract 1 from the first day of the month after
subBusinessDays(new Date(2024, 3, 1), 1); // Date, 2024-03-28 00:00 (2024-03-29 is Sexta-feira Santa, then a weekend)
subBusinessDays(new Date(2024, 1, 1), 2); // Date, 2024-01-30 00:00 (2nd to last of January 2024)

// payroll deadline of CLT art. 459 § 1º: the 5th business day in the labour law count
addBusinessDays(new Date(2024, 2, 0), 5, { includeSaturday: true }); // Date, 2024-03-06 00:00 (2024-03-02, a Saturday, counts; the Monday to Friday count gives 2024-03-07)
addBusinessDays(new Date(2024, 10, 0), 5, { includeSaturday: true }); // Date, 2024-11-07 00:00 (2024-11-02 is Finados, a holiday on a Saturday)
subBusinessDays(new Date(2024, 8, 1), 1, { includeSaturday: true }); // Date, 2024-08-31 00:00 (last business day of August 2024, a Saturday)