Brazilian Utils

https://github.com/brazilian-utils/javascript
Admin
Zero-dependency, tree-shakeable utils for Brazilian-specific businesses: CPF, CNPJ, boleto, Pix,...
Tokens:274,345
Snippets:991
Trust Score:9.1
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- The package has zero runtime dependencies and ships as ESM plus a UMD build; nothing else needs to be installed to use it.
- Import from the root: import { isValidCpf } from '@brazilian-utils/brazilian-utils'. Every util is also a kebab-case subpath, e.g. '@brazilian-utils/brazilian-utils/is-valid-cpf'.
- Never import the same util from both the root and its subpath in one app: a bundler treats them as two unrelated modules and bundles the dataset twice.
- Public functions never throw on bad input (null, undefined, wrong type): isValid* return false, format* and parse* return '', single-item getters return null, list getters return [].
- The only utils that reject are the async getAddressInfoByCep (GetAddressInfoByCepError: NotFound, Validation, Service) and getCepInfoByAddress (GetCepInfoByAddressError: NotFound, Validation).
- isValid* accept the usual mask characters and whitespace, so there is no need to strip formatting first; format* return the masked string and parse* return the unmasked value.
- Alphanumeric CNPJ (IN RFB 2.229/2024): set the version option to 2 in isValidCnpj, formatCnpj and parseCnpj (second argument, an options object), and call generateCnpj(2) to generate one.
- CNPJ version 2 accepts both numeric and alphanumeric values and folds lowercase to uppercase; the default version 1 is numeric only, so parseCnpj without the version option set to 2 drops the letters.
- CNPJ version 2 has no reserved-value list: a repeated-character alphanumeric base that passes the checksum is valid, unlike the repeated numeric values that version 1 rejects.
- The 1.x aliases formatCEP, formatCNPJ, formatCPF, generateCNPJ, generateCPF, isValidCEP, isValidCNPJ, isValidCPF, isValidIE and isValidPIS are deprecated; use the camelCase names.
- Deprecated since 2.4.0: getCities (use getMunicipalities, which returns { name, code } objects) and the async getMunicipality (use the synchronous, offline getMunicipalityByCode for a code, or getCodeByMunicipalityName for a name).
- Deprecated since 2.4.0: the positional isValidIe(stateCode, ie), replaced by isValidIe({ value, stateCode }), and the 'widenet' provider of getAddressInfoByCep.
- Deprecated since 2.4.0: the *Options type aliases of the single-object-argument functions; use the *Params names (GetHolidaysParams, IsHolidayParams, GetMunicipalityParams, ...).
- Every util is synchronous and pure except getAddressInfoByCep, getCepInfoByAddress and the deprecated getMunicipality, which are async; the first two query public CEP APIs over HTTPS.
- The generate* utils draw random values with Math.random() (generatePixPayload is the exception, built from its parameters), so use them for tests and fixtures, never for security.
- Supported runtimes: Node.js ^20.19.0 || >=22.12.0, Bun, Deno and evergreen browsers. Types ship with the package; import option and result types by name from the root.
- toStandardSchema(isValidCpf, options) wraps any isValid* in a Standard Schema (the ~standard interface) for TanStack Form, tRPC, Hono and the like; inside Zod use z.string().refine(isValidCpf), inside Valibot v.check(isValidCpf).

================
CODE SNIPPETS
================
### Prompt for Context7 MCP server

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Example prompt for a coding agent connected to the Context7 MCP server to use the library.

```text
Validate a CNPJ with Brazilian Utils. use library /brazilian-utils/javascript
```

--------------------------------

### Import and use isValidCpf

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Shows how to import a function from the package root and call it. The example returns false for the given CPF.

```javascript
import { isValidCpf } from '@brazilian-utils/brazilian-utils';

isValidCpf('1232454233345'); // false
```

--------------------------------

### Install with npm

Source: https://github.com/brazilian-utils/javascript/blob/main/README.md

Install the package via npm. The same package works with yarn, pnpm, and bun.

```bash
npm install @brazilian-utils/brazilian-utils
```

--------------------------------

### Lazy-load getCities from subpath

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Shows dynamic import from the get-cities subpath to avoid bundling the heavy dataset into the main bundle. The example calls getCities('SP').

```javascript
const { getCities } = await import('@brazilian-utils/brazilian-utils/get-cities');

getCities('SP');
```

--------------------------------

