validation-br 0.8.3 → 1.0.0-b

package/readme.md

@@ -1,8 +1,12 @@
 # validation-br
 
-Biblioteca de validação de documentos pessoais do Brasil com suporte a CPF, CNPJ, Título Eleitoral, PIS/PASEP, CNH, e Objetos registrados de rastreamento dos Correios.
+Biblioteca de validação de documentos pessoais do Brasil com suporte a CPF, CNPJ, Título Eleitoral, PIS/PASEP, CNH. Também valida numerações de outros tipos de registros como RENAVAM, Processos Judiciais e Objetos registrados de Rastreamento dos Correios.
 
-## Instalação
+Validation-BR também permite a criação de números fake das numerações acima para fins de teste de desenvolvimento, além de aplicação de máscaras e cálculo do dígito verificador.
+
+Validation-BR também permite criação de números fake para facilitar o desenvolvimento e testes, além de aplicar máscaras e calcular somente os dígitos verificadores.
+
+# Instalação
 
 ```sh
 # Usando yarn
@@ -14,174 +18,325 @@ npm install validation-br
 
 ```
 
-## Importação
+# Importação
 
-```js
+## Importação direta
+
+Permite realizar diretamente uma validação a partir do objeto principal
 
+```js
 // Modules
-const { isCPF, isCNPJ } = require('validation-br');
+const { isCPF, isCNPJ } = require('validation-br')
 
 // ES6
-import { isCPF, isCNPJ } from ('validation-br');
+import { isCPF, isCNPJ } from 'validation-br'
+```
+
+## Importação de submódulos
+
+Importando os submódulos, é possível criar máscaras, números fake para testes de desenvolvimento e calcular dígitos verificadores.
+
+### Exemplos
+
+```js
+// ES6
+import { dv, fake, mask, validate } from 'validation-br/cpf'
+
+// Modules
+const cpf = require('validation-br/cpf')
+const { dv, fake, mask, validate } = require('validation-br/cpf')
+
+// Calculo do dígito verificador de um CPF. Os métodos aceitam inteiros e strings, inclusive com máscaras.
+cpf.dv(906259666) // -> '51'
+cpf.dv('906259666') // -> '51'
+cpf.dv('906.259.666') // -> '51'
 
+// Cria um número fake de CPF para fins de testes.
+cpf.fake() // -> 90625966651
+// Passe um parâmetro true para gerar o número com máscara
+cpf.fake(true) // -> 906.259.666-51
 
+// Aplique uma máscara a um cpf
+cpf.mask(90625966651) // -> 906.259.666-51
+
+// Valida um número
+cpf.validate('01234567890') // -> true
+
+// Valida um número e retorna exceção se a validação falhar
+cpf.validateOrFail('01234567890') // -> true
 ```
 
 ## Tabela de Conteúdo
 
-- [isCPF](#isCPF) - Validação do CPF
-- [isCNPJ](#isCNPJ) - Validação do CNPJ
-- [isTitulo](#isTitulo) - Validação do Título de Eleitor
-- [isCNH](#isCNH) - Validação do CNH
-- [isPostalCode](#isPostalCode) - Validação de Objetos Registrados dos Correios
-- [isPIS](#isPIS) - Validação de PIS, PASEP, NIS e NIT
+- [isCNH](#isCNH-value-) - Validação do CNH
+- [isCPF](#isCPF-value-) - Validação do CPF
+- [isCNPJ](#isCNPJ-value-) - Validação do CNPJ
+- [isPostalCode](#isPostalCode-value-) - Validação de Objetos Registrados dos Correios
+- [isJudicialProcess](#isJudicialProcess-value-) - Validação de Números de Processos Judiciais
+- [isPIS](#isPIS-value-) - Validação de PIS, PASEP, NIS e NIT
+- [isPostalCode](#isPostalCode-value-) - Validação de Objetos Registrados dos Correios
+- [isRenavam](#isRenavam-value-) - Validação de RENAVAM
+- [isTituloEleitor](#isTituloEleitor-value-) - Validação do Título de Eleitor
 
-### isCPF
+### isCNH( `value` )
 
-Valida um CPF
+Valida o documento da carteira nacional de habilitação.
 
 ```js
