Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hyanmandian wants to merge 1 commit into from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 26 additions & 6 deletions docs/pt-br/utilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1806,7 +1806,10 @@ isHoliday(); // false

Verifica se uma data é dia útil no Brasil: não é sábado, domingo nem um feriado que `getHolidays` lista para o seu dia de calendário local.

- **Opções** (`BusinessDayOptions`, as mesmas de todos os utilitários de dias úteis): `includeOptional` (padrão `true`) também conta os feriados `"optional"`, Carnaval e Corpus Christi, como dias não úteis; `stateCode` também conta os feriados daquele estado.
- **Opções** (`BusinessDayOptions`, as mesmas de todos os utilitários de dias úteis): `includeOptional` (padrão `true`) também conta os feriados `"optional"`, Carnaval e Corpus Christi, como dias não úteis; `includeSaturday` (padrão `false`) conta o sábado como dia útil; `stateCode` também conta os feriados daquele estado.
- Com `includeSaturday` desligado, é a contagem de segunda a sexta usada por bancos e tribunais. Ligado, é a contagem trabalhista do prazo de pagamento do salário do art. 459, § 1º, da CLT, a que a fiscalização do trabalho lê pela Instrução Normativa MTP nº 2/2021, art. 14, I: "na contagem dos dias será incluído o sábado, excluindo-se o domingo e o feriado, inclusive o municipal".
- Com `includeSaturday` ligado, o domingo e os feriados continuam excluídos, então um feriado que cai em um sábado continua não sendo dia útil.
- O trecho "inclusive o municipal" dessa regra não é coberto: `getHolidays` tem apenas feriados nacionais e estaduais, então um feriado municipal é contado aqui como dia útil comum. Retire os feriados municipais por conta própria quando a contagem precisar ser exata para um município.
- Retorna `false` quando `value` não é um `Date` válido ou o seu ano está fora de 1900 a 2099, ou quando `stateCode` está presente e não é string.