### Lazy-load getMunicipalityByCode from subpath

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Shows dynamic import from the get-municipality-by-code subpath to avoid bundling the heavy dataset into the main bundle. The example calls getMunicipalityByCode('3550308').

```javascript
const { getMunicipalityByCode } = await import(
  '@brazilian-utils/brazilian-utils/get-municipality-by-code'
);

getMunicipalityByCode('3550308');
```

--------------------------------

### Development commands

Source: https://github.com/brazilian-utils/javascript/blob/main/README.md

Install dependencies, run checks, tests, and build the project. Requires Node.js 24 as specified in .nvmrc.

```bash
npm install
npm run check
npm test
npm run build
```

--------------------------------

### getGtinInfo usage examples

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Parses GTIN values into a GtinInfo object. Returns null for invalid GTINs under the same rules as isValidGtin. The prefix is determined per GS1 General Specifications, and isBrazilian is true for prefixes 789 or 790. The last example shows a null result for a wrong check digit.

```javascript
import { getGtinInfo } from '@brazilian-utils/brazilian-utils';

getGtinInfo('7890000000017');
// { type: 'GTIN-13', length: 13, prefix: '789', isBrazilian: true,
//   isRestrictedCirculation: false, checkDigit: 7 }

getGtinInfo('17890000000014');
// { type: 'GTIN-14', length: 14, prefix: '789', isBrazilian: true,
//   isRestrictedCirculation: false, checkDigit: 4 }

getGtinInfo('061414112345');
// { type: 'GTIN-12', length: 12, prefix: '006', isBrazilian: false,
//   isRestrictedCirculation: false, checkDigit: 5 }

getGtinInfo('2000000000015')?.isRestrictedCirculation; // true (in-store number)
getGtinInfo('7890000000018'); // null (wrong check digit)
```

--------------------------------

### v1 imports and usage of isValidCPF, formatCPF, generateCNPJ

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/guides/migration-v1-to-v2.md

Shows the v1 API before migration, using the old camelCase function names. Replace these with the v2 names as shown in the 'After (v2)' example.

```javascript
import { isValidCPF, formatCPF, generateCNPJ } from '@brazilian-utils/brazilian-utils';

const isValid = isValidCPF('12345678909');
const formatted = formatCPF('12345678909');
const cnpj = generateCNPJ();
```

--------------------------------

### Import and use isValidCpf

Source: https://github.com/brazilian-utils/javascript/blob/main/README.md

Import the isValidCpf function from the package and call it with a CPF string. The example shows a false return for an invalid CPF.

```javascript
import { isValidCpf } from "@brazilian-utils/brazilian-utils";

isValidCpf("1232454233345"); // false
```

--------------------------------

### addBusinessDays usage examples

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Shows how to use addBusinessDays from @brazilian-utils/brazilian-utils to add or subtract Brazilian business days, skipping weekends and holidays. Options include includeOptional, includeSaturday, and stateCode. Returns null for invalid dates or non-integer amounts.

```javascript
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)
```

--------------------------------

### getCepInfoByAddress usage example

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Fetches CEPs for an address from ViaCEP. The argument requires federalUnit, city, and street; city and street are trimmed and stripped of accents, and each must be at least 3 characters. Rejects with GetCepInfoByAddressValidationError for invalid input, GetCepInfoByAddressNotFoundError when no address matches, and GetCepInfoByAddressError on HTTP errors. ViaCEP caps results at 50 addresses.

```javascript
import { getCepInfoByAddress } from '@brazilian-utils/brazilian-utils';

const ceps = await getCepInfoByAddress({
  federalUnit: 'MG',
  city: 'Ouro Preto',
  street: 'Rua Direita'
});

// [
//   {
//     cep: '35411-152',
//     logradouro: 'Rua Direita',
//     complemento: '',
//     unidade: '',
//     bairro: 'Riacho (Amarantina)',
//     localidade: 'Ouro Preto',
//     uf: 'MG',
//     estado: 'Minas Gerais',
//     regiao: 'Sudeste',
//     ibge: '3146107',
//     gia: '',
//     ddd: '31',
//     siafi: '4921'
//   }
// ]
```

--------------------------------

### isValidNfeKey usage examples

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Validates DF-e access keys (44 characters) for models like NF-e, NFC-e, CT-e, MDF-e, etc. Handles XML Id prefixes, masking characters, and alphanumeric CNPJ. Rejects invalid separators, cUF, mod, tpEmis, and cNF per rule B03-10.

