@bakissation/dinar

A type-safe Algerian Dinar (DZD) money type for TypeScript. Amounts are stored as integer centimes, so arithmetic never drifts into floating-point error — and it ships with zero runtime dependencies.

• 🪙 Integer-precise — every amount is an integer number of centimes; no 0.1 + 0.2 surprises.
• ➗ Remainder-free allocation — split a total across shares without creating or losing a centime.
• 🧮 Money-correct rounding — half-up (default), half-even, floor, ceil for VAT/percentage math.
• 🌍 fr / ar formatting & parsing — render 1 234,56 DA / 1 234,56 دج; parse messy human and CSV input.
• 🧩 Zero dependencies, ESM + CommonJS, strict types.

Install

npm install @bakissation/dinar

Requires Node.js ≥ 18. No runtime dependencies.

Quick start

import { Dinar } from '@bakissation/dinar';

const price = Dinar.fromDinars(1500);               // 1 500,00 DA
const total = price.add(price.percentage(19));      // + 19% VAT
console.log(total.format());                        // "1 785,00 DA"

// Split a bill three ways — no lost centime
Dinar.fromCentimes(100).allocate([1, 1, 1]);        // 34 + 33 + 33

// Minor units, exactly what the SATIM gateway expects
price.toCentimes();                                 // 150000

// Parse messy human / CSV input
Dinar.fromString('1 234,56 DA').centimes;           // 123456

Why centimes?

Money in floating point is a bug waiting to happen (0.1 + 0.2 !== 0.3). Dinar keeps every value as an integer count of centimes (1 DA = 100 centimes) and only converts to a decimal for display. That single invariant is what makes totals, taxes, and splits trustworthy. See docs/overview.

Documentation

Full docs live in docs/:

| | | |---|---| | Overview & concepts | Why a money type, the centimes invariant, rounding, glossary | | Getting started | Install, construct, the common recipes | | API reference | Every constructor, method, and option on Dinar | | Architecture | Internals: the integer invariant, the allocation algorithm, parsing & formatting |

A foundation for Algerian fintech

dinar is a foundational money primitive for open, direct-integration TypeScript tooling around Algerian payments and fiscal workflows. Because every amount is integer centimes, toCentimes() returns exactly the minor-units value payment gateways expect.

Contributing

Issues and PRs welcome — read CONTRIBUTING.md and the Code of Conduct. Releases are automated from Conventional Commits via semantic-release; don't bump the version or edit the changelog by hand.

Credits

Built and maintained by Abdelbaki Berkati — berkati.xyz · @bakissation.

License

MIT