Biblioteca JavaScript

O que a biblioteca JavaScript implementa do contrato compartilhado, o que falha e o que fazer agora.

Instalação

npm install @brazilian-utils/brazilian-utils

Roda em

Ambiente	Suportado	Testado no CI
Node.js	`^20.19.0 \|\| >=22.12.0`	20, 22, 24, 26
Bun	`a mais recente`	a mais recente
Deno	`2.x`	2.x
Navegadores	`versões atuais`	Chrome, Firefox, Edge, Safari

JavaScript implementa 180 das 182 funções do contrato e 100% das funções principais. 5033 casos compartilhados passam e 0 falham.

Comparação com as outras bibliotecas

Biblioteca	Funções principais	Implementadas	Casos que passam
JavaScript	100%	180/182	5033
Rust, biblioteca	37.5%	132/182	1732
Go, biblioteca	35%	136/182	2081
.NET, biblioteca	32.5%	133/182	2194
Ruby, biblioteca	27.5%	133/182	2589
Python, biblioteca	17.5%	40/182	500
Erlang, biblioteca	12.5%	29/182	340

O que fazer agora

A lista começa pelas funções que falham, depois assinaturas erradas, depois funções principais que faltam, depois o resto. Em cada grupo, vêm primeiro as funções implementadas por mais bibliotecas, porque há mais código de onde portar. Cada item também é uma issue no repositório da biblioteca.

Nada a fazer. A biblioteca implementa todas as funções do contrato e todos os casos passam.

Convenções da API

Estas regras valem para todas as funções, a não ser que a seção diga o contrário.

Nada lança erro com entrada inválida (null, undefined, tipo errado): isValid* retornam false, format* e parse* retornam '', get* de um item retornam null, get* de lista retornam []. As únicas exceções são as assíncronas getAddressInfoByCep e getCepInfoByAddress, que rejeitam com erros tipados.
Validadores aceitam o valor com ou sem máscara: os caracteres de máscara usuais (., -, /) e espaços entre ou ao redor dos grupos são ignorados, então não é preciso limpar a formatação antes.
Um número só é lido quando é um inteiro seguro não negativo: as funções que recebem string | number tratam um número negativo, fracionário, não finito ou inseguro como entrada inválida (isValidCep(-20040020) é false, formatCpf(-1) e parseCpf(1.5) são ''), já que num número - e . não são caracteres de máscara.
Formatadores aplicam a máscara até onde o valor vai, então também servem como máscara de digitação. As funções parse* fazem o inverso e mantêm só os caracteres que importam.
Geradores usam Math.random(), então servem para testes e dados de exemplo e nunca para nada relacionado a segurança.
Getters retornam um array ou objeto novo a cada chamada, então alterar um resultado nunca afeta a chamada seguinte.
Todas as funções são síncronas, exceto getAddressInfoByCep, getCepInfoByAddress e a descontinuada getMunicipality.

Badge para o seu README

O badge mostra a parcela de funções principais e os casos que passam, e muda a cada execução. Cole este Markdown no README da biblioteca:

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