```javascript
import { isValidNfeKey } from '@brazilian-utils/brazilian-utils';

isValidNfeKey('35170458716523000119550010000000121000123458'); // true (NF-e, SP)
isValidNfeKey('NFe35170458716523000119550010000000121000123458'); // true (XML Id prefix)
isValidNfeKey('CTe35170458716523000119570010000000128000123452'); // true (CT-e authorised by the SVC-SP)
isValidNfeKey('3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458'); // true (masked)
isValidNfeKey('3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458'); // true (any of the mask characters)
isValidNfeKey('35260712ABC34501DE35550010000001231102030403'); // true (alphanumeric CNPJ 12ABC34501DE35)
isValidNfeKey('35260712ABC34501DEA5550010000001231102030408'); // false (a letter in position 19, a CNPJ check digit)
isValidNfeKey('351 70458716523000119550010000000121000123458'); // false (a separator inside a group of 4)
isValidNfeKey('99170458716523000119550010000000121000123458'); // false (invalid cUF)
isValidNfeKey('35170458716523000119010010000000121000123450'); // false (invalid mod)
isValidNfeKey('35170458716523000119550010000000128000123455'); // false (the NF-e MOC does not assign tpEmis 8)
isValidNfeKey('35170458716523000119550010000000121000000003'); // false (cNF 00000000, rule B03-10)
```

--------------------------------

### Use validators directly in Zod or Valibot schemas

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Plug validators like isValidCpf and isValidCep directly into Zod or Valibot schemas without a wrapper; the result is itself a Standard Schema. The example shows both schema types and a react-hook-form resolver that accepts either. Requires the @hookform/resolvers/standard-schema package.

```javascript
import { standardSchemaResolver } from '@hookform/resolvers/standard-schema';
import { isValidCep, isValidCpf } from '@brazilian-utils/brazilian-utils';
import { useForm } from 'react-hook-form';
import * as v from 'valibot';
import { z } from 'zod';

const zodSchema = z.object({
  cpf: z.string().refine(isValidCpf, 'CPF inválido'),
  cep: z.string().refine(isValidCep, 'CEP inválido'),
});

const valibotSchema = v.object({
  cpf: v.pipe(v.string(), v.check(isValidCpf, 'CPF inválido')),
  cep: v.pipe(v.string(), v.check(isValidCep, 'CEP inválido')),
});

const form = useForm({ resolver: standardSchemaResolver(zodSchema) }); // or valibotSchema
```

--------------------------------

### getCest: Look up CEST code and get description and segment

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Looks up a CEST code and returns a Cest record with code, description, and segment. Returns null for unknown, revoked, or malformed codes. Accepts both string and numeric inputs, but numeric inputs must be non-negative safe integers.

```javascript
import { getCest } from '@brazilian-utils/brazilian-utils';

getCest('05.001.00'); // { code: '0500100', description: 'Cimento', segment: 'Cimentos' }
getCest(500100); // { code: '0500100', description: 'Cimento', segment: 'Cimentos' }
getCest('03.001.00'); // null (a revoked item)
getCest('0000000'); // null
getCest('abc0500100'); // null (not a documented form)
```

--------------------------------

### Load via script tag

Source: https://github.com/brazilian-utils/javascript/blob/main/README.md

Load the UMD build in a plain HTML script tag, exposing the global BrazilianUtils.

```html
<script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.umd.cjs"></script>
```

--------------------------------

### getHolidays - Get holidays for a specific state

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Calls getHolidays with an object containing year and stateCode to retrieve national holidays plus state-specific holidays for that state. The example uses stateCode 'SP' and notes that it includes state-specific holidays like 'Revolução Constitucionalista'.

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

--------------------------------

### generateCnpj and the version

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/guides/migration-v1-to-v2.md

Explains how `generateCnpj` behaves with and without arguments, and how to specify a version.

```APIDOC
### `generateCnpj` and the version

`generateCnpj()` without arguments generates a numeric CNPJ in v2.x. In v3.0.0 it will pick numeric or alphanumeric at random, so pass the version when you need a specific one:

```javascript
generateCnpj(1); // always numeric
generateCnpj(2); // always alphanumeric, e.g. "Q0SLFMBD7VX439"
generateCnpj(); // numeric today, random in v3.0.0
```

`isValidCnpj` validates numeric CNPJs by default. To validate alphanumeric ones, pass `{ version: 2 }`:

```javascript
isValidCnpj('12.345.678/0001-95'); // true
isValidCnpj('Q0.SLF.MBD/7VX4-39', { version: 2 }); // true
isValidCnpj('Q0.SLF.MBD/7VX4-39'); // false (numeric only without the option)
```
```

