feat(business-days): count Saturday with includeSaturday - #573

Stacked on #561. The base of this PR is claude/business-day-helpers, not main, because it also touches getNthBusinessDay, getNextBusinessDay and getLastBusinessDayOfMonth, which #561 adds. Merge #561 first; GitHub will retarget this one to main afterwards.

What

Today isBusinessDay and the whole family count Monday to Friday minus holidays. That is the banking count, and it is the wrong one for the payroll deadline of CLT art. 459 § 1º ("até o quinto dia útil do mês subsequente ao vencido"): labour inspection reads that deadline through Instrução Normativa MTP nº 2/2021, art. 14, I, which says verbatim "na contagem dos dias será incluído o sábado, excluindo-se o domingo e o feriado, inclusive o municipal". So the labour "quinto dia útil" can fall a day earlier than the banking one: in March 2024 it is Wednesday the 6th (Saturday 2 March counts), while the banking one is Thursday the 7th.

This PR adds includeSaturday to the shared BusinessDayOptions. It defaults to false, which is exactly today's behaviour, so nothing existing changes. Every utility of the family honours it, since they all evaluate days through isBusinessDay with the caller's options.

With the option on, Sunday and holidays are still excluded, exactly as the article says, so a holiday that falls on a Saturday is still not a business day (Finados on Saturday 2 November 2024, Independência on Saturday 7 September 2024, Dia do Evangélico on Saturday 30 November 2024 in the DF).

On top of #561's shared day walk

#561 now also replaces the setDate day walk of addBusinessDays, differenceInBusinessDays and getNthBusinessDay with one internal, _internals/each-local-day, which walks integer day offsets and yields each day at noon, so it cannot hang in Pacific/Apia, Pacific/Fakaofo, Pacific/Kwajalein, Pacific/Kiritimati or Pacific/Enderbury. This PR is rebased on that. includeSaturday needs no code in the walk: every util calls isBusinessDay(candidate, options) on the days eachLocalDay yields, so the option goes through the shared walk unchanged. Tests pin it under TZ=Pacific/Apia across the missing Friday 30 December 2011, against the same calls under UTC:

• getNthBusinessDay(new Date(2011, 11, 15), -2, { includeSaturday: true }) is Thu 2011-12-29 in Apia (Fri 30th skipped, Sat 31st counted) and Fri 2011-12-30 in UTC; December 2011 has 26 such business days in Apia and 27 in UTC.
• differenceInBusinessDays(new Date(2011, 11, 1), new Date(2011, 11, 31), { includeSaturday: true }) is -25 in Apia and -26 in UTC.
• subBusinessDays(new Date(2012, 0, 2, 12), 2, { includeSaturday: true }) is Thu 2011-12-29 12:00 in Apia.

Why includeSaturday and not something else

• It is the same shape and the same prefix as the option already on the type, includeOptional: a boolean that widens what counts, named after what it includes. saturdays: boolean does not say what setting it does; includeSaturday does.
• Singular, because it is one weekday, not a set.
• It deliberately does not name the law (clt, laborLaw, payroll, in2/2021). A name like that would promise the whole rule of art. 14, I, and this library cannot deliver the "inclusive o municipal" half of it (see Open points). includeSaturday promises exactly what it does.
• false is the default, so the existing Monday-to-Friday answer is what every current call keeps getting.

API

No signature changes. One new optional key on the existing shared type:

export type BusinessDayOptions = {
	stateCode?: StateCode;
	includeOptional?: boolean;
	/** Whether Saturday counts as a business day, the labour law count of Instrução Normativa MTP nº 2/2021, art. 14, I (default: `false`, the Monday to Friday banking count). */
	includeSaturday?: boolean;
};

isBusinessDay(new Date(2024, 0, 6)); // false (Saturday, banking count)
isBusinessDay(new Date(2024, 0, 6), { includeSaturday: true }); // true
isBusinessDay(new Date(2024, 0, 7), { includeSaturday: true }); // false (Sunday is never included)
isBusinessDay(new Date(2024, 8, 7), { includeSaturday: true }); // false (Independência, a holiday on a Saturday)

// The payroll deadline of CLT art. 459 § 1º, March 2024
getNthBusinessDay(new Date(2024, 2, 1), 5); // Thu 2024-03-07 (banking count)
getNthBusinessDay(new Date(2024, 2, 1), 5, { includeSaturday: true }); // Wed 2024-03-06 (labour count)

// November 2024: both counts give Thursday the 7th, because Saturday the 2nd is Finados
getNthBusinessDay(new Date(2024, 10, 1), 5, { includeSaturday: true }); // Thu 2024-11-07

addBusinessDays(new Date(2024, 0, 5, 12), 1, { includeSaturday: true }); // Sat 2024-01-06 12:00
subBusinessDays(new Date(2024, 0, 8, 12), 1, { includeSaturday: true }); // Sat 2024-01-06 12:00
getNextBusinessDay(new Date(2024, 0, 5, 12), { includeSaturday: true }); // Sat 2024-01-06 12:00
differenceInBusinessDays(new Date(2024, 0, 8), new Date(2024, 0, 1)); // 4
differenceInBusinessDays(new Date(2024, 0, 8), new Date(2024, 0, 1), { includeSaturday: true }); // 5
getLastBusinessDayOfMonth(new Date(2024, 7, 1), { includeSaturday: true }); // Sat 2024-08-31

Sources

Read in full, not from memory:

