Skip to content

[2.4.0 stack 18/18] Review rounds 3 to 5: holidays, date-fns business days, capitalize defaults, currency, words, CEP typed errors, subpath types, citations #520

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 53 commits into from
Open

[2.4.0 stack 18/18] Review rounds 3 to 5: holidays, date-fns business days, capitalize defaults, currency, words, CEP typed errors, subpath types, citations #520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
53 commits
Select commit Hold shift + click to select a range
09408b1
feat(cnae,ncm): add the pad option to formatCnae and formatNcm
hyanmandian Sep 13, 2026
4645f54
fix(holidays): add the GO and DF state entries, end PB 26/07 in 2015 …
hyanmandian Sep 13, 2026
7cb4fed
test(runtime): honour the vitest mockClear semantics and rethrow matc…
hyanmandian Sep 13, 2026
688359f
feat(business-days): follow the date-fns signatures and add subBusine…
hyanmandian Sep 13, 2026
898186f
fix(registro-profissional): read T and S as transfer suffixes after t…
hyanmandian Sep 13, 2026
3710dfa
test(ie): pin the 38 SINTEGRA worked examples and the prototype-key s…
hyanmandian Sep 13, 2026
e9e8eba
refactor(municipality): keep collapsing whitespace runs in name looku…
hyanmandian Sep 13, 2026
b6cb522
feat(capitalize): keep company designations, roman numerals and state…
hyanmandian Sep 13, 2026
c9f5a5e
fix(currency): coerce a non-string value without throwing and read th…
hyanmandian Sep 13, 2026
e10f878
refactor(words): always return lower case, drop the case option
hyanmandian Sep 13, 2026
6f2b2e8
feat(types): export the public types from the subpath entries
hyanmandian Sep 13, 2026
40563db
ci(tree-shaking): fail the job when the base measurement fails
hyanmandian Sep 13, 2026
01b7d32
docs: cite the annexes, decrees and manuals behind the identifiers an…
hyanmandian Sep 13, 2026
033d6bd
fix(municipality): return a fresh pair and overload the return type o…
hyanmandian Sep 13, 2026
f0abf92
ci(datasets): validate both bank outputs before writing either file
hyanmandian Sep 13, 2026
89cb3d5
fix(holidays): move the Santa Catarina state holidays to Sunday per t…
hyanmandian Sep 13, 2026
e935499
docs: describe the acervo codes of art. 473, the arrecadação result a…
hyanmandian Sep 13, 2026
03e5c11
fix(business-days): return false from isBusinessDay for a non-string …
hyanmandian Sep 13, 2026
edf4577
fix(types): re-export the option and state types from the calendar an…
hyanmandian Sep 13, 2026
02bd64f
fix(cep): reject with the typed errors for a bad providers list, a mi…
hyanmandian Sep 13, 2026
aeef62c
fix(email): cap the final domain label at 63 letters
hyanmandian Sep 13, 2026
ee2f02b
fix(boleto): keep the fator de vencimento inside the first cycle for …
hyanmandian Sep 13, 2026
cfc5ed0
fix(service-phone): drop 112 and 911 and add 141 per the Anatel Ato 4…
hyanmandian Sep 13, 2026
7d23f3a
fix(nfe-key): return an empty string from formatNfeKey for a value th…
hyanmandian Sep 13, 2026
40bc6a8
fix(cst): accept a separator only after the origin digit
hyanmandian Sep 13, 2026
c16f096
fix(pix): reject a dynamic payload that carries a Pix Saque facilitator
hyanmandian Sep 13, 2026
f7eb3bb
fix(caepf): reject a repeated base like CEI and CNO do
hyanmandian Sep 13, 2026
fac0769
fix(cns,cei): accept a run of separators like the other document formats
hyanmandian Sep 13, 2026
95f1958
refactor(format): read the obfuscate option truthily like pad
hyanmandian Sep 13, 2026
af8a8bd
ci(datasets): reject a zero bank code and parse the NCM dates strictly
hyanmandian Sep 13, 2026
75f875d
ci(release): hide the CI and build sections from the changelog
hyanmandian Sep 13, 2026
b86b153
test: pin the published worked examples and the boleto moeda leniency
hyanmandian Sep 13, 2026
1d3aeb0
docs: cite the acts and ajustes behind the fiscal and calendar utilities
hyanmandian Sep 13, 2026
4d44ec4
fix(types): re-export the bank and state types from the eight subpath…
hyanmandian Sep 13, 2026
1a27003
fix(package): resolve the subpath declarations under moduleResolution…
hyanmandian Sep 13, 2026
da567b5
ci(tree-shaking): treat any unexpected exit code as a comparison failure
hyanmandian Sep 13, 2026
811cb10
feat(cep): declare the unidade, estado and regiao fields of the ViaCE…
hyanmandian Sep 13, 2026
eee5e88
test(business-days): pin the non-string state code rejection for an a…
hyanmandian Sep 13, 2026
e35bc22
docs: describe every option used in the examples and correct the rema…
hyanmandian Sep 13, 2026
ddf63fc
ci(tree-shaking): mark a missing build as a comparison failure and de…
hyanmandian Sep 13, 2026
68bc902
docs: put every cited URL on its own citation line and fill the thin …
hyanmandian Sep 13, 2026
1397171
ci(datasets): decode entities and require a complete CFOP annex befor…
hyanmandian Sep 13, 2026
1882ed8
test(cep): skip the live Widenet check while the service is offline
hyanmandian Sep 13, 2026
882cf95
docs(cep): say a CEP that starts with 0 has to be a string when given…
hyanmandian Sep 13, 2026
6d47c14
fix(words): write the groups the way the official texts do, without c…
hyanmandian Sep 13, 2026
214da0d
fix(csosn): read only the bare 3 digits, the code has no printed grou…
hyanmandian Sep 13, 2026
3600310
docs(business-days): name the includeOptional and stateCode options i…
hyanmandian Sep 13, 2026
33e27be
feat(cnpj): accept a branch number in generateCnpj
hyanmandian Sep 13, 2026
e46aa21
feat(renavam): add generateRenavam
hyanmandian Sep 13, 2026
defbdf8
feat(legal-nature): expose the CONCLA category and add getLegalNature…
hyanmandian Sep 13, 2026
af21b77
feat(phone): accept 7 and 8 as mobile first digits under version 2
hyanmandian Sep 13, 2026
77cf05b
ci: reference the setup action with the self-repository syntax
hyanmandian Sep 13, 2026
e879cb4
docs: state the measured isValidCpf size and fix two comments in the …
hyanmandian Sep 13, 2026
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
7 changes: 7 additions & 0 deletions .github/actionlint.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# actionlint 1.7.12 does not know GitHub's self-repository `uses: $/...` syntax yet
# (https://github.com/rhysd/actionlint/issues/711); zizmor's self-repository audit and the GitHub
# docs recommend it over the workspace-relative `./...` form. Drop this once actionlint supports it.
paths:
.github/workflows/**/*.yml:
ignore:
- 'specifying action "\$/\.github/actions/setup" in invalid format because ref is missing'
19 changes: 10 additions & 9 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Run build
run: vp run build
Expand All @@ -52,7 +52,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Checkout base
if: ${{ github.event_name == 'pull_request' }}
Expand All @@ -69,26 +69,27 @@ jobs:
if: ${{ github.event_name == 'pull_request' }}
id: base
run: |
if [ -f base/scripts/tree-shaking.ts ]; then
node scripts/tree-shaking.ts --json head.json
(cd base && npm ci && npm run build && node scripts/tree-shaking.ts --json ../base.json --surviving ../head.json) || true
fi
if [ -f base.json ]; then
echo "measured=true" >> "$GITHUB_OUTPUT"
else
if [ ! -f base/scripts/tree-shaking.ts ]; then
echo "measured=false" >> "$GITHUB_OUTPUT"
exit 0
fi
node scripts/tree-shaking.ts --json head.json
(cd base && npm ci && npm run build && node scripts/tree-shaking.ts --json ../base.json --surviving ../head.json)
echo "measured=true" >> "$GITHUB_OUTPUT"