--------------------------------

### formatBoleto

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Formats a boleto number. Accepts an optional options object with a `pad` property to left-pad the value with zeros to the length of the pattern before masking. A 48-digit linha digitável starting with '8' gets the arrecadação mask; the 44-digit arrecadação barcode keeps the 'cobrança bancária' mask.

```APIDOC
## formatBoleto

### Description
Formats a boleto number. Accepts an optional options object with a `pad` property to left-pad the value with zeros to the length of the pattern before masking. A 48-digit linha digitável starting with '8' gets the arrecadação mask; the 44-digit arrecadação barcode keeps the 'cobrança bancária' mask.

### Method
N/A (JavaScript function)

### Endpoint
N/A

### Parameters
- **boleto** (string) - Required - The boleto value to format.
- **options** (FormatBoletoOptions) - Optional - An object with a `pad` boolean property (default `false`).

### Response
#### Success Response (200)
- **string** - The formatted boleto string.

### Request Example
```javascript
import { formatBoleto } from '@brazilian-utils/brazilian-utils';

formatBoleto('00190000090114971860168524522114675860000102656'); // 00190.00009 01149.718601 68524.522114 6 75860000102656
formatBoleto('1900000901149', { pad: true }); // 00000.00000 00000.000000 00000.000000 0 01900000901149
formatBoleto('846100000005246100291102005460339004695895061080'); // 84610000000-5 24610029110-2 00546033900-4 69589506108-0 (48 digit arrecadação linha digitável)
formatBoleto('84610000000246100291100054603390069589506108'); // 84610.00000 02461.002911 00054.603390 0 69589506108 (44 digit arrecadação barcode keeps the bancária mask)
```
```

--------------------------------

### formatLicensePlate - Format license plates with progressive masking

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Formats a license plate: old Brazilian plates (LLLNNNN) get a hyphen, Mercosul plates (LLLNLNN) are returned without a separator. Returns an empty string when the value cannot start a valid plate. Works as an input mask, formatting partial values progressively.

```javascript
import { formatLicensePlate } from '@brazilian-utils/brazilian-utils';

formatLicensePlate('abc1234'); // 'ABC-1234'
formatLicensePlate('abc1d23'); // 'ABC1D23'
formatLicensePlate('abc1'); // 'ABC-1' (a partial value is formatted as far as it goes)
formatLicensePlate('abc1d'); // 'ABC1D'
```

--------------------------------

### n-th and last business day of a month

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Computes the n-th or last business day of a month by starting from a day just outside the month. Includes examples for the CLT art. 459 § 1º payroll deadline using includeSaturday. Results may land in the next month if n exceeds available business days.

```javascript
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)
```

--------------------------------

### getAddressInfoByCep errors

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/guides/migration-v1-to-v2.md

Shows how to handle errors thrown by `getAddressInfoByCep` using the provided error classes.

```APIDOC
### `getAddressInfoByCep` errors

```javascript
import {
  getAddressInfoByCep,
  GetAddressInfoByCepValidationError,
  GetAddressInfoByCepNotFoundError,
  GetAddressInfoByCepServiceError
} from '@brazilian-utils/brazilian-utils';

try {
  const address = await getAddressInfoByCep('01310100');
} catch (error) {
  if (error instanceof GetAddressInfoByCepValidationError) {
    // invalid CEP
  } else if (error instanceof GetAddressInfoByCepNotFoundError) {
    // no address for this CEP
  } else if (error instanceof GetAddressInfoByCepServiceError) {
    // the providers failed
  }
}
```
```

--------------------------------

### v2 imports and usage of isValidCpf, formatCpf, generateCnpj

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/guides/migration-v1-to-v2.md

Shows the v2 API with the renamed functions. Use these names after migrating from v1.

```javascript
import { isValidCpf, formatCpf, generateCnpj } from '@brazilian-utils/brazilian-utils';

const isValid = isValidCpf('12345678909');
const formatted = formatCpf('12345678909');
const cnpj = generateCnpj();
```

--------------------------------

### isValidIe usage examples

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Validates a state registration (IE) using the object form. The stateCode is case-insensitive and surrounding whitespace is ignored. The examples show valid and invalid registrations, including special cases like produtor rural (SP) and 9-digit MT.

