{"_id":"monie-utils","_rev":"3-e6463b7b1407da677bb264bf061a22ec","name":"monie-utils","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"monie-utils","version":"1.0.0","keywords":["money","currency","finance","utilities","formatting","conversion","typescript","javascript","payments","calculations"],"author":"","license":"MIT","_id":"monie-utils@1.0.0","maintainers":[{"name":"devferanmi","email":"devferanmi@gmail.com"}],"homepage":"https://github.com/yourusername/monie-utils#readme","bugs":{"url":"https://github.com/yourusername/monie-utils/issues"},"dist":{"shasum":"ecf6697e50aaceb6a1695d8905a8ad98f2e0835b","tarball":"https://registry.npmjs.org/monie-utils/-/monie-utils-1.0.0.tgz","fileCount":9,"integrity":"sha512-fYpv6zqBkCYqPKpnsGRaYtgnF6ZifdcesN43QtCIfYnyY0O7ihA71sJxJ9OcpjBHsQ3gqqYRzSGPESa/i6kzsg==","signatures":[{"sig":"MEUCIGU0PFd4QNoZYqqhO1Lck2Idh+1xedzDtWrPlHHfSr4KAiEAhhPrtrfRkpmHqONSzcbKVM61v2/S7bID2ahP1c5Q6q0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":561549},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","gitHead":"ef6ec95b15780fff02c2890226e0217d10eeb7ea","scripts":{"dev":"vite","docs":"typedoc","lint":"eslint src/**/*.ts","test":"jest","build":"tsup","format":"prettier --write src/**/*.ts","prepare":"husky","lint:fix":"eslint src/**/*.ts --fix","test:watch":"jest --watch","type-check":"tsc --noEmit","format:check":"prettier --check src/**/*.ts","test:coverage":"jest --coverage","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"devferanmi","email":"devferanmi@gmail.com"},"repository":{"url":"git+https://github.com/yourusername/monie-utils.git","type":"git"},"_npmVersion":"10.9.2","description":"A comprehensive TypeScript library for money-related utilities including currency formatting, conversion, validation, and financial calculations","directories":{"doc":"docs"},"_nodeVersion":"23.6.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.5.0","vite":"^7.0.6","husky":"^9.1.7","eslint":"^9.31.0","ts-jest":"^29.4.0","typedoc":"^0.28.7","prettier":"^3.6.2","@eslint/js":"^9.31.0","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^24.1.0","@commitlint/cli":"^19.8.1","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.3","@typescript-eslint/parser":"^8.38.0","@commitlint/config-conventional":"^19.8.1","@typescript-eslint/eslint-plugin":"^8.38.0"},"_npmOperationalInternal":{"tmp":"tmp/monie-utils_1.0.0_1753456819770_0.7552858026408606","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"monie-utils","version":"1.1.0","keywords":["money","currency","finance","utilities","formatting","conversion","typescript","javascript","payments","calculations"],"author":"","license":"MIT","_id":"monie-utils@1.1.0","maintainers":[{"name":"devferanmi","email":"devferanmi@gmail.com"}],"homepage":"https://github.com/yourusername/monie-utils#readme","bugs":{"url":"https://github.com/yourusername/monie-utils/issues"},"dist":{"shasum":"e505de6106f26e8a74f63df20f4c78f42598821b","tarball":"https://registry.npmjs.org/monie-utils/-/monie-utils-1.1.0.tgz","fileCount":9,"integrity":"sha512-i5CLI0ra2YGDQNKMZL3XM8QX5wWwZN/fHuoTg4HA9fGBBBEz4v7i6KORZ9mRWqkEB1mwZYsTD8jP0FUYi9jclQ==","signatures":[{"sig":"MEUCIQDSWsvPASZtfC6YIoYR9SSlz2fIZZ/jtXr8Ii/59QfDrwIgWujuXYbjDThJph71mupy1yhV6pNvS+M6n4WyWAxbwxw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":577588},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","gitHead":"6e4e824ae7e797e8adf67e240f6c350798f72e65","scripts":{"dev":"vite","docs":"typedoc","lint":"eslint src/**/*.ts","test":"jest","build":"tsup","format":"prettier --write src/**/*.ts","prepare":"husky","lint:fix":"eslint src/**/*.ts --fix","test:watch":"jest --watch","type-check":"tsc --noEmit","format:check":"prettier --check src/**/*.ts","test:coverage":"jest --coverage","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"devferanmi","email":"devferanmi@gmail.com"},"repository":{"url":"git+https://github.com/yourusername/monie-utils.git","type":"git"},"_npmVersion":"10.9.2","description":"A comprehensive TypeScript library for money-related utilities including currency formatting, conversion, validation, and financial calculations","directories":{"doc":"docs"},"_nodeVersion":"23.6.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.5.0","vite":"^7.0.6","husky":"^9.1.7","eslint":"^9.31.0","ts-jest":"^29.4.0","typedoc":"^0.28.7","prettier":"^3.6.2","@eslint/js":"^9.31.0","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^24.1.0","@commitlint/cli":"^19.8.1","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.3","@typescript-eslint/parser":"^8.38.0","@commitlint/config-conventional":"^19.8.1","@typescript-eslint/eslint-plugin":"^8.38.0"},"_npmOperationalInternal":{"tmp":"tmp/monie-utils_1.1.0_1753457321035_0.4807838475939268","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"monie-utils","version":"1.1.1","description":"A comprehensive TypeScript library for money-related utilities including currency formatting, conversion, validation, and financial calculations","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","directories":{"doc":"docs"},"scripts":{"dev":"vite","build":"tsup","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","format":"prettier --write src/**/*.ts","format:check":"prettier --check src/**/*.ts","type-check":"tsc --noEmit","docs":"typedoc","prepare":"husky","prepublishOnly":"npm run build && npm run test"},"keywords":["money","currency","finance","utilities","formatting","conversion","typescript","javascript","payments","calculations"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/spiderocious/monie-utils.git"},"bugs":{"url":"https://github.com/spiderocious/monie-utils/issues"},"homepage":"https://github.com/spiderocious/monie-utils#readme","devDependencies":{"@commitlint/cli":"^19.8.1","@commitlint/config-conventional":"^19.8.1","@eslint/js":"^9.31.0","@types/jest":"^30.0.0","@types/node":"^24.1.0","@typescript-eslint/eslint-plugin":"^8.38.0","@typescript-eslint/parser":"^8.38.0","eslint":"^9.31.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.3","husky":"^9.1.7","jest":"^29.7.0","prettier":"^3.6.2","ts-jest":"^29.4.0","tsup":"^8.5.0","typedoc":"^0.28.7","typescript":"^5.8.3","vite":"^7.0.6"},"_id":"monie-utils@1.1.1","gitHead":"86a6bca39c6c9689c2b208147464513959ea70e3","_nodeVersion":"23.6.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-+fLHM3rLIi9JSVAeAE6KoiSez8FQjzreqlMGty5HTTbyvzyCKTOuyqzFwTWqQZxtey8sotJFkabE7X0VrQMiOw==","shasum":"47ae6a992815a09eb2d262ab746fc51aaf9edad5","tarball":"https://registry.npmjs.org/monie-utils/-/monie-utils-1.1.1.tgz","fileCount":9,"unpackedSize":577588,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBWvfsSUmKNBL8vI5xW38XjifTj7GEKg+yQupho3oed8AiANAGPZOvQ282BqChgsxwi4/SY0iS6ztVafIeu1+3OtmQ=="}]},"_npmUser":{"name":"devferanmi","email":"devferanmi@gmail.com"},"maintainers":[{"name":"devferanmi","email":"devferanmi@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/monie-utils_1.1.1_1753457459599_0.8537766640570106"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-25T15:20:19.769Z","modified":"2025-07-25T15:30:59.975Z","1.0.0":"2025-07-25T15:20:19.975Z","1.1.0":"2025-07-25T15:28:41.238Z","1.1.1":"2025-07-25T15:30:59.812Z"},"bugs":{"url":"https://github.com/spiderocious/monie-utils/issues"},"license":"MIT","homepage":"https://github.com/spiderocious/monie-utils#readme","keywords":["money","currency","finance","utilities","formatting","conversion","typescript","javascript","payments","calculations"],"repository":{"type":"git","url":"git+https://github.com/spiderocious/monie-utils.git"},"description":"A comprehensive TypeScript library for money-related utilities including currency formatting, conversion, validation, and financial calculations","maintainers":[{"name":"devferanmi","email":"devferanmi@gmail.com"}],"readme":"# 💰 Monie Utils\n\nA comprehensive TypeScript library for money-related utilities including currency formatting, conversion, validation, and financial calculations.\n\n[![npm version](https://badge.fury.io/js/monie-utils.svg)](https://badge.fury.io/js/monie-utils)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n\n## ✨ Features\n\n- 🎯 **Type-safe** - Built with TypeScript for excellent developer experience\n- 🌍 **International** - Support for multiple currencies and locales\n- 💱 **Currency operations** - Formatting, conversion, and validation\n- 🧮 **Financial calculations** - Interest, loans, investments, and more\n- 📊 **Business utilities** - Payment processing, subscriptions, analytics\n- 🚀 **Lightweight** - Tree-shakeable with zero dependencies\n- ✅ **Well-tested** - Comprehensive test coverage\n- 📚 **Well-documented** - Extensive documentation and examples\n\n## 🚀 Installation\n\n```bash\nnpm install monie-utils\n```\n\n```bash\nyarn add monie-utils\n```\n\n```bash\npnpm add monie-utils\n```\n\n## 📖 Quick Start\n\n```typescript\nimport { \n  isValidAmount, \n  isValidCurrency, \n} from 'monie-utils';\n\n// Validate amounts\nconsole.log(isValidAmount(100.50)); // true\nconsole.log(isValidAmount(NaN)); // false\n\n// Validate currencies\nconsole.log(isValidCurrency('USD')); // true\nconsole.log(isValidCurrency('BTC')); // true\nconsole.log(isValidCurrency('INVALID')); // false\n\n```\n\n\n## 📚 API Reference\n\n### Currency Formatting\n\n#### `formatCurrency(amount: number, currency: string, options?: FormatCurrencyOptions): FormattedCurrency`\nFormats a currency amount with locale-specific formatting.\n\n```typescript\nformatCurrency(1234.56, 'USD')\n// Returns: { formatted: '$1,234.56', amount: 1234.56, currency: 'USD', locale: 'en-US', isCompact: false }\n\nformatCurrency(1234.56, 'EUR', { locale: 'de-DE', showCode: true })\n// Returns: { formatted: '1.234,56 EUR', amount: 1234.56, currency: 'EUR', locale: 'de-DE', isCompact: false }\n```\n\n#### `formatMoney(amount: number, currency: string, locale?: string): string`\nSimple string formatting for currency amounts.\n\n```typescript\nformatMoney(1234.56, 'USD')\n// Returns: '$1,234.56'\n\nformatMoney(1234.56, 'EUR', 'de-DE')\n// Returns: '1.234,56 €'\n```\n\n#### `formatCents(cents: number, currency: string, options?: FormatCurrencyOptions): FormattedCurrency`\nFormats amounts from smallest currency unit (cents/satoshis).\n\n```typescript\nformatCents(12345, 'USD')\n// Returns: { formatted: '$123.45', amount: 123.45, currency: 'USD', locale: 'en-US', isCompact: false }\n\nformatCents(10000000, 'BTC')\n// Returns: { formatted: '₿0.10000000', amount: 0.1, currency: 'BTC', locale: 'en-US', isCompact: false }\n```\n\n#### `formatCompactCurrency(amount: number, currency: string, options?: FormatCurrencyOptions): FormattedCurrency`\nFormats large amounts in compact notation (1M, 1B, etc.).\n\n```typescript\nformatCompactCurrency(1500000, 'USD')\n// Returns: { formatted: '$1.5M', amount: 1500000, currency: 'USD', locale: 'en-US', isCompact: true }\n\nformatCompactCurrency(2500000000, 'USD')\n// Returns: { formatted: '$2.5B', amount: 2500000000, currency: 'USD', locale: 'en-US', isCompact: true }\n```\n\n### Percentage Formatting\n\n#### `formatPercentage(decimal: number, options?: PercentageOptions): string`\nFormats decimal values as percentages.\n\n```typescript\nformatPercentage(0.1525)\n// Returns: '15.25%'\n\nformatPercentage(0.1525, { precision: 1, locale: 'de-DE' })\n// Returns: '15,3 %'\n```\n\n### Localization\n\n#### `formatCurrencyByLocale(amount: number, currency: string, locale: string): string`\nFormats currency with specific locale rules.\n\n```typescript\nformatCurrencyByLocale(1234.56, 'USD', 'en-US')\n// Returns: '$1,234.56'\n\nformatCurrencyByLocale(1234.56, 'EUR', 'de-DE')\n// Returns: '1.234,56 €'\n```\n\n#### `getLocaleCurrencyInfo(locale: string): LocaleCurrencyInfo`\nGets currency information for a locale.\n\n```typescript\ngetLocaleCurrencyInfo('en-US')\n// Returns: { currency: 'USD', symbol: '$', name: 'US Dollar' }\n\ngetLocaleCurrencyInfo('de-DE')\n// Returns: { currency: 'EUR', symbol: '€', name: 'Euro' }\n```\n\n#### `formatWithGrouping(amount: number, locale?: string): string`\nAdds thousand separators based on locale.\n\n```typescript\nformatWithGrouping(1234567.89)\n// Returns: '1,234,567.89'\n\nformatWithGrouping(1234567.89, 'de-DE')\n// Returns: '1.234.567,89'\n```\n\n#### `formatDecimalPlaces(amount: number, decimalPlaces: number): string`\nFormats number with specific decimal places.\n\n```typescript\nformatDecimalPlaces(123.456789, 2)\n// Returns: '123.46'\n\nformatDecimalPlaces(123.1, 4)\n// Returns: '123.1000'\n```\n\n### Validation and Parsing\n\n#### `isValidAmount(amount: unknown): amount is number`\nChecks if a value is a valid money amount.\n\n```typescript\nisValidAmount(100.50)\n// Returns: true\n\nisValidAmount(NaN)\n// Returns: false\n```\n\n#### `isValidCurrency(currencyCode): currencyCode is string`\nValidates currency codes against ISO 4217 and cryptocurrencies.\n\n```typescript\nisValidCurrency('USD')\n// Returns: true\n\nisValidCurrency('BTC')\n// Returns: true\n\nisValidCurrency('INVALID')\n// Returns: false\n```\n\n#### `isPositiveAmount(amount: number): boolean`\nChecks if an amount is positive.\n\n```typescript\nisPositiveAmount(100)\n// Returns: true\n\nisPositiveAmount(-50)\n// Returns: false\n```\n\n#### `isWithinRange(amount: number, min: number, max: number): boolean`\nChecks if an amount is within a specified range.\n\n```typescript\nisWithinRange(50, 10, 100)\n// Returns: true\n\nisWithinRange(150, 10, 100)\n// Returns: false\n```\n\n#### `parseAmount(amountString: string): ParsedAmount`\nParses string to number amount.\n\n```typescript\nparseAmount('123.45')\n// Returns: { amount: 123.45, isValid: true }\n\nparseAmount('invalid')\n// Returns: { amount: 0, isValid: false }\n```\n\n#### `parseCurrencyString(currencyString: string): ParsedCurrency`\nExtracts amount and currency from formatted string.\n\n```typescript\nparseCurrencyString('$123.45')\n// Returns: { amount: 123.45, currency: 'USD', isValid: true }\n\nparseCurrencyString('€1.234,56')\n// Returns: { amount: 1234.56, currency: 'EUR', isValid: true }\n```\n\n#### `normalizeAmount(amount: number, decimalPlaces?: number): number`\nNormalizes amount to standard format.\n\n```typescript\nnormalizeAmount(123.456789)\n// Returns: 123.46\n\nnormalizeAmount(123.456789, 4)\n// Returns: 123.4568\n```\n\n#### `parseFormattedCurrency(formattedString: string, locale?: string): ParsedCurrency`\nParses formatted currency string with locale awareness.\n\n```typescript\nparseFormattedCurrency('$1,234.56', 'en-US')\n// Returns: { amount: 1234.56, currency: 'USD', isValid: true }\n\nparseFormattedCurrency('1.234,56 €', 'de-DE')\n// Returns: { amount: 1234.56, currency: 'EUR', isValid: true }\n```\n\n### Currency Conversion\n\n#### `convertCurrency(amount: number, fromCurrency: string, toCurrency: string, rate?: number): ConversionResult`\nConverts between currencies with exchange rates.\n\n```typescript\nconvertCurrency(100, 'USD', 'EUR', 0.85)\n// Returns: { amount: 85, fromCurrency: 'USD', toCurrency: 'EUR', rate: 0.85 }\n\nconvertCurrency(100, 'USD', 'USD')\n// Returns: { amount: 100, fromCurrency: 'USD', toCurrency: 'USD', rate: 1 }\n```\n\n#### `convertWithFee(amount: number, rate: number, feePercentage: number): ConversionWithFee`\nConverts currency with transaction fee.\n\n```typescript\nconvertWithFee(100, 0.85, 2.5)\n// Returns: { convertedAmount: 85, fee: 2.125, totalCost: 87.125, effectiveRate: 0.8713 }\n```\n\n#### `bulkConvert(amounts: number[], fromCurrency: string, toCurrency: string, rate: number): BulkConversionResult`\nConverts multiple amounts at once.\n\n```typescript\nbulkConvert([100, 200, 300], 'USD', 'EUR', 0.85)\n// Returns: { convertedAmounts: [85, 170, 255], totalOriginal: 600, totalConverted: 510, rate: 0.85 }\n```\n\n### Arithmetic Operations\n\n#### `roundMoney(amount: number, precision?: number): number`\nRounds money to specified precision.\n\n```typescript\nroundMoney(123.456)\n// Returns: 123.46\n\nroundMoney(123.456, 1)\n// Returns: 123.5\n```\n\n#### `addMoney(amount1: number, amount2: number, currency?: string): number`\nAdds two money amounts.\n\n```typescript\naddMoney(100.25, 50.75)\n// Returns: 151\n\naddMoney(100.25, 50.75, 'USD')\n// Returns: 151\n```\n\n#### `subtractMoney(amount1: number, amount2: number, currency?: string): number`\nSubtracts money amounts.\n\n```typescript\nsubtractMoney(100.75, 25.25)\n// Returns: 75.5\n\nsubtractMoney(100.75, 25.25, 'USD')\n// Returns: 75.5\n```\n\n#### `multiplyMoney(amount: number, multiplier: number): number`\nMultiplies money by a number.\n\n```typescript\nmultiplyMoney(50.25, 3)\n// Returns: 150.75\n\nmultiplyMoney(100, 1.5)\n// Returns: 150\n```\n\n#### `divideMoney(amount: number, divisor: number): number`\nDivides money by a number.\n\n```typescript\ndivideMoney(150, 3)\n// Returns: 50\n\ndivideMoney(100, 4)\n// Returns: 25\n```\n\n#### `calculateTip(amount: number, percentage: number): number`\nCalculates tip amount.\n\n```typescript\ncalculateTip(100, 15)\n// Returns: 15\n\ncalculateTip(85.50, 20)\n// Returns: 17.1\n```\n\n#### `calculateTax(amount: number, taxRate: number): number`\nCalculates tax amount.\n\n```typescript\ncalculateTax(100, 8.5)\n// Returns: 8.5\n\ncalculateTax(250, 10)\n// Returns: 25\n```\n\n#### `calculateDiscount(amount: number, discountRate: number): number`\nCalculates discount amount.\n\n```typescript\ncalculateDiscount(100, 10)\n// Returns: 10\n\ncalculateDiscount(250, 15)\n// Returns: 37.5\n```\n\n#### `calculateSimpleInterest(principal: number, rate: number, time: number): number`\nCalculates simple interest.\n\n```typescript\ncalculateSimpleInterest(1000, 5, 2)\n// Returns: 100\n\ncalculateSimpleInterest(5000, 3.5, 1.5)\n// Returns: 262.5\n```\n\n#### `calculateCompoundInterest(principal: number, rate: number, time: number, frequency?: number): CompoundInterestResult`\nCalculates compound interest.\n\n```typescript\ncalculateCompoundInterest(1000, 5, 2)\n// Returns: { finalAmount: 1102.5, interestEarned: 102.5, effectiveRate: 5.125 }\n\ncalculateCompoundInterest(1000, 5, 2, 12)\n// Returns: { finalAmount: 1104.89, interestEarned: 104.89, effectiveRate: 5.244 }\n```\n\n#### `splitAmount(totalAmount: number, numberOfParts: number): number[]`\nSplits amount into equal parts.\n\n```typescript\nsplitAmount(100, 3)\n// Returns: [33.33, 33.33, 33.34]\n\nsplitAmount(150, 4)\n// Returns: [37.5, 37.5, 37.5, 37.5]\n```\n\n#### `distributeProportionally(totalAmount: number, ratios: number[]): number[]`\nDistributes amount by ratios.\n\n```typescript\ndistributeProportionally(100, [1, 2, 3])\n// Returns: [16.67, 33.33, 50]\n\ndistributeProportionally(500, [40, 30, 30])\n// Returns: [200, 150, 150]\n```\n\n#### `calculatePercentageOfTotal(amount: number, total: number): number`\nCalculates percentage share.\n\n```typescript\ncalculatePercentageOfTotal(25, 100)\n// Returns: 25\n\ncalculatePercentageOfTotal(150, 500)\n// Returns: 30\n```\n\n### Loan and Credit Utilities\n\n#### `calculateMonthlyPayment(principal: number, rate: number, termMonths: number): number`\nCalculates monthly loan payment.\n\n```typescript\ncalculateMonthlyPayment(200000, 4.5, 360)\n// Returns: 1013.37\n\ncalculateMonthlyPayment(50000, 6, 60)\n// Returns: 966.64\n```\n\n#### `calculateLoanBalance(principal: number, rate: number, termMonths: number, paymentsMade: number): number`\nCalculates remaining loan balance.\n\n```typescript\ncalculateLoanBalance(200000, 4.5, 360, 12)\n// Returns: 197834.23\n\ncalculateLoanBalance(50000, 6, 60, 24)\n// Returns: 28844.35\n```\n\n#### `calculateTotalInterest(principal: number, rate: number, termMonths: number): number`\nCalculates total interest over loan term.\n\n```typescript\ncalculateTotalInterest(200000, 4.5, 360)\n// Returns: 164813.42\n\ncalculateTotalInterest(50000, 6, 60)\n// Returns: 7998.12\n```\n\n#### `generateAmortizationSchedule(principal: number, rate: number, termMonths: number): AmortizationEntry[]`\nGenerates complete amortization schedule.\n\n```typescript\ngenerateAmortizationSchedule(100000, 5, 12)\n// Returns: [\n//   { month: 1, payment: 8560.75, principal: 8144.08, interest: 416.67, balance: 91855.92 },\n//   { month: 2, payment: 8560.75, principal: 8178.02, interest: 382.73, balance: 83677.90 },\n//   ...\n// ]\n```\n\n#### `calculateCreditUtilization(usedCredit: number, totalCredit: number): number`\nCalculates credit utilization ratio.\n\n```typescript\ncalculateCreditUtilization(2500, 10000)\n// Returns: 25\n\ncalculateCreditUtilization(1200, 5000)\n// Returns: 24\n```\n\n#### `calculateMinimumPayment(balance: number, rate: number, minimumRate: number): number`\nCalculates minimum credit payment.\n\n```typescript\ncalculateMinimumPayment(5000, 18, 2)\n// Returns: 100\n\ncalculateMinimumPayment(2500, 24, 3)\n// Returns: 75\n```\n\n#### `calculatePayoffTime(balance: number, payment: number, rate: number): PayoffResult`\nCalculates time to pay off debt.\n\n```typescript\ncalculatePayoffTime(5000, 200, 18)\n// Returns: { months: 30, totalInterest: 983.45, totalPaid: 5983.45 }\n\ncalculatePayoffTime(10000, 300, 24)\n// Returns: { months: 43, totalInterest: 2804.32, totalPaid: 12804.32 }\n```\n\n### Investment and Returns\n\n#### `calculateROI(initialInvestment: number, finalValue: number): number`\nCalculates return on investment.\n\n```typescript\ncalculateROI(10000, 12000)\n// Returns: 20\n\ncalculateROI(5000, 4500)\n// Returns: -10\n```\n\n#### `calculateAnnualizedReturn(initialValue: number, finalValue: number, years: number): number`\nCalculates annualized return.\n\n```typescript\ncalculateAnnualizedReturn(10000, 15000, 3)\n// Returns: 14.47\n\ncalculateAnnualizedReturn(5000, 7500, 2)\n// Returns: 22.47\n```\n\n#### `calculateDividendYield(dividendPerShare: number, pricePerShare: number): number`\nCalculates dividend yield.\n\n```typescript\ncalculateDividendYield(2.50, 50)\n// Returns: 5\n\ncalculateDividendYield(1.25, 75)\n// Returns: 1.67\n```\n\n#### `calculateFutureValue(presentValue: number, rate: number, periods: number): number`\nCalculates future value.\n\n```typescript\ncalculateFutureValue(10000, 7, 10)\n// Returns: 19671.51\n\ncalculateFutureValue(5000, 5, 20)\n// Returns: 13266.49\n```\n\n### Subscription and Recurring Payments\n\n#### `calculateSubscriptionValue(monthlyAmount: number, months: number): number`\nCalculates total subscription cost.\n\n```typescript\ncalculateSubscriptionValue(29.99, 12)\n// Returns: 359.88\n\ncalculateSubscriptionValue(99, 6)\n// Returns: 594\n```\n\n#### `compareSubscriptionPlans(plans: SubscriptionPlan[]): PlanComparison[]`\nCompares subscription plans.\n\n```typescript\ncompareSubscriptionPlans([\n  { name: 'Basic', monthlyPrice: 10, features: [] },\n  { name: 'Pro', monthlyPrice: 25, features: [] }\n])\n// Returns: [\n//   { plan: 'Basic', monthlyPrice: 10, annualPrice: 120, savings: 0 },\n//   { plan: 'Pro', monthlyPrice: 25, annualPrice: 300, savings: 0 }\n// ]\n```\n\n#### `calculateProrationAmount(amount: number, daysUsed: number, totalDays: number): number`\nCalculates prorated amount.\n\n```typescript\ncalculateProrationAmount(100, 15, 30)\n// Returns: 50\n\ncalculateProrationAmount(299, 10, 31)\n// Returns: 96.45\n```\n\n#### `calculateUpgradeCredit(oldPlan: SubscriptionPlan, newPlan: SubscriptionPlan, daysRemaining: number): UpgradeCredit`\nCalculates upgrade credit.\n\n```typescript\ncalculateUpgradeCredit(\n  { name: 'Basic', monthlyPrice: 10 },\n  { name: 'Pro', monthlyPrice: 25 },\n  15\n)\n// Returns: { credit: 5, additionalCost: 12.5, totalCost: 7.5 }\n```\n\n#### `calculateAnnualEquivalent(amount: number, frequency: 'monthly' | 'weekly' | 'quarterly'): number`\nConverts to annual amount.\n\n```typescript\ncalculateAnnualEquivalent(100, 'monthly')\n// Returns: 1200\n\ncalculateAnnualEquivalent(25, 'weekly')\n// Returns: 1300\n```\n\n#### `calculateNextPaymentDate(startDate: Date, frequency: 'monthly' | 'weekly' | 'quarterly'): Date`\nCalculates next payment date.\n\n```typescript\ncalculateNextPaymentDate(new Date('2024-01-15'), 'monthly')\n// Returns: Date object for 2024-02-15\n\ncalculateNextPaymentDate(new Date('2024-01-15'), 'weekly')\n// Returns: Date object for 2024-01-22\n```\n\n#### `calculateTotalRecurringCost(amount: number, frequency: 'monthly' | 'weekly' | 'quarterly', duration: number): number`\nCalculates total recurring cost.\n\n```typescript\ncalculateTotalRecurringCost(50, 'monthly', 12)\n// Returns: 600\n\ncalculateTotalRecurringCost(25, 'weekly', 52)\n// Returns: 1300\n```\n\n### Utility Functions\n\n#### `roundToNearestCent(amount: number): number`\nRounds to nearest cent.\n\n```typescript\nroundToNearestCent(123.456)\n// Returns: 123.46\n\nroundToNearestCent(99.994)\n// Returns: 99.99\n```\n\n#### `roundToBankersRounding(amount: number, decimalPlaces?: number): number`\nApplies banker's rounding (round half to even).\n\n```typescript\nroundToBankersRounding(2.125, 2)\n// Returns: 2.12\n\nroundToBankersRounding(2.135, 2)\n// Returns: 2.14\n```\n\n#### `truncateToDecimalPlaces(amount: number, places: number): number`\nTruncates without rounding.\n\n```typescript\ntruncateToDecimalPlaces(123.789, 2)\n// Returns: 123.78\n\ntruncateToDecimalPlaces(99.999, 1)\n// Returns: 99.9\n```\n\n#### `ceilToNearestCent(amount: number): number`\nCeils to nearest cent.\n\n```typescript\nceilToNearestCent(123.451)\n// Returns: 123.46\n\nceilToNearestCent(99.001)\n// Returns: 99.01\n```\n\n#### `formatThousands(number: number, options?: ThousandsOptions): string`\nAdds thousand separators.\n\n```typescript\nformatThousands(1234567.89)\n// Returns: '1,234,567.89'\n\nformatThousands(1234567.89, { thousandsSeparator: '.', decimalSeparator: ',' })\n// Returns: '1.234.567,89'\n```\n\n#### `formatToHundreds(amount: number, options?: ThousandsOptions): string`\nFormats cents to dollars with separators.\n\n```typescript\nformatToHundreds(123456)\n// Returns: '1,234.56'\n\nformatToHundreds(987654, { thousandsSeparator: ' ', decimalSeparator: ',' })\n// Returns: '9 876,54'\n```\n\n#### `removeFormattingFromNumber(formattedString: string): string`\nRemoves formatting characters.\n\n```typescript\nremoveFormattingFromNumber('$1,234.56')\n// Returns: '1234.56'\n\nremoveFormattingFromNumber('€ 1.234,56')\n// Returns: '1234.56'\n```\n\n#### `convertToWords(amount: number, options?: { currency?: string }): NumberToWordsResult`\nConverts number to words.\n\n```typescript\nconvertToWords(123.45)\n// Returns: { words: 'one hundred twenty-three and forty-five cents' }\n\nconvertToWords(1500, { currency: 'USD' })\n// Returns: { words: 'one thousand five hundred dollars', currency: 'USD' }\n```\n\n#### `formatAccountNumber(accountNumber: string, options?: AccountNumberOptions): FormattedAccountResult`\nFormats account numbers with masking.\n\n```typescript\nformatAccountNumber('1234567890')\n// Returns: { formatted: '******7890', masked: true, groupSize: 4 }\n\nformatAccountNumber('1234567890', { maskCharacter: 'X', showLast: 6 })\n// Returns: { formatted: 'XXXX567890', masked: true, groupSize: 4 }\n```\n\n## 🧪 Development\n\n### Prerequisites\n\n- Node.js 18+\n- npm, yarn, or pnpm\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/spiderocious/monie-utils.git\ncd monie-utils\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Build the library\nnpm run build\n\n# Lint and format\nnpm run lint\nnpm run format\n```\n\n### Scripts\n\n- `npm run dev` - Start development server with Vite\n- `npm run build` - Build the library with tsup\n- `npm test` - Run tests with Jest\n- `npm run test:watch` - Run tests in watch mode\n- `npm run test:coverage` - Run tests with coverage report\n- `npm run lint` - Lint code with ESLint\n- `npm run lint:fix` - Fix linting issues\n- `npm run format` - Format code with Prettier\n- `npm run type-check` - Run TypeScript type checking\n\n\n## 🙏 Acknowledgments\n\n- Inspired by financial libraries from Stripe, PayStack, Monnify, and other payment processors\n- Built with modern TypeScript and development tools\n- Thanks to all contributors and the open-source community\n\n---\n\nMade with ❤️ by Oluwaferanmi (https://github.com/spiderocious)\n","readmeFilename":"README.md"}