utilsbr - v0.9.0

utilsbr

Package Version Hex Docs Total Download License Last Updated

A Gleam library for Brazilian document validation and generation. Provides utilities for working with CPF and CNPJ documents, including support for the new alphanumeric CNPJ format.

Features

Installation

gleam add utilsbr

Quick Start

import utilsbr/cpf
import utilsbr/cnpj

pub fn main() {
  // Validate documents
  cpf.validate("873.220.050-15")  // True

  // Validate both numeric and alphanumeric CNPJs
  cnpj.validate("84.980.771/0001-82")  // True (numeric)
  cnpj.validate("12.ABC.345/01DE-35")  // True (alphanumeric)

  // Format and strip work automatically
  cnpj.format("12ABC34501DE35")  // Ok("12.ABC.345/01DE-35")
  cnpj.strip("84.980.771/0001-82")  // Ok("84980771000182")

  // Generate new documents
  let new_cpf = cpf.generate(True)  // "123.456.789-09"
  let new_cnpj = cnpj.generate(False)  // "12345678000195"
}

API Reference

CPF

import utilsbr/cpf

// Validation - flexible mode (allows whitespace and special chars)
cpf.validate("873.220.050-15")  // True
cpf.validate("  873.220.050-15  ")  // True
cpf.validate("123.456.789-09")  // False

// Validation - strict mode (exact format required)
cpf.strict_validate("873.220.050-15")  // True
cpf.strict_validate(" 873.220.050-15 ")  // False

// Generation
cpf.generate(True)  // "873.220.050-15" (formatted)
cpf.generate(False)  // "87322005015" (unformatted)

// Formatting and stripping
cpf.format("87322005015")  // Ok("873.220.050-15")
cpf.strip("873.220.050-15")  // Ok("87322005015")

CNPJ

All CNPJ functions work seamlessly with both numeric and alphanumeric formats. The library automatically detects the format and applies the appropriate validation and formatting rules.

Alphanumeric CNPJ Support: Starting from version 0.6.0, utilsbr supports the new alphanumeric CNPJ format announced by Receita Federal (effective July 2026). The alphanumeric CNPJ consists of 12 alphanumeric characters (A-Z and 0-9) followed by 2 numeric verification digits.

import utilsbr/cnpj

// Validation - flexible mode (works with both formats)
cnpj.validate("84.980.771/0001-82")  // True (numeric)
cnpj.validate("12.ABC.345/01DE-35")  // True (alphanumeric)
cnpj.validate("12abc34501de35")     // True (case insensitive)
cnpj.validate("  84.980.771/0001-82  ")  // True
cnpj.validate("12.345.678/0001-09")  // False

// Validation - strict mode (works with both formats)
cnpj.strict_validate("84.980.771/0001-82")   // True (numeric formatted)
cnpj.strict_validate("84980771000182")        // True (numeric unformatted)
cnpj.strict_validate("12.ABC.345/01DE-35")   // True (alphanumeric formatted)
cnpj.strict_validate("12ABC34501DE35")        // True (alphanumeric unformatted)
cnpj.strict_validate("12.abc.345/01de-35")   // True (case insensitive)
cnpj.strict_validate(" 84.980.771/0001-82 ") // False (no spaces allowed)
cnpj.strict_validate("12*ABC*345*01DE*35")   // False (wrong separators)

// Generation (numeric only)
cnpj.generate(True)  // "84.980.771/0001-82" (formatted)
cnpj.generate(False)  // "84980771000182" (unformatted)

// Formatting - automatic detection
cnpj.format("84980771000182")    // Ok("84.980.771/0001-82")
cnpj.format("12ABC34501DE35")    // Ok("12.ABC.345/01DE-35")
cnpj.format("12abc34501de35")    // Ok("12.ABC.345/01DE-35")

// Stripping - automatic detection
cnpj.strip("84.980.771/0001-82")  // Ok("84980771000182")
cnpj.strip("12.ABC.345/01DE-35")  // Ok("12ABC34501DE35")
cnpj.strip("12.abc.345/01de-35")  // Ok("12ABC34501DE35")

Compatibility

This library works on both the Erlang and JavaScript targets.

Documentation

For detailed API documentation and more examples, visit HexDocs.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache-2.0 License.

✨ Search Document