```javascript
import { isValidIe } from '@brazilian-utils/brazilian-utils';

isValidIe({ value: '110042490114', stateCode: 'SP' }); // true
isValidIe({ value: 'P011004243002', stateCode: 'SP' }); // true (produtor rural)
isValidIe({ value: '0187634580933', stateCode: 'AC' }); // false
isValidIe({ value: '109161793', stateCode: 'go' }); // true (case-insensitive)
isValidIe({ value: '109161793', stateCode: ' GO ' }); // true (surrounding whitespace ignored)
isValidIe({ value: '200000004', stateCode: 'GO' }); // true (prefix 20)
isValidIe({ value: '130000019', stateCode: 'MT' }); // true (9 digits)
```

--------------------------------

### getAddressInfoByCep error handling with custom error classes

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/guides/migration-v1-to-v2.md

Shows how to catch and distinguish validation, not-found, and service errors when calling getAddressInfoByCep. The error classes are exported from the package.

```javascript
import {
  getAddressInfoByCep,
  GetAddressInfoByCepValidationError,
  GetAddressInfoByCepNotFoundError,
  GetAddressInfoByCepServiceError
} from '@brazilian-utils/brazilian-utils';

try {
  const address = await getAddressInfoByCep('01310100');
} catch (error) {
  if (error instanceof GetAddressInfoByCepValidationError) {
    // invalid CEP
  } else if (error instanceof GetAddressInfoByCepNotFoundError) {
    // no address for this CEP
  } else if (error instanceof GetAddressInfoByCepServiceError) {
    // the providers failed
  }
}
```

--------------------------------

### getHolidays - Get national and optional holidays for a year

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Imports getHolidays from @brazilian-utils/brazilian-utils and retrieves all holidays for 2024, including national, optional, and religious types. The output shows the full list with names, dates, and types. Use this to get a complete list of Brazilian holidays for a given year.

```javascript
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' },
// ]
```

--------------------------------

### generatePhone - random Brazilian phone number

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Generates a random Brazilian phone number. Accepts 'mobile', 'landline', or 'service' (GeneratePhoneType); when omitted, generates a mobile or landline at random, never a service number. Mobile starts with 9 after DDD; landline has 8 digits starting with 2-5; service has no DDD.

```javascript
import { generatePhone } from '@brazilian-utils/brazilian-utils';

generatePhone(); // '11912345678' or '1131234567'
generatePhone('mobile'); // '11912345678'
generatePhone('landline'); // '1131234567'
generatePhone('service'); // '08001234567' or '40041234'
```

--------------------------------

### getAddressInfoByCep usage examples

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Shows how to fetch address info by CEP using default providers, a specific provider, number input, and a timeout. The default providers are ['viacep', 'brasilapi']; 'widenet' is deprecated. A string CEP strips non-digits and must leave 8 digits; a number is left-padded to 8 digits. The call rejects with GetAddressInfoByCepNotFoundError when no provider knows the CEP, and with GetAddressInfoByCepServiceError on other failures.

```javascript
import { getAddressInfoByCep, GetAddressInfoByCepNotFoundError } from '@brazilian-utils/brazilian-utils';

// Using the default providers (['viacep', 'brasilapi'])
const address = await getAddressInfoByCep('01310100');
// { cep: '01310100', state: 'SP', city: 'São Paulo', neighborhood: 'Bela Vista', street: 'Avenida Paulista' }

// Using a specific provider, and telling an unknown CEP from a failure
try {
  await getAddressInfoByCep('01310-100', { providers: ['brasilapi'] });
} catch (error) {
  if (error instanceof GetAddressInfoByCepNotFoundError) {
    // no provider knows the CEP
  }
}

// Using number input (will be padded automatically)
const addressFromNumber = await getAddressInfoByCep(1310100);

// Giving up after 5 seconds
const addressWithinFiveSeconds = await getAddressInfoByCep('01310100', { timeoutMs: 5000 });
```

--------------------------------

### isValidCns

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Checks if a CNS (Cartão Nacional de Saúde) number is valid. The value must be 15 digits, optionally split into groups of 3-4-4-4 by whitespace, '.', '-', or '/'. It supports definitive cards (starting with 1 or 2) and provisional ones (starting with 7, 8, or 9), each with its own modulus 11 rule.

