Brazilian Values V2

🇺🇸 Switch to english version


Validar e formatar valores brasileiros como dinheiro (BRL), CPF, CNPJ, datas etc.

> Nota: Este é um fork do projeto brazilian-values que aparentemente foi descontinuado. Mantido e atualizado por Tyago Veras.

Instalação

Este módulo está publicado no NPM, por isso você pode instalar usando qualquer gerenciador de pacotes Node.js.

``sh
npm install brazilian-values-v2 --save

Use o comando abaixo para o Yarn.


yarn add brazilian-values-v2
`

$3

Os pacotes desse módulo também estão disponíveis nas CDNs JSDelivr e UNPKG.

> Em ambas você pode solicitar o pacote desejado ou usar o padrão, que é o UMD.

`html







`

Como usar

brazilian-values fornece funções para lidar com formatação, validação e conversão de valores brasileiros. Todas essas funções podem ser importadas do pacote.

`js
import { isCNPJ, isCNPJAlphanumeric, formatToCNPJ } from "brazilian-values-v2";

const value = "12727442000113";

if (!isCNPJ(value)) throw new Error("CNPJ is not valid.");
const document = formatToCNPJ(value);
//=> '12.727.442/0001-13'

const alphanumericValue = "AB12CD34EF5602";
if (!isCNPJAlphanumeric(alphanumericValue))
throw new Error("CNPJ alfanumérico não é válido.");
`

API

Formatadores

- formatToBRL
- formatToCapitalized
- formatToCEP
- formatToCNPJ
- formatToCNPJAlphanumeric
- formatToCAEPF
- formatToCPF
- formatToCPFOrCNPJ
- formatToDate
- formatToDateTime
- formatToList
- formatToNumber
- formatToPhone
- formatToRG
- formatToHiddenDigits

Conversores

- parseToArray
- parseToDate
- parseToNumber

Validadores

- isCEP
- isCNPJ
- isCNPJAlphanumeric
- isCAEPF
- isCPF
- isCPFOrCNPJ
- isDate
- isDDD
- isPhone

$3

#### formatToBRL

Formata números ou string que contém números para a moeda brasileira (BRL).

`js
formatToBRL(1928.93);
//=> 'R$ 1.928,93'

formatToBRL("9211928.18203");
//=> 'R$ 9.211.928,18'

formatToBRL(-18.49);
//=> 'R$ -18,49'
`

#### formatToCapitalized

Capitaliza as palavras de um texto, com exceção das palavras configuradas para serem deixadas em caixa-alta ou em caixa-baixa.

> A primeira palavra do texto não será caixa-baixa mesmo se configurada como.

`js
formatToCapitalized("SERVIDOR PÚBLICO MUNICIPAL");
//=> 'Servidor Público Municipal'

formatToCapitalized(" os PrimEIROS HOMens da tERra", {
wordsToKeepLowerCase: ["os", "da"],
});
//=> 'Os Primeiros Homens da Terra'

formatToCapitalized("nova tv foi lançada", {
wordsToKeepUpperCase: ["tv"],
});
//=> 'Nova TV Foi Lançada'

formatToCapitalized(" com espaços antes e depois ", {
trimTrailingWhiteSpaces: false,
});
//=> ' Com Espaços Antes e Depois '
`

#### formatToCEP

Formata uma string que contém números em CEP.

`js
formatToCEP("15998030");
//=> '15998-030'

formatToCEP("02999");
//=> '02999'
`

#### formatToCNPJ

Formata uma string que contém números em CNPJ numérico.

> Para formatar CNPJs alfanuméricos, use formatToCNPJAlphanumeric.

`js
formatToCNPJ("128781");
//=> '12.878.1'

formatToCNPJ("32284981000138");
//=> '32.284.981/0001-38'

formatToCNPJ("00.0.000.00.00--00-00");
//=> '00.000.000/0000-00'
`

#### formatToCNPJAlphanumeric

Formata uma string que contém caracteres alfanuméricos em CNPJ alfanumérico.
Suporta tanto CNPJs numéricos quanto alfanuméricos no formato AA.AAA.AAA/AAAA-99.

> A partir de 2026, CNPJs poderão conter letras nos primeiros 12 caracteres.

`js
formatToCNPJAlphanumeric("AB12CD34EF5602");
//=> 'AB.12C.D34/EF56-02'

formatToCNPJAlphanumeric("ab12cd34ef5602");
//=> 'AB.12C.D34/EF56-02' (converte automaticamente para maiúsculas)

formatToCNPJAlphanumeric("AB.12C.D34/EF56-02");
//=> 'AB.12C.D34/EF56-02'

formatToCNPJAlphanumeric("32284981000138");
//=> '32.284.981/0001-38' (também funciona com CNPJs numéricos)
`

#### formatToCAEPF

Formata uma string que contém números em CAEPF.

`js
formatToCAEPF("128781");
//=> '128.781'

formatToCAEPF("32284981000150");
//=> '322.849.810/001-50'