• CLT (Decreto-Lei 5.452/1943), art. 459 § 1º — the deadline itself: "Quando o pagamento houver sido estipulado por mês, deverá ser efetuado, o mais tardar, até o quinto dia útil do mês subsequente ao vencido" (Redação dada pela Lei nº 7.855, de 24.10.1989). Note that the article's original parágrafo único, still shown struck through on the Planalto page, said "décimo dia útil"; the § 1º wording is the one in force.
• Instrução Normativa MTP nº 2, de 8 de novembro de 2021 (gov.br PDF, DOU 28/11/2021, Edição 213, Seção 1, Página 153), art. 14: "Para efeito de orientação quanto ao prazo para o pagamento dos salários, os Auditores-Fiscais do Trabalho deverão observar o seguinte: I - na contagem dos dias será incluído o sábado, excluindo-se o domingo e o feriado, inclusive o municipal". This is the rule the option implements. Its § 2º ties the infraction back to § 1º do art. 459 da CLT, which is why the two sources belong together.
• Lei 9.093/1995, art. 2º — "São feriados religiosos os dias de guarda, declarados em lei municipal, de acordo com a tradição local e em número não superior a quatro". This is why the municipal half of art. 14, I cannot be implemented here: those holidays live in each municipality's own law and getHolidays does not carry them.

The national and state holidays the count subtracts are unchanged and keep the sources already cited in getHolidays/isBusinessDay.

Verification

• npm run check — pass (format, lint, types).
• npm run test -- --run — 6277 passed (after the rebase on feat(business-days): add getNthBusinessDay, getNextBusinessDay and getLastBusinessDayOfMonth, and fix the day walk that hangs in five time zones #561).
• npm run test:coverage — 100% statements/branches/functions/lines.
• npm run test:bun / npm run test:deno — passed before the rebase (6244); after it, left to CI.
• npm run build — pass, attw and publint clean.
• npm run check:api:update — the report gains exactly one line, includeSaturday?: boolean;; committed.
• npm run check:unused — pass. npm run check:duplication — 0 clones. npm run check:tree-shaking — pass. npm run check:commits — 0 problems.
• npm run test:mutation on each touched source file (before the rebase; the rebase changed no line of this PR's source, only its tests): is-business-day.ts 100% (55 killed), add-business-days.ts 100%, sub-business-days.ts 100%, difference-in-business-days.ts 100%, get-nth-business-day.ts 100%, get-next-business-day.ts 100%, get-last-business-day-of-month.ts 100%. No survivors, no new Stryker disables.
• npm run build:llms run, docs/llms.txt and docs/llms-full.txt committed.

Tests

Every expectation is a literal date counted by hand against the holiday tables, including:

• A Saturday that changes the answer: 6 January 2024 (isBusinessDay), Friday 5 January + 1 landing on it, Monday 8 January - 1 landing on it, 31 August 2024 as the last business day of August, the 26 business days January 2024 has with Saturdays (22 + the Saturdays 6, 13, 20 and 27) against the 22 without them.
• A holiday that falls on a Saturday, which the option must not promote: Finados on 2 November 2024, Independência on 7 September 2024, Dia do Evangélico on 30 November 2024 with stateCode: "DF". September 2024 exercises both at once: the 11th business day is Saturday the 14th with the option (Saturday the 7th skipped as Independência) and Monday the 16th without it.
• Sunday, which the option must never touch, both as a literal case and as a fast-check property over the whole supported year range.
• A describe("no breaking change") block pinning that an absent, false or undefined includeSaturday, and an options carrying only stateCode or includeOptional, all still answer false for a Saturday.
• The should agree with getHolidays and the weekend rule property now ranges over includeSaturday too.

Open points

• Municipal holidays are not covered. Art. 14, I excludes "o feriado, inclusive o municipal". getHolidays has national and state holidays only, so with includeSaturday: true a municipal holiday is counted here as an ordinary business day while the labour inspection would exclude it. A count that has to be exact for one municipality still needs those days removed on top of this option. This is stated in the JSDoc of isBusinessDay and getNthBusinessDay and in both docs/utilities.md files rather than glossed over. Adding a municipal holiday dataset is a separate piece of work.
• The IN was later amended (by IN MTP nº 2 de 22/12/2022 and IN MTP nº 3 de 28/12/2022, both listed on the header of the PDF above). Neither touches art. 14; the wording quoted here is the one in the consolidated PDF the ministry publishes.
• A non-boolean truthy includeSaturday (for example the string "false") enables the option, the same way a non-boolean truthy includeOptional behaves today. That is existing house behaviour for these flags, not something this PR changes; the never-throws property covers hostile values.
• isBusinessDay no longer builds a module level new Set([0, 6]) for the weekend check, replaced by two plain number constants, which is what the tree-shaking rule in CONTRIBUTING.md asks modules to do. Behaviour is identical.

CI

Rebased onto the current tip of #561 and force-pushed: every check green on 5619d05 (Build, Check, Stryker, Node 20/22/24/26, Bun, Deno, the four browsers). The first Check run failed in Audit dependencies with audit-ci exiting on code undefined before any project code ran, a registry hiccup; the rerun passed.

Summary by CodeRabbit

• New Features

  • Added an includeSaturday option to business-day utilities.
  • When enabled, Saturdays count as business days unless they are holidays; Sundays and holidays remain excluded.
  • The option defaults to false, preserving existing banking-day behavior.
  • Supports forward and backward calculations, differences, next and nth business days, and month-end calculations.

• Documentation

  • Added examples covering labor-law counts, banking-day counts, state holidays, and Saturday holidays.