brazilian-utils/brazilian-utils

Utils library for specific Brazilian businesses

🇧🇷 Brazilian Utils

Utils library for Brazilian-specific businesses.

📖 Documentation

---

Vidas Negras Importam | Black Lives Matter. ✊🏽✊🏾✊🏿

To know how to help, just go to Vidas Negras Importam or Black Lives Matter.

---

We are changing

After one year of Brazilian Utils and lots of feedback, we decided to refactor our library to fix issues, create a website and make it easier for other developers to contribute. If you use v0 version, please, check v0 branch.

---

Table of Contents

• Getting Started
  • Installation
  • Usage
  • Contributors
  • License

Getting Started

Brazilian Utils is a library focused on solving problems that we face daily in the development of applications for the Brazilian business.

Installation

Using Brazilian Utils is quite simple and you can use it in some ways:

as npm package:

npm install --save @brazilian-utils/brazilian-utils

with yarn package manager:

yarn add @brazilian-utils/brazilian-utils

or <script> tag (global brazilianUtils):

<script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.cjs.production.min.js"></script>

Usage

To use one of our utilities you just need to import the required function as in the example below:

import { isValidCPF } from '@brazilian-utils/brazilian-utils';

isValidCPF('1232454233345'); // false

You can check a list of utilities by clicking here.

Contributors

Our "thank you" goes to these wonderful people (emoji key):

Hyan Mandian 💻 📖 🤔 ⚠️	Lucas Veloso 💻 📖 🤔 ⚠️	Andreo Vieira 💻 📖 🤔 🔧	Matheus Almeida 💻 📖 ⚠️	Fernando Rogelin 💻 📖 ⚠️	rodineijf 💻 📖 ⚠️	Emerson Laurentino 💻 📖 ⚠️
Leonardo Dutra 💻 📖 ⚠️	Victor Magalhães 💻 🔧	Amauri Dias 💻 🔧	Felipe F. Diogo 💻 ⚠️	Alan Raso 💻 ⚠️	Felipe Fetter 📖	Rafael Franco 💻 📖
Rafael Pezzetti 💻 ⚠️ 📖	Antonio Roberto Furlaneto 💻 📖 ⚠️	Felipe Nolleto Nascimento 💻 📖 ⚠️	Saulo Joab 📖	Pedro Arantes 💻 📖 ⚠️	Silvio Clécio 💻 📖 ⚠️	Lucas Nascimento 💻
Lincon Kusunoki 💻 📖 ⚠️	Marcelo Cristiano 💻 📖 ⚠️	Tarcísio Batista de Freitas Junior 📖	Lucas Carrias 📖 ⚠️ 💻 🔧

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

MIT

brazilian-utils's Issues

Boleto Validator - Support "convenio" and return which partial is wrong

This issue propose 2 features:

1. Add support for "convenio" in "boleto" validator, since it related formatter (format-boleto) supports "convenio"

2. Returns which partial is wrong in is-valid-boleto. To avoid break the current contract, we could just add a second parameter, that will be a flag to turn on this feature.

---

I could work on both, just checking if are valid features

Credit Card Validator

So, are you guys intrested, or have plans on implementing a credit card validator and issuer identifier?
If so, I would love to discuss and contribute. =D

[Feature request] Get "boleto" information from digitable line

The "boleto"'s digitable line has some information about the charge, for example:

• Expiration date
• Charge Value
• Associate Bank code
• Currency code

With that considered, I suggest that we should create a single function to get all values as bellow:

{
  expirationDate: Date,
  valueInCents: number,
  bankCode: string,
  currency: string
}

An alternative feature is to create functions to get each "boleto" information:

  function getExpirationDate(boleto: string): Date
  function getValueInCents(boleto: string): number
  function getBankCode(boleto: string) : string
  function getCurrency(boleto: string): string

Reference:
Campos dos boletos e linha digitável: o que significam?
Código dos bancos associados - Febraban

---

Edit: Add functions declaration examples

Add CPF mask

Improve class exports for better tree-shaking

On the issue #117 , @hyanmandian suggested a change on the way we import our functions in order to improve the tree-shaking.