formatToCAEPF("00.0.000.00.00--00-00");
//=> '000.000.000/000-00'
`

#### formatToCPF

Formata uma string que contém números em CPF.

`js
formatToCPF("00000000");
//=> '000.000.00'

formatToCPF("00000000000");
//=> '000.000.000-00'

formatToCPF("366.418.768-70");
//=> '366.418.768-70'
`

#### formatToCPFOrCNPJ

Formata uma string em CPF ou CNPJ dependendo do conteúdo.
Detecta automaticamente se é CPF, CNPJ numérico ou CNPJ alfanumérico.

`js
formatToCPFOrCNPJ("00000000");
//=> '000.000.00'

formatToCPFOrCNPJ("366.418.768-70");
//=> '366.418.768-70' (CPF)

formatToCPFOrCNPJ("32284981000138");
//=> '32.284.981/0001-38' (CNPJ numérico)

formatToCPFOrCNPJ("AB12CD34EF5602");
//=> 'AB.12C.D34/EF56-02' (CNPJ alfanumérico)

formatToCPFOrCNPJ("00.0.000.00.00--00-00");
//=> '00.000.000/0000-00'
`

#### formatToDate

Formata uma instância de Date para o estilo brasileiro, DD/MM/YYYY.

`js
formatToDate(new Date(2002, 7, 21));
//=> '21/08/2002'

formatToDate(new Date());
//=> '08/09/2018'
`

#### formatToDateTime

Formata uma instância de Date para o data e horário no formato brasileiro, DD/MM/YYYY HH:mm.

`js
formatToDateTime(new Date(2002, 7, 21, 18, 30));
//=> '21/08/2002 18:30'
`

#### formatToList

Formata os valores de um Array de string no estilo brasileiro.

`js
formatToList(["Vitor", "William", "Fernando"]);
//=> 'Vitor, William e Fernando'

formatToList([]);
// => ''

formatToList(["1", "2"]);
// => '1 e 2'

formatToList(["Direito Civil"]);
//=> 'Direito Civil'
`

#### formatToNumber

Formata um número para o estilo brasileiro.

`js
formatToNumber(0);
//=> '0'

formatToNumber(-1299);
//=> '-1.299'

formatToNumber(0.981);
//=> '0,981'

formatToNumber("19898.1298");
//=> '19.898,1298'
`

#### formatToPhone

Formata uma string contendo números para o estilo do número de telefone brasileiro.

`js
formatToPhone("11");
//=> '(11'

formatToPhone("11971626");
//=> '(11) 9716-26'

formatToPhone("11971626799");
//=> '(11) 9 7162-6799'
`

#### formatToRG

Formata uma string contendo números para RG.

> Hoje, brazilian-values suporta apenas os formatos de SP e RJ.

> Outros valores serão apenas "escapados" no input.

`js
formatToRG("00000000A", "SP");
//=> '00.000.000-A'

formatToRG("00.00.0000-0", "RJ");
//=> '00.000.000-0'

formatToRG("MG-14.808.688", "MG");
//=> 'MG-14.808.688'
`

#### formatToHiddenDigits

Formata uma string contendo dígitos substituindo os dígitos dentro do
intervalo pelo caractere oculto (hider).

> O intervalo pode receber números positivos ou negativos como atalho para o
> intervalo. Nesse caso o 2 equivale aos primeiros dois dígitos, e -3 aos
> últimos três dígitos.

> O intervalo padrão são os três primeiros dígitos, e o caractere oculto padrão
> é o "\*" (asterísco).

`js
formatToHiddenDigits("00.000-000");
//=> '*.00-000'

formatToHiddenDigits("03/04/2002", { hider: "-" });
//=> '--/-4/2002'

formatToHiddenDigits("111.111.111-11", { range: [4, 9] });
//=> '111..-11'

formatToHiddenDigits("12.345.678-9", { hider: "#", range: 5 });
//=> '##.###.678-9'

formatToHiddenDigits("52.715.348/0001-69", { hider: "@", range: -9 });
//=> '52.715.@@@/@@@@-@@'
`

$3

#### parseToArray

Converte uma lista no formato brasileiro para um Array de string.

`js
parseToArray("");
//=> []

parseToArray("1");
//=> ['1']

parseToArray("1 e 2");
//=> ['1', '2']

parseToArray("Fernanda, Luana e Ana Carolina");
//=> ['Fernanda', 'Luana', 'Ana Carolina']
`

#### parseToDate

Converte a data no formato brasileiro para uma instância de Date.

> Lança um erro se o valor for inválido ou não corresponder a o formato de data brasileiro.

`js
parseToDate("28/03/1996");
//=> Date('1996-03-28T03:00:00.000Z')

parseToDate("28/03/1996 20:00");
//=> Date('1996-03-28T23:00:00.000Z')

parseToDate("28/03/1996 20:00:00");
//=> Date('1996-03-28T23:00:00.000Z')

parseToDate("31/02/2018");
//=> throws Error('Value "31/02/2018" is an invalid date.')
`

#### parseToNumber

Converte o número no estilo brasileiro para um número.

`js
parseToNumber("10");
//=> 10