-// Importação
-import { isCPF } from ('validation-br');
+// Importação somente da validação
+import { isCNH } from 'validation-br'
+// ou
+// Importação do submódulo
+import cnh from 'validation-br/cnh'
 
 // Valida
-isCPF('01234567890')
-//-> true
+isCNH('69044271146') //-> true
+isCNH('62472927637') //-> true
+isCNH('46190476839') //-> false
+cnh.validate('62472927637') //-> true
+cnh.validateOrFail('62472927637') //-> true
 
-// Valida
-isCPF('012.345.678-90')
-//-> true
+// Número fake com e sem máscara
+cnh.fake() // -> 62472927637
+cnh.fake(true) // -> 624729276-37
 
-// Valida
-isCPF('01234567891')
-//-> false
+// Aplica uma máscara
+cnh.mask('62472927637') // -> 624729276-37
+
+// Calcula o DV
+cnh.dv('624729276') // -> '37'
 ```
 
-### isCNPJ
+### isCNPJ( `value` )
 
 Valida um CNPJ
 
 ```js
-// Importação
-import { isCNPJ } from ('validation-br');
+// Importação somente da validação
+import { isCNPJ } from 'validation-br'
+// ou
+// Importação do submódulo
+import cnpj from 'validation-br/cnpj'
 
 // Valida
-isCNPJ('73.797.980/0001-79')
-//-> true
+isCNPJ('73.797.980/0001-79') //-> true
+isCNPJ('55585709000198') //-> true
+isCNPJ('99362238000180') //-> false
+cnpj.validate('99362238000180') //-> true
+cnpj.validateOrFail('99362238000180') //-> true
 
-// Valida
-isCNPJ('55585709000198')
-//-> true
+// Número fake com e sem máscara
+cnpj.fake() // -> 55585709000198
+cnpj.fake(true) // -> 55.585.709/0001-98
 
-// Valida
-isCNPJ('99362238000180')
-//-> false
+// Aplica uma máscara
+cnpj.mask('99362238000180') // -> 99.362.238/0001-80
+
+// Calcula o DV
+cnpj.dv('993622380001') // -> '80'
 ```
 
-### isTitulo
+### isCPF( `value` )
 
-Valida um título eleitoral
+Valida um CPF
 
 ```js
-// Importação
-import { isTitulo } from ('validation-br');
+// Importação somente da validação
+import { isCPF } from 'validation-br'
+// ou
+// Importação do submódulo
+import cpf from 'validation-br/cpf'
 
 // Valida
-isTitulo('743650641660')
-//-> true
+isCPF('01234567890') //-> true
+isCPF('012.345.678-90') //-> true
+isCPF('01234567891') //-> false
+cpf.validate('01234567890') //-> true
+cpf.validateOrFail('01234567890') //-> true
 
-// Valida
-isTitulo('525028881694')
-//-> true
+// Número fake com e sem máscara
+cpf.fake() // -> 01234567891
+cpf.fake(true) // -> 012.345.678-91
 
-// Valida
-isTitulo('153016161686')
-//-> false
+// Aplica uma máscara
+cpf.mask('01234567890') // -> 012.345.678-90
+
+// Calcula o DV
+cpf.dv('012345678') // -> '90'
 ```
 
-### isCNH
+### isJudicialProcess( `value` )
 
-Valida o documento da carteira nacional de habilitação.
+Valida códigos PIS, PASEP, NIS e NIT, que usam o mesmo algoritmo. Aceita números com e sem pontos e traços.
 
 ```js
-// Importação
-import { isCNH } from ('validation-br');
+// Importação somente da validação
+import { isJudicialProcess } from 'validation-br'
+// ou
+// Importação do submódulo
+import judicialProcess from 'validation-br/judicial-process'
 
 // Valida
