A type-safe, comprehensive, and Fiqh-compliant Zakat calculation library. Supports Gold, Silver, Business, Agriculture, Livestock, Professional Income, and Modern Assets (Crypto/Stocks).
npm install @islamic/zakattext
███████╗ █████╗ ██╗ ██╗ █████╗ ████████╗
╚══███╔╝██╔══██╗██║ ██╔╝██╔══██╗╚══██╔══╝
███╔╝ ███████║█████╔╝ ███████║ ██║
███╔╝ ██╔══██║██╔═██╗ ██╔══██║ ██║
███████╗██║ ██║██║ ██╗██║ ██║ ██║
╚══════╝╚═╝ ╚═╝╚╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝
P U R I F Y Y O U R W E A L T H
`
> "Take from their wealth a charity by which you purify them and cause them increase..."
> — Surah At-Tawbah 9:103
Zakat






!License
Rust library for Islamic Zakat calculation. Uses rust_decimal for precision.
Features
- Gold, Silver, Business, Agriculture, Livestock, Mining & Rikaz
- Stocks, Mutual Funds, Crypto (as liquid assets)
- Professional Income (Gross/Net)
- Zakat Fitrah
- Configurable Nisab thresholds
- Portfolio aggregation (Dam' al-Amwal)
- Dynamic Portfolio (Add, Remove, Replace assets with stable UUIDs)
- Asset Labeling (e.g., "Main Store", "Crypto Wallet")
- Input Sanitization & Validation (Rejects negative values, ensures safe configuration)
- Arabic Numeral Support (Eastern Arabic ٠-٩, Perso-Arabic ۰-۹)
- Flexible Configuration (Env Vars, JSON, Fluent API, Partial Loading)
- Fiqh Compliance (Jewelry exemptions, Madhab-specific rules, Hawl requirements)
- Hawl (Lunar Year) Tracking (Precise date-based eligibility)
- Stock Purification (Tathir) (Deduct impure income before calculation)
- Async Support (Optional integration with tokio and async-trait)
- Live Pricing Interface (e.g. for API integration)
- Detailed Reporting (Livestock in-kind details, calculation traces, metadata support)
- explain() Debugging (Get human-readable trace of calculations)
- to_explanation() Structured API (Get structured data for frontend rendering)
- with_locale() Input Parsing (Explicit EU/US/Arabic locale handling)
- Custom Strategies (Pluggable ZakatStrategy trait for custom rules)
- Full Serialization (Save/Load Portfolios via serde & JSON)
Internationalization (i18n)
zakat now fully supports internationalization for calculation summaries and explanations.
$3
- English (US): ZakatLocale::EnUS (Default)
- Indonesian: ZakatLocale::IdID
- Arabic (Saudi): ZakatLocale::ArSA
Use Cases & Documentation
We support multiple platforms. Please refer to the specific documentation for your needs:
- 🦀 Rust Usage Guide: Full API documentation for Rust developers.
- 🐍 Python Usage Guide: Using zakatrs bindings.
- 📦 JavaScript / Node.js Usage: Using @islamic/zakat WASM package.
- 💙 Flutter / Dart Usage: Using the zakat package.
Installation
$3
With Async Support (Default):
`toml
[dependencies]
zakat = "1.4.0"
rust_decimal = "1.39"
tokio = { version = "1", features = ["full"] }
`
Synchronous Only:
`toml
[dependencies]
zakat = { version = "1.4.0", default-features = false }
rust_decimal = "1.39"
`
$3
`bash
pip install zakatrs
`
$3
NPM:
`bash
npm install @islamic/zakat
`
JSR:
`bash
npx jsr add @islam/zakat
`
$3
`bash
dart pub add zakat
`
Build & Development
This project uses xtask — a Rust-based task runner that works cross-platform without needing external shell scripts.
$3
- Rust: Install via rustup
- wasm-pack: cargo install wasm-pack
- typeshare (optional): cargo install typeshare-cli for type generation
- flutter_rust_bridge (for Dart): See flutter_rust_bridge docs
$3
`bash
Build everything (Rust core, WASM, Dart, and generate types)
cargo xtask build-all
Sync version numbers across all manifests (Cargo.toml → package.json, pubspec.yaml, jsr.json)
cargo xtask sync-versions
Publish to all registries (Crates.io, NPM, JSR, PyPI, Pub.dev)
cargo xtask publish-all
Publish to individual platforms
cargo xtask publish-crates # Crates.io only
cargo xtask publish-pypi # PyPI only
cargo xtask publish-npm # NPM only
cargo xtask publish-jsr # JSR only
cargo xtask publish-dart # Pub.dev only
Dry run (validate without publishing)
cargo xtask publish-dart --dry-run
cargo xtask publish-all --dry-run
`
$3
1. Rust Core: Compiles the main library with cargo build --release
2. WASM Package: Uses wasm-pack build to generate the NPM package in pkg/
3. Type Generation: Uses typeshare to generate TypeScript (pkg/types.ts) and Kotlin (zakat_android/.../Types.kt) type definitions
4. Dart Bindings: Runs flutter_rust_bridge_codegen for Flutter bindings in zakat_dart/
$3
`bash
Build Rust core only
cargo build --release
Build WASM only
wasm-pack build --target web --out-dir pkg
Generate types only (requires typeshare-cli)
typeshare ./zakat-core --lang=typescript --output-file=./pkg/types.ts
typeshare ./zakat-core --lang=kotlin --output-file=./zakat_android/lib/src/main/java/com/islamic/zakat/Types.kt
Build Dart bindings only
cd zakat_dart && flutter_rust_bridge_codegen generate
`
$3
`bash
Run all tests
cargo test
Run tests without async features
cargo test --no-default-features
Run specific test file
cargo test --test portfolio_aggregation
`
Modules
| Module | Nisab |
| :--- | :--- |
| maal::precious_metals | 85g Gold / 595g Silver |
| maal::business | 85g Gold |
| maal::income | 85g Gold |
| maal::investments | 85g Gold |
| maal::agriculture | 653 kg |
| maal::livestock | Count-based |
| maal::mining | Rikaz: None / Mines: 85g Gold |
| fitrah | N/A |
Contributing
1. Add tests
2. Use rust_decimal
3. If adding async features, ensure they are gated behind #[cfg(feature = "async")]
4. Run cargo test and cargo check --no-default-features`