Extenso.js

Uma biblioteca avançada para escrever números por extenso (em português).

Features

• Números até duodecilhões.
• Números negativos.
• Números decimais.
• Valores monetários (BRL, EUR e mais).
• Escala curta e longa.
• Preferências de dialetos (Brasil, Portugal e mais).
• Preferências de gênero.

Instalação

Instale-o com seu gerenciador preferido:

• npm: npm install extenso
• Yarn: yarn add extenso

Uso

var extenso = require('extenso')

Sintaxe

extenso(number[, options])

number

Obs.: Parâmetro obrigatório.

• Tipo: string, number ou bigint

O número que deverá ser escrito por extenso.

Se o valor for do tipo number, ele deve ser um número com parte inteira segura, ou seja, o valor deve ser válido na verificação com Number.isSafeInteger(). No entanto, é altamente recomendado que os números sejam encapsulados em string devido ao fato de que, no JavaScript, números (do tipo number) maiores que 9 quatrilhões perdem precisão. Alternativamente, pode-se utilizar números BigInt (do tipo bigint) adicionando n no final, por exemplo, 10000000000000001n (leia este artigo para mais informações).

Números envolvidos em strings deverão seguir o formato natural de escrita de números. Você pode usar - no início para representar números negativos e vírgula (,) ou ponto (.) para separação de milhares e decimais, seguindo, por padrão, o formato de escrita do Brasil. Esse formato pode ser alterado conforme a preferência, utilizando o parâmetro number.decimalSeparator.

options

Obs.: Parâmetro opcional.

• Tipo: object

Configurações opcionais de escrita.

• mode (string)
• locale (string)
• negative (string)
• scale (* string *)
• currency (object)
• currency.type (string)
• number (object)
• number.gender (string)
• number.decimal (string)
• number.decimalSeparator (string)

mode

Define o modo de escrita do número.

Pode ser:

• number (valor padrão) - Para escrever números simples.
• currency - Para escrever valores monetários.

Exemplo

extenso('42') // 'quarenta e dois'
extenso('42', { mode: 'number' }) // 'quarenta e dois'
extenso('42', { mode: 'currency' }) // 'quarenta e dois reais'

negative

Define o modo de escrita do valor negativo.

• formal (valor padrão) - Para escrever o número no modo formal.
• informal - Para escrever o número no modo informal.

Exemplo

extenso('-42') // 'quarenta e dois negativo'
extenso('-42', { negative: 'formal' }) // 'quarenta e dois negativo'
extenso('-42', { negative: 'informal' }) // 'menos quarenta e dois'

scale

Define a escala de escrita (curta ou longa).

As escalas curta e longa são dois sistemas de escrita dos números. A escala curta é a utilizado no Brasil, enquanto que a escala longa é a utilizada no restante dos paises de lingua portuguesa.

A escrita diverge somente em números iguais ou superiores a um milhar de milhões (>= 10e9), números inferiores a isso seguem com a escrita idêntica em ambas as escalas.

Mais informações aqui [Wikipédia].

• short (valor padrão) - Para escrever o número utilizando a escala curta.
• long - Para escrever o número utilizando a escala longa.

Exemplo

extenso('2.000.000.001') // 'dois bilhões e um'
extenso('2.000.000.001', { scale: 'short' }) // 'dois bilhões e um'
extenso('2.000.000.001', { scale: 'long' }) // 'dois mil milhões e um'

locale

Define a localização para o modo de escrita.

A escrita de alguns números pode váriar de país para país (e talvez até de região para região), por exemplo, o número 16 é escrito dezesseis no Brasil, enquanto que em Portugal é escrito dezasseis. A configuração dessas diferenças é feita aqui.

• br (valor padrão) - Para escrever no dialeto do Brasil.
• pt - Para escrever no dialeto de Portugal.

Exemplo

extenso('16') // 'dezesseis'
extenso('16', { locale: 'br' }) // 'dezesseis'
extenso('16', { locale: 'pt' }) // 'dezasseis'

currency.type

Define o código ISO da moeda em que o número deverá ser escrito.

• BRL (valor padrão) - Para escrever valores em Real brasileiro.
• EUR - Para escrever valores em Euro.
• CVE - Para escrever valores em Escudo cabo-verdiano.
• MZN - Para escrever valores em Metical moçambicano.

Exemplo

extenso('42', { mode: 'currency' }) // 'quarenta e dois reais'
extenso('42', { mode: 'currency', currency: { type: 'BRL' } }) // 'quarenta e dois reais'
extenso('42', { mode: 'currency', currency: { type: 'EUR' } }) // 'quarenta e dois euros'
extenso('42', { mode: 'currency', currency: { type: 'CVE' } }) // 'quarenta e dois escudos'
extenso('42', { mode: 'currency', currency: { type: 'MZN' } }) // 'quarenta e dois meticais'

number.gender

Define o gênero do número que será escrito.

Alguns números podem ser representados tanto no modo masculino quanto no modo feminino, por exemplo, 42 pode ser escrito como quarenta e dois ou 42 ou quarenta e duas.

• m (valor padrão) - Para escrever no modo masculino.
• f - Para escrever no modo feminino.

Exemplo

extenso('42') // 'quarenta e dois'
extenso('42', { number: { gender: 'm' } }) // 'quarenta e dois'
extenso('42', { number: { gender: 'f' } }) // 'quarenta e duas'

number.decimal

Define o modo de escrita do valor decimal.

• formal (valor padrão) - Para escrever no modo formal.
• informal - Para escrever no modo informal.

Exemplo

extenso('3,14') // 'três inteiros e quatorze centésimos'
extenso('3,14', { number: { decimal: 'formal' } }) // 'três inteiros e quatorze centésimos'
extenso('3,14', { number: { decimal: 'informal' } }) // 'três vírgula quatorze'

number.decimalSeparator

Define o separador de inteiro e decimal.

• comma (valor padrão) - Para usar vírgula como separador (ex. 3,14).
• dot - Para usar ponto como separador (ex.: 3.14)

Observação

Quando o separador de decimal é o . (ponto) automaticamente o separador de milhar será o , (vírgula) e vice-versa.

Exemplo

extenso('3,14')
extenso('3,14', { number: { decimalSeparator: 'comma' } })
extenso('3.14', { number: { decimalSeparator: 'dot' } })

// 'três inteiros e quatorze centésimos'

Contribuição

Oi, você é de Portugal, Angola, Moçambique ou qualquer outro país que usa fala português? Viu alguma escrita de números que é diferente no seu país? Então abra uma issue e vamos discutir como adaptar essas caracteristicas ao projeto para deixá-lo o mais completo possível.

Viu algum erro ou qualquer coisa que pode ser melhorada?

Você pode, portanto:

• Abrir uma issue.
• Enviar um pull request.
• Comentar no trecho do código que você acredita que pode ser melhorado.

Regras

Tendo em vista a participação de falantes da língua portuguesa, escreva:

• Nome de váriaveis, funções e outras coisas do tipo em inglês.
• Nome dos arquivos e diretórios em inglês.
• Issues, pull requests e comentários em português.
• Descrição dos testes em português.
  • Regra 1: Deve ter o formato: Deve(m) + verbo + descrição.
  • Regra 2: Nunca use ponto final na descrição.
• Mensagem de commits em português.
  • Regra 1: Inicie-os sempre em caixa alta.
  • Regra 2: Nunca use ponto final na descrição.

TODO

• Traduzir o README.md em inglês (README-en.md).

Licença

MIT © Matheus Alves