-isCNH('69044271146')
-//-> true
+isJudicialProcess('71282677380') //-> true
+isJudicialProcess('237.95126.95-5') //-> true
+isJudicialProcess('500.12973.80-1') //-> false
+judicialProcess.validate('71282677380') //-> true
+judicialProcess.validateOrFail('71282677380') //-> true
 
-// Valida
-isCNH('62472927637')
-//-> true
+// Número fake com e sem máscara
+judicialProcess.fake() // -> 71282677380
+judicialProcess.fake(true) // -> 712.82677.38-0
+
+// Aplica uma máscara
+judicialProcess.mask('71282677380') // -> 712.82677.38-0
+
+// Calcula o DV
+judicialProcess.dv('7128267738') // -> '0'
+```
+
+### isPIS( `value` )
+
+Valida códigos PIS, PASEP, NIS e NIT, que usam o mesmo algoritmo. Aceita números com e sem pontos e traços.
+
+```js
+// Importação somente da validação
+import { isPIS } from 'validation-br'
+// ou
+// Importação do submódulo
+import pis from 'validation-br/pis'
 
 // Valida
-isCNH('46190476839')
-//-> false
+isPIS('71282677380') //-> true
+isPIS('237.95126.95-5') //-> true
+isPIS('500.12973.80-1') //-> false
+pis.validate('71282677380') //-> true
+pis.validateOrFail('71282677380') //-> true
+
+// Número fake com e sem máscara
+pis.fake() // -> 71282677380
+pis.fake(true) // -> 712.82677.38-0
+
+// Aplica uma máscara
+pis.mask('71282677380') // -> 712.82677.38-0
+
+// Calcula o DV
+pis.dv('7128267738') // -> '0'
 ```
 
-### isPostalCode
+### isPostalCode( `value` )
 
-Valida um código de rastreamento de objetos postais no formato XX000000000YY, onde:
+Valida um código de rastreamento de objetos postais no formato XX00000000DYY, onde:
 
 - XX: O código do objeto postal com 2 dígitos;
-- 000000000: Número sequencial do objeto com 9 dígitos;
+- 00000000: Número sequencial do objeto com 8 dígitos;
+- D: Dígito Verificador
 - YY: País de origem do objeto com 2 dígitos.
 
 ```js
-// Importação
-import { isPostalCode } from ('validation-br');
+// Importação somente da validação
+import { isPostalCode } from 'validation-br'
+// ou
+// Importação do submódulo
+import postalCode from 'validation-br/postal-code'
 
 // Valida
-isPostalCode('PN718252423BR')
-//-> true
+isPostalCode('PN718252423BR') //-> true
+isPostalCode('RY728187035CN') //-> true
+isPostalCode('JT194624698BR') //-> false
+postalCode.validate('PN718252423BR') //-> true
+postalCode.validateOrFail('PN718252423BR') //-> true
+
+// Número fake com e sem máscara.
+postalCode.fake() // -> PN718252423BR
+postalCode.fake(true) // -> PN718252423BR
+
+// Aplica uma máscara
+// No caso de PostalCode, a máscara apenas coloca as letras em maiúsculas
+postalCode.mask('pn718252423br') // -> PN718252423BR
+
+// Calcula o DV
+postalCode.dv('PN718252423BR') // -> '3'
+```
 
-// Valida
-isPostalCode('RY728187035CN')
-//-> true
+### isRenavam( `value` )
+
+Valida o número de um RENAVAM de 11 dígitos
+
+```js
+// Importação somente da validação
+import { isRenavam } from 'validation-br'
+// ou
+// Importação do submódulo
+import renavam from 'validation-br/renavam'
 
 // Valida
