# Brazilian Values V2 [🇺🇸 Switch to english version](./README.en.md) [![Licença](https://badgen.net/github/license/tyagoveras/brazilian-values-v2)](./LICENSE) [![Tamanho da biblioteca minificada](https://badgen.net/bundlephobia/min/brazilian-values-v2)](https://bundlephobia.com/result?p=brazilian-values-v2) [![Tamanho da biblioteca minificada + gzipada](https://badgen.net/bundlephobia/minzip/brazilian-values-v2)](https://bundlephobia.com/result?p=brazilian-values-v2) Validar e formatar valores brasileiros como dinheiro (BRL), CPF, CNPJ, datas etc. > **Nota:** Este é um fork do projeto [brazilian-values](https://github.com/VitorLuizC/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 ``` ### Instalação por CDN Os pacotes desse módulo também estão disponíveis nas CDNs [JSDelivr](https://www.jsdelivr.com/) e [UNPKG](https://unpkg.com/). > 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`](#formattobrl) - [`formatToCapitalized`](#formattocapitalized) - [`formatToCEP`](#formattocep) - [`formatToCNPJ`](#formattocnpj) - [`formatToCNPJAlphanumeric`](#formattocnpjalphanumeric) - [`formatToCAEPF`](#formattocaepf) - [`formatToCPF`](#formattocpf) - [`formatToCPFOrCNPJ`](#formattocpforcnpj) - [`formatToDate`](#formattodate) - [`formatToDateTime`](#formattodatetime) - [`formatToList`](#formattolist) - [`formatToNumber`](#formattonumber) - [`formatToPhone`](#formattophone) - [`formatToRG`](#formattorg) - [`formatToHiddenDigits`](#formattohiddendigits)
Conversores - [`parseToArray`](#parsetoarray) - [`parseToDate`](#parsetodate) - [`parseToNumber`](#parsetonumber)
Validadores - [`isCEP`](#iscep) - [`isCNPJ`](#iscnpj) - [`isCNPJAlphanumeric`](#iscnpjalphanumeric) - [`isCAEPF`](#iscaepf) - [`isCPF`](#iscpf) - [`isCPFOrCNPJ`](#iscpforcnpj) - [`isDate`](#isdate) - [`isDDD`](#isddd) - [`isPhone`](#isphone)
### Formatação #### `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`](#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.@@@/@@@@-@@' ``` ### Conversores #### `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 ``` ### Validadores #### `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`](#iscpforcnpj), [`isCNPJAlphanumeric`](#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`](#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`](#iscpf), [`isCNPJ`](#iscnpj), [`isCNPJAlphanumeric`](#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](https://www.anatel.gov.br/legislacao/resolucoes/16-2001/383-resolucao-263). ```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 ### Docker Caso queira rodar em um ambiente isolado(container) você pode usar o [docker](https://www.docker.com/). 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](./LICENSE). [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FVitorLuizC%2Fbrazilian-values.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2FVitorLuizC%2Fbrazilian-values?ref=badge_large)