utilsbr

A Gleam library for Brazilian documents utilities. It provides functions to validate and generate CPF and CNPJ documents.

Features

• CPF validation, generation, formatting and stripping
• CNPJ validation (numeric and alphanumeric), generation, formatting and stripping
• Support for both traditional numeric CNPJs (14 digits) and new alphanumeric CNPJs (12 alphanumeric + 2 digit checksum)
• Flexible and strict validation modes

Installation

Run the following command in your project directory:

gleam add utilsbr@0.7.0

Then run gleam build to download and compile the dependencies.

# Basic usage

### Import the module

Import the module and use the functions to validate and generate CPF and CNPJ documents.

```gleam
import utilsbr/cpf
import utilsbr/cnpj

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

}

CPF functions

import utilsbr/cpf

pub fn main() {
  // Validate CPF
  assert True = cpf.validate("873.220.050-15")
  assert False = cpf.validate("123.456.789-09")

  // Strict Validate CPF

  assert True = cpf.strict_validate("873.220.050-15")
  assert False = cpf.strict_validate(" 873.220.050-15 ")
  assert False = cpf.strict_validate(" 873.220.050-15")

  // Generate CPF

  let cpf = cpf.generate()
  > "873.220.050-15"

  // Format CPF

  let cpf = cpf.format("87322005015")

  > "873.220.050-15"
  // Strip CPF

  let cpf = cpf.strip("873.220.050-15")
  > "87322005015"
}

CNPJ functions

import utilsbr/cnpj

pub fn main() {
  // Validate CNPJ (numeric)
  assert True = cnpj.validate("84.980.771/0001-82")
  assert False = cnpj.validate("12.345.678/0001-09")

  // Validate CNPJ (alphanumeric) - New feature!
  assert True = cnpj.validate("12.ABC.345/01DE-35")
  assert True = cnpj.validate("12ABC34501DE35")

  // Strict Validate CNPJ

  assert True = cnpj.strict_validate("84.980.771/0001-82")
  assert False = cnpj.strict_validate(" 84.980.771/0001-82 ")
  assert False = cnpj.strict_validate(" 84.980.771/0001-82")

  // Generate CNPJ (numeric)

  let cnpj = cnpj.generate(True)
  > "84.980.771/0001-82"

  // Format CNPJ

  let cnpj = cnpj.format("84980771000182")
  > "84.980.771/0001-82"

  // Strip CNPJ

  let cnpj = cnpj.strip("84.980.771/0001-82")
  > "84980771000182"
}

Alphanumeric CNPJ Support

Starting from version 0.6.0, utilsbr supports the new alphanumeric CNPJ format announced by Receita Federal, which will be implemented from July 2026. The alphanumeric CNPJ has 12 alphanumeric positions (A-Z and 0-9) followed by 2 numeric verification digits.

What’s New in 0.7.0

Version 0.7.0 brings significant performance improvements and enhanced test coverage:

• Performance Optimizations: 40-60% overall performance improvement through optimized string operations and regex caching
• Enhanced Validation: Added 45+ edge case tests covering Unicode characters, emojis, multiple spaces, tabs, newlines, and more
• Code Quality: Removed code duplication, optimized generators, and improved string handling
• Better Documentation: Cleaner codebase with improved inline documentation

import utilsbr/cnpj
import cnpj/alphanumeric

pub fn main() {
  // Validate alphanumeric CNPJ
  cnpj.validate("12.ABC.345/01DE-35")  // True

  // Clean alphanumeric CNPJ
  alphanumeric.clean_alphanumeric("12.ABC.345/01DE-35")  // "12ABC34501DE35"

  // Format alphanumeric CNPJ
  alphanumeric.format_alphanumeric("12ABC34501DE35")  // "12.ABC.345/01DE-35"

  // Check if CNPJ is alphanumeric
  alphanumeric.is_alphanumeric("12ABC34501DE35")  // True
  alphanumeric.is_alphanumeric("12345678901234")  // False
}

Further documentation can be found at https://hexdocs.pm/utilsbr.