```APIDOC
## isValidCns

### Description
Checks if a CNS (Cartão Nacional de Saúde) number is valid. The value must be 15 digits, optionally split into groups of 3-4-4-4 by whitespace, '.', '-', or '/'. It supports definitive cards (starting with 1 or 2) and provisional ones (starting with 7, 8, or 9), each with its own modulus 11 rule.

### Method
isValidCns

### Parameters
- **value** (string|number) - Required - The CNS number to validate. Must be a non-negative safe integer or a string with 15 digits, optionally formatted.

### Returns
- **boolean** - `true` if the CNS is valid, `false` otherwise.

### Request Example
```javascript
import { isValidCns } from '@brazilian-utils/brazilian-utils';

isValidCns('123456789010000'); // true (definitive)
isValidCns('100000000060018'); // true (definitive, raw check digit 10, suffix 001)
isValidCns('700000000000005'); // true (provisional)
isValidCns('123.4567-8901/0000'); // true (any of the mask characters)
isValidCns(-123456789010000); // false (not a non-negative safe integer)
isValidCns('123456789010001'); // false (wrong check digit)
isValidCns('12345678901'); // false (wrong length)
isValidCns('abc123456789010000'); // false (not written as a CNS)
```
```

--------------------------------

### generatePixPayload with key, amount, and merchant details

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Generates a static Pix BR Code payload using a key (normalized by getPixKeyInfo). The key is required; amount is optional and must have two decimal places. The output is a string representing the BR Code payload.

```javascript
import { generatePixPayload } from '@brazilian-utils/brazilian-utils';

generatePixPayload({
  key: '123.456.789-09',
  merchantName: 'Fulano de Tal',
  merchantCity: 'Brasília',
  amount: 123.45
});
// "00020126330014br.gov.bcb.pix0111123456789095204000053039865406123.455802BR5913Fulano de Tal6008Brasilia62070503***630479EE"
```

--------------------------------

### isValidVin usage examples

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Validates a VIN (Vehicle Identification Number) according to Brazilian rules (Resolução CONTRAN nº 968/2022) by default, with optional North-American check digit enforcement (49 CFR 565.15). The function is case-insensitive, trims whitespace, rejects repeated-character values, and rejects separators or non-ASCII letters. The examples show true/false results for various VINs and options.

```javascript
import { isValidVin } from '@brazilian-utils/brazilian-utils';

isValidVin('9BWZZZ377VT004251'); // true (Brazilian VIN, no check digit)
isValidVin('9BWZZZ377VT004251', { checkDigit: true }); // false (its 9th character is not the check digit)
isValidVin('1HGCM82633A004352', { checkDigit: true }); // true
isValidVin('1m8gdm9axkp042788', { checkDigit: true }); // true (check digit X, lowercase)
isValidVin('1HGCM82633A004353', { checkDigit: true }); // false (bad check digit)
isValidVin('00000000000000000'); // false (every character the same)
isValidVin('1HGCM8263IA004352'); // false (contains the excluded letter I)
isValidVin('1HGCM82633A00435'); // false (16 characters)
isValidVin('1HGCM 82633 A004352'); // false (a separator among the characters)
```

--------------------------------

### getNfseKeyInfo(key)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Parses the access key of a national NFS-e into its fields, returning an NfseKeyInfo object. Returns null when the key is not valid.

```APIDOC
## getNfseKeyInfo(key)

### Description
Parses the access key of a national NFS-e into its fields, returning an `NfseKeyInfo` object. Accepts the same input forms as `isValidNfseKey`. Returns `null` when the key is not valid.

### Method
Function

### Endpoint
`getNfseKeyInfo(key)`

### Parameters
- **key** (string) - Required - The NFS-e access key to parse.

### Returns
- **municipalityCode** (string) - The municipality code.
- **stateCode** (string) - The state code.
- **generatorEnvironment** (NfseKeyGeneratorEnvironment) - `1` for the system of the municipality, `2` for the Sistema Nacional NFS-e.
- **taxIdType** (NfseKeyTaxIdType) - `'cpf'` or `'cnpj'`.
- **taxId** (string) - The CPF (11 digits, without the `000` padding) or CNPJ (14 characters, numeric or alphanumeric, upper case).
- **number** (number) - The number.
- **year** (number) - The year.
- **month** (number) - The month.
- **code** (string) - The code.
- **checkDigit** (number) - The check digit.

### Request Example
```javascript
import { getNfseKeyInfo } from '@brazilian-utils/brazilian-utils';

