@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).

🌟 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:

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.

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.

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.

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).

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)

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

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

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

<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 (LTS version recommended, e.g., v18+ or v20+)
• npm (usually installed automatically with Node.js)

🛠️ Environment Setup

• Fork this repository to your GitHub account.
• Clone your forked repository to your local machine:

git clone https://github.com/YOUR_USERNAME/redenominasi.git
cd redenominasi

• Install dependencies:

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:

/**

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.

git checkout -b feat/your-feature-name

• Make changes and commit:
  Use clear commit messages (Conventional Commits recommended).
  Examples:

feat: add support for custom thousand separator
fix: resolve floating point issue in conversion

• Push to your fork repository:

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! 🇮🇩