{"id":13448520,"url":"https://github.com/parsify-dev/cashify","last_synced_at":"2025-04-05T15:09:52.679Z","repository":{"id":51340507,"uuid":"201118750","full_name":"parsify-dev/cashify","owner":"parsify-dev","description":"💸  Lightweight currency conversion library, successor of money.js","archived":false,"fork":false,"pushed_at":"2023-11-12T16:11:36.000Z","size":174,"stargazers_count":406,"open_issues_count":5,"forks_count":19,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T06:31:34.562Z","etag":null,"topics":["cash","cashify","convert","convert-currencies","convert-currency-rates","converter","currency","currency-exchange","currency-rates","exchange","exchange-rates","fixer","money","moneyjs","npm","open-exchange-rates","package","rates"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parsify-dev.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"xxczaki"}},"created_at":"2019-08-07T19:55:39.000Z","updated_at":"2025-03-15T00:12:46.000Z","dependencies_parsed_at":"2024-03-17T05:25:24.383Z","dependency_job_id":"fccbac40-bd25-4a76-803a-9976992c11c4","html_url":"https://github.com/parsify-dev/cashify","commit_stats":{"total_commits":130,"total_committers":7,"mean_commits":"18.571428571428573","dds":0.2615384615384615,"last_synced_commit":"e3cce810c593dfba7e4a1fd39b03126d6ac5511d"},"previous_names":["xxczaki/cashify"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parsify-dev%2Fcashify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parsify-dev%2Fcashify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parsify-dev%2Fcashify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parsify-dev%2Fcashify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parsify-dev","download_url":"https://codeload.github.com/parsify-dev/cashify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271527,"owners_count":20911587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cash","cashify","convert","convert-currencies","convert-currency-rates","converter","currency","currency-exchange","currency-rates","exchange","exchange-rates","fixer","money","moneyjs","npm","open-exchange-rates","package","rates"],"created_at":"2024-07-31T05:01:47.908Z","updated_at":"2025-04-05T15:09:52.661Z","avatar_url":"https://github.com/parsify-dev.png","language":"TypeScript","readme":"# Cashify 💸\n\n\u003e Lightweight currency conversion library, successor of money.js\n\n[![Build Status](https://github.com/xxczaki/cashify/workflows/CI/badge.svg)](https://github.com/xxczaki/cashify/actions?query=workflow%3ACI)\n[![Coverage Status](https://coveralls.io/repos/github/xxczaki/cashify/badge.svg?branch=master)](https://coveralls.io/github/xxczaki/cashify?branch=master)\n[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo)\n[![install size](https://packagephobia.now.sh/badge?p=cashify)](https://packagephobia.now.sh/result?p=cashify)\n![minified size](https://img.shields.io/bundlephobia/minzip/cashify)\n[![Mentioned in Awesome Node.js](https://awesome.re/mentioned-badge.svg)](https://github.com/sindresorhus/awesome-nodejs)\n\n- [Motivation](#motivation)\n- [Highlights](#highlights)\n- [Install](#install)\n- [Usage](#usage)\n\t- [With constructor](#with-constructor)\n\t- [Without constructor](#without-constructor)\n\t- [Parsing](#parsing)\n\t- [Integration with big.js](#integration-bigjs)\n\t- [Integration with currency.js](#integration-currencyjs)\n- [API](#api)\n\t- [Cashify({base, rates})](#cashifybase-rates)\n\t\t- [base](#base)\n\t\t- [rates](#rates)\n\t\t- [BigJs](#bigjs)\n\t- [convert(amount, {from, to, base, rates})](#convertamount-from-to-base-rates-with-and-without-constructor)\n        - [amount](#amount)\n        - [from](#from)\n        - [to](#to)\n        - [base](#base-1)\n        - [rates](#rates-1)\n        - [BigJs](#bigjs-1)\n    - [parse(expression)](#parseexpression)\n        - [expression](#expression)\n- [Migrating from money.js](#migrating-from-moneyjs)\n- [Floating point issues](#floating-point-issues)\n- [Related projects](#related-projects)\n- [License](#license)\n\n---\n\n## Motivation\n\nThis package was created, because the popular [money.js](http://openexchangerates.github.io/money.js/) library:\n* is not maintained (last commit was ~5 years ago)\n* has over 20 open issues\n* does not support TypeScript\n* has implicit globals\n* does not have any unit tests\n* [has floating point issues](#floating-point-issues)\n\n## Highlights\n\n- Simple API\n- 0 dependencies\n- Actively maintained\n- Well tested and documented\n- [Easy migration from money.js](#migrating-from-moneyjs)\n- Written in TypeScript\n- ESM-only\n\n## Install\n\n```\n$ npm install cashify\n```\n\n**Please note that starting with version `3.0.0` this package is ESM-only and thus requires Node.js v14 or higher.**\n\n## Usage\n\n### With constructor\n\n```js\nimport {Cashify} from 'cashify';\n\nconst rates = {\n\tGBP: 0.92,\n\tEUR: 1.00,\n\tUSD: 1.12\n};\n\nconst cashify = new Cashify({base: 'EUR', rates});\n\nconst result = cashify.convert(10, {from: 'EUR', to: 'GBP'});\n\nconsole.log(result); //=\u003e 9.2\n```\n\n### Without constructor\n\nUsing the `Cashify` constructor is not required. Instead, you can just use the `convert` function:\n\n```js\nimport {convert} from 'cashify';\n\nconst rates = {\n\tGBP: 0.92,\n\tEUR: 1.00,\n\tUSD: 1.12\n};\n\nconst result = convert(10, {from: 'EUR', to: 'GBP', base: 'EUR', rates});\n\nconsole.log(result); //=\u003e 9.2\n```\n\n### Parsing\n\nCashify supports parsing, so you can pass a `string` to the `amount` argument and the `from` and/or `to` currency will be automatically detected:\n\n```js\nimport {Cashify} from 'cashify';\n\nconst rates = {\n\tGBP: 0.92,\n\tEUR: 1.00,\n\tUSD: 1.12\n};\n\nconst cashify = new Cashify({base: 'EUR', rates});\n\n// Basic parsing\ncashify.convert('€10 EUR', {to: 'GBP'});\n\n// Full parsing\ncashify.convert('10 EUR to GBP');\n```\n\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:\n\n```js\nimport {parse} from 'cashify';\n\nparse('10 EUR to GBP'); //=\u003e {amount: 10, from: 'EUR', to: 'GBP'}\n```\n\n**Note:** If you want to use full parsing, you need to pass a `string` in a specific format:\n\n```\n10 usd to pln\n12.5 GBP in EUR\n3.1415 eur as chf\n```\n\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.\n\n\u003ca id=\"integration-bigjs\"\u003e\u003c/a\u003e\n\n### Integration with [big.js](https://github.com/MikeMcl/big.js/)\n\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:\n\n```js\nimport {Cashify} from 'cashify';\nimport Big from 'big.js';\n\nconst rates = {\n\tEUR: 0.8235,\n\tUSD: 1\n};\n\nconst cashify = new Cashify({base: 'USD', rates});\n\nconst result = cashify.convert(1, {\n\tfrom: 'USD',\n\tto: 'EUR',\n\tBigJs: Big\n});\n\nconsole.log(result); //=\u003e 8.235 (without big.js you would get something like 0.8234999999999999)\n```\n\n\u003ca id=\"integration-currencyjs\"\u003e\u003c/a\u003e\n\n### Integration with [currency.js](https://github.com/scurker/currency.js/)\n\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:\n\n```js\nimport {Cashify} from 'cashify';\nimport currency from 'currency.js';\n\nconst rates = {\n\tGBP: 0.92,\n\tEUR: 1.00,\n\tUSD: 1.12\n};\n\nconst cashify = new Cashify({base: 'EUR', rates});\n\nconst converted = cashify.convert(8635619, {from: 'EUR', to: 'GBP'}); // =\u003e 7944769.48\n\n// Format the conversion result\ncurrency(converted, {symbol: '€', formatWithSymbol: true}).format(); // =\u003e €7,944,769.48\n```\n\n## API\n\n### Cashify({base, rates, BigJs})\n\nConstructor.\n\n##### base\n\nType: `string`\n\nThe base currency.\n\n##### rates\n\nType: `object`\n\nAn object containing currency rates (for example from an API, such as Open Exchange Rates).\n\n##### BigJs\n\nType: [big.js](https://github.com/MikeMcl/big.js/) constructor\n\nSee [integration with big.js](#integration-bigjs).\n\n### convert(amount, {from, to, base, rates}) *`with and without constructor`*\n\nReturns conversion result (`number`).\n\n##### amount\n\nType: `number` or `string`\n\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).\n\n##### from\n\nType: `string`\n\nCurrency from which you want to convert. You might not need to specify it if you are using [parsing](#parsing).\n\n##### to\n\nType: `string`\n\nCurrency to which you want to convert. You might not need to specify it if you are using [parsing](#parsing).\n\n##### base\n\nType: `string`\n\nThe base currency.\n\n##### rates\n\nType: `object`\n\nAn object containing currency rates (for example from an API, such as Open Exchange Rates).\n\n##### BigJs\n\nType: [big.js](https://github.com/MikeMcl/big.js/) constructor\n\nSee [integration with big.js](#integration-bigjs).\n\n### parse(expression)\n\nReturns an `object`, which contains parsing results:\n\n```\n{\n\tamount: number;\n\tfrom: string | undefined;\n\tto: string | undefined;\n}\n```\n\n##### expression\n\nType: `string`\n\nExpression you want to parse, ex. `10 usd to pln` or `€1.23 eur`\n\n## Migrating from money.js\n\nWith `Cashify` constructor:\n\n```diff\n- import fx from 'money';\n+ import {Cashify} from 'cashify';\n\n- fx.base = 'EUR';\n- fx.rates = {\n-\tGBP: 0.92,\n-\tEUR: 1.00,\n-\tUSD: 1.12\n- };\n\n+ const rates = {\n+\t GBP: 0.92,\n+\t EUR: 1.00,\n+\t USD: 1.12\n+ };\n\n+ const cashify = new Cashify({base: 'EUR', rates});\n\n- fx.convert(10, {from: 'GBP', to: 'EUR'});\n+ cashify.convert(10, {from: 'GBP', to: 'EUR'});\n```\n\nWith `convert` function:\n\n```diff\n- import fx from 'money';\n+ import {convert} from 'cashify';\n\n- fx.base = 'EUR';\n- fx.rates = {\n-\tGBP: 0.92,\n-\tEUR: 1.00,\n-\tUSD: 1.12\n- };\n\n+ const rates = {\n+\t GBP: 0.92,\n+\t EUR: 1.00,\n+\t USD: 1.12\n+ };\n\n- fx.convert(10, {from: 'GBP', to: 'EUR'});\n+ convert(10, {from: 'GBP', to: 'EUR', base: 'EUR', rates});\n```\n\n## Floating point issues\n\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.\n\nLet's take a look at the following example:\n\n```js\nimport fx from 'money';\nimport {Cashify} from 'cashify';\n\nconst rates = {\n\tGBP: 0.92,\n\tUSD: 1.12\n};\n\nfx.rates = rates;\nfx.base = 'EUR';\n\nconst cashify = new Cashify({base: 'EUR', rates});\n\nfx.convert(10, {from: 'EUR', to: 'GBP'}); //=\u003e 9.200000000000001\ncashify.convert(10, {from: 'EUR', to: 'GBP'}); //=\u003e 9.2\n```\n\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.\n\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]().\n\n## Related projects\n\n* [nestjs-cashify](https://github.com/vahidvdn/nestjs-cashify) - Node.js Cashify module for Nest.js.\n* [cashify-rs](https://github.com/xxczaki/cashify-rs) - Cashify port for Rust.\n\n## License\n\nMIT © [Antoni Kępiński](https://www.kepinski.ch)\n","funding_links":["https://github.com/sponsors/xxczaki"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparsify-dev%2Fcashify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparsify-dev%2Fcashify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparsify-dev%2Fcashify/lists"}