npm package: @rupiah-reborn/redenominasi
Description: The Indonesian Rupiah currency library support for redenomination that is decimal safe, zero-dependency, tree-shakeable.
Author: Bramasto Daru
Latest version: 0.1.0

# @rupiah-reborn/redenominasi 💸

Library TypeScript ringan, aman, dan tanpa dependensi eksternal untuk menangani kalkulasi dan formatting redenominasi Rupiah (Transisi dari Rp 1.000 menjadi Rp 1).

![npm version](https://img.shields.io/npm/v/@rupiah-reborn/redenominasi)
![license](https://img.shields.io/npm/l/@rupiah-reborn/redenominasi)
![size](https://img.shields.io/bundlephobia/min/@rupiah-reborn/redenominasi)

## 🌟 Fitur Utama

* **Zero Runtime Dependency:** Tidak memberatkan proyek Anda dengan library tambahan.
* **Decimal Safe:** Menggunakan metode aritmatika integer first untuk menjamin presisi (misal: 0.1 + 0.2 = 0.3).
* **Smart Input Cleaning:** Otomatis mendeteksi dan membersihkan format string kotor (misal: "Rp 1.500.000,00" atau "$1,500.50").
* **Dual Mode:** Mendukung konversi dari Rupiah Lama ke Baru, dan sebaliknya.
* **Formatting:** Built-in formatter untuk tampilan mata uang yang rapi (IDR).
* **Bulk Operations:** Memproses array data dalam satu kali pemanggilan fungsi (sangat cepat).
* **Framework Agnostic:** Kompatibel penuh dengan React, Vue, Angular, Svelte, atau Node.js murni.
* **TypeScript Ready:** Ditulis dengan TypeScript dan menyertakan definisi tipe lengka

## 📦 Instalasi

Install menggunakan npm, yarn, atau pnpm:

```bash
npm install @rupiah-reborn/redenominasi
# atau
yarn add @rupiah-reborn/redenominasi
# atau
pnpm add @rupiah-reborn/redenominasi
```
## 🚀 Usage JavaScript / TypeScript
#### 1. Konversi & Format (Paling Umum)
Berikut adalah panduan cepat menggunakan library ini di dalam project Anda. Gunakan ```formatOldToNew()``` untuk mengubah nilai Rupiah lama menjadi string tampilan Rupiah baru.
```bash
import { formatOldToNew } from '@rupiah-reborn/redenominasi';

const oldPrice = 150000; // Rp 150.000
const newPriceFormatted = formatOldToNew(hargaLama);

console.log(newPriceFormatted); // Output: "Rp 150,00" (Default config)
```

#### 2. Aritmatika (Best Practice)
Untuk menghindari floating point error, lakukan operasi matematika pada nilai lama, baru konversikan hasilnya.
```bash
import { oldToNew } from '@rupiah-reborn/redenominasi';

const barangA = 100; // 0.1
const barangB = 200; // 0.2

// ✅ Benar
const total = oldToNew(barangA + barangB);
console.log(total); // Output: 0.3 (Aman)

// ❌ Salah
// const total = oldToNew(barangA) + oldToNew(barangB); // Bisa jadi 0.30000000000000004
```
#### 3. Input String (Auto-Cleaning)
Library ini mendukung membaca input string yang mengandung simbol mata uang atau pemisah.
```bash
import { oldToNew } from '@rupiah-reborn/redenominasi';

console.log(oldToNew("Rp 1.500.000,50")); // Output: 1500.5 (Default config)
console.log(oldToNew("$1,500.50"));       // Output: 1.5005 (Default config)
```

#### 4. Operasi Bulk (Batch Processing)
Memproses banyak data sekaligus (misalnya untuk tabel atau list produk).
```bash
import { formatOldToNewBulk } from '@rupiah-reborn/redenominasi';

const listHarga = [15000, "Rp 25.000", 50000];
const hasil = formatOldToNewBulk(listHarga);

console.log(hasil); 
// Output: ['Rp 15,00', 'Rp 25,00', 'Rp 50,00']
```
## ⚙️ Konfigurasi
Anda bisa mengatur konfigurasi secara global atau per-panggilan fungsi (override).

#### Global Configuration (Disarankan di App.tsx / main.ts)

```bash
import { setConfig } from '@rupiah-reborn/redenominasi';

setConfig({
  currencySymbol: 'IDR', // Ganti simbol jadi IDR
  decimals: 1,           // Hanya 1 angka desimal
  trailingZero: true,    // Selalu tampilkan desimal (misal 100,0)
  locale: 'id-ID'        // Format Indonesia
});
```
#### Method-Level Override

```bash
import { formatOldToNew } from '@rupiah-reborn/redenominasi';

// Override khusus untuk panggilan ini saja (misal format USD style)
formatOldToNew(15000000, { 
    locale: 'en-US', 
    currencySymbol: 'IDR',
    trailingZero: true 

});
// Output: "IDR 15,000.00"
```
## ⚛️ Integrasi Framework
#### React JS
```tsx
import { formatOldToNew } from '@rupiah-reborn/redenominasi';

const ProductPrice = ({ price, config }) => (
  <span className="text-green-600 font-bold">
    {formatOldToNew(price, config)}
  </span>
);

/** Usage */

<ProductPrice 
  price={15000} 
  config={{ 
    locale: 'en-US',
    currencySymbol: 'IDR'
  }} 
/>
```
#### Vue 3
```javascript
<script setup>
import { formatOldToNew } from '@rupiah-reborn/redenominasi';
</script>

<template>
  <span>{{ formatOldToNew(15000, { currencySymbol: 'IDR', decimals: 0 }) }}</span>
</template>
```
## 🧩 API Reference
####  Core Functions
| Functions        | Input           | Output | Descriptions                           |
|---------------|-----------------|--------|-----------------------------------|
| oldToNew      | string \| number | number | Numeric conversion to new value (1000 -> 1). |
| newToOld      | string \| number | number | Numeric conversion to old value (1 -> 1000). |
| formatOldToNew| string \| number | string | Conversion + display formatting.          |
| formatNew     | string \| number | string | Display format for the new value. |
| formatOld     | string \| number | string | Display format for the old value (without conversion). |

####  Bulk Functions
| Fungsi            | Input | Output  |
|-------------------|-------|---------|
| oldToNewBulk      | Array | number[] |
| newToOldBulk      | Array | number[] |
| formatOldToNewBulk| Array | string[] |
| formatNewBulk     | Array | string[] |
| formatOldBulk     | Array | string[] |

# Contribution Guide

Thank you for your interest in contributing to @rupiah-reborn/redenominasi! 🎉  
We greatly appreciate your help, whether it's reporting bugs, suggesting new features, fixing documentation, or writing code. This document will help you get started smoothly with contributions.

## 📋 Prerequisites  
Before starting, make sure you have installed:  
- [Node.js](https://nodejs.org/) (LTS version recommended, e.g., v18+ or v20+)  
- [npm](https://www.npmjs.com/) (usually installed automatically with Node.js)

## 🛠️ Environment Setup  
- Fork this repository to your GitHub account.  
- Clone your forked repository to your local machine: 
```bash
git clone https://github.com/YOUR_USERNAME/redenominasi.git
cd redenominasi
```

- Install dependencies:  
```bash
npm install
```
## 💻 Development Workflow  
- **Project Structure:**  
- `src/`: TypeScript source code  
- `tests/`: Unit tests using Jest  
- `dist/`: Build outputs (do not manually edit files here)

- **Important Commands:**  
- Build once:  
  ```
  npm run build
  ```  
  (This uses Rollup to generate files in `dist/` folder (CJS, ESM, UMD).)  
- Watch mode (development):  
  ```
  npm run watch
  ```  
  (Automatically rebuilds when files are saved.)  
- Run tests:  
  ```
  npm test
  ```  
  (Must be run to ensure no regressions.)  
- Run tests in watch mode:  
  ```
  npm run test:watch
  ```

## 📏 Coding Guidelines  
- **Zero Runtime Dependency:**  
Do NOT add dependencies (like lodash, decimal.js, etc.) in `package.json` except as devDependencies. This library must stay lightweight and self-contained.

- **Type Safety:**  
Expect number or string as much as possible. Use the `RerValue` type for flexible input. See `src/public.ts` if uncertain.

- **Comments & Documentation (JSDoc):**  
Use English for all JSDoc and code comments (in `src/`).  
Example:  
```bash
/**

Converts value safely.

@param value Input value

@returns Converted number
*/

const myFunction(param) => {...}
```
## ✅ Testing  
- This project uses Jest.  
- Every new feature or bug fix must include test cases.  
- Add new test files in `tests/` if needed, or add to existing ones (`parser.test.ts`, `conversion.test.ts`, etc.).  
- Make sure all tests pass before creating a Pull Request:

- For bug fixes, first create a failing test that reproduces the bug, then fix the code until the test passes.

## 🚀 Submitting a Pull Request (PR)  
- Create a new branch from main:  
Use a descriptive name, e.g., `feat/add-bulk-support` or `fix/parser-comma-bug`. 

```bash
git checkout -b feat/your-feature-name
```

- Make changes and commit:  
Use clear commit messages (Conventional Commits recommended).  
Examples:
```bash  
feat: add support for custom thousand separator
fix: resolve floating point issue in conversion
```
- Push to your fork repository:  
```bash 
git push origin feat/your-feature-name
```
- Open a Pull Request on the main GitHub repository.  
- Describe what you changed and why.

## 📝 Reporting Bugs  
If you find an issue, please open a new Issue including:  
- Library version used  
- Sample code causing the error  
- Expected vs actual results

---

Thank you for contributing to make Rupiah redenomination easier for all developers! 🇮🇩