v3: breaking changes to make in the next major

[hyanmandian]

This issue lists every change deferred to v3 because it would break 2.x consumers. Anything kept for compatibility, or held back to avoid a break, gets a line here with where it lives in the code, so the v3 release (and its docs/migration-v2-to-v3.md) can be built from this list instead of a grep.

How to add an item: name the export or behaviour, what v3 changes, and the file (or PR) where the compatibility is kept. Tick it when the v3 branch does it.

Deprecated exports to remove

Every one of these carries @deprecated in the code (src/index.ts and the util's own file).

• Upper-case aliases: formatCEP, formatCNPJ, formatCPF, generateCNPJ, generateCPF, isValidCEP, isValidCNPJ, isValidCPF, isValidIE, isValidPIS. Use the camel-case names.

• Old type names: GenerateProcessoJuridicoOptions, GetCepInfoByAddressOptions, GetHolidaysOptions, GetMunicipalityByCodeOptions, GetMunicipalityByNameOptions, GetMunicipalityOptions, IsHolidayOptions, IsValidBankAccountOptions. Use the …Params names (src/index.ts, and src/is-valid-bank-account/is-valid-bank-account.ts, "stays as an alias until v3").

• getCities. Use getMunicipalities (src/get-cities/get-cities.ts).

• getMunicipality, both of its lookups (src/get-municipality/get-municipality.ts):

  • by code: use getMunicipalityByCode;
  • by name: use getCodeByMunicipalityName (branch claude/municipality-code-by-name), which matches the name the same way.

  Both replacements are synchronous and offline.

• The positional form isValidIe(stateCode, ie). Use isValidIe({ value, stateCode }) (src/is-valid-ie/is-valid-ie.ts; its tests say it "has to keep working [...] until v3").

Defaults to change

• CNPJ: make version 2 (alphanumeric) the default of isValidCnpj, formatCnpj and generateCnpj, which default to 1 (numeric only) in 2.x.

Compatibility behaviours to decide on

Each of these keeps a 2.x behaviour on purpose. For each one, v3 either keeps it (and documents it as intended) or drops it.

• formatCurrency coerces any other value through Number() the way 2.3.0 did, so null, [] and true still format (src/format-currency/format-currency.ts).

Considered and not deferred

• getHolidays and the business day utils ignoring an unknown stateCode: fixed without a break in fix(holidays): read stateCode like the other state utils, and follow the official texts on the open holiday questions #603. The code is now read ignoring case and whitespace, and a value that is not a state code is rejected ([], false or null).
• isValidPixPayload reading a lower-case CRC ("1d3d") as upper case (src/is-valid-pix-payload/is-valid-pix-payload.ts): kept on purpose. No official source states the case of the CRC's hexadecimal digits (the BCB manuals only show upper-case examples), so by the stack's rule the behaviour stays and is documented. Revisit only if a source such as the EMVCo MPM specification (ID 63) is found requiring upper case.
• State with capital and regionIbgeCode (feat(states): add getStateCapital, getRegions and getStatesByRegion #601): dropped instead of being made optional-then-required, because it grew getStates, getStateByIbgeCode and getStateByCep by about 870 B each. The capital lives in getStateCapital and the region identifier in getRegions, so State has nothing pending for v3.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH