Merge pull request #477 from brazilian-utils/sync-code-with-python-lib

feat: implement some extra utilities

Author: hyanmandian

docs/pt-br/utilities.md

@@ -25,7 +25,7 @@ formatCpf('746506880', { pad: true }); // 007.465.068-80
 
 ## parseCpf
 
-Remove a formatação do CPF e retorna apenas os dígitos.
+Remove a formatação do CPF, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parseCpf } from '@brazilian-utils/brazilian-utils';
@@ -67,7 +67,7 @@ formatCnpj('12OUT345000199', { version: 2 }); // 12.OUT.345/0001-99
 
 ## parseCnpj
 
-Remove a formatação do CNPJ e retorna um valor normalizado.
+Remove a formatação do CNPJ, retorna um valor normalizado e limita o resultado a 14 caracteres.
 
 ```javascript
 import { parseCnpj } from '@brazilian-utils/brazilian-utils';
@@ -119,7 +119,7 @@ formatBoleto('1900000901149', { pad: true }); // 00000.00000 00000.000019 00000.
 
 ## parseBoleto
 
-Remove a formatação do boleto e retorna apenas os dígitos.
+Remove a formatação do boleto, mantém apenas os dígitos e limita o resultado a 47 dígitos.
 
 ```javascript
 import { parseBoleto } from '@brazilian-utils/brazilian-utils';
@@ -182,12 +182,13 @@ formatPhone('11900000000', { mask: 'auto' }); // Detecta automaticamente a másc
 
 ## parsePhone
 
-Remove a formatação do telefone e retorna apenas os dígitos.
+Remove a formatação do telefone, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parsePhone } from '@brazilian-utils/brazilian-utils';
 
 parsePhone('(11) 90000-0000'); // 11900000000
+parsePhone('+55 (11) 90000-0000'); // 55119000000
 ```
 
 ## isValidMobilePhone
@@ -258,7 +259,7 @@ formatPis('123456789', { pad: true }); // 001.23456.78-9
 
 ## parsePis
 
-Remove a formatação do PIS e retorna apenas os dígitos.
+Remove a formatação do PIS, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parsePis } from '@brazilian-utils/brazilian-utils';
@@ -278,7 +279,7 @@ formatCep('92500000'); // 92500-000
 
 ## parseCep
 
-Remove a formatação do CEP e retorna apenas os dígitos.
+Remove a formatação do CEP, mantém apenas os dígitos e limita o resultado a 8 dígitos.
 
 ```javascript
 import { parseCep } from '@brazilian-utils/brazilian-utils';
@@ -328,7 +329,7 @@ formatProcessoJuridico('00020802520125150049'); // 0002080-25.2012.515.0049
 
 ## parseProcessoJuridico
 
-Remove a formatação do processo jurídico e retorna apenas os dígitos.
+Remove a formatação do processo jurídico, mantém apenas os dígitos e limita o resultado a 20 dígitos.
 
 ```javascript
 import { parseProcessoJuridico } from '@brazilian-utils/brazilian-utils';
@@ -518,7 +519,7 @@ isValidPassport('12345678'); // false
 
 ## formatPassport
 
-Formata um número de passaporte brasileiro (maiúsculas, sem símbolos).
+Formata um número de passaporte brasileiro (maiúsculas, sem símbolos, limitado a 8 caracteres).
 
 ```javascript
 import { formatPassport } from '@brazilian-utils/brazilian-utils';
@@ -539,11 +540,287 @@ generatePassport(); // 'RY393097'
 
 ## parsePassport
 
-Remove todos os caracteres não alfanuméricos (incluindo '-', '.' e espaços) de um número de passaporte.
+Remove todos os caracteres não alfanuméricos de um número de passaporte, converte para maiúsculas e limita o resultado a 8 caracteres.
 
 ```javascript
 import { parsePassport } from '@brazilian-utils/brazilian-utils';
 
 parsePassport('AB-123.456'); // 'AB123456'
 parsePassport(' AB 123 456 '); // 'AB123456'
 ```
