portujs/extenso.js

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

Extenso.js

Números por extenso com JavaScript.

Características

• Números até duodecilhões.
• Números negativos.
• Números decimais.
• Valores monetários (BRL, EUR e mais).
• 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 ou number

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

Se o valor for do tipo number, então 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, é muito recomendado que os números sejam encapsulados em string devivo ao fato que no JavaScript números (do tipo number) maiores que 9 quatrilhões perdem valores sendo imprecisos (experimente este artigo para mais informações [Tableless]).

Números envolvidos em strings deverão seguir o formato natural de escrita de números. Você poder usar - no início para representar números negativos e vírgula (,) ou ponto (.) para separação de milhares e decimais, onde por padrão segue-se o formato de escrita do Brasil podendo alterar as prefencias (como será visto no parâmetro number.decimalSeparator).

options

Obs.: Parâmetro opcional.

• Tipo: object

Configurações opcionais de escrita.

• mode (string)
• locale (string)
• negative (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'

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 (moeda brasileira).
• EUR - Para escrever valores em Euro (moeda da maior parte da União Européia).
• ECV - Para escrever valores em Escudo (moeda de Cabo Verde).

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: 'ECV' } }) // '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

extenso.js's Issues

Criar modo informal para números grandes

Por exemplo:

• 2,5 bi - Um vírgula cinco bilhões

extenso.min.js vulnerabilidade

node_modules/extenso/dist/extenso.min.js (6:46822): Use of eval in "node_modules/extenso/dist/extenso.min.js" is strongly
discouraged as it poses security risks and may cause issues with minification.
Esse erro ocorre em diversas outras linhas porém ia ficar muito sujo aqui
Ao rodar o build no meu projeto peguei essa notificação.
Lendo as docs no w3c e no mdn altamente desencorajado o uso do eval.
Visto que ele é muito perigoso.

Retorno do valor 0

Quando passo:
extenso(0, { mode: 'currency' })
#=> zero centavos

Mas com:
extenso(0)
#=> undefined

Escalas curta e longa

Olá, Matheus! Primeiramente obrigado pelo projeto, que com certeza irei utilizar.

Mas eu vim aqui relatar que há uma pequena diferença na nomenclatura de escalas pt_PT/pt_BR

---

Resumidamente, o "nosso" bilhão é mil milhões em Portugal, nosso trilhão é bilião etc

Wikipedia – Escalas curta e longa

---

Eu não acredito que isso seja um problema urgente - até porque meu alvo é pt_BR - mas como tem a opção locale, acredito que devemos pensar em uma possível solução para isso.

Desde já agradeço!
Gabriel Rodrigues

Extenso com reais e/ou centavos?

Que tal escrever o valor já com a(s) palavra(s) reais e/ou centavos?
Se concordar, faço um pull request.

Valores monetários com uma casa decimal devolve texto incorreto.

Este exemplo:
extenso("6.5", { locale: 'pt', mode: 'currency', currency: { type: 'EUR' } })
devolve ""seis euros e cinco cêntimos""
onde deveria estar
"seis euros e cinquenta cêntimos"

no meu cenário corrigi da segunte forma
var valor = parseFloat('6.5').toFixed(2);
var valorExtenso = extenso(valor, { locale: 'pt', mode: 'currency', currency: { type: 'EUR' } });

Criar opção de numeros ordinais

Uma sugestão seria poder escrever os números de forma ordinal:

console.log(extenso(1, {
mode: 'number',
number: {
ordinal:true
}
}));
resultado: primeiro

console.log(extenso(11, {
mode: 'number',
number: {
ordinal:true
}
}));
resultado: décimo primeiro

Erro em valor monetário acima de 1 milhão

Olá, ocorre um erro na formatação do número extenso quando tento puxar um valor monetário acima de 1 milhão de reais:

Melhoria na flexão de gêneros

Não está passado para o feminino: duzentos > duzentas, trezentos > trezentas, e assim por diante.

Ver mais em https://pt.wikipedia.org/wiki/Dual.

Esse repo ainda é ativo?

Conheci o projeto por conta um tweet e resolvi dar uma olhada, notei que tem algumas issues em aberto, mas não parece que tem muito desenvolvimento, acredito que seria interessaste adicionar tipos utilizando typscript ou js doc.

0 (zero) retorna undefined no modo numerico

extenso('0', {mode: 'number'}) retorna undefined ao invés de zero

Se o mode for currency funciona OK, mas numerico não

usando a versao 2.0.1

Considerar usar .npmignore para filtrar o que é publicado

Talvez coisas como webpack.config.js etc não devam ir.

Data por extenso?

Tem interesse em implementar data por extenso?

Ou de aceitar implementação?

Pacote não publicado no NPM

Aparentemente a publicação npm desse pacote está desatualizada.

Alguma previsão de publicar as novas features para o npm em uma nova versão?

Problema com números fracionários

Os exemplos com números fracionários do README estão retornando Error: Invalid number

Os exemplos:

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'

O erro:

webpack://extenso/./src/write-all.js?:56
    throw new Error('Invalid number');
    ^

Error: Invalid number
    at eval (webpack://extenso/./src/write-all.js?:56:11)
    at main (/home/matheus/test/random/index2.js:4:13)
    at Object.<anonymous> (/home/matheus/test/random/index2.js:8:1)
    at Module._compile (internal/modules/cjs/loader.js:955:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:991:10)
    at Module.load (internal/modules/cjs/loader.js:811:32)
    at Function.Module._load (internal/modules/cjs/loader.js:723:14)
    at Function.Module.runMain (internal/modules/cjs/loader.js:1043:10)
    at internal/main/run_main_module.js:17:11

ERROR in extenso.min.js from UglifyJs

me da um erro ao fazer builder

Tem como usar no react-native?

Estou com um projeto em react-native, e ao usar "import extenso from 'extenso';
tenho um erro.
`ReferenceError: Property 'module' doesn't exist, js engine: hermes
ERROR Invariant Violation: "main" has not been registered. This can happen if:

• Metro (the local dev server) is run from the wrong folder. Check if Metro is running, stop it and restart it in the current project.
• A module failed to load due to an error and AppRegistry.registerComponent wasn't called., js engine: hermes`

só apagar o uso dele, e nao tem erro, então queria saber se tem alguma maneira de usar ele.
Eu uso React-Native em um projeto Expo.

Criar modo informal para decimais

Criar modo de escrita informal para números decimais.

Por exemplo:

• 1,5 - Um vírgula cinco.
• 1,10 - Um vírgula dez.
• 3,14 - Três vírgula quatorze.

Adicionar opção para a moeda de Cabo Verde

Sou de Cabo Verde aonde se fala portugues, sugiro que o current.type também tenha opção de personalizar para outras moedas por exemplo "quarenta e dois escudos" escudos é a moeda que se usa aqui

Originally posted by @natalio in #10 (comment)

Erro ao solicitar valores monetários não inteiros

Números sem acentos

Criar uma opção para retornar números sem acentos.

Adicionar suporte para o Metical de Moçambique

Pude notar que ainda não tem a opção da moeda Moçambicana que é o metical, proponho que seja adicionada esta opção.

A abreviação é MZM, mas usa-se também o MZN
Singular = metical
Plural = meticais

Por exemplo:
1 metical
2 meticais

Criar dois modos para números negativos

Podemos dizer, por exemplo, um negativo ou menos um.