Skip to content

Latest commit

 

History

History
578 lines (392 loc) · 10.8 KB

README.en.md

File metadata and controls

578 lines (392 loc) · 10.8 KB

Brazilian Values

🇧🇷 Trocar para a versão em português

Build Status FOSSA Status License Library minified size Library minified + gzipped size

Validates and formats brazilian values, like money (BRL), CPF, CNPJ, dates etc.

Read this in other language: Brazilian portuguese

Install

This module is published under NPM registry, so you can install using any Node.js package manager.

npm install brazilian-values --save

# For Yarn use the command below.
yarn add brazilian-values

Install from CDN

The bundles of this module are also available on JSDelivr and UNPKG CDNs.

In both you can import just the bundle you want or use default one, UMD.

<!-- Using default bundle from JSDelivr -->
<script src="https://cdn.jsdelivr.net/npm/brazilian-values"></script>

<!-- Using default bundle from UNPKG -->
<script src="https://unpkg.com/brazilian-values"></script>

<script>
  /**
   * UMD bundle expose brazilian-values through `BrazilianValues` object.
   */
  BrazilianValues.formatToBRL(100);
  //=> 'R$ 100,00'
</script>

Usage

brazilian-values provides functions to deal with formatting, validating and parsing brazilian values. All those functions could be imported from package.

import { isCNPJ, formatToCNPJ } from 'brazilian-values';

const value = '12727442000113'

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

API

Formatters
Parsers
Validators

Formatters

formatToBRL

Formats numbers or texts containing numbers to brazilian currency (BRL).

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

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

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

formatToCAEPF

Formats a text containing numbers to CAEPF.

formatToCAEPF('128781')
//=> '128.781'

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

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

formatToCapitalized

Capitalizes the words in a text, except for words that are set to be uppercase or lowercase.

The first word of the text will not be lowercase even if set to.

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

Formats a text containing numbers to CEP.

formatToCEP('15998030')
//=> '15998-030'

formatToCEP('02999')
//=> '02999'

formatToCNPJ

Formats a text containing numbers to CNPJ.

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'

formatToCPF

Formats a text containing numbers to CPF.

formatToCPF('00000000')
//=> '000.000.00'

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

formatToCPF('366.418.768-70')
//=> '366.418.768-70'

formatToCPFOrCNPJ

Formats a string value containing numbers to CPF or CNPJ depending on its length.

formatToCPFOrCNPJ('00000000')
//=> '000.000.00'

formatToCPFOrCNPJ('366.418.768-70')
//=> '366.418.768-70'

formatToCPFOrCNPJ('32284981000138')
//=> '32.284.981/0001-38'

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

formatToDate

Formats a Date instance to brazilian formatted date, DD/MM/YYYY.

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

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

formatToDateTime

Formats a Date instance to brazilian formatted date and time, DD/MM/YYYY HH:mm.

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

formatToList

Formats an Array of string values into brazilian formatted list.

formatToList(['Vitor', 'William', 'Fernando'])
//=> 'Vitor, William e Fernando'

formatToList([])
// => ''

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

formatToList(['Direito Civil'])
//=> 'Direito Civil'

formatToNumber

Formats a number to brazilian formatted number.

formatToNumber(0)
//=> '0'

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

formatToNumber(.981)
//=> '0,981'

formatToNumber('19898.1298')
//=> '19.898,1298'

formatToPhone

Formats a text containing numbers to common brazilian phone.

formatToPhone('11')
//=> '(11'

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

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

formatToRG

Formats a text containing numbers to RG, specifying the state.

Today, brazilian-values supports only SP and RJ formats. Other values are just escaped to input.

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

Formats a string with digits by replacing digits within the range by the hider character.

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.@@@/@@@@-@@'

Parsers

parseToArray

Parses a brazilian formatted list into an Array.

parseToArray('')
//=> []

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

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

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

parseToDate

Parses a brazilian formatted date to a Date instance.

Throws an error if value does not match brazilian date format and if value is an invalid date.

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

Parses a brazilian formatted number to a number.

parseToNumber('10')
//=> 10

parseToNumber('-1.299')
//=> -1299

parseToNumber('0,981')
//=> 0.981

parseToNumber('19.898,1298')
//=> 19898.1298

Validators

isCAEPF

Validates if value is a CAEPF.

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

isCEP

Validates if value is a CEP.

isCEP('50.833-000')
//=> true

isCEP('02998-050')
//=> true

isCEP('00000000')
//=> true

isCEP('0')
//=> false

isCEP('1982891928981982198')
//=> false

isCNPJ

Validates if value is a CNPJ.

Related: isCPFOrCNPJ.

isCNPJ('41142260000189')
//=> true

isCNPJ('45.723.174/0001-10')
//=> true

isCNPJ('411407182')
//=> false

isCNPJ('11.111.111/1111-11')
//=> false

isCPF

Validates if value is a CPF.

Related: isCPFOrCNPJ.

isCPF('366.418.768-70')
//=> true

isCPF('36641876870')
//=> true

isCPF('213.198.013-20')
//=> false

isCPF('2131201872781')
//=> false

isCPF('11111111111')
//=> false

isCPFOrCNPJ

Validates if value is either a CPF or a CNPJ.

Related: isCPF, isCNPJ.

isCPFOrCNPJ('366.418.768-70')
//=> true

isCPFOrCNPJ('36641876870')
//=> true

isCPFOrCNPJ('213.198.013-20')
//=> false

isCPFOrCNPJ('2131201872781')
//=> false

isCPFOrCNPJ('11111111111')
//=> false

isCPFOrCNPJ('41142260000189')
//=> true

isCPFOrCNPJ('45.723.174/0001-10')
//=> true

isCPFOrCNPJ('411407182')
//=> false

isCPFOrCNPJ('11.111.111/1111-11')
//=> false

isDate

Validates if value matches brazilian date format and is a valid date.

isDate('03/08/2017')
//=> true

isDate('28/13/2017')
//=> false

isDate('03-08-2017')
//=> false

isDate('31/03/18')
//=> false

isDDD

Validates if value is a brazilian valid DDD (direct dialing at a distance) code.

Based on resolution No. 263 of June 8, 2001.

isDDD('81')
//=> true

isDDD('10')
//=> false

isDDD('555')
//=> false

isPhone

Validates if value matches common brazilian phone number, optionally with DDI, DDD and the ninth digit. If DDD is defined it'll be validated with isDDD.

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

License

Released under MIT license.

FOSSA Status