-isPostalCode('JT194624698BR')
-//-> false
+isRenavam('14283256656') //-> true
+isRenavam('95059845976') //-> true
+isRenavam('67747331626') //-> false
+renavam.validate('95059845976') //-> true
+renavam.validateOrFail('95059845976') //-> true
+
+// Número fake com e sem máscara
+renavam.fake() // -> 95059845976
+renavam.fake(true) // -> 9505984597-6
+
+// Aplica uma máscara
+renavam.mask('95059845976') // -> 9505984597-6
+
+// Calcula o DV
+renavam.dv('950598459') // -> '76'
 ```
 
-### isPIS
+### isTituloEleitor( `value` )
 
-Valida códigos PIS, PASEP, NIS e NIT, que usam o mesmo algoritmo. Aceita números com e sem pontos e traços.
+Valida um título eleitoral
 
 ```js
-// Importação
-import { isPIS } from ('validation-br');
+// Importação somente da validação
+import { isTituloEleitor } from 'validation-br'
+// ou
+// Importação do submódulo
+import titulo from 'validation-br/titulo'
 
 // Valida
-isPIS('71282677380')
-//-> true
+isTituloEleitor('743650641660') //-> true
+isTituloEleitor('525028881694') //-> true
+isTituloEleitor('153016161686') //-> false
+titulo.validate('01234567890') //-> true
+titulo.validateOrFail('01234567890') //-> true
 
-// Valida
-isPIS('237.95126.95-5')
-//-> true
+// Número fake com e sem máscara
+titulo.fake() // -> 153016161686
+titulo.fake(true) // -> 1530.1616.1686
 
-// Valida
-isPIS('500.12973.80-1')
-//-> false
-```
+// Aplica uma máscara
+titulo.mask('525028881694') // -> 5250.2888.1694
 
-## Tests
-![image](https://user-images.githubusercontent.com/100168/133695302-17744b22-2bf0-41e8-8907-58ea4770be3c.png)
+// Calcula o DV
+titulo.dv('5250288816') // -> '94'
+```
 
+# Tests
 