- name: Compare against base
if: ${{ github.event_name == 'pull_request' }}
id: compare
continue-on-error: true
run: |
if [ "${{ steps.base.outputs.measured }}" = "true" ]; then
code=2
echo "code=$code" >> "$GITHUB_OUTPUT"
set +e
node scripts/tree-shaking.ts --compare base.json --markdown tree-shaking.md
code=$?
set -e
case "$code" in 0 | 1) ;; *) code=2 ;; esac
echo "code=$code" >> "$GITHUB_OUTPUT"
exit "$code"
else
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/check.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Run checks
run: vp check
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/datasets.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Rebuild datasets
run: npm run build:data
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/live-tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Run live CEP tests
run: vp run test:live
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/mutation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Mutation test every file
run: npm run test:mutation
Expand Down
5 changes: 3 additions & 2 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup
with:
node-version: 24

Expand All @@ -104,6 +104,7 @@ jobs:
cat tree-shaking.md >> "$GITHUB_STEP_SUMMARY"

- name: Ensure npm supports staged publishing and OIDC (npm >= 11.15)
# zizmor: ignore[adhoc-packages] npm is pinned to an exact version and is not a package.json dependency
run: npm install -g npm@12.0.2

- name: Stage on npm
Expand All @@ -126,7 +127,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Generate the CycloneDX SBOM of the published package
# The package has no runtime dependencies, so the SBOM describes the package itself;
Expand Down
10 changes: 5 additions & 5 deletions .github/workflows/tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup
with:
node-version: ${{ matrix.node-version }}

