@glister/currency-utils 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+
+# @glister/currency-utils
+
+Lightweight, zero-dependency currency and number formatting utilities built on
+the native `Intl` API.
+
+- Auto locale detection  
+- Configurable default currency per project  
+- Tree-shakable (ESM)  
+- TypeScript-first  
+- Works in browser, Node.js, and Next.js (SSR-safe)
+
+---
+
+## Installation
+
+```bash
+npm install @glister/currency-utils
+# or
+pnpm add @glister/currency-utils
+# or
+yarn add @glister/currency-utils
+````
+
+---
+
+## Quick Start
+
+```ts
+import {
+  formatCurrency,
+  formatCompact,
+  formatCompactCurrency,
+  formatNumber,
+  formatPercent,
+} from '@glister/currency-utils';
+
+formatCurrency(1500);          // $1,500.00
+formatCompact(1500000);        // 1.5M
+formatCompactCurrency(1500);   // $1.5K
+formatNumber(1234567);         // 1,234,567
+formatPercent(0.075);          // 7.5%
+```
+
+---
+
+## Project-level Configuration
+
+You can configure the default currency and locale **once per project**.
+
+```ts
+import { setCurrencyConfig } from '@glister/currency-utils';
+
+setCurrencyConfig({
+  currency: 'NGN',
+  locale: 'en-NG',
+});
+```
+
+After this, **all formatters automatically respect the config**.
+
+```ts
+formatCurrency(1000); // ₦1,000.00
+```
+
+---
+
+## Auto Locale Detection
+
+If no locale is provided, the library automatically detects the user’s locale
+using the `Intl` API.
+
+* Browser → user locale
+* Node.js / SSR → safe fallback
+
+---
+
+## API Reference
+
+### `formatCurrency(amount)`
+
+Formats a number as currency.
+
+```ts
+formatCurrency(1200);
+// $1,200.00
+```
+
+---
+
+### `formatCompactCurrency(amount)`
+
+Formats a currency value using compact notation.
+
+```ts
+formatCompactCurrency(1200);
+// $1.2K
+```
+
+---
+
+### `formatCompact(amount)`
+
+Formats a number using compact notation.
+
+```ts
+formatCompact(1500000);
+// 1.5M
+```
+
+---
+
+### `formatNumber(amount)`
+
+Formats a number with locale separators.
+
+```ts
+formatNumber(1000000);
+// 1,000,000
+```
+
+---
+
+### `formatPercent(amount, fractionDigits?)`
+
+Formats a number as a percentage.
+
+```ts
+formatPercent(0.25);
+// 25%
+```
+
+---
+
+## TypeScript Support
+
+This package is written in TypeScript and ships with full type definitions.
+
+---
+
+## Zero Dependencies
+
+This library has **no external dependencies** and relies entirely on the
+native `Intl` API.
+
+---
+
+## License
+
+MIT
+
+````

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export type CurrencyConfig = {
+    locale?: string;
+    currency?: string;
+};
+export declare const setCurrencyConfig: (overrides: CurrencyConfig) => void;
+export declare const getCurrencyConfig: () => Required<CurrencyConfig>;

package/dist/config.js

@@ -0,0 +1,19 @@
+let config = {
+    locale: 'en-US',
+    currency: 'USD',
+};
+export const setCurrencyConfig = (overrides) => {
+    config = { ...config, ...overrides };
+};
+export const getCurrencyConfig = () => {
+    if (config.locale) {
+        return config;
+    }
+    const locale = typeof Intl !== 'undefined'
+        ? Intl.DateTimeFormat().resolvedOptions().locale
+        : 'en-US';
+    return {
+        locale,
+        currency: config.currency,
+    };
+};

package/dist/format.d.ts

@@ -0,0 +1,6 @@
+import { Amount } from './utils';
+export declare const formatCurrency: (amount: Amount) => string;
+export declare const formatCompactCurrency: (amount: Amount) => string;
+export declare const formatCompact: (amount: Amount) => string;
+export declare const formatNumber: (amount: Amount) => string;
+export declare const formatPercent: (amount: Amount, fractionDigits?: number) => string;

package/dist/format.js

@@ -0,0 +1,53 @@
+import { toNumber } from './utils';
+import { getCurrencyConfig } from './config';
+export const formatCurrency = (amount) => {
+    const value = toNumber(amount);
+    const { locale, currency } = getCurrencyConfig();
+    if (value === null)
+        return `${currency} 0.00`;
+    return value.toLocaleString(locale, {
+        style: 'currency',
+        currency,
+        currencyDisplay: 'narrowSymbol',
+    });
+};
+export const formatCompactCurrency = (amount) => {
+    const value = toNumber(amount);
+    const { locale, currency } = getCurrencyConfig();
+    if (value === null)
+        return `${currency} 0`;
+    return value.toLocaleString(locale, {
+        style: 'currency',
+        currency,
+        currencyDisplay: 'narrowSymbol',
+        notation: 'compact',
+        maximumFractionDigits: 2,
+    });
+};
+export const formatCompact = (amount) => {
+    const value = toNumber(amount);
+    const { locale } = getCurrencyConfig();
+    if (value === null)
+        return '0';
+    return value.toLocaleString(locale, {
+        notation: 'compact',
+        maximumFractionDigits: 2,
+    });
+};
+export const formatNumber = (amount) => {
+    const value = toNumber(amount);
+    const { locale } = getCurrencyConfig();
+    if (value === null)
+        return '0';
+    return value.toLocaleString(locale);
+};
+export const formatPercent = (amount, fractionDigits = 2) => {
+    const value = toNumber(amount);
+    const { locale } = getCurrencyConfig();
+    if (value === null)
+        return '0%';
+    return value.toLocaleString(locale, {
+        style: 'percent',
+        maximumFractionDigits: fractionDigits,
+    });
+};

package/dist/format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/format.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { formatCurrency, formatCompact, formatCompactCurrency, formatNumber, formatPercent, } from './format';
+import { setCurrencyConfig } from './config';
+describe('currency utils', () => {
+    it('formats currency', () => {
+        setCurrencyConfig({ currency: 'USD', locale: 'en-US' });
+        expect(formatCurrency(1200)).toBe('$1,200.00');
+    });
+    it('formats compact numbers', () => {
+        expect(formatCompact(1200000)).toContain('1.2');
+    });
+    it('formats compact currency', () => {
+        expect(formatCompactCurrency(1200)).toContain('$');
+    });
+    it('formats plain numbers', () => {
+        expect(formatNumber(1000000)).toBe('1,000,000');
+    });
+    it('formats percent', () => {
+        expect(formatPercent(0.25)).toBe('25%');
+    });
+    it('respects project currency config', () => {
+        setCurrencyConfig({ currency: 'NGN', locale: 'en-NG' });
+        expect(formatCurrency(1000)).toContain('₦');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './format';
+export * from './config';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './format';
+export * from './config';

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export type Amount = number | string;
+export declare const toNumber: (amount: Amount) => number | null;

package/dist/utils.js

@@ -0,0 +1,4 @@
+export const toNumber = (amount) => {
+    const value = Number(amount);
+    return Number.isFinite(value) ? value : null;
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@glister/currency-utils",
+  "version": "1.0.0",
+  "description": "Lightweight, tree-shakable currency and number formatting utilities",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "currency",
+    "intl",
+    "format",
+    "money",
+    "typescript",
+    "tree-shaking"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kherleefer/currency-utils/issues"
+  },
+  "homepage": "https://github.com/kherleefer/currency-utils#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kherleefer/currency-utils.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}