DOCSEARCHbyAlgolia
Submit Docs

Brazilian Utils

repository·main·Indexed 23 days ago

https://github.com/brazilian-utils/javascript

A JavaScript utility library version 2.3.0 designed for the Brazilian business landscape. It provides tools for validating and formatting Brazilian identification numbers (CPF, CNPJ, PIS, RENAVAM), postal codes (CEP), boletos, phone numbers, and legal process numbers (CNJ). Additional features include BRL currency formatting, bank account validation, retrieval of Brazilian states, cities, and holidays, and address lookup via CEP.

Tokens
12.6K
Snippets
44
Records
59
Agent score
80%

What's inside @brazilian-utils/brazilian-utils

  1. Use alphanumeric CNPJ in v2

    main

    Version 2.0.0 introduces support for the alphanumeric CNPJ format.

    • To generate an alphanumeric CNPJ, pass 2 as the argument to generateCnpj(2).
    • To validate an alphanumeric CNPJ, you must explicitly pass { version: 2 } in the options object. By default, isValidCnpj() only validates numeric (version 1) CNPJs.

    Note on generateCnpj behavior: In v2.x, generateCnpj() defaults to version 1. In v3.0.0, this will change to a random selection between version 1 and 2. To ensure consistent results, always specify the version explicitly.

    import { isValidCnpj, generateCnpj } from '@brazilian-utils/brazilian-utils';

// Generate alphanumeric CNPJ
const alphaCnpj = generateCnpj(2); // e.g., "Q0SLFMBD7VX439"

// Validate alphanumeric CNPJ (requires version option)
isValidCnpj("Q0.SLF.MBD/7VX4-39", { version: 2 }); // true
isValidCnpj("Q0SLFMBD7VX439", { version: 2 }); // true

// Version 1 (numeric) is the default
isValidCnpj("12.345.678/0001-95"); // true (validates numeric only)
isValidCnpj("12.345.678/0001-95", { version: 1 }); // true (explicit)

  2. Use @brazilian-utils/brazilian-utils via <script> tag

    main

    For browser-based environments without a module bundler, you can include the library via a <script> tag. This will expose the library under the global brazilianUtils object.

    <script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.cjs.production.min.js"></script>

  3. Use @brazilian-utils/brazilian-utils via CDN

    main

    For direct usage in the browser without a package manager, you can include the library via a <script> tag. This exposes the library under the global brazilianUtils object.

    <script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.cjs.production.min.js"></script>

  6. Migrate from v1 to v2

    main

    When upgrading from Brazilian Utils v1.x to v2.0.0, most breaking changes are backward compatible. Old PascalCase function names (e.g., formatCPF, isValidCNPJ) still work in v2.x but are deprecated and will be removed in v3.0.0. It is recommended to migrate to the new camelCase names immediately.

    Mandatory Migrations (No Backward Compatibility): You must replace these helper functions before upgrading, as they are no longer exported in the public API:

    • onlyNumbers $\rightarrow$ use string.replace(/\D/g, '')
    • isLastChar $\rightarrow$ use index === input.length - 1
    • generateChecksum $\rightarrow$ now internal only
    • generateRandomNumber $\rightarrow$ now internal only

  7. Summary of Brazilian Utils public API

    main

    The brazilian-utils library provides a comprehensive suite of utilities for handling Brazilian data formats, validation, and generation. The public API is organized into several functional categories:

    Validation

    Verify the validity of Brazilian documents and identifiers:

    • isValidCpf, isValidCnpj, isValidCnh, isValidPis, isValidRenavam, isValidVoterId, isValidPassport, isValidLicensePlate, isValidProcessoJuridico, isValidLegalNature, isValidIe.
    • isValidCep, isValidEmail, isValidPhone, isValidMobilePhone, isValidLandlinePhone, isValidBankAccount.

    Formatting

    Apply standard Brazilian masks and formatting to raw strings:

    • formatCpf, formatCnpj, formatCep, formatCnh, formatPis, formatVoterId, formatPassport, formatLicensePlate, formatProcessoJuridico, formatLegalNature, formatPhone, formatCurrency, formatBoleto.

    Generation

    Generate valid (checksum-compliant) test data:

    • generateCpf, generateCnpj, generateCep, generateCnh, generatePis, generateVoterId, generatePassport, generateLicensePlate, generateProcessoJuridico, generateLegalNature, generatePhone, generateBoleto.

    Parsing

    Extract raw values from formatted strings:

    • parseCpf, parseCnpj, parseCep, parseCnh, parsePis, parseVoterId, parsePassport, parseLicensePlate, parseProcessoJuridico, parseLegalNature, parsePhone, parseCurrency, parseBoleto.

    Information Retrieval

    Fetch data related to Brazilian geography and logistics:

    • getAddressInfoByCep: Get address details from a CEP.
    • getCepInfoByAddress: Get a CEP from an address.
    • getMunicipality: Retrieve municipality info by code or name.
    • getStates, getCities: Retrieve lists of states and cities.
    • getHolidays: Check for Brazilian holidays.
    • isHoliday: Check if a specific date is a holiday.
    • getBoletoInfo: Retrieve information about a boleto.
    • getLegalNatures, getLegalNatures: Retrieve legal nature lists.

  9. Import and use utilities from @brazilian-utils/brazilian-utils

    main

    To use a specific utility, import the required function from the @brazilian-utils/brazilian-utils package. For example, you can use isValidCpf to validate a CPF string.

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

isValidCpf('1232454233345'); // false

  10. Validate and format CPF

    main

    Use the CPF utilities to validate, format, or parse Brazilian individual taxpayer IDs (CPF).

    • isValidCpf(cpf): Returns true if the CPF is valid.
    • formatCpf(cpf, options): Formats a CPF string. Use { pad: true } to add leading zeros if the input is shorter than 11 digits.
    • parseCpf(cpf): Removes all non-digit characters and caps the result to 11 digits.
    • generateCpf(): Generates a valid random CPF.
    import { isValidCpf, formatCpf, parseCpf, generateCpf } from '@brazilian-utils/brazilian-utils';

isValidCpf('155151475'); // false
formatCpf('74650688000'); // 746.506.880-00
formatCpf('746506880', { pad: true }); // 007.465.068-80
parseCpf('746.506.880-00'); // 74650688000
generateCpf();

  11. Fetch CEP info by address with getCepInfoByAddress

    main

    Asynchronously fetch CEP (Postal Code) information using the ViaCEP service based on an address object.

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

const ceps = await getCepInfoByAddress({
  federalUnit: 'SP',
  city: 'Sao Paulo',
  street: 'Avenida Paulista'
});

// Returns array of objects containing: cep, logradouro, complemento, bairro, localidade, uf

  12. Manage Brazilian passports

    main

    The library provides utilities for validating, formatting, generating, and parsing Brazilian passport numbers (2 uppercase letters followed by 6 digits).

    • isValidPassport(value): Validates the format.
    • formatPassport(value): Returns uppercase, no symbols, capped to 8 chars.
    • generatePassport(): Generates a random valid passport.
    • parsePassport(value): Removes non-alphanumeric characters and caps to 8 chars.
    import { isValidPassport, formatPassport, generatePassport, parsePassport } from '@brazilian-utils/brazilian-utils';

isValidPassport('AB123456'); // true
formatPassport('ab123456'); // 'AB123456'
formatPassport('AB-123.456'); // 'AB123456'
generatePassport(); // 'RY393097'
parsePassport('AB-123.456'); // 'AB123456'