Today we import something like that: import { isValidCPF } from" @ brazilian-utils/brazilian-utils" in a tree shakable way we import something like this: import isValidCPF from" @brazilian-utils/brazilian-utils/is-valid-cpf ";, so the babel plugin will help just replacing @brazilian-utils / brazilian-utils to @brazilian-utils/brazilian-utils. You can see something like that in date-fns or lodash libraries.`

I opened this issue so we can better discuss how to proceed with this feature.

Add eslint

Code formatter

Maybe use prettier integrated with eslint for that?

Problem with getCities on Node 10

The getCities function calls Array.prototype.flat() that is not available on Node 10.

I setup a Github Workflow that runs our tests using Node 10, 12 and 14... the Node 10 test fails.

https://github.com/brazilian-utils/brazilian-utils/actions/runs/186457250

Add prettier

Add Yarn install to documentation

Currently, the documentation only shows an installation with NPM. It'd be a good idea to add:

yarn add @brazilian-utils/brasilizan-utils
In my case, as I use the Yarn package manager, I had problems using the NPM Install directly. Some problems arose with nonexistent modules and types not found.
I had to delete node_modules and yarn.lock and then reinstall yarn to restore my project.

Add boleto validation

Adicionar gerador de CPF/CNPJ

Útil para testes.

Brazilian states

What do you guys think about functions to handle the Brazilian states?

something like:

• Get all states
• Find a specific state

where this could be applied?

• Select a state
• Show a state by its code

[
{code: 'sp', name: 'São Paulo'}, 
{code: 'rj', name: 'Rio de Janeiro'}
]

Add Yarn install to documentation

Description

Currently, the documentation only shows an installation with NPM. It'd be a good idea to add:

yarn add @brazilian-utils/brasilizan-utils

In my case, as I use the Yarn package manager, I had problems using the NPM Install directly. Some problems arose with nonexistent modules and types not found.
I had to delete node_modules and yarn.lock and then reinstall yarn to restore my project.

Improve documentation

[feature-request] Add formatPhone

I think it's a good idea to have the ability to format phones (landline and mobile)

as we already have the validators (isValidMobilePhone and isValidLandlinePhone),
we could also have the formaters (formatMobilePhone and formatLandlinePhone)

or

just have formatPhone that check if it's mobile or landline and apply the correct mask

Add CEP validation

Add CPF generator

[FEATURE REQUEST] isValidPhone(type) instead of isValidPhone()

Hi.

It would be nice to allow to validade a phone number by its type, for example:

const test = isValidPhone(); // Validates both phone and mobile phone number
const test = isValidPhone(false); // Validates only phone number
const test = isValidPhone(true); // Validates only mobile phone number

or maybe providing separated functions, like isValidPhone() and isValidMobilePhone().

cheers

Major release

When is this package leaving RC?

CPF with letters pass validation

Describe the bug
I'm not exactly sure if this is expected behaviour or a bug, but if I try to validade a CPF string with letters in it, the validator returns true IF the numbers match a valid CPF.

To Reproduce

// expected return: true
// returns: true
isValidCpf('391.838.380-66')

// expected return: false
// returns: false
isValidCpf('391.838.300-66')

// expected return: false
// returns: false
isValidCpf('391.838.3800-66')

// expected return: false
// returns: true
isValidCpf('foo391.838.380-66')

// expected return: false
// returns: true
isValidCpf('foo391.838.38test0-66')

// expected return: false
// returns: true
isValidCpf('3s9o1.8m3e8.3t8e0s-6t6')

// expected return: false
// returns: false (extra zero at end)
isValidCpf('3s9o1.8m3e8.3t8e0s-6t60')

While it seems nice that isValidCpf() get only the number types, I think this could lead to problems. I don't know, maybe I should use the /helper-only-numbers as well?

Environment:

• OS: macOS Mojave v10.14
• Node: v10.15.0
• @brazilian-utils/validators: v0.1.9

An in-range update of lint-staged is breaking the build 🚨

---

☝️ Important announcement: Greenkeeper will be saying goodbye 👋 and passing the torch to Snyk on June 3rd, 2020! Find out how to migrate to Snyk and more at greenkeeper.io

---

The devDependency lint-staged was updated from 10.0.8 to 10.0.9.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

lint-staged is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build could not complete due to an error (Details).

---

Release Notes for v10.0.9

10.0.9 (2020-03-24)

Bug Fixes

• use path.join and normalize to improve msys compatibility in resolveGitRepo (1ad263a)

Commits

The new version differs by 1 commits.

• 1ad263a fix: use path.join and normalize to improve msys compatibility in resolveGitRepo

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

CONTRIBUTING.md not have information how to create a new package

Is your feature request related to a problem? Please describe it.
I fork this project, but, i don't see any information how to create a new package with a correct structure.

Describe the solution you'd like
Just incrise information in CONTRIBUTING.md how to create a correct structure.

Add CNPJ generator

Create gh-pages branch

Publish all packages .d.ts (Typescript)

Is there any roadmap to publishing?

publish @brazilian-utils/generate-cnpj

The package @brazilian-utils/generate-cnpj is not published at npmjs. Are there any plans to publish this?

i would like suggest add the function of electronic invoice

Hello,

First, I would like to congratulate this idea of project! Nice!

I would like suggest add the function of electronic invoice.

Based on the 44-character code of an electronic key, to create one function to idnetify the type of document, for example:

Link: https://www.oobj.com.br/bc/article/como-%C3%A9-formada-a-chave-de-acesso-de-uma-nf-e-nfc-e-de-um-ct-e-e-um-mdf-e-281.html

Brazilian cities

Related to #82, is it a good idea to create a method that returns all Brazilian cities?

We may create a script that gets all cities from IBGE API, for instance, and saves them in a JSON. This way is easier to update cities.

[Documentation] Group utilities by category

At brazilian-utils site, All utilities are listed together without grouping by utility group/category, e.g CPF utilities, Boletos utilities and so on. Grouping the categories can make the navigation easier.

As you can see bellow, this is the current sidebar:

One suggestion is just to add a group title for each category in the docs, as this example from date-fns docs:

Improve tests

[FEATURE REQUEST] Add formatLandlinePhone()/formatMobilePhone()/formatPhone()

Hi.

It would be nice to provide the following format functions:

• formatLandlinePhone(landlinePhone: string): string - Formats a landline phone, e.g.: 9999999999 → (99) 9999-9999;
• formatMobilePhone(mobilePhone: string): string - Formats a mobile phone, e.g.: 99999999999 → (99) 99999-9999;
• formatPhone(phone: string): string - Formats a landline or mobile phone, e.g.: 9999999999 → (99) 9999-9999 or 99999999999 → (99) 99999-9999.

cheers

[FEATURE REQUEST] License Plate

I really don't know if we have some rules to create Mercosul/Brazilian license plate, but I think that we should keep support for both (after 2024 we can drop Brazilian support since Brazil will only use Mercosul format).

Add "Processo" validation

check if NNNNNNN-DD.AAAA.JTR.OOOO is valid.

ref: CNJ unifica numeração de processos em todo o país

Could not find a declaration file for module

Describe the bug

Could not find a declaration file for module '@brazilian-utils/is-valid-cpf'. 'node_modules/@brazilian-utils/is-valid-cpf/dist/index.js' implicitly has an 'any' type.
  Try `npm install @types/brazilian-utils__is-valid-cpf` if it exists or add a new declaration (.d.ts) file containing `declare module '@brazilian-utils/is-valid-cpf';`ts(7016)

Same with

import isValidCnpj from '@brazilian-utils/is-valid-cnpj';
or
import { isValidCpf, isValidCnpj } from '@brazilian-utils/validators';

To Reproduce
Steps to reproduce the behavior:

1. npm install @brazilian-utils/is-valid-cpf --save
2. import isValidCpf from '@brazilian-utils/is-valid-cpf';
3. See error

Expected behavior
It should import with no problem

Boleto Python.

Olá Pessoal, primeiramente, peço desculpas pela minha pergunta fugir do contexto deste projeto. Mas gostaria de saber se alguém que está aqui tem interesse em desenvolver uma lib para extração de dados de boletos bancários em python. Eu vejo uma certa limitação no javascript, pelo fato dele funcionar apenas na página web. Pretendo desenvolver uma lib que funcione ao lado do servidor, para tornar possível e facilitar o uso da api do servidor e do mobile. Alguém tem interessado?

Add CNPJ mask

Type definitions

Packages do not expose their type definitions

Describe the bug
Even though this project now uses Typescript, its packages do not expose their type definitions. This has been pointed by @matheusgrieger in #29 (comment).

As an example, see the dist folder for [email protected], which does not include a index.d.ts file.

[FEATURE REQUEST] New function: capitalize()

Hi.

It would be nice to provide some function like this:

capitalize("esponja de aço 60g") // Capitalizes to "Esponja de Aço 60G"
capitalize("fulano de tal") // Capitalizes to "Fulano de Tal"

cheers

Add phone validation

Update README.md

We need to update our README.md file before the 1.0 release.

[FEATURE REQUEST] formatCurrency() / formatDecimal() / formatPercent()

Hi.

What do you think about to declare those three functions? Something like:

function formatCurrency(value: number, precision: number = 2): string;

function formatDecimal(value: number, precision: number = 2): string;

function formatPercent(value: number): string;

cheers

---

Useful naive examples for study:

const number = 1234.56;

console.log("Preço:", number.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' }));

// > "Preço: R$ 1.234,56"

console.log("Quantidade:", number.toLocaleString('pt-BR', { style: 'decimal' }));

// > "Quantidade: 1.234,56"

console.log("Desconto:", number.toLocaleString('pt-BR', { style: 'percent' }));

// > "Desconto: 123.456%"

References:

• https://www.freeformatter.com/brazil-standards-code-snippets.html
• https://pt.stackoverflow.com/a/186798/14540
• https://www.w3schools.com/jsref/jsref_tolocalestring_number.asp
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat

[FIX] getCities

Today getCities return just city name, but in Brazil, we have some cities with same name in different states... So I think that we should return stateCode and maybe code (IBGE id) in the returned data.

Something like that:

[
  {
    code: 14324,
    name: 'Bom Jesus',
    stateCode: 'SC',
  },
  {
    code: 14324,
    name: 'Bom Jesus',
    stateCode: 'RS',
  },
  {
    code: 14324,
    name: 'Bom Jesus',
    stateCode: 'RN',
  },
  {
    code: 14324,
    name: 'Bom Jesus',
    stateCode: 'PB',
  },
  {
    code: 14324,
    name: 'Bom Jesus',
    stateCode: 'PI',
  }
]

I know this change will break our API, but since we're still in RC, maybe it's not a big problem. What do you think about it @arantespp @andreoav ?

[FEATURE REQUEST] Registry Office

Sometimes banking applications need a way to select a civil registry office when you need to registry something in the B3. The Brazilian government has a CSV with available civil registry offices https://portal.mj.gov.br/CartorioInterConsulta/. So the idea here is to create a utility function (like getCities and getStates) called getCivilRegistryOffices with filters like state and city that return an array with civil registry offices.

ReferenceError on Travis CI Build (Node 11.x)

I'm getting the following error at the Node v11 Travis CI build:

> npm run build

> @brazilian-utils/[email protected] prebuild /home/travis/build/LucasCarrias/brazilian-utils

> npm run update-cities

> @brazilian-utils/[email protected] update-cities /home/travis/build/LucasCarrias/brazilian-utils

> node scripts/getCitiesFromIBGE.js && prettier --write ./src/common/cities.ts

/home/travis/build/LucasCarrias/brazilian-utils/node_modules/prettier/index.js:35440

var queueMicrotask_1 = typeof queueMicrotask === 'function' ? queueMicrotask.bind(globalThis) // reuse resolved promise, and allocate it lazily
                                                                                
ReferenceError: globalThis is not defined

    at Object.<anonymous> (/home/travis/build/LucasCarrias/brazilian-utils/node_modules/prettier/index.js:35440:83)
    at Module._compile (internal/modules/cjs/loader.js:816:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:827:10)
    at Module.load (internal/modules/cjs/loader.js:685:32)
    at Function.Module._load (internal/modules/cjs/loader.js:620:12)
    at Module.require (internal/modules/cjs/loader.js:723:19)
    at require (internal/modules/cjs/helpers.js:14:16)
    at Object.<anonymous> (/home/travis/build/LucasCarrias/brazilian-utils/node_modules/prettier/bin-prettier.js:131:18)
    at Module._compile (internal/modules/cjs/loader.js:816:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:827:10)

This error seems to be triggered by the prettier --write ./src/common/cities.ts call.

One possible workaround is to update the .travis.yml Node build versions to the same versions as the GitHub's Workflows build.yml Node version. As far as I've checked, Node 10.x doesn't breaks the Travis build.

Not able to use getCities method

Hey guys, I'm trying to use the getCities method but I'm getting:
Uncaught TypeError: (0 , _brazilianUtils.getCities) is not a function error on the console. I installed the lib using yarn and I'm importing it in my js file as below. What could be the issue?

import { getCities } from '@brazilian-utils/brazilian-utils';
...

const Methods = {
async init() {
    await Methods.getCitiesList();
 }

getSelectedOption(sel) {
     var opt;
     for (var i = 0, len = sel.options.length; i < len; i++) {
       opt = sel.options[i];
       if (opt.selected === true) {
         break;
       }
     }
     return opt;
   },

async getCitiesList() {
     Elements.selectState.addEventListener('change', (el) => {
       const selectedState = Methods.getSelectedOption(Elements.selectState).value;
       const citiesList = getCities(selectedState);
       console.log(citiesList);
     });
   },

};

Validador de conta bancária

Boa noite.

Gostaria de saber se pra vocês, incluir um validador de contras bancárias, para alguns bancos em que possuem esse padrão bem definido, é relevante.
Se sim, posso organizar o PR dessa funcionalidade.

Abaixo um PDF com todas as regras:
http://177.153.6.25/ercompany.com.br/boleto/laravel-boleto-master/manuais/Regras%20Validacao%20Conta%20Corrente%20VI_EPS.pdf

@brazilian-utils/format-boleto unavailable on NPM

Describe the bug
Package format-boleto not being found on NPM to be installed on project.

To Reproduce
Steps to reproduce the behavior:

1. npm install @brazilian-utils/format-boleto --save
2. See error

Expected behavior
Package should be installed without problems.

Additional context
Package is not being found on the NPM registry.

Add Yarn install to documentation

Description

Currently, the documentation only shows an installation with NPM. It'd be a good idea to add:

yarn add @brazilian-utils/brazilian-utils

In my case, as I use the Yarn package manager, I had problems using the NPM Install directly. Some problems arose with nonexistent modules and types not found.
I had to delete node_modules and yarn.lock and then reinstall yarn to restore my project.