```javascript
Expand All @@ -1815,6 +1818,9 @@ import { isBusinessDay } from '@brazilian-utils/brazilian-utils';
isBusinessDay(new Date(2024, 0, 2)); // true (terça-feira, não é feriado)
isBusinessDay(new Date(2024, 0, 1)); // false (Ano novo)
isBusinessDay(new Date(2024, 0, 6)); // false (sábado)
isBusinessDay(new Date(2024, 0, 6), { includeSaturday: true }); // true (contagem trabalhista)
isBusinessDay(new Date(2024, 8, 7), { includeSaturday: true }); // false (Independência, feriado em um sábado)
isBusinessDay(new Date(2024, 0, 7), { includeSaturday: true }); // false (o domingo nunca é incluído)
isBusinessDay(new Date(2024, 1, 13)); // false (Carnaval, feriado facultativo, conta por padrão)
isBusinessDay(new Date(2024, 1, 13), { includeOptional: false }); // true
isBusinessDay(new Date(2024, 6, 9), { stateCode: 'SP' }); // false (Revolução Constitucionalista)
Expand All @@ -1826,7 +1832,7 @@ isBusinessDay(new Date('not a date')); // false

Soma dias úteis a uma data, pulando sábados, domingos e os feriados que `isBusinessDay` considera. Assinatura: `addBusinessDays(date, amount, options?)`, a mesma do date-fns.

- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `stateCode` também pula os feriados daquele estado.
- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `includeSaturday` (padrão `false`) conta o sábado como dia útil; `stateCode` também pula os feriados daquele estado.
- Retorna um novo `Date`, com o horário preservado; `date` não é alterado.
- `amount` igual a `0` retorna a mesma data, mesmo em fim de semana ou feriado. Um `amount` negativo anda para trás.
- Retorna `null` quando `date` é inválido, `amount` não é um inteiro finito, `stateCode` não é string ou o resultado sai dos anos de 1900 a 2099.
Expand All @@ -1838,6 +1844,8 @@ addBusinessDays(new Date(2024, 0, 2, 12), 1); // Date, 2024-01-03 12:00 (o dia s
addBusinessDays(new Date(2024, 11, 31, 12), 1); // Date, 2025-01-02 12:00 (2025-01-01 é Ano novo, pulado)
addBusinessDays(new Date(2024, 0, 5, 12), -1); // Date, 2024-01-04 12:00 (anda para trás)
addBusinessDays(new Date(2024, 0, 6, 12), 0); // Date, 2024-01-06 12:00 (sem alteração, mesmo o sábado não sendo dia útil)
addBusinessDays(new Date(2024, 0, 5, 12), 1, { includeSaturday: true }); // Date, 2024-01-06 12:00 (contagem trabalhista, o sábado conta)
addBusinessDays(new Date(2024, 10, 1, 12), 1, { includeSaturday: true }); // Date, 2024-11-04 12:00 (2024-11-02 é Finados, feriado em um sábado)
addBusinessDays(new Date(2024, 6, 8, 12), 1, { stateCode: 'SP' }); // Date, 2024-07-10 12:00 (2024-07-09 é a Revolução Constitucionalista em SP, pulado)
addBusinessDays(new Date('not a date'), 1); // null
addBusinessDays(new Date(2024, 0, 2), 1.5); // null (não é um número inteiro)
Expand All @@ -1857,6 +1865,8 @@ subBusinessDays(new Date(2024, 0, 8, 12), 1); // Date, 2024-01-05 12:00 (anda pa
subBusinessDays(new Date(2025, 0, 2, 12), 1); // Date, 2024-12-31 12:00 (2025-01-01 é Ano novo, pulado)
subBusinessDays(new Date(2024, 0, 5, 12), -1); // Date, 2024-01-08 12:00 (anda para frente)
subBusinessDays(new Date(2024, 0, 6, 12), 0); // Date, 2024-01-06 12:00 (sem alteração, mesmo o sábado não sendo dia útil)
subBusinessDays(new Date(2024, 0, 8, 12), 1, { includeSaturday: true }); // Date, 2024-01-06 12:00 (contagem trabalhista, o sábado conta)
subBusinessDays(new Date(2024, 10, 4, 12), 1, { includeSaturday: true }); // Date, 2024-11-01 12:00 (2024-11-02 é Finados, feriado em um sábado)
subBusinessDays(new Date(2024, 6, 10, 12), 1, { stateCode: 'SP' }); // Date, 2024-07-08 12:00 (2024-07-09 é a Revolução Constitucionalista em SP, pulado)
subBusinessDays(new Date('not a date'), 1); // null
subBusinessDays(new Date(2024, 0, 2), 1.5); // null (não é um número inteiro)
Expand All @@ -1866,7 +1876,7 @@ subBusinessDays(new Date(2024, 0, 2), 1.5); // null (não é um número inteiro)

Conta os dias úteis entre duas datas. Assinatura: `differenceInBusinessDays(laterDate, earlierDate, options?)`, a mesma do date-fns.

- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `stateCode` também pula os feriados daquele estado.
- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `includeSaturday` (padrão `false`) conta o sábado como dia útil; `stateCode` também pula os feriados daquele estado.
- Conta `earlierDate` quando é dia útil e cada dia útil estritamente entre as duas datas; `laterDate` nunca é contado. O horário é ignorado.
- O resultado é negativo quando `laterDate` é anterior a `earlierDate`, e `0` no mesmo dia de calendário.
- Retorna `null` quando uma das datas não é um `Date` válido ou está fora dos anos de 1900 a 2099, ou quando `stateCode` não é string.
Expand All @@ -1878,6 +1888,9 @@ differenceInBusinessDays(new Date(2024, 0, 2), new Date(2024, 0, 1)); // 0 (01/0
differenceInBusinessDays(new Date(2024, 0, 3), new Date(2024, 0, 2)); // 1 (02/01 contado, uma terça-feira; 03/01 não)
differenceInBusinessDays(new Date(2024, 0, 2), new Date(2024, 0, 3)); // -1 (a data posterior vem primeiro, então a contagem é negativa)
differenceInBusinessDays(new Date(2024, 0, 2), new Date(2024, 0, 2)); // 0 (mesmo dia)
differenceInBusinessDays(new Date(2024, 0, 8), new Date(2024, 0, 1)); // 4 (contagem bancária, de 2024-01-02 a 2024-01-05)
differenceInBusinessDays(new Date(2024, 0, 8), new Date(2024, 0, 1), { includeSaturday: true }); // 5 (2024-01-06, um sábado, também conta)
differenceInBusinessDays(new Date(2024, 10, 4), new Date(2024, 10, 1), { includeSaturday: true }); // 1 (2024-11-02 é Finados, feriado em um sábado)
differenceInBusinessDays(new Date(2024, 6, 10), new Date(2024, 6, 8), { stateCode: 'SP' }); // 1 (09/07/2024 é feriado estadual em SP)
differenceInBusinessDays(new Date(), new Date('not a date')); // null
```
Expand All @@ -1886,7 +1899,7 @@ differenceInBusinessDays(new Date(), new Date('not a date')); // null

