intl-currency-helper 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# Intl Currency Helper
+
+A lightweight, zero-dependency JavaScript library for formatting numbers to currency strings using the native `Intl.NumberFormat` API. Compatible with both **Node.js** and **React**.
+
+## Features
+
+- 📂 **Universal**: Works in the browser and Node.js.
+- 🇲🇽 **Smart Defaults**: Pre-configured for Mexican Peso (`MXN`) and Spanish (Mexico) (`es-MX`).
+- 🛠️ **Customizable**: Easy to override currency, locale, and decimal precision.
+- 🧪 **Safe**: Includes input validation.
+
+## Installation
+
+```bash
+# If you published it to NPM
+npm install intl-currency-helper
+```
+
+Or just copy the files into your project.
+
+## Usage
+
+### Basic Usage (ES Modules)
+
+```javascript
+import { formatCurrency } from './index.js';
+
+// Default: MXN / es-MX
+console.log(formatCurrency(1234.56)); // Output: "$1,234.56"
+console.log(formatCurrency("100"));    // Output: "$100.00"
+```
+
+### Advanced Usage
+
+You can customize the formatting by passing an options object.
+
+```javascript
+import { formatCurrency, CURRENCIES, LOCALES } from './index.js';
+
+// US Dollars
+formatCurrency(1234.56, { 
+  currency: CURRENCIES.USD, 
+  locale: LOCALES.US 
+}); 
+// Output: "$1,234.56"
+
+// Euros in Spain
+formatCurrency(1234.56, { 
+  currency: CURRENCIES.EUR, 
+  locale: LOCALES.ES 
+}); 
+// Output: "1.234,56 €"
+
+// No decimals
+formatCurrency(1234.56, { 
+  minimumFractionDigits: 0, 
+  maximumFractionDigits: 0 
+}); 
+// Output: "$1,235"
+```
+
+## API
+
+### `formatCurrency(amount, options)`
+
+| Argument | Type | Description |
+| :--- | :--- | :--- |
+| `amount` | `Number`\|`String` | The value to format. |
+| `options` | `Object` | (Optional) Configuration object. |
+
+#### Options
+- `locale` (String): BCP 47 language tag (default: `'es-MX'`).
+- `currency` (String): ISO 4217 currency code (default: `'MXN'`).
+- `minimumFractionDigits` (Number): Default `2`.
+- `maximumFractionDigits` (Number): Default `2`.
+- `useGrouping` (Boolean): Whether to use thousand separators (default: `true`).
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,48 @@
+import { validateNumber, normalizeOptions } from './utils.js';
+
+/**
+ * Formats a number into a currency string using Intl.NumberFormat.
+ * 
+ * @param {number|string} amount - The numeric value to format.
+ * @param {object} [options] - Optional configuration.
+ * @param {string} [options.locale='es-MX'] - The BCP 47 language tag (e.g., 'es-MX', 'en-US').
+ * @param {string} [options.currency='MXN'] - The ISO 4217 currency code (e.g., 'MXN', 'USD', 'EUR').
+ * @param {number} [options.minimumFractionDigits=2] - Minimum number of decimal places.
+ * @param {number} [options.maximumFractionDigits=2] - Maximum number of decimal places.
+ * @param {boolean} [options.useGrouping=true] - Whether to use thousand separators.
+ * @returns {string} The formatted currency string.
+ * @example
+ * formatCurrency(1234.56) // "$1,234.56" (default MXN)
+ * formatCurrency(1234.56, { currency: 'USD', locale: 'en-US' }) // "$1,234.56"
+ */
+export const formatCurrency = (amount, options = {}) => {
+  const number = validateNumber(amount);
+  const config = normalizeOptions(options);
+
+  return new Intl.NumberFormat(config.locale, config).format(number);
+};
+
+/**
+ * Common currency codes for easy reference.
+ */
+export const CURRENCIES = {
+  MXN: 'MXN',
+  USD: 'USD',
+  EUR: 'EUR',
+  GBP: 'GBP',
+  CAD: 'CAD',
+  JPY: 'JPY',
+};
+
+/**
+ * Common locales for easy reference.
+ */
+export const LOCALES = {
+  MX: 'es-MX',
+  US: 'en-US',
+  ES: 'es-ES',
+  GB: 'en-GB',
+  JP: 'ja-JP',
+};
+
+export default formatCurrency;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "intl-currency-helper",
+  "version": "1.0.0",
+  "description": "A lightweight library for formatting numbers to currency using Intl.NumberFormat, optimized for both Node.js and React.",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "currency",
+    "format",
+    "intl",
+    "money",
+    "react",
+    "nodejs"
+  ],
+  "author": "Antigravity",
+  "license": "MIT"
+}

package/test.js

@@ -0,0 +1,78 @@
+import { formatCurrency, CURRENCIES, LOCALES } from './index.js';
+
+const tests = [
+  {
+    name: 'Default formatting (MXN / es-MX)',
+    input: 1234.56,
+    expected: '$1,234.56', // Note: specific spacing can vary by environment, we'll check contains
+  },
+  {
+    name: 'USD / en-US',
+    input: 1234.56,
+    options: { currency: CURRENCIES.USD, locale: LOCALES.US },
+    expected: '$1,234.56',
+  },
+  {
+    name: 'EUR / es-ES',
+    input: 1234.56,
+    options: { currency: CURRENCIES.EUR, locale: LOCALES.ES },
+    expected: '1.234,56\u00A0€', // Note: \u00A0 is non-breaking space
+  },
+  {
+    name: 'Negative number',
+    input: -500,
+    expected: '-$500.00',
+  },
+  {
+    name: 'Zero',
+    input: 0,
+    expected: '$0.00',
+  },
+  {
+    name: 'String input',
+    input: "99.99",
+    expected: '$99.99',
+  }
+];
+
+let passed = 0;
+let total = tests.length;
+
+console.log('--- Starting Tests ---\n');
+
+tests.forEach(test => {
+  try {
+    const result = formatCurrency(test.input, test.options);
+    // Use includes/regex/normalize to avoid tiny formatting discrepancies in different environments (like nbsp)
+    const normalizedResult = result.replace(/\u00A0/g, ' ').trim();
+    const normalizedExpected = test.expected.replace(/\u00A0/g, ' ').trim();
+
+    if (normalizedResult === normalizedExpected || normalizedResult.includes(normalizedExpected)) {
+      console.log(`✅ [PASS] ${test.name}`);
+      passed++;
+    } else {
+      console.log(`❌ [FAIL] ${test.name}`);
+      console.log(`   Expected: ${test.expected}`);
+      console.log(`   Received: ${result}`);
+    }
+  } catch (error) {
+    console.log(`❌ [ERROR] ${test.name}: ${error.message}`);
+  }
+});
+
+// Error handling test
+console.log('\n--- Error Handling Test ---');
+try {
+  formatCurrency('not-a-number');
+  console.log('❌ [FAIL] Should have thrown an error for invalid input');
+} catch (error) {
+  console.log('✅ [PASS] Threw error for invalid input: ' + error.message);
+}
+
+console.log(`\n--- Summary: ${passed}/${total} passed ---`);
+
+if (passed === total) {
+  process.exit(0);
+} else {
+  process.exit(1);
+}

package/utils.js

@@ -0,0 +1,31 @@
+/**
+ * Validates if the input is a valid number.
+ * @param {any} value - The value to validate.
+ * @returns {number} The validated number.
+ * @throws {Error} if the value is not a valid number.
+ */
+export const validateNumber = (value) => {
+  const number = Number(value);
+  if (isNaN(number)) {
+    throw new Error(`Invalid input: expected a number, but received ${typeof value} (${value})`);
+  }
+  return number;
+};
+
+/**
+ * Normalizes options for Intl.NumberFormat.
+ * @param {object} options - User-provided options.
+ * @returns {object} Normalized options.
+ */
+export const normalizeOptions = (options = {}) => {
+  const defaults = {
+    locale: 'es-MX',
+    currency: 'MXN',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+    style: 'currency',
+    useGrouping: true,
+  };
+
+  return { ...defaults, ...options };
+};