Expand Down Expand Up @@ -65,7 +65,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Setup Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
Expand All @@ -85,7 +85,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Setup Deno
uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
Expand All @@ -110,7 +110,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Run tests in ${{ matrix.browser }}
run: vp test --browser.enabled --browser.name=${{ matrix.browser }}
Expand All @@ -127,7 +127,7 @@ jobs:
persist-credentials: false

- name: Setup
uses: ./.github/actions/setup
uses: $/.github/actions/setup

- name: Run tests in Safari
run: vp test --browser.enabled --browser.name=safari --browser.headless=false
48 changes: 28 additions & 20 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,24 +28,28 @@ and is invoked through the `npm` scripts below, so you don't need to install any

### Useful scripts

| Command | What it does |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run check` | Runs `vp check`: format check, lint and type-check together. Run this before opening a PR. |
| `npm run check:fix` | Same as above, but auto-fixes what it can. |
| `npm run format` / `npm run format:check` | Formats the codebase / checks formatting with `vp fmt`. |
| `npm run lint` / `npm run lint:fix` | Lints the codebase with `vp lint`. |
| `npm run test` | Runs the unit test suite with `vp test`. |
| `npm run test:coverage` | Runs tests with coverage (`vp test run --coverage`). |
| `npm run test:bun` | Runs the test suite on [Bun](https://bun.sh) (`bun test src`). |
| `npm run test:deno` | Runs the test suite on [Deno](https://deno.com) (`deno test`). |
| `npm run test:chrome-browser`, `npm run test:firefox-browser`, `npm run test:edge-browser`, `npm run test:safari-browser` | Runs the test suite in real browsers via `vp test --browser.enabled`. |
| `npm run build` | Builds the library with `vp build`. |
| `npm run check:duplication` | Runs [jscpd](https://jscpd.dev) over `src` and `scripts`; any copy-pasted block of 5+ lines / 50+ tokens fails. |
| `npm run check:unused` | Runs [knip](https://knip.dev): unused files, exports, types and dependencies fail. |
| `npm run test:mutation` | Runs [Stryker](https://stryker-mutator.io) mutation tests (`stryker run`); pass `-- --mutate src/<util>/<util>.ts` for one file. |
| `npm run check:api` | Builds the package and runs API Extractor over `dist/brazilian-utils.d.ts`: a public type without a doc comment, or a type the API refers to without exporting, fails. |
| `npm run check:commits` | Checks the commit messages since `origin/main` with commitlint (Conventional Commits). |
| `npm run check:lockfile` | Checks `package-lock.json` only resolves to the npm registry over HTTPS with integrity hashes (lockfile-lint). |
| Command | What it does |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run check` | Runs `vp check`: format check, lint and type-check together. Run this before opening a PR. |
| `npm run check:fix` | Same as above, but auto-fixes what it can. |
| `npm run format` / `npm run format:check` | Formats the codebase / checks formatting with `vp fmt`. |
| `npm run lint` / `npm run lint:fix` | Lints the codebase with `vp lint`. |
| `npm run test` | Runs the unit test suite with `vp test`. |
| `npm run test:coverage` | Runs tests with coverage (`vp test run --coverage`). |
| `npm run test:bun` | Runs the test suite on [Bun](https://bun.sh) (`bun test src`). |
| `npm run test:deno` | Runs the test suite on [Deno](https://deno.com) (`deno test`). |
| `npm run test:live` | Runs the live CEP-provider test against the real network (`RUN_LIVE_CEP_TESTS=1 vp test src/get-address-info-by-cep/get-address-info-by-cep.test.ts`); not part of the regular test run, only of the scheduled `Live tests` workflow. |
| `npm run test:chrome-browser`, `npm run test:firefox-browser`, `npm run test:edge-browser`, `npm run test:safari-browser` | Runs the test suite in real browsers via `vp test --browser.enabled`. |
| `npm run build` | Builds the library for publishing with `vp pack` (also runs attw and publint over the built output). |
| `npm run build:data` | Regenerates the datasets under `src/_internals/constants` from the IBGE/CONCLA sources (`scripts/data.ts`); run by the scheduled `Update datasets` workflow. |
| `npm run build:llms` | Regenerates `docs/llms.txt` and `docs/llms-full.txt` from the docs (`scripts/llms.ts`); CI fails if they're out of date. |
| `npm run check:dependencies` | Fails if `package.json` declares any runtime `dependencies` (this package ships zero by design). |
| `npm run check:duplication` | Runs [jscpd](https://jscpd.dev) over `src` and `scripts`; any copy-pasted block of 5+ lines / 50+ tokens fails. |
| `npm run check:unused` | Runs [knip](https://knip.dev): unused files, exports, types and dependencies fail. |
| `npm run test:mutation` | Runs [Stryker](https://stryker-mutator.io) mutation tests (`stryker run`); pass `-- --mutate src/<util>/<util>.ts` for one file. |
| `npm run check:api` | Builds the package and runs API Extractor over `dist/brazilian-utils.d.ts`: a public type without a doc comment, or a type the API refers to without exporting, fails. |
| `npm run check:commits` | Checks the commit messages since `origin/main` with commitlint (Conventional Commits). |
| `npm run check:lockfile` | Checks `package-lock.json` only resolves to the npm registry over HTTPS with integrity hashes (lockfile-lint). |

Before opening a pull request, make sure `npm run check` and `npm run test` both pass locally. If your
change touches runtime behavior, also consider running the Bun/Deno scripts above. The library is
Expand Down Expand Up @@ -110,8 +114,12 @@ When an exported function has a source to credit, list the authoritative source
`@see Official:` (a law, regulator, standard body or government dataset), followed by one
`@see Based on:` line for every third-party implementation, mirror dataset or reference test
vector the code actually relied on (a GitHub repo, a blog article, a community CSV/JSON mirror,
and so on), one `@see` per line. A utility with no located source of either kind (e.g.
`capitalize`, `formatCurrency`) can be left without an `@see` block. See
and so on), one `@see` per line. A regulator's own repository counts as `Official:` even though it
is a GitHub URL: `https://github.com/bacen/pix-api` is the Banco Central publishing the normative
Pix/SPI specification, not a third party reimplementing it. Put the URL alone on the `@see` line
and the description on the lines below it. Every utility in the package currently has at least one
`@see`; if you add one whose behaviour is a plain convention with no locatable source, say so in
prose in the JSDoc instead of inventing a citation. See
`src/is-valid-certidao/is-valid-certidao.ts` and `src/is-valid-cei/is-valid-cei.ts` for the style.

Shared helpers used by multiple utilities live under `src/_internals/`. Check there before
Expand Down
Loading
Loading