Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sunny/active_currency

Rails plugin to store currency rates in the database
https://github.com/sunny/active_currency

Last synced: about 17 hours ago
JSON representation

Rails plugin to store currency rates in the database

Awesome Lists containing this project

README 

        
# ActiveCurrency



Rails plugin to retrieve and store the currency rates daily to integrate

with the [money-rails] gem.



## Rationale



Storing the current currency rates with ActiveCurrency provides the following

advantages:



- Lets you query for the currency rate you actually used in your application at

  any given time.

- Does not need to call an API to get the rates when starting or restarting

  your web server.

- Does not depend on the file system to store cached rates.

- Choose how often you want to update the currency rates (daily for example).

- Your users do not suffer the cost of making calls to the bank rates API.

- Your app does not go down when the bank rates API does.



To fetch the *current* rate it uses your application cache instead of making

a call to the database.



## Usage



Store the current rate regularly by calling in a scheduled job (using something

like [sidekiq-scheduler], [whenever], or [active_scheduler]) with the currencies

you want to store:



```rb

ActiveCurrency::AddRates.call(currencies: %w[EUR USD])

```



You can then exchange money by using the Money gem helpers:



```rb

10.to_money('EUR').exchange_to('USD').cents

```



If you need to look up the previous currency rates:



```rb

ActiveCurrency::Rate.value_for('EUR', 'USD', 1.month.ago)

# => 1.151

ActiveCurrency::Rate.where(from: 'EUR', to: 'USD').pluck(:value)

# => [1.162, 1.162, 1.161, 1.161, 1.163, …]

```



## Installation



Add these lines to your application’s `Gemfile`:



```rb

# Store and retrieve the currency from the database.

gem 'active_currency'

```



And in `config/initializers/money.rb`:



```rb

MoneyRails.configure do |config|

  config.default_bank = ActiveCurrency::Bank.new

end

```



Then call `bin/rake db:migrate` to create the table that holds

the currency rates and fill it for the first time.



## Fetching rates



Call the following regularly in a scheduled job:



```rb

ActiveCurrency::AddRates.call(currencies: %w[EUR USD])

```



The first currency you give in `currencies` is considered the default currency

against which other currency rates will be guessed if they are unavailable.



### Fetching from the European Central Bank



By defaut it uses the [eu_central_bank] to fill the currency rates.



### Fetching from openexchangerates.org



To use the [money-open-exchange-rates] gem, add the gem to your `Gemfile`, then

add the following to your application’s initializers:



```rb

ActiveCurrency.configure do |config|

  config.remote_bank = :open_exchange_rates

  config.open_exchange_rates_app_id = '…'

end

```



### Fetching from a custom bank



You can provide any Money-compatible bank when calling

`ActiveCurrency::AddRates`:



```rb

ActiveCurrency::AddRates.call(…, bank: …)

```



## Apply a multiplier



If you want to increase or decrease the currency rates by a given multiplier,

you can do so by setting the `multiplier` option:



```rb

ActiveCurrency.configure do |config|

  config.multiplier = {

    ["EUR", "USD"] => 1.01,

  }

end

```



## Tests



In your app test suite you may not want to have to fill your database to be

able to exchange currencies.



For that, you can use a fake rate store in your `rails_helper.rb`:



```rb

MoneyRails.configure do |config|

  rate_store = Money::RatesStore::Memory.new.tap do |store|

    store.add_rate('USD', 'EUR', 1.5)

    store.add_rate('EUR', 'USD', 0.67)

  end

  config.default_bank = Money::Bank::VariableExchange.new(rate_store)

end

```



## Contributing



Please file issues and pull requests [on GitHub].



## Development



Install:



```sh

BUNDLE_GEMFILE=Gemfile-rails7.0 bundle install

```



Launch specs and linters:



```sh

BUNDLE_GEMFILE=Gemfile-rails7.0 bin/rake

```



## Release



Update `CHANGELOG.md`, update version in `lib/active_currency/version.rb`.



Then:



```sh

BUNDLE_GEMFILE=Gemfile-rails6.1 bundle update

BUNDLE_GEMFILE=Gemfile-rails7.0 bundle update



git add CHANGELOG.md lib/active_currency/version.rb Gemfile-rails*

git commit -m v`ruby -r./lib/active_currency/version <<< 'puts ActiveCurrency::VERSION'`

bin/rake release

```



## License



The gem is available as open source under the terms of the [MIT License].



[money-rails]: https://github.com/RubyMoney/money-rails

[sidekiq-scheduler]: https://github.com/Moove-it/sidekiq-scheduler

[whenever]: https://github.com/javan/whenever

[active_scheduler]: https://github.com/JustinAiken/active_scheduler

[eu_central_bank]: https://github.com/RubyMoney/eu_central_bank

[money-open-exchange-rates]: https://github.com/spk/money-open-exchange-rates

[on GitHub]: https://github.com/sunny/active_currency

[MIT License]: http://opensource.org/licenses/MIT