+![image](https://user-images.githubusercontent.com/100168/148705528-7c810b3c-851a-49c4-bc08-f9631498d526.png)
 
-## Changelog
+# Changelog
 
+- **09/01/2022**:
+  - 1.0.0 - Biblioteca convertida para Typescript e testes convertidos para Jest
+- **08/01/2022**:
+  - 0.21.1 - Adicionadas as funções isRenavam e isJudicialProcess
 - **16/09/2021**:
-  - 0.5.0 - Adicionadas as funções isCPF, isCNPJ e isTitulo
+  - 0.5.0 - Adicionadas as funções isCPF, isCNPJ e isTituloEleitor
   - 0.7.0 - Adicionadas as funções isPostalCode e isCNH
   - 0.8.0 - Adicionada a função isPIS
 
-## Referências
+# Referências
 
 - [Cálculo do DV do CPF](http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-cpf/)
 - [Cálculo do DV do CNPJ](http://www.macoratti.net/alg_cnpj.htm)
 - [Cálculo do DV do Título Eleitoral](http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/)
 - [Cálculo do PIS](http://www.macoratti.net/alg_pis.htm)
 - [Diferença entre PIS, PASEP, NIS e NIT](https://www.jornalcontabil.com.br/entenda-de-uma-vez-a-diferenca-entre-pis-pasep-nit-e-nis/#:~:text=NIS%20%E2%80%93%20N%C3%BAmero%20de%20Identifica%C3%A7%C3%A3o%20Social,do%20Patrim%C3%B4nio%20do%20Servidor%20P%C3%BAblico)
+- [Documentação Oficial de Numeração de Processos Judiciais](https://juslaboris.tst.jus.br/bitstream/handle/20.500.12178/30318/2008_res0065_cnj_rep01.pdf?sequence=2)
+- [Cálculos de DV](http://ghiorzi.org/DVnew.htm)

package/src/cnh.test.ts

@@ -0,0 +1,114 @@
+// import { isCNH } from './cnh'
+import isCNH, { dv, fake, mask, validate, validateOrFail } from './cnh'
+
+describe('CNH', () => {
+  test('isCNH() - Números válidos', () => {
+    const list = [
+      // como inteiro
+      50195131143,
+      58316794534,
+      50195471165,
+      // como string
+      '69044271146',
+      '46190906839',
+      // com máscara
+      '624729276-37',
+    ]
+
+    list.forEach((cnh) => {
+      // t.true(isCNH(cnh), `CNH ${cnh} deve ser válida`)
+      expect(isCNH(cnh)).toBeTruthy()
+    })
+
+    // t.end()
+  })
+
+  test('validate() - Números válidos', () => {
+    const list = [
+      // como inteiro
+      50195131143,
+      58316794534,
+      // como string
+      '69044271146',
+      '46190906839',
+      // com máscara
+      '624729276-37',
+    ]
+
+    list.forEach((cnh) => {
+      // t.true(isCNH(cnh), `CNH ${cnh} deve ser válida`)
+      expect(validate(cnh)).toBeTruthy()
+    })
+  })
+
+  test('validate() - Números inválidos', () => {
+    const list = ['50195471143', '58316474534', '69044471146', '33333333333', '88888888888']
+
+    list.forEach((cnh) => {
+      expect(validate(cnh)).toBeFalsy()
+    })
+  })
+
+  test('validateOrFail() - Números inválidos', () => {
+    const list = ['50195471143', '58316474534', '69044471146', '33333333333', '88888888888']
+
+    list.forEach((cnh) => {
+      expect(() => validateOrFail(cnh)).toThrow()
+    })
+  })
+
+  test('Parâmetro não informado', () => {
+    expect(isCNH('')).toBeFalsy()
+    expect(validate('')).toBeFalsy()
+    expect(() => validateOrFail('')).toThrow()
+    expect(() => dv('')).toThrow()
+  })
+
+  test('fake() - Gera fakes sem máscara', () => {
+    for (let i = 0; i < 5; i += 1) {
+      const cnh = fake()
+      expect(validate(cnh)).toBeTruthy()
+      expect(cnh).toHaveLength(11)
+    }
+  })
+
+  test('fake() - Gera fakes com máscara', () => {
+    for (let i = 0; i < 5; i += 1) {
+      const cnh = fake(true)
+      expect(validate(cnh)).toBeTruthy()
+      expect(cnh).toHaveLength(12)
+    }
+
+    // t.end()
+  })
+
+  test('dv() - Verificando se o DV gerado está correto', () => {
+    const list = [
+      { num: '501954711', expected: '65' },
+      { num: 583164745, expected: '75' },
+      { num: 690444711, expected: '17' },
+    ]
+
+    list.forEach((item) => {
+      const calcDv = dv(item.num)
+
+      expect(calcDv).toBe(item.expected)
+      expect(typeof calcDv).toBe('string')
+    })
+  })
+
+  test('mask() - Testando se a máscara foi gerada corretamente', () => {
+    const list = [
+      { value: 50195471143, expected: '501954711-43' },
+      { value: 58316474534, expected: '583164745-34' },
+      { value: 69044471146, expected: '690444711-46' },
+    ]
+
+    list.forEach((item) => {
+      const masked = mask(item.value)
+
+      expect(masked).toBe(item.expected)
+      expect(masked).toHaveLength(12)
+    })
+  })
+})

package/src/cnh.ts

@@ -0,0 +1,140 @@
+/**
+ * isCNH()
+ * Calcula se uma CNH é válida
+ *
+ * @doc
+ * CNH deve possuir 11 caracteres
+ *
+ * - Os caracteres 1 a 9 são números sequenciais.
+ *
+ *
+ * - Os caracteres 10 e 11 são dígitos verificadores.
+ *
+ * 1) Partes do número
+ *  ____________________________ ______
+ * |  Número                    | D V |
+ * |  5  8  3  1  6  7  9  4  5   3 4 |
+ * |____________________________|_____|
+ *
+ * 2) Cálculo do primeiro DV.
+ *
+ *  - Soma-se o produto das algarismos 1 a 9 pelos números 2, 3, 4, 5, 6, 7, 8, 9, 10.
+ *
+ *    5   8   3   1   6   7   9   4   5
+ *    x   x   x   x   x   x   x   x   x
+ *    2   3   4   5   6   7   8   9   10
+ * = 10 +24 +12  +5 +36 +49 +72 +36  +50  = 294
+ *
+ *  - O somatório encontrado é dividido por 11. O DV1 é 11 subtraído do resto da divisão. Se o
+ *    resto for 10, o DV1 é 0.
+ *
+ * 2.1) 294 / 11 tem resto igual a 8. 11-7 = 3
+ *      DV1 = 3
+ *
+ * 3) Cálculo do segundo DV
+ *
+ *  - Soma-se o produto das algarismos 1 a 9 juntamente com o 10 caractere
+ *    que é o DV1, pelos números 3, 4, 5, 6, 7, 8, 9, 10, 11, 2. O DV1 será
+ *    multiplicado por 2 e ficará no final.
+ *
+ *    5   8   3   1   6   7   9   4   5   3
+ *    x   x   x   x   x   x   x   x   x   x
+ *    3   4   5   6   7   8   9  10  11   2
+ * = 10 +24 +12  +5 +36 +49 +72 +36 +50  +6  =  348
+ *
+ * 3.1) 348 / 11 tem resto igual a 7. 11 - 7 = 4.
+ *      DV2 = 4
+ *
+ *  - O somatório encontrado é dividido por 11. O DV2 é 11 subtraído do resto da divisão. Se o
+ *    resto for 10, o DV2 é 0.
+ *
+ * Fonte: https://www.devmedia.com.br/forum/validacao-de-cnh/372972
+ *
+ * @param {String} value Título eleitoral
+ * @returns {Boolean}
+ */
+
+import {
+  sumElementsByMultipliers,
+  sumToDV,
+  invalidListGenerator,
+  clearValue,
+  applyMask,
+  fakeNumber,
+} from './utils'
+
+/**
+ * Calcula o Dígito Verificador de um RENAVAM informado
+ *
+ * @returns String Número fake de um cnh válido
+ */
+export const dv = (value: string | number): string => {
+  if (!value) throw new Error('CNH não informado')
+
+  const cnh = clearValue(value, 9)
+
+  const invalidList = invalidListGenerator(9)
+  if (invalidList.includes(cnh)) {
+    throw new Error('CNH não pode ser uma sequência de números iguais')
+  }
+
+  const sum1 = sumElementsByMultipliers(cnh.substring(0, 9), [2, 3, 4, 5, 6, 7, 8, 9, 10])
+  const dv1 = sumToDV(sum1)
+
+  const sum2 = sumElementsByMultipliers(cnh.substring(0, 9) + dv1, [3, 4, 5, 6, 7, 8, 9, 10, 11, 2])
+  const dv2 = sumToDV(sum2)
+
+  return `${dv1}${dv2}`
+}
+
+/**
+ * Valida um número de cnh e retorna uma exceção caso seja inválido
+ *
+ * @returns String Número fake de um cnh válido
+ */
+export const validateOrFail = (value: string | number): boolean => {
+  const cnh = clearValue(value, 11)
+
+  if (dv(cnh) !== cnh.substring(9, 11)) {
+    throw new Error('Dígito verificador inválido')
+  }
+
+  return true
+}
+
+/**
+ * Valida um número de cnh
+ *
+ * @returns String Valor a ser validado
+ */
+export const validate = (value: string | number): boolean => {
+  try {
+    return validateOrFail(value)
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * Aplica uma máscara a uma string
+ *
+ * @returns String string com a máscara aplicada
+ */
+export const mask = (value: string | number): string => applyMask(value, '000000000-00')
+
+/**
+ * Cria um número fake
+ *
+ * @returns String Número fake porém válido
+ */
+export const fake = (withMask: boolean = false): string => {
+  const value = fakeNumber(9, true)
+
+  const cnh = `${value}${dv(value)}`
+
+  if (withMask) return mask(cnh)
+
+  return cnh
+}
+
+export default validate