parseToNumber("-1.299");
//=> -1299

parseToNumber("0,981");
//=> 0.981

parseToNumber("19.898,1298");
//=> 19898.1298
`

$3

#### isCEP

Verifica se é um CEP válido.

`js
isCEP("50.833-000");
//=> true

isCEP("02998-050");
//=> true

isCEP("00000000");
//=> true

isCEP("0");
//=> false

isCEP("1982891928981982198");
//=> false
`

#### isCNPJ

Verifica se é um CNPJ válido (numérico ou alfanumérico).
Aceita tanto CNPJs numéricos tradicionais quanto os novos CNPJs alfanuméricos (válidos a partir de 2026).

> Relacionado: isCPFOrCNPJ, isCNPJAlphanumeric.

`js
isCNPJ("41142260000189");
//=> true (CNPJ numérico)

isCNPJ("45.723.174/0001-10");
//=> true (CNPJ numérico formatado)

isCNPJ("AB12CD34EF5602");
//=> true (CNPJ alfanumérico)

isCNPJ("AB.12C.D34/EF56-02");
//=> true (CNPJ alfanumérico formatado)

isCNPJ("411407182");
//=> false

isCNPJ("11.111.111/1111-11");
//=> false
`

#### isCNPJAlphanumeric

Verifica se é um CNPJ alfanumérico válido.

`js
isCNPJAlphanumeric("AB12CD34EF5602");
//=> true

isCNPJAlphanumeric("AB.12C.D34/EF56-02");
//=> true

isCNPJAlphanumeric("AB12CD34EF5600");
//=> false
`

#### isCAEPF

Verifica se é um CAEPF válido.

`js
isCAEPF("45723174000122");
//=> true

isCAEPF("457.231.740/001-22");
//=> false

isCAEPF("45.723.174/0001-22");
//=> false

isCAEPF("411407182");
//=> false

isCAEPF("111.111.111/111-11");
//=> false
`

#### isCPF

Verifica se é um CPF válido.

> Relacionado: isCPFOrCNPJ.

`js
isCPF("366.418.768-70");
//=> true

isCPF("36641876870");
//=> true

isCPF("213.198.013-20");
//=> false

isCPF("2131201872781");
//=> false

isCPF("11111111111");
//=> false
`

#### isCPFOrCNPJ

Verifica se é um CPF ou um CNPJ válido (numérico ou alfanumérico).

> Relacionado: isCPF, isCNPJ, isCNPJAlphanumeric.

`js
isCPFOrCNPJ("366.418.768-70");
//=> true (CPF)

isCPFOrCNPJ("36641876870");
//=> true (CPF)

isCPFOrCNPJ("213.198.013-20");
//=> false

isCPFOrCNPJ("2131201872781");
//=> false

isCPFOrCNPJ("11111111111");
//=> false

isCPFOrCNPJ("41142260000189");
//=> true (CNPJ numérico)

isCPFOrCNPJ("45.723.174/0001-10");
//=> true (CNPJ numérico)

isCPFOrCNPJ("AB12CD34EF5602");
//=> true (CNPJ alfanumérico)

isCPFOrCNPJ("AB.12C.D34/EF56-02");
//=> true (CNPJ alfanumérico)

isCPFOrCNPJ("411407182");
//=> false

isCPFOrCNPJ("11.111.111/1111-11");
//=> false
`

#### isDate

Verifica se é uma data válida e se corresponde ao formato brasileiro.

`js
isDate("03/08/2017");
//=> true

isDate("28/13/2017");
//=> false

isDate("03-08-2017");
//=> false

isDate("31/03/18");
//=> false
`

#### isDDD

Verifica se é um código DDD (discagem direta à distância) brasileiro válido.

> Baseado na resolução nº 263, de 8 de junho de 2001.

`js
isDDD("81");
//=> true

isDDD("10");
//=> false

isDDD("555");
//=> false
`

#### isPhone

Verifica se está em um formato comum de número de telefone brazileiro, opcionalmente com DDI, DDD e o nono dígito.
Se o DDD estiver definido ele será verificado com isDDD.

`js
isPhone("+55 (11) 9 8273-1182");
//=> true

isPhone("11 9 8273 1182");
//=> true

isPhone("1139723768");
//=> true

isPhone("(23) 3972-3768");
//=> false

isPhone("(13) 6 5093-2093");
//=> false

isPhone("(81) 555 178");
//=> false
`

Contribuindo

$3

Caso queira rodar em um ambiente isolado(container) você pode usar o docker.

Primeiro construa a imagem em sua maquina

`
docker build -t brazilian-values:latest .
`

Após isso rode o ambiente em modo interativo

`
docker run -it -v ${PWD}:/usr/src/app brazilian-values:latest bash
`

Você entrara em um container com o ambiente isolado da maquina. rode o yarn install e pode começar a usar todo o projeto

``
yarn install
``

Licença

Lançado sob a licença MIT.