README

A high-performance, dual-language utility package for formatting Indian currency amounts, percentages, and ranges.

This monorepo contains native implementations for both TypeScript and PHP, guaranteed to behave identically via shared test fixtures.

📚 Packages

✨ Features

• Standardized Indian currency short-form: K, Lakh, Cr.
• Percentage formatting: Automatic trailing zero removal.
• Range formatting: For min/max values (e.g., ₹1 Lakh - ₹5 Lakh).
• Transparent formatting: Shows both short-form and actual numeric values.
• 100% native performance: Zero FFI overhead in both languages.
• Guaranteed behavioral parity: Verified via shared JSON test fixtures.

📦 Installation

TypeScript / Node.js

npm install @sikandarmoyaldev/indian-amount-formatter
# or
pnpm add @sikandarmoyaldev/indian-amount-formatter

PHP

composer require sikandarmoyaldev/indian-amount-formatter

📖 Usage

TypeScript

import * as Inr from '@sikandarmoyaldev/indian-amount-formatter';

console.log(Inr.formatAmount(200000)); // Output: ₹2 Lakh
console.log(Inr.formatAmount(4999)); // Output: ₹4.99K
console.log(Inr.formatAmount(null)); // Output: Unlimited
console.log(Inr.formatPercentage(3.5)); // Output: 3.5%
console.log(Inr.formatAmountRange(100000, 500000)); // Output: ₹1 Lakh - ₹5 Lakh
console.log(Inr.formatAmountWithActual(140000)); // Output: ₹1.4 Lakh (₹1,40,000)

PHP

use Sikandarmoyaldev\IndianAmountFormatter\InrFormatter as Inr;

echo Inr::formatAmount(200000); // Output: ₹2 Lakh
echo Inr::formatAmount(4999); // Output: ₹4.99K
echo Inr::formatAmount(null); // Output: Unlimited
echo Inr::formatPercentage(3.5); // Output: 3.5%
echo Inr::formatAmountRange(100000, 500000); // Output: ₹1 Lakh - ₹5 Lakh
echo Inr::formatAmountWithActual(140000); // Output: ₹1.4 Lakh (₹1,40,000)

💡 API Reference

Note: You can also use the InrFormatter class to configure options like round: true or round: false.

🛠️ Development

This project uses a monorepo structure managed by pnpm (for TypeScript) and composer (for PHP).

Prerequisites

• Node.js (v18 or higher)
• pnpm
• PHP (v8.1 or higher)
• Composer

Setup

# Install root and TypeScript dependencies
pnpm install

# Install PHP dependencies
pnpm run php install

🧪 Running Tests

# Run all tests (TypeScript + PHP)
pnpm test

# Run only TypeScript tests (Vitest)
pnpm run test:ts

# Run only PHP tests (PHPUnit)
pnpm run test:php

🎨 Formatting Code

We use Prettier globally to format TS, JS, JSON, MD, and PHP files.

# Format all files
pnpm format

# Check if files are formatted correctly (used in CI)
pnpm format:check

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.