Moeda

A stdlib Moeda fornece aritmética monetária segura, formatação BRL e operações de negócio. Não requer importação — está disponível globalmente como Moeda.metodo(args).

Por que usar Moeda em vez de operadores normais? JavaScript (e portanto Jade DSL) usa IEEE 754 de ponto flutuante: 0.1 + 0.2 resulta em 0.30000000000000004, não 0.30. Moeda.somar(0.1, 0.2) retorna exatamente 0.30. Toda aritmética da Moeda é feita em centavos inteiros internamente.

---

Formatação

formatarBRL

formatado = Moeda.formatarBRL(valor)

Formata um número como moeda brasileira.

Console.escrever(Moeda.formatarBRL(1234.50))   // "R$ 1.234,50"
Console.escrever(Moeda.formatarBRL(1000000))   // "R$ 1.000.000,00"
Console.escrever(Moeda.formatarBRL(-500))      // "-R$ 500,00"
Console.escrever(Moeda.formatarBRL(0))         // "R$ 0,00"

formatarCompacto

formatado = Moeda.formatarCompacto(valor)

Formato abreviado para dashboards.

Console.escrever(Moeda.formatarCompacto(1500000))  // "R$ 1,5mi"
Console.escrever(Moeda.formatarCompacto(2000000))  // "R$ 2mi"
Console.escrever(Moeda.formatarCompacto(45000))     // "R$ 45mil"
Console.escrever(Moeda.formatarCompacto(1500))      // "R$ 1,5mil"
Console.escrever(Moeda.formatarCompacto(500))        // "R$ 500,00"

---

Parsing

parseBRL

valor = Moeda.parseBRL(entrada)

Converte texto no formato brasileiro para número. Retorna NaN se o formato não for reconhecido.

Moeda.parseBRL("R$ 1.234,50")  // 1234.50
Moeda.parseBRL("1.234,50")     // 1234.50
Moeda.parseBRL("1234,50")      // 1234.50
Moeda.parseBRL("-R$ 500,00")   // -500.00

---

Aritmética segura

somar, subtrair

resultado = Moeda.somar(a, b)
resultado = Moeda.subtrair(a, b)

total = Moeda.somar(0.1, 0.2)      // 0.30 (correto)
troco = Moeda.subtrair(10.00, 0.01) // 9.99 (correto)

multiplicar, dividir

resultado = Moeda.multiplicar(valor, fator)
resultado = Moeda.dividir(valor, divisor)

Arredonda para centavos. dividir por zero retorna NaN.

Moeda.multiplicar(3.33, 3)   // 9.99
Moeda.dividir(10.00, 3)      // 3.33
Moeda.dividir(100, 0)        // NaN

---

Comparações

Moeda.igual(a, b)        // booleano
Moeda.maior(a, b)        // booleano
Moeda.menor(a, b)        // booleano
Moeda.maiorOuIgual(a, b) // booleano
Moeda.menorOuIgual(a, b) // booleano

Comparam com precisão de centavos, evitando erros de ponto flutuante.

Moeda.igual(0.1 + 0.2, 0.3)  // verdadeiro (seria falso com ==)
Moeda.maior(100.01, 100.00)  // verdadeiro

---

Operações de negócio

descontar, acrescentar

resultado = Moeda.descontar(valor, percentual)
resultado = Moeda.acrescentar(valor, percentual)

preco_final = Moeda.descontar(100.00, 10)   // 90.00  (10% de desconto)
com_juros   = Moeda.acrescentar(100.00, 10) // 110.00 (10% de juros)

porcentagem

valor_perc = Moeda.porcentagem(base, percentual)

Calcula o valor que corresponde ao percentual.

comissao = Moeda.porcentagem(200.00, 15)  // 30.00

distribuir

parcelas = Moeda.distribuir(total, n)

Distribui um valor em n parcelas iguais, resolvendo o problema do centavo — a soma das parcelas sempre fecha exatamente o total.

parcelas = Moeda.distribuir(10.00, 3)
// [3.34, 3.33, 3.33]  ← soma = 10.00 exato
// Sem Moeda: 3.33 × 3 = 9.99 (perde 1 centavo)

parcelas = Moeda.distribuir(100.00, 4)
// [25, 25, 25, 25]

totalItens

total = Moeda.totalItens(lista_itens)

Calcula o total de um carrinho (quantidade × preço unitário), sem erros de ponto flutuante.

itens = EntityManager.buscar(ItemCarrinho)
total = Moeda.totalItens(itens)  // soma quantidade * precoUnitario de cada item

---

Referência completa

Método	Parâmetros	Retorno	Descrição
formatarBRL	valor: decimal	texto	Formato R$ 1.234,50
formatarCompacto	valor: decimal	texto	Formato R$ 1,5mi / R$ 45mil
parseBRL	texto: texto	decimal	Converte texto BRL para número
somar	a, b: decimal	decimal	Soma segura
subtrair	a, b: decimal	decimal	Subtração segura
multiplicar	valor, fator: decimal	decimal	Multiplica e arredonda
dividir	valor, divisor: decimal	decimal	Divide e arredonda (NaN se divisor=0)
igual	a, b: decimal	booleano	Igualdade com precisão de centavos
maior	a, b: decimal	booleano	Maior que
menor	a, b: decimal	booleano	Menor que
maiorOuIgual	a, b: decimal	booleano	≥ com precisão de centavos
menorOuIgual	a, b: decimal	booleano	≤ com precisão de centavos
descontar	valor, %: decimal	decimal	Aplica desconto percentual
acrescentar	valor, %: decimal	decimal	Aplica acréscimo percentual
porcentagem	base, %: decimal	decimal	Calcula valor do percentual
distribuir	total: decimal, n: numero	lista<decimal>	Distribui em parcelas (resolve centavo)
totalItens	itens: lista	decimal	Soma quantidade × preço