JavaScript library

What the JavaScript library implements from the shared contract, what fails, and what to do next.

Install

npm install @brazilian-utils/brazilian-utils

Runs on

Runtime	Supported	Tested in CI
Node.js	`^20.19.0 \|\| >=22.12.0`	20, 22, 24, 26
Bun	`latest`	latest
Deno	`2.x`	2.x
Browsers	`evergreen`	Chrome, Firefox, Edge, Safari

JavaScript implements 180 of the 182 contract functions and 100% of the core functions. 5033 shared cases pass and 0 fail.

Compared with the other libraries

Library	Core functions	Implemented	Cases that pass
JavaScript	100%	180/182	5033
Rust library	37.5%	132/182	1732
Go library	35%	136/182	2081
.NET library	32.5%	133/182	2194
Ruby library	27.5%	133/182	2589
Python library	17.5%	40/182	500
Erlang library	12.5%	29/182	340

What to do next

The list starts with failing functions, then wrong signatures, then missing core functions, then the rest. In each group, functions implemented by more libraries come first, since there is more code to port from. Each item is also an issue in the library's repository.

Nothing to do. The library implements every contract function and passes every case.

API conventions

These rules hold for every function unless its section says otherwise.

Nothing throws on bad input (null, undefined, the wrong type): isValid* return false, format* and parse* return '', single-item get* return null, list get* return []. The only exceptions are the async getAddressInfoByCep and getCepInfoByAddress, which reject with typed errors.
Validators accept the value masked or not: the usual mask characters (., -, /) and spaces between or around the groups are ignored, so there is no need to strip formatting first.
A number is read only when it is a non-negative safe integer: the functions that take string | number treat a negative, fractional, non-finite or unsafe number as bad input (isValidCep(-20040020) is false, formatCpf(-1) and parseCpf(1.5) are ''), since in a number - and . are not mask characters.
Formatters mask as far as the value goes, so they also work as input masks while the user types. parse* functions do the reverse and keep only the meaningful characters.
Generators use Math.random(), so they are fine for tests and fixtures and never for anything security-related.
Getters return a new array or object on every call, so mutating a result never affects the next call.
Every function is synchronous except getAddressInfoByCep, getCepInfoByAddress and the deprecated getMunicipality.

Badge for your README

The badge shows the share of core functions and the cases that pass, and changes with every run. Paste this Markdown in the library's README:

[![API contract](https://brazilian-utils.com.br/badges/javascript.svg)](https://brazilian-utils.com.br/libs/javascript/)