+
+## generateCep
+
+Gera um CEP aleatório.
+
+```javascript
+import { generateCep } from '@brazilian-utils/brazilian-utils';
+
+generateCep(); // '92500000'
+```
+
+## formatCnh
+
+Formata a CNH.
+
+```javascript
+import { formatCnh } from '@brazilian-utils/brazilian-utils';
+
+formatCnh('02650306461'); // 026503064-61
+formatCnh('2650306461', { pad: true }); // 026503064-61
+```
+
+## isValidCnh
+
+Valida se a CNH é válida.
+
+```javascript
+import { isValidCnh } from '@brazilian-utils/brazilian-utils';
+
+isValidCnh('00000000119'); // true
+```
+
+## generateCnh
+
+Gera uma CNH válida aleatória.
+
+```javascript
+import { generateCnh } from '@brazilian-utils/brazilian-utils';
+
+generateCnh(); // '02650306461'
+```
+
+## parseCnh
+
+Remove a formatação da CNH, mantém apenas os dígitos e limita o resultado a 11 dígitos.
+
+```javascript
+import { parseCnh } from '@brazilian-utils/brazilian-utils';
+
+parseCnh('026503064-61'); // '02650306461'
+```
+
+## getCepInfoByAddress
+
+Busca CEPs a partir de um endereço usando a ViaCEP.
+
+```javascript
+import { getCepInfoByAddress } from '@brazilian-utils/brazilian-utils';
+
+const ceps = await getCepInfoByAddress({
+  federalUnit: 'SP',
+  city: 'Sao Paulo',
+  street: 'Avenida Paulista'
+});
+
+// [
+//   {
+//     cep: '01310100',
+//     logradouro: 'Avenida Paulista',
+//     complemento: 'lado par',
+//     bairro: 'Bela Vista',
+//     localidade: 'São Paulo',
+//     uf: 'SP'
+//   }
+// ]
+```
+
+## generateProcessoJuridico
+
+Gera um número de processo jurídico válido de acordo com a definição do [CNJ](https://www.conjur.com.br/dl/resolucao-65-cnj.pdf).
+
+```javascript
+import { generateProcessoJuridico } from '@brazilian-utils/brazilian-utils';
+
+generateProcessoJuridico(); // '00020802520125150049'
+generateProcessoJuridico({ year: 2026, court: 5 }); // string | null
+```
+
+## formatLegalNature
+
+Formata um código de natureza jurídica.
+
+```javascript
+import { formatLegalNature } from '@brazilian-utils/brazilian-utils';
+
+formatLegalNature('2062'); // 206-2
+```
+
+## isValidLegalNature
+
+Valida se um código de natureza jurídica existe na lista oficial.
+
+```javascript
+import { isValidLegalNature } from '@brazilian-utils/brazilian-utils';
+
+isValidLegalNature('2062'); // true
+isValidLegalNature('9999'); // false
+```
+
+## generateLegalNature
+
+Gera um código de natureza jurídica válido aleatório.
+
+```javascript
+import { generateLegalNature } from '@brazilian-utils/brazilian-utils';
+
+generateLegalNature(); // '2062'
+```
+
+## parseLegalNature
+
+Remove a formatação da natureza jurídica, mantém apenas os dígitos e limita o resultado a 4 dígitos.
+
+```javascript
+import { parseLegalNature } from '@brazilian-utils/brazilian-utils';
+
+parseLegalNature('206-2'); // '2062'
+```
+
+## getLegalNatures
+
+Retorna o mapa de naturezas jurídicas indexado pelo código.
+
+```javascript
+import { getLegalNatures } from '@brazilian-utils/brazilian-utils';
+
+const legalNatures = getLegalNatures();
+
+legalNatures['2062']; // 'Sociedade Empresária Limitada'
+```
+
+## generatePhone
+
+Gera um telefone brasileiro aleatório.
+
+```javascript
+import { generatePhone } from '@brazilian-utils/brazilian-utils';
+
+generatePhone(); // '11912345678' ou '1131234567'
+generatePhone('mobile'); // '11912345678'
+generatePhone('landline'); // '1131234567'
+```
+
+## formatLicensePlate
+
+Formata uma placa. Placas antigas brasileiras são retornadas com hífen e placas Mercosul permanecem normalizadas.
+
+```javascript
+import { formatLicensePlate } from '@brazilian-utils/brazilian-utils';
+
+formatLicensePlate('abc1234'); // 'ABC-1234'
+formatLicensePlate('abc1d23'); // 'ABC1D23'
+```
+
+## generateLicensePlate
+
+Gera uma placa aleatória no formato escolhido.
+
+```javascript
+import { generateLicensePlate } from '@brazilian-utils/brazilian-utils';
+
+generateLicensePlate(); // 'ABC1D23'
+generateLicensePlate('LLLNNNN'); // 'ABC1234'
+generateLicensePlate('LLLNNLN'); // 'ABC12D3'
+```
+
+## getFormatLicensePlate
+
+Detecta o formato normalizado de uma placa.
+
+```javascript
+import { getFormatLicensePlate } from '@brazilian-utils/brazilian-utils';
+
+getFormatLicensePlate('ABC-1234'); // 'LLLNNNN'
+getFormatLicensePlate('ABC1D23'); // 'LLLNLNN'
+getFormatLicensePlate('ABC12D3'); // 'LLLNNLN'
+getFormatLicensePlate('INVALID'); // null
+```
+
+## parseLicensePlate
+
+Remove separadores de uma placa, normaliza para letras maiúsculas e limita o resultado a 7 caracteres.
+
+```javascript
+import { parseLicensePlate } from '@brazilian-utils/brazilian-utils';
+
+parseLicensePlate('abc-1234'); // 'ABC1234'
+```
+
+## generatePis
+
+Gera um PIS válido aleatório.
+
+```javascript
+import { generatePis } from '@brazilian-utils/brazilian-utils';
+
+generatePis(); // '12345678901'
+```
+
+## getMunicipality
+
+Busca informações de município por código IBGE, ou obtém o código IBGE a partir do nome do município e UF.
+
+```javascript
+import { getMunicipality } from '@brazilian-utils/brazilian-utils';
+
+await getMunicipality({ code: '3550308' });
+// ['São Paulo', 'SP']
+
+await getMunicipality({ municipalityName: 'São Paulo', uf: 'SP' });
+// '3550308'
+```
+
+## isHoliday
+
+Verifica se uma data específica é feriado brasileiro.
+
+```javascript
+import { isHoliday } from '@brazilian-utils/brazilian-utils';
+
+isHoliday({ targetDate: new Date('2024-01-01') }); // true
+isHoliday({ targetDate: new Date('2024-07-09'), stateCode: 'SP' }); // true
+```
+
+## formatVoterId
+
+Formata um título de eleitor.
+
+```javascript
+import { formatVoterId } from '@brazilian-utils/brazilian-utils';
+
+formatVoterId('123456780175'); // '1234 5678 01 75'
+```
+
+## isValidVoterId
+
+Valida se um título de eleitor é válido.
+
+```javascript
+import { generateVoterId, isValidVoterId } from '@brazilian-utils/brazilian-utils';
+
+const voterId = generateVoterId('SP');
+
+isValidVoterId(voterId); // true
+```
+
+## generateVoterId
+
+Gera um título de eleitor válido aleatório. Você pode opcionalmente informar a UF.
+
+```javascript
+import { generateVoterId } from '@brazilian-utils/brazilian-utils';
+
+generateVoterId(); // título de eleitor aleatório válido
+generateVoterId('SP'); // título de eleitor aleatório válido de São Paulo
+```
+
+## parseVoterId
+
+Remove a formatação do título de eleitor, mantém apenas os dígitos e limita o resultado a 12 dígitos.
+
+```javascript
+import { parseVoterId } from '@brazilian-utils/brazilian-utils';
+
+parseVoterId('1234 5678 01 75'); // '123456780175'
+```