getNfseKeyInfo('35503082258716523000119000000000001226011357924683');
```

### Response Example
```javascript
// { municipalityCode: '3550308', stateCode: 'SP', generatorEnvironment: 2, taxIdType: 'cnpj',
//   taxId: '58716523000119', number: 12, year: 2026, month: 1, code: '135792468', checkDigit: 3 }
```

### Request Example
```javascript
getNfseKeyInfo('43149021100040364478829000000000105725120484407255');
```

### Response Example
```javascript
// { municipalityCode: '4314902', stateCode: 'RS', generatorEnvironment: 1, taxIdType: 'cpf',
//   taxId: '40364478829', number: 1057, year: 2025, month: 12, code: '048440725', checkDigit: 5 }
```

### Request Example
```javascript
getNfseKeyInfo('35503082212ABC34501DE35000000000001226091357924682');
```

### Response Example
```javascript
// { municipalityCode: '3550308', stateCode: 'SP', generatorEnvironment: 2, taxIdType: 'cnpj',
//   taxId: '12ABC34501DE35', number: 12, year: 2026, month: 9, code: '135792468', checkDigit: 2 }
```

### Request Example
```javascript
getNfseKeyInfo('invalid');
```

### Response Example
```javascript
// null
```
```

--------------------------------

### parseCfop

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Removes CFOP formatting, keeping only digits, and caps the result to 4 digits. No CFOP code starts with a zero, so nothing is padded here.

```APIDOC
## parseCfop

### Description
Remove CFOP (Código Fiscal de Operações e Prestações) formatting, keep only digits, and cap the result to 4 digits.

- No CFOP code starts with a zero, so nothing is padded here.

### Request Example
```javascript
import { parseCfop } from '@brazilian-utils/brazilian-utils';

parseCfop('5.102'); // '5102'
```
```

--------------------------------

### getRegions

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Get the five Brazilian regions (Grandes Regiões), each with its code, name, and IBGE identifier, in the order of that identifier. Exports the `Region` and `RegionCode` types.

```APIDOC
## getRegions

### Description
Get the five Brazilian regions (Grandes Regiões), each with its code (the same `regionCode` every state carries), name and IBGE identifier, in the order of that identifier. Exports the `Region` and `RegionCode` types.

### Parameters
None.

### Response
#### Success Response
Returns an array of `Region` objects with properties: `code`, `name`, `ibgeCode`.

#### Request Example
```javascript
import { getRegions } from '@brazilian-utils/brazilian-utils';

getRegions();
// [
//   { code: 'N', name: 'Norte', ibgeCode: 1 },
//   { code: 'NE', name: 'Nordeste', ibgeCode: 2 },
//   { code: 'SE', name: 'Sudeste', ibgeCode: 3 },
//   { code: 'S', name: 'Sul', ibgeCode: 4 },
//   { code: 'CO', name: 'Centro-Oeste', ibgeCode: 5 },
// ]
```
```

--------------------------------

### isValidLandlinePhone - Validate Brazilian landline phone numbers

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Checks if a landline phone number is valid, accepting and removing a Brazilian country code (+55, 0055, or bare 55) first. Any character other than digits, whitespace, and `()+.-/` makes the value invalid. The number must be the DDD plus 8 digits starting with 2 to 6 (STFC and SCM range). A scheduled change from 1 March 2027 will leave only 2 to 5 for STFC and move SCM to 9-digit numbers starting with 6.

```javascript
import { isValidLandlinePhone } from '@brazilian-utils/brazilian-utils';

isValidLandlinePhone('1130000000'); // true
isValidLandlinePhone('+55 11 3000-0000'); // true (country code accepted)
```

--------------------------------

### getServiceItem

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Looks up a subitem of the service list annexed to Lei Complementar 116/2003 and returns its official description. Returns a `ServiceItem` record with `code` and `description` fields, or `null` if not found.

```APIDOC
## getServiceItem

### Description
Looks up a subitem of the service list annexed to Lei Complementar 116/2003 and returns its official description. Returns a `ServiceItem` record with `code` and `description` fields, or `null` if not found.

### Method
Function

### Parameters
- **value** (string | number) - Required - The value to look up.

### Returns
- **ServiceItem | null** - An object `{ code, description }` if found, otherwise `null`.

### Request Example
```javascript
import { getServiceItem } from '@brazilian-utils/brazilian-utils';