Retorna o primeiro dia útil brasileiro estritamente depois de uma data. `getNextBusinessDay(date, options?)` é `addBusinessDays(date, 1, options)`.

- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `stateCode` também pula os feriados daquele estado.
- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `includeSaturday` (padrão `false`) conta o sábado como dia útil; `stateCode` também pula os feriados daquele estado.
- "Próximo" significa estritamente depois, o sentido que o date-fns dá em `nextDay`: um `date` que já é dia útil nunca é retornado. Para "no dia ou depois", consulte `isBusinessDay(date)` antes e fique com `date` quando a resposta for `true`.
- Retorna um novo `Date`, com o horário preservado; `date` nunca é modificado.
- Retorna `null` quando `date` é inválido, `stateCode` não é string, ou o resultado sai dos anos de 1900 a 2099.
Expand All @@ -1897,6 +1910,8 @@ import { getNextBusinessDay } from '@brazilian-utils/brazilian-utils';
getNextBusinessDay(new Date(2024, 0, 2, 12)); // Date, 2024-01-03 12:00 (estritamente depois, embora 02/01/2024 seja dia útil)
getNextBusinessDay(new Date(2024, 0, 5, 12)); // Date, 2024-01-08 12:00 (pula o fim de semana)
getNextBusinessDay(new Date(2024, 0, 6, 12)); // Date, 2024-01-08 12:00 (a partir de um sábado)
getNextBusinessDay(new Date(2024, 0, 5, 12), { includeSaturday: true }); // Date, 2024-01-06 12:00 (contagem trabalhista, o sábado conta)
getNextBusinessDay(new Date(2024, 10, 1, 12), { includeSaturday: true }); // Date, 2024-11-04 12:00 (2024-11-02 é Finados, feriado em um sábado)
getNextBusinessDay(new Date(2024, 11, 31, 12)); // Date, 2025-01-02 12:00 (01/01/2025 é Ano novo, pulado)
getNextBusinessDay(new Date(2024, 6, 8, 12), { stateCode: 'SP' }); // Date, 2024-07-10 12:00 (09/07/2024 é Revolução Constitucionalista em SP, pulado)
getNextBusinessDay(new Date('not a date')); // null
Expand All @@ -1907,12 +1922,12 @@ getNextBusinessDay(new Date(2099, 11, 31)); // null (o percurso sai dos anos sup

Retorna o n-ésimo dia útil brasileiro do mês em que uma data cai. Assinatura: `getNthBusinessDay(date, n, options?)`, a ordem de argumentos de `addBusinessDays`.

- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `stateCode` também pula os feriados daquele estado.
- **Opções** (`BusinessDayOptions`, as mesmas de `isBusinessDay`): `includeOptional` (padrão `true`) também pula Carnaval e Corpus Christi; `includeSaturday` (padrão `false`) conta o sábado como dia útil; `stateCode` também pula os feriados daquele estado.
- `date` é qualquer data dentro do mês: o que importa são o ano e o mês locais, o dia do mês e o horário são ignorados.
- Um `n` positivo conta a partir do primeiro dia do mês (`1` é o primeiro dia útil) e um `n` negativo conta a partir do último (`-1` é o último dia útil, `-2` o anterior a ele), como `Array#at` lê um índice.
- Retorna um novo `Date` no início daquele dia local (00:00); `date` nunca é modificado.
- Retorna `null` quando `date` é inválido, `n` não é um inteiro finito, é `0` ou vai além dos dias úteis que o mês tem (a resposta nunca transborda para um mês vizinho), `stateCode` não é string, ou o mês sai dos anos de 1900 a 2099. Um `options` que não é um objeto é ignorado.
- O prazo de pagamento de salário do art. 459, § 1º, da CLT ("até o quinto dia útil do mês subsequente ao vencido") é contado de outro modo pela inspeção do trabalho, que conta o sábado como dia útil e ignora os feriados municipais. O quinto dia útil retornado aqui é o bancário, que pode cair depois do trabalhista.
- O prazo de pagamento de salário do art. 459, § 1º, da CLT ("até o quinto dia útil do mês subsequente ao vencido") é a contagem trabalhista, não a bancária que esta função dá por padrão: passe `{ includeSaturday: true }`, como em `getNthBusinessDay(date, 5, { includeSaturday: true })`. Os feriados municipais continuam contando como dias úteis, e essa regra os exclui.
- A contagem percorre dias do calendário local, então vale em qualquer fuso horário. Quando o dia local resultante não tem 00:00 (o horário de verão brasileiro sempre começava à meia-noite, então 6 de outubro de 1997 começa à 01:00 em São Paulo), é retornado o instante mais próximo daquele dia, o mesmo `Date` que o `startOfDay` do date-fns dá ali.
- Um dia do calendário local que o fuso nunca teve, como 30 de dezembro de 2011 em `Pacific/Apia`, não é contado nem retornado.

Expand All @@ -1923,6 +1938,9 @@ getNthBusinessDay(new Date(2024, 0, 15), 1); // Date, 2024-01-02 00:00 (01/01/20
getNthBusinessDay(new Date(2024, 0, 15), 5); // Date, 2024-01-08 00:00
getNthBusinessDay(new Date(2024, 1, 1), 10); // Date, 2024-02-15 00:00 (Carnaval, 13/02/2024, pulado)
getNthBusinessDay(new Date(2024, 1, 1), 10, { includeOptional: false }); // Date, 2024-02-14 00:00
getNthBusinessDay(new Date(2024, 2, 1), 5); // Date, 2024-03-07 00:00 (contagem bancária)
getNthBusinessDay(new Date(2024, 2, 1), 5, { includeSaturday: true }); // Date, 2024-03-06 00:00 (contagem trabalhista, 2024-03-02 é um sábado)
getNthBusinessDay(new Date(2024, 10, 1), 5, { includeSaturday: true }); // Date, 2024-11-07 00:00 (2024-11-02 é Finados, feriado em um sábado)
getNthBusinessDay(new Date(2024, 6, 1), 7, { stateCode: 'SP' }); // Date, 2024-07-10 00:00 (09/07/2024 é Revolução Constitucionalista em SP, pulado)
getNthBusinessDay(new Date(2024, 0, 15), -1); // Date, 2024-01-31 00:00 (o último dia útil)
getNthBusinessDay(new Date(2024, 0, 15), -2); // Date, 2024-01-30 00:00
Expand All @@ -1946,6 +1964,8 @@ getLastBusinessDayOfMonth(new Date(2024, 2, 1)); // Date, 2024-03-28 00:00 (29/0
getLastBusinessDayOfMonth(new Date(2024, 7, 31, 18, 30)); // Date, 2024-08-30 00:00 (31/08/2024 é um sábado)
getLastBusinessDayOfMonth(new Date(2018, 4, 1)); // Date, 2018-05-30 00:00 (31/05/2018 é Corpus Christi, facultativo, conta por padrão)
getLastBusinessDayOfMonth(new Date(2018, 4, 1), { includeOptional: false }); // Date, 2018-05-31 00:00
getLastBusinessDayOfMonth(new Date(2024, 7, 1), { includeSaturday: true }); // Date, 2024-08-31 00:00 (contagem trabalhista, o sábado conta)
getLastBusinessDayOfMonth(new Date(2024, 10, 1), { stateCode: 'DF', includeSaturday: true }); // Date, 2024-11-29 00:00 (o sábado 2024-11-30 é o Dia do Evangélico no DF)
getLastBusinessDayOfMonth(new Date(2023, 10, 1), { stateCode: 'DF' }); // Date, 2023-11-29 00:00 (30/11/2023 é Dia do Evangélico no DF)
getLastBusinessDayOfMonth(new Date('not a date')); // null
```
Expand Down
Loading
Loading