28

Ruby Gem: Currency Converter

A Ruby gem for converting amounts between currencies using real-time exchange rates, with caching and error handling. The CurrencyConverter gem is a powerful, lightweight, and intuitive tool designed to simplify the process of converting currencies in Ruby applications. Whether you're building an e-commerce platform, a financial dashboard, or an analytics tool, this gem empowers developers to handle currency conversions with precision and ease. The gem integrates seamlessly with an external exchange rate API to fetch real-time rates, ensuring accuracy for all conversions. At the same time, it provides a caching mechanism to store exchange rates temporarily, reducing redundant API calls and improving performance. The caching duration is fully configurable, allowing you to strike the perfect balance between freshness and efficiency based on your application's needs.

GitHub Website

Developers often face challenges when dealing with dynamic exchange rates due to network issues or unavailable rate pairs. To address these scenarios, CurrencyConverter includes robust error-handling mechanisms. It differentiates between API errors (e.g., missing rates) and general operational failures (e.g., network issues), allowing developers to write reliable, fault-tolerant applications.

Beyond its core functionality, the gem boasts a clean and flexible configuration system. With just a few lines of code, you can set up your API key, specify caching preferences, and even enable detailed logging for debugging purposes. The gem leverages Ruby's standard libraries, ensuring compatibility and ease of use without adding unnecessary dependencies.

Key Features:

  • Real-Time Exchange Rates: Fetches up-to-date exchange rates from an external API to ensure accuracy in conversions.
  • Built-in Caching: Stores exchange rates temporarily to minimize API requests and enhance application performance.
  • Error Handling: Differentiates between missing rates and other failures, providing actionable error messages.
  • Flexible Configuration: Allows you to set an API key, cache duration, and optional logging preferences.
  • Simple and Intuitive API: Designed to be easy to use, with a straightforward method for performing conversions.
  • Test-Friendly Design: Mocking API calls during tests is simple, ensuring consistency in testing environments.

Why Choose CurrencyConverter?

Currency conversion is a critical functionality in many applications, but building and maintaining a custom solution can be time-consuming and error-prone. CurrencyConverter removes the complexity of managing exchange rates and currency conversions by providing a comprehensive, out-of-the-box solution.

The gem is ideal for:

  • E-commerce Platforms: Convert product prices and order totals into customers' local currencies.
  • Financial Applications: Analyze and display data in a consistent currency for reporting or visualization.
  • Travel Booking Services: Display pricing and billing details in different currencies based on the user's location.
  • Global SaaS Platforms: Handle subscription payments and billing in various currencies.

With its robust design and thoughtful feature set, CurrencyConverter ensures that your application can handle currency conversions confidently, even in edge cases.

How It Works:

  • Initialization: Configure the gem with your API key, cache settings, and optional logging preferences.
  • Perform Conversions: Use the convert method to seamlessly convert amounts between supported currencies.
  • Handle Errors Gracefully: Rely on built-in error handling to catch issues, such as unsupported currencies or network outages, and take appropriate actions.

Example Scenarios:

  • Real-Time Price Conversion: Convert the price of a product from USD to EUR dynamically based on the latest exchange rate when a customer views the product page.
  • Batch Conversion for Reports: Use the gem to process financial data in bulk, converting all values into a base currency for reporting purposes.
  • Integration with APIs: Pair the CurrencyConverter gem with external APIs or services to process payments in local currencies and reconcile amounts in a standard currency.

By abstracting the complexities of currency conversion, CurrencyConverter allows developers to focus on building the core features of their applications while leaving the intricate details of exchange rate management to the gem.

Why It Stands Out:

  • Performance Optimization: The caching mechanism is a standout feature, drastically reducing API calls and ensuring fast, repeated conversions.
  • Ease of Use: With a clean API design, the gem is accessible even for developers new to Ruby or currency conversion.
  • Reliability: Detailed error handling ensures that unexpected issues don’t disrupt your application.

In summary, the CurrencyConverter gem is an essential utility for any application dealing with global currencies. Its combination of real-time accuracy, performance, and robustness makes it the go-to choice for developers seeking a dependable currency conversion solution.

CurrencyConverter

The CurrencyConverter gem provides an easy way to perform currency conversions. It allows you to convert amounts between different currencies using real-time exchange rates from an external API, while offering caching for performance improvements and error handling for robustness.

Developed by Shobhit Jain.

Installation

Add this line to your application's Gemfile:

gem 'currency-converter', '~> 1.1.0'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install currency-converter

Configuration

Before using the gem, you need to configure it by setting up the necessary API key and cache duration. The gem uses an external API for exchange rates, so you'll need an API key for that.

Setting up Configuration To get your api key, you can sign up for free at Exchange Rate API

CurrencyConverter.configure do |config|
  config.api_key = 'your_api_key_here'     # Your API key for the external API
  config.cache_duration = 60               # Cache duration in seconds
  config.logger = Logger.new(STDOUT)       # Optional: Configure logging
end

api_key: Your API key for accessing exchange rates from the external provider.

cache_duration: The duration for which exchange rates should be cached (in seconds).

logger: Optional logging configuration for debugging purposes.

Usage

Creating an Instance of the Converter You can create an instance of the CurrencyConverter::Converter class to perform currency conversions.

# Initialize the converter with the configured API key
converter = CurrencyConverter::Converter.new

Converting Currency

Use the convert method to convert an amount from one currency to another.

# Convert 100 USD to EUR
amount_in_eur = converter.convert(100, 'USD', 'EUR')
puts amount_in_eur

amount: The amount you want to convert.

from_currency: The source currency code (e.g., "USD").

to_currency: The target currency code (e.g., "EUR").

This method will return the converted amount as a Float and will raise an error if the conversion fails (e.g., if the exchange rate for the requested currency pair is unavailable).

Handling Errors

The convert method raises errors in the following situations:

Missing Rate: If the exchange rate for the requested currency pair is not available, a CurrencyConverter::APIError is raised.

General Conversion Failure: If any other issues occur (e.g., network failure), a StandardError is raised.

Example of Handling Errors:

begin
  amount_in_eur = converter.convert(100, 'USD', 'EUR')
  puts "Converted amount: #{amount_in_eur} EUR"
rescue CurrencyConverter::APIError => e
  puts "Conversion failed: #{e.message}"
rescue StandardError => e
  puts "An unexpected error occurred: #{e.message}"
end

Testing

The gem is tested with RSpec, and several tests are included for verifying the correctness of functionality such as caching, conversion, and error handling.

Example Test:

RSpec.describe CurrencyConverter::Converter do
  let(:converter) { CurrencyConverter::Converter.new }
 
  it 'performs currency conversion successfully' do
    result = converter.convert(100, 'USD', 'EUR')
    expect(result).to be_a(Float)
  end
 
  it 'raises an error if the conversion fails' do
    expect { converter.convert(100, 'USD', 'XYZ') }.to raise_error(CurrencyConverter::APIError)
  end
end

Test Setup:

Ensure you have the required API key and any necessary configuration before running the tests. Mocking external API calls in tests is recommended for consistent results.

Changelog

v1.0.0

Initial release with currency conversion and caching support. Error handling for missing rates and failed conversions.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

If you'd like to contribute to the development of this gem, feel free to fork the repository and create a pull request with your changes. Ensure that you write tests for any new features or bug fixes, and follow the style guide for Ruby code and RSpec testing.

Bug reports and pull requests are welcome on GitHub at https://github.com/shobhits7/currency_converter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the CurrencyConverter project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.