{"_id":"@afzalimdad9/cashify","_rev":"1-e91d90dc1096e72bbbb2f9c58c259be0","name":"@afzalimdad9/cashify","dist-tags":{"latest":"3.0.2"},"versions":{"3.0.1":{"name":"@afzalimdad9/cashify","version":"3.0.1","keywords":["cashify","cash","moneyjs","money.js","money","conversion","exchange","currency-exchange","exchange-rates","open-exchange-rates","fixer","currencies","convert-currency-rates","replacement","convert-currencies","typescript","money-conversion"],"author":{"url":"https://afzalimdad9.vercel.app","name":"Afzal Imdad","email":"afzalimdad9@gmail.com"},"license":"MIT","_id":"@afzalimdad9/cashify@3.0.1","maintainers":[{"name":"afzalimdad9","email":"afzalimdad9@gmail.com"}],"homepage":"https://github.com/afzalimdad9/cashify","bugs":{"url":"https://github.com/afzalimdad9/cashify/issues"},"xo":{"rules":{"@typescript-eslint/naming-convention":"off"}},"ava":{"extensions":{"ts":"module"},"nodeArguments":["--loader=ts-node/esm"],"nonSemVerExperiments":{"configurableModuleFormat":true}},"dist":{"shasum":"b6913849f201f3a82049198bfe7da2b2fcfaec5c","tarball":"https://registry.npmjs.org/@afzalimdad9/cashify/-/cashify-3.0.1.tgz","fileCount":17,"integrity":"sha512-e6Rrh5o5eXWZIyWipOIdwyRqu/jWDTmk0apZzFnVsiPiRjBMHKLllRMxYxMH9nnOhJS7ObFjB2uiCsDiAUsKww==","signatures":[{"sig":"MEYCIQDkiRYMEq0WT6YxeBJkrUt+C1m4HWm835D0QPubyg/GNgIhAOn6IuFitbp91YecGksOiPNRdNavPQeuNHP/kTNwVWE5","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":21209},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=14"},"gitHead":"dc20d01b9118d16d77a95c22d96e9ae789f756f2","scripts":{"test":"xo && c8 --reporter=lcov ava","build":"tsc","prebuild":"del-cli dist","prepublishOnly":"npm run build"},"_npmUser":{"name":"afzalimdad9","email":"afzalimdad9@gmail.com"},"repository":{"url":"git+https://github.com/afzalimdad9/cashify.git","type":"git"},"_npmVersion":"10.8.2","description":"Lightweight currency conversion library, successor of money.js","directories":{},"sideEffects":false,"_nodeVersion":"18.20.5","dependencies":{"@types/big.js":"^6.1.2"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^7.10.0","xo":"^0.46.4","ava":"^3.15.0","big.js":"^6.1.1","del-cli":"^4.0.1","ts-node":"^10.4.0","coveralls":"^3.1.1","typescript":"^4.4.4","@types/node":"^16.11.6","@sindresorhus/tsconfig":"^2.0.0"},"peerDependencies":{"big.js":">=6.1.1"},"peerDependenciesMeta":{"big.js":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/cashify_3.0.1_1736885093506_0.7370484643369561","host":"s3://npm-registry-packages-npm-production"}},"3.0.2":{"name":"@afzalimdad9/cashify","version":"3.0.2","description":"Lightweight currency conversion library, successor of money.js","main":"dist/index.js","type":"module","types":"dist/index.d.ts","author":{"name":"Afzal Imdad","email":"afzalimdad9@gmail.com","url":"https://afzalimdad9.vercel.app"},"bugs":{"url":"https://github.com/afzalimdad9/cashify/issues"},"scripts":{"prebuild":"del-cli dist","build":"tsc","test":"xo && c8 --reporter=lcov ava","prepublishOnly":"npm run build"},"engines":{"node":">=14"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/afzalimdad9/cashify.git"},"homepage":"https://github.com/afzalimdad9/cashify","keywords":["cashify","cash","moneyjs","money.js","money","conversion","exchange","currency-exchange","exchange-rates","open-exchange-rates","fixer","currencies","convert-currency-rates","replacement","convert-currencies","typescript","money-conversion"],"devDependencies":{"@sindresorhus/tsconfig":"^2.0.0","@types/node":"^16.11.6","ava":"^3.15.0","big.js":"^6.1.1","c8":"^7.10.0","coveralls":"^3.1.1","del-cli":"^4.0.1","ts-node":"^10.4.0","typescript":"^4.4.4","xo":"^0.46.4"},"sideEffects":false,"ava":{"extensions":{"ts":"module"},"nonSemVerExperiments":{"configurableModuleFormat":true},"nodeArguments":["--loader=ts-node/esm"]},"xo":{"rules":{"@typescript-eslint/naming-convention":"off","unicorn/expiring-todo-comments":"off"}},"dependencies":{"@types/big.js":"^6.1.2"},"peerDependencies":{"big.js":">=6.1.1"},"peerDependenciesMeta":{"big.js":{"optional":true}},"_id":"@afzalimdad9/cashify@3.0.2","gitHead":"dc20d01b9118d16d77a95c22d96e9ae789f756f2","_nodeVersion":"18.20.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qR1ASOYTHScrVNNzqCDU1hFtSw9PZpSKozRtZyODLM7USBz5y2FIeJK0to3GEvzq856MmxhpNn6oErqDgOmdMA==","shasum":"167b2b885a6653f1c80dcc7559bb6f6907adac79","tarball":"https://registry.npmjs.org/@afzalimdad9/cashify/-/cashify-3.0.2.tgz","fileCount":17,"unpackedSize":21263,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDTWDLcvssq1FL70ULuqP5QhCmO6gN3MOOjOc+TVFm/CAiEAvMkTpL7OfPpzXs7N5Ju0fkAVuQNN5P2EfGUFgcdjNUA="}]},"_npmUser":{"name":"afzalimdad9","email":"afzalimdad9@gmail.com"},"directories":{},"maintainers":[{"name":"afzalimdad9","email":"afzalimdad9@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cashify_3.0.2_1736887361920_0.8367816901189573"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-14T20:04:53.390Z","modified":"2025-01-14T20:42:42.363Z","3.0.1":"2025-01-14T20:04:53.804Z","3.0.2":"2025-01-14T20:42:42.154Z"},"bugs":{"url":"https://github.com/afzalimdad9/cashify/issues"},"author":{"name":"Afzal Imdad","email":"afzalimdad9@gmail.com","url":"https://afzalimdad9.vercel.app"},"license":"MIT","homepage":"https://github.com/afzalimdad9/cashify","keywords":["cashify","cash","moneyjs","money.js","money","conversion","exchange","currency-exchange","exchange-rates","open-exchange-rates","fixer","currencies","convert-currency-rates","replacement","convert-currencies","typescript","money-conversion"],"repository":{"type":"git","url":"git+https://github.com/afzalimdad9/cashify.git"},"description":"Lightweight currency conversion library, successor of money.js","maintainers":[{"name":"afzalimdad9","email":"afzalimdad9@gmail.com"}],"readme":"# Cashify 💸\r\n\r\n> Lightweight currency conversion library, successor of money.js\r\n\r\n[![Build Status](https://github.com/afzalimdad9/cashify/workflows/CI/badge.svg)](https://github.com/afzalimdad9/cashify/actions?query=workflow%3ACI)\r\n[![Coverage Status](https://coveralls.io/repos/github/afzalimdad9/cashify/badge.svg?branch=master)](https://coveralls.io/github/afzalimdad9/cashify?branch=master)\r\n[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo)\r\n[![install size](https://packagephobia.now.sh/badge?p=@afzalimdad9/cashify)](https://packagephobia.now.sh/result?p=@afzalimdad9/cashify)\r\n![minified size](https://img.shields.io/bundlephobia/minzip/@afzalimdad9/cashify)\r\n[![Mentioned in Awesome Node.js](https://awesome.re/mentioned-badge.svg)](https://github.com/sindresorhus/awesome-nodejs)\r\n\r\n- [Motivation](#motivation)\r\n- [Highlights](#highlights)\r\n- [Install](#install)\r\n- [Usage](#usage)\r\n  - [With constructor](#with-constructor)\r\n  - [Without constructor](#without-constructor)\r\n  - [Parsing](#parsing)\r\n  - [Integration with big.js](#integration-bigjs)\r\n  - [Integration with currency.js](#integration-currencyjs)\r\n- [API](#api)\r\n  - [Cashify({base, rates})](#cashifybase-rates)\r\n    - [base](#base)\r\n    - [rates](#rates)\r\n    - [BigJs](#bigjs)\r\n  - [convert(amount, {from, to, base, rates})](#convertamount-from-to-base-rates-with-and-without-constructor)\r\n  - [amount](#amount)\r\n  - [from](#from)\r\n  - [to](#to)\r\n  - [base](#base-1)\r\n  - [rates](#rates-1)\r\n  - [BigJs](#bigjs-1)\r\n  - [parse(expression)](#parseexpression)\r\n    - [expression](#expression)\r\n- [Migrating from money.js](#migrating-from-moneyjs)\r\n- [Floating point issues](#floating-point-issues)\r\n- [Related projects](#related-projects)\r\n- [License](#license)\r\n\r\n---\r\n\r\n## Motivation\r\n\r\nThis package was created, because the popular [money.js](http://openexchangerates.github.io/money.js/) library:\r\n\r\n- is not maintained (last commit was ~5 years ago)\r\n- has over 20 open issues\r\n- does not support TypeScript\r\n- has implicit globals\r\n- does not have any unit tests\r\n- [has floating point issues](#floating-point-issues)\r\n\r\n## Highlights\r\n\r\n- Simple API\r\n- 0 dependencies\r\n- Actively maintained\r\n- Well tested and documented\r\n- [Easy migration from money.js](#migrating-from-moneyjs)\r\n- Written in TypeScript\r\n- ESM-only\r\n\r\n## Install\r\n\r\n```\r\nnpm install @afzalimdad9/cashify\r\n```\r\n\r\n**Please note that starting with version `3.0.0` this package is ESM-only and thus requires Node.js v14 or higher.**\r\n\r\n## Usage\r\n\r\n### With constructor\r\n\r\n```js\r\nimport {Cashify} from '@afzalimdad9/cashify';\r\n\r\nconst rates = {\r\n GBP: 0.92,\r\n EUR: 1.00,\r\n USD: 1.12\r\n};\r\n\r\nconst cashify = new Cashify({base: 'EUR', rates});\r\n\r\nconst result = cashify.convert(10, {from: 'EUR', to: 'GBP'});\r\n\r\nconsole.log(result); //=> 9.2\r\n```\r\n\r\n### Without constructor\r\n\r\nUsing the `Cashify` constructor is not required. Instead, you can just use the `convert` function:\r\n\r\n```js\r\nimport {convert} from '@afzalimdad9/cashify';\r\n\r\nconst rates = {\r\n GBP: 0.92,\r\n EUR: 1.00,\r\n USD: 1.12\r\n};\r\n\r\nconst result = convert(10, {from: 'EUR', to: 'GBP', base: 'EUR', rates});\r\n\r\nconsole.log(result); //=> 9.2\r\n```\r\n\r\n### Parsing\r\n\r\nCashify supports parsing, so you can pass a `string` to the `amount` argument and the `from` and/or `to` currency will be automatically detected:\r\n\r\n```js\r\nimport {Cashify} from '@afzalimdad9/cashify';\r\n\r\nconst rates = {\r\n GBP: 0.92,\r\n EUR: 1.00,\r\n USD: 1.12\r\n};\r\n\r\nconst cashify = new Cashify({base: 'EUR', rates});\r\n\r\n// Basic parsing\r\ncashify.convert('€10 EUR', {to: 'GBP'});\r\n\r\n// Full parsing\r\ncashify.convert('10 EUR to GBP');\r\n```\r\n\r\nAlternatively, if you just want to parse a `string` without conversion you can use the [`parse`](#parseexpression) function which returns an `object` with parsing results:\r\n\r\n```js\r\nimport {parse} from 'cashify';\r\n\r\nparse('10 EUR to GBP'); //=> {amount: 10, from: 'EUR', to: 'GBP'}\r\n```\r\n\r\n**Note:** If you want to use full parsing, you need to pass a `string` in a specific format:\r\n\r\n```\r\n10 usd to pln\r\n12.5 GBP in EUR\r\n3.1415 eur as chf\r\n```\r\n\r\nYou can use `to`, `in` or `as` to separate the expression (case insensitive). Used currencies name case doesn't matter, as cashify will automatically convert them to upper case.\r\n\r\n<a id=\"integration-bigjs\"></a>\r\n\r\n### Integration with [big.js](https://github.com/MikeMcl/big.js/)\r\n\r\n[big.js](https://github.com/scurker/currency.js/) is a small JavaScript library for arbitrary-precision decimal arithmetic. You can use it with cashify to make sure you won't run into floating point issues:\r\n\r\n```js\r\nimport {Cashify} from 'cashify';\r\nimport Big from 'big.js';\r\n\r\nconst rates = {\r\n EUR: 0.8235,\r\n USD: 1\r\n};\r\n\r\nconst cashify = new Cashify({base: 'USD', rates});\r\n\r\nconst result = cashify.convert(1, {\r\n from: 'USD',\r\n to: 'EUR',\r\n BigJs: Big\r\n});\r\n\r\nconsole.log(result); //=> 8.235 (without big.js you would get something like 0.8234999999999999)\r\n```\r\n\r\n<a id=\"integration-currencyjs\"></a>\r\n\r\n### Integration with [currency.js](https://github.com/scurker/currency.js/)\r\n\r\n[currency.js](https://github.com/scurker/currency.js/) is a small and lightweight library for working with currency values. It integrates well with cashify. In the following example we are using it to format the conversion result:\r\n\r\n```js\r\nimport {Cashify} from 'cashify';\r\nimport currency from 'currency.js';\r\n\r\nconst rates = {\r\n GBP: 0.92,\r\n EUR: 1.00,\r\n USD: 1.12\r\n};\r\n\r\nconst cashify = new Cashify({base: 'EUR', rates});\r\n\r\nconst converted = cashify.convert(8635619, {from: 'EUR', to: 'GBP'}); // => 7944769.48\r\n\r\n// Format the conversion result\r\ncurrency(converted, {symbol: '€', formatWithSymbol: true}).format(); // => €7,944,769.48\r\n```\r\n\r\n## API\r\n\r\n### Cashify({base, rates, BigJs})\r\n\r\nConstructor.\r\n\r\n##### base\r\n\r\nType: `string`\r\n\r\nThe base currency.\r\n\r\n##### rates\r\n\r\nType: `object`\r\n\r\nAn object containing currency rates (for example from an API, such as Open Exchange Rates).\r\n\r\n##### BigJs\r\n\r\nType: [big.js](https://github.com/MikeMcl/big.js/) constructor\r\n\r\nSee [integration with big.js](#integration-bigjs).\r\n\r\n### convert(amount, {from, to, base, rates}) *`with and without constructor`*\r\n\r\nReturns conversion result (`number`).\r\n\r\n##### amount\r\n\r\nType: `number` or `string`\r\n\r\nAmount of money you want to convert. You can either use a `number` or a `string`. If you choose the second option, you can take advantage of [parsing](#parsing) and not specify `from` and/or `to` argument(s).\r\n\r\n##### from\r\n\r\nType: `string`\r\n\r\nCurrency from which you want to convert. You might not need to specify it if you are using [parsing](#parsing).\r\n\r\n##### to\r\n\r\nType: `string`\r\n\r\nCurrency to which you want to convert. You might not need to specify it if you are using [parsing](#parsing).\r\n\r\n##### base\r\n\r\nType: `string`\r\n\r\nThe base currency.\r\n\r\n##### rates\r\n\r\nType: `object`\r\n\r\nAn object containing currency rates (for example from an API, such as Open Exchange Rates).\r\n\r\n##### BigJs\r\n\r\nType: [big.js](https://github.com/MikeMcl/big.js/) constructor\r\n\r\nSee [integration with big.js](#integration-bigjs).\r\n\r\n### parse(expression)\r\n\r\nReturns an `object`, which contains parsing results:\r\n\r\n```\r\n{\r\n amount: number;\r\n from: string | undefined;\r\n to: string | undefined;\r\n}\r\n```\r\n\r\n##### expression\r\n\r\nType: `string`\r\n\r\nExpression you want to parse, ex. `10 usd to pln` or `€1.23 eur`\r\n\r\n## Migrating from money.js\r\n\r\nWith `Cashify` constructor:\r\n\r\n```diff\r\n- import fx from 'money';\r\n+ import {Cashify} from 'cashify';\r\n\r\n- fx.base = 'EUR';\r\n- fx.rates = {\r\n- GBP: 0.92,\r\n- EUR: 1.00,\r\n- USD: 1.12\r\n- };\r\n\r\n+ const rates = {\r\n+  GBP: 0.92,\r\n+  EUR: 1.00,\r\n+  USD: 1.12\r\n+ };\r\n\r\n+ const cashify = new Cashify({base: 'EUR', rates});\r\n\r\n- fx.convert(10, {from: 'GBP', to: 'EUR'});\r\n+ cashify.convert(10, {from: 'GBP', to: 'EUR'});\r\n```\r\n\r\nWith `convert` function:\r\n\r\n```diff\r\n- import fx from 'money';\r\n+ import {convert} from 'cashify';\r\n\r\n- fx.base = 'EUR';\r\n- fx.rates = {\r\n- GBP: 0.92,\r\n- EUR: 1.00,\r\n- USD: 1.12\r\n- };\r\n\r\n+ const rates = {\r\n+  GBP: 0.92,\r\n+  EUR: 1.00,\r\n+  USD: 1.12\r\n+ };\r\n\r\n- fx.convert(10, {from: 'GBP', to: 'EUR'});\r\n+ convert(10, {from: 'GBP', to: 'EUR', base: 'EUR', rates});\r\n```\r\n\r\n## Floating point issues\r\n\r\nWhen working with currencies, decimals only need to be precise up to the smallest cent value while avoiding common floating point errors when performing basic arithmetic.\r\n\r\nLet's take a look at the following example:\r\n\r\n```js\r\nimport fx from 'money';\r\nimport {Cashify} from '@afzalimdad9/cashify';\r\n\r\nconst rates = {\r\n GBP: 0.92,\r\n USD: 1.12\r\n};\r\n\r\nfx.rates = rates;\r\nfx.base = 'EUR';\r\n\r\nconst cashify = new Cashify({base: 'EUR', rates});\r\n\r\nfx.convert(10, {from: 'EUR', to: 'GBP'}); //=> 9.200000000000001\r\ncashify.convert(10, {from: 'EUR', to: 'GBP'}); //=> 9.2\r\n```\r\n\r\nAs you can see, money.js doesn't handle currencies correctly and therefore a floating point issues are occuring. Even though there's just a minor discrepancy between the results, if you're converting large amounts, that can add up.\r\n\r\nCashify solves this problem the same way as [currency.js](https://github.com/scurker/currency.js/) - by working with integers behind the scenes. **This should be okay for most reasonable values of currencies**; if you want to avoid all floating point issues, see [integration with big.js]().\r\n\r\n## Related projects\r\n\r\n- [nestjs-cashify](https://github.com/vahidvdn/nestjs-cashify) - Node.js Cashify module for Nest.js.\r\n- [cashify-rs](https://github.com/xxczaki/cashify-rs) - Cashify port for Rust.\r\n\r\n## License\r\n\r\nMIT © [Afzal Imdad](https://afzalimdad9.vercel.app)\r\n","readmeFilename":"readme.md"}