getServiceItem('1.01'); // { code: '1.01', description: 'Análise e desenvolvimento de sistemas.' }
getServiceItem('0101'); // { code: '1.01', description: 'Análise e desenvolvimento de sistemas.' }
getServiceItem('40.01'); // { code: '40.01', description: 'Obras de arte sob encomenda.' }
getServiceItem('3.01'); // null (vetoed)
```
```

--------------------------------

### formatNfeKey

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Formats a DF-e access key into groups of 4 characters separated by spaces, as printed on DANFE, DACTE, etc. Supports padding, alphanumeric CNPJ, and XML Id prefixes.

```APIDOC
## formatNfeKey

### Description
Formats a DF-e access key into groups of 4 characters separated by spaces, as printed on DANFE, DACTE, etc. Supports padding, alphanumeric CNPJ, and XML Id prefixes.

### Method
Function

### Signature
`formatNfeKey(value, options?)`

### Parameters
- **value** (string | number) - Required - The access key to format.
- **options** (FormatNfeKeyOptions) - Optional - `pad` (boolean, default `false`) left pads the value with zeros up to 44 characters.

### Behavior
- Empty or non-digit values return `''` even with `pad`.
- Masked or partial keys are grouped as far as characters go.
- Letters in positions 7-18 (alphanumeric CNPJ) are kept and upper cased; other letters are dropped.
- XML Id prefixes (`NFe`, `CTe`, `MDFe`, `BPe`, `NF3e`, `NFCom`) are stripped first.
- Non-string, non-non-negative-safe-integer values return `''`.

### Request Example
```javascript
import { formatNfeKey } from '@brazilian-utils/brazilian-utils';

formatNfeKey('35170458716523000119550010000000121000123458');
// '3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458'

formatNfeKey('35260712abc34501de35550010000001231102030403');
// '3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403' (alphanumeric CNPJ)

formatNfeKey('NF3e35170458716523000119550010000000121000123458');
// '3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458' (XML Id prefix)

formatNfeKey('12345'); // '1234 5'

formatNfeKey('12345', { pad: true });
// '0000 0000 0000 0000 0000 0000 0000 0000 0000 0001 2345'
```
```

--------------------------------

### getCnpjInfo(input, options?)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Parses a CNPJ string into its encoded fields (root, branch, check digits) and indicates whether the branch is the initial headquarters. Accepts the same input forms as isValidCnpj and returns null when validation fails.

```APIDOC
## getCnpjInfo(input, options?)

### Description
Parses a CNPJ into the fields the number encodes. Accepts the same input forms as `isValidCnpj` and returns `null` whenever it would return `false` for the same arguments, so an alphanumeric CNPJ read under version `1` is `null`.

### Parameters
- **input** (string) - Required - The CNPJ string to parse.
- **options** (`GetCnpjInfoOptions`) - Optional - `version` is read the way `isValidCnpj` reads it, `1` (default) the numeric-only format, `2` both the numeric and the alphanumeric one.

### Returns
Returns a `CnpjInfo` object with the following fields:
- **root** (string) - The 8-digit raiz that identifies the entity.
- **branch** (string) - The 4-digit establishment (número de ordem).
- **checkDigits** (string) - The 2-digit check digits, always numeric.
- **isInitialHeadquarters** (boolean) - Whether the branch is `0001`, the one the Receita Federal gives the headquarters (matriz) when the root is registered.

### Request Example
```javascript
import { getCnpjInfo } from '@brazilian-utils/brazilian-utils';

getCnpjInfo('12.345.678/0001-95');
```

### Response Example
```javascript
// {
//   root: '12345678',
//   branch: '0001',
//   checkDigits: '95',
//   isInitialHeadquarters: true
// }
```

### Additional Examples
```javascript
getCnpjInfo('12.abc.345/01de-35', { version: 2 });
// {
//   root: '12ABC345',
//   branch: '01DE',
//   checkDigits: '35',
//   isInitialHeadquarters: false
// }

getCnpjInfo('12.ABC.345/01DE-35'); // null (alphanumeric, read under version 1)
getCnpjInfo('12.345.678/0001-90'); // null (bad check digits)
```
```

--------------------------------

### parseCfop - Remove CFOP formatting and keep digits

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Removes CFOP formatting, keeps only digits, and caps the result to 4 digits. No padding is applied because no CFOP code starts with zero.

```javascript
import { parseCfop } from '@brazilian-utils/brazilian-utils';

parseCfop('5.102'); // '5102'
```
Tokens:
Raw