minting-rails 0.4.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 766443a16444b6968e71bd7a6413e354a694e5caa34372ccc75a5b0e8f2c3521
-  data.tar.gz: c8ddbbfdbf40da375086007a7c6483b6667a508254aab7dcd4e5cb3a4f34a4ee
+  metadata.gz: cc64238c2cc33c623696eb7c602c81a1d6c8850495dd2e46f4eaa3039aabb85b
+  data.tar.gz: a7f7f743d80954eaa09c919a2cf823c28effcbac266f1e3f1a28a9b5859def15
 SHA512:
-  metadata.gz: a3c077a74cbdc2a828d827aeaf9f19350d4eb78b3c413bdd5250e6e756f3b75e328de4a96bb7a25ef66427fb63bfb478c30d511e48dc6948fece318f719a7162
-  data.tar.gz: 3d04dd4a937c093ca1ae96516773077284226fa918b2cb633fa32fd64a35f8b75abbbb623d490bf5ace0cf8ec2755f03e9e83b576f4eae7915f8ae910cb8209a
+  metadata.gz: 2759ac6f5abf6f77effe34aaed92629af1ce4c13ffd712c15db3103406831310cae7fad543329e6f331e135c3778c1b8ce48c4354ccdf01f5a2b655cf660eadf
+  data.tar.gz: 0d031ef7e3dcd06fc31d0eba693b9c79396325af96f1e1a6177f818c8fb8a076ca57e7159d113157f8b5451d08a7308b76ff1227124a2ea16cfac1a205165b9f

data/README.md

@@ -1,65 +1,266 @@
 # Minting::Rails
 
-Minting::Rails is a gem that provides money attributes to ActiveRecord models. It integrates the [Minting](https://github.com/gferraz/minting) library into your Rails application.
+Minting::Rails brings [Minting](https://github.com/gferraz/minting) money objects to Active Record models.
+
+It adds a `money_attribute` model helper, registers a `:mint_money` Active Record type, and includes small convenience methods such as `12.to_money(:USD)`, `12.dollars`, and `'12.00'.mint(:BRL)`.
+
+## What it does
+
+- Stores and reads model attributes as `Mint::Money` objects.
+- Supports composed money attributes backed by amount and currency columns.
+- Normalizes numeric, string, and `Mint::Money` assignments.
+- Validates currencies against the currencies enabled in Minting.
+
+## Requirements
+
+- Ruby 3.3 or newer.
+- Rails 7.1.3.2 or newer.
+- Minting 1.0.0 or newer.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your Rails application's `Gemfile`:
 
 ```ruby
 gem 'minting-rails'
 ```
 
-And then execute:
+Install it:
 
-```bash
-  bundle
+```sh
+bundle install
+```
+
+Generate the initializer:
+
+```sh
+bin/rails g mint:initializer
 ```
 
 ## Configuration
 
-After intalling generate Minting configuration initializer:
+Configure Minting in `config/initializers/minting.rb`:
 
-```sh
-rails g mint:initializer
+```ruby
+Mint.configure do |config|
+  config.enabled_currencies = :all
+  config.default_currency = 'USD'
+end
 ```
 
-You can configure the default currency for your application by adding the following line to your config/initializers/minting.rb:
+You can limit the currencies that may be used:
 
 ```ruby
-Minting.configure do |config|
-  config.default_currency = :usd
+Mint.configure do |config|
+  config.enabled_currencies = %w[USD EUR BRL]
+  config.default_currency = 'USD'
 end
 ```
 
+You can also register custom currencies before enabling or using them:
+
+```ruby
+Mint.configure do |config|
+  config.added_currencies = [
+    { currency: 'CRC', subunit: 2, symbol: 'CRC' },
+    { currency: 'NGN', subunit: 2, symbol: 'NGN' }
+  ]
+
+  config.enabled_currencies = :all
+  config.default_currency = 'CRC'
+end
+```
+
+The default currency must be registered and included in `enabled_currencies`.
+
 ## Usage
 
-To use Minting::Rails, you add the money_attribute method to your ActiveRecord models. For example:
+Declare money attributes in your Active Record models with `money_attribute`.
+
+### Single-column fixed currency
+
+Use this when a column always stores one currency, such as a `price` column that is always USD.
+
+Migration:
+
+```ruby
+class CreateProducts < ActiveRecord::Migration[7.1]
+  def change
+    create_table :products do |t|
+      t.decimal :price
+      t.decimal :discount
+
+      t.timestamps
+    end
+  end
+end
+```
+
+Model:
 
 ```ruby
-class SimpleOffer < ApplicationRecord
+class Product < ApplicationRecord
   money_attribute :price, currency: 'USD'
   money_attribute :discount, currency: 'USD'
 end
 ```
 
-Now you can use the price attribute as a Money object:
+Assignments are normalized to `Mint::Money`:
+
+```ruby
+product = Product.new(price: 12, discount: '3.50')
+
+product.price
+# => #<Mint::Money ... USD 12.00>
+
+product.discount
+# => #<Mint::Money ... USD 3.50>
+```
+
+Assigning a `Mint::Money` with a different currency raises `ArgumentError`:
+
+```ruby
+Product.new(price: 12.to_money(:EUR))
+# raises ArgumentError because the attribute only accepts USD
+```
+
+### Amount and currency columns
+
+Use this when each row can store a different currency per record.
+
+Migration:
+
+```ruby
+class CreateOffers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :offers do |t|
+      t.decimal :price_amount
+      t.string :price_currency
+
+      t.timestamps
+    end
+  end
+end
+```
+
+Model:
+
+```ruby
+class Offer < ApplicationRecord
+  money_attribute :price
+end
+```
+
+The attribute is composed from `price_amount` and `price_currency`:
 
 ```ruby
-product = Product.ne(price: 100)
-puts product.price # => "$100.00"
+offer = Offer.new(price: 15.to_money(:EUR))
+
+offer.price
+# => #<Mint::Money ... EUR 15.00>
+
+offer.price_amount
+# => 15.0
+
+offer.price_currency
+# => "EUR"
+```
+
+When you assign a plain number or string, Minting::Rails uses `Mint.default_currency`:
+
+```ruby
+offer = Offer.new(price: '12')
+
+offer.price.currency_code
+# => "USD"
+```
+
+### Custom column names
+
+If your amount and currency columns do not follow the `<name>_amount` and `<name>_currency` convention, pass a mapping:
+
+```ruby
+class Invoice < ApplicationRecord
+  money_attribute :total, mapping: {
+    total_amount: :amount,
+    currency_code: :currency
+  }
+end
+```
+
+The mapping keys are your database columns. The values must identify which column stores the `:amount` and which stores the `:currency`.
+
+## Querying
+
+Fixed-currency attributes can be queried with `Mint::Money` values:
+
+```ruby
+Product.where(price: 15.to_money(:USD))
+```
+
+Composed attributes can also be queried with a money object:
+
+```ruby
+Offer.where(price: 15.to_money(:EUR))
+```
+
+You can still query the backing columns directly when that is clearer:
+
+```ruby
+Offer.where(price_amount: 15, price_currency: 'EUR')
+```
+
+## Convenience methods
+
+Minting::Rails adds a few small helpers:
+
+```ruby
+12.to_money(:USD)
+12.mint(:BRL)
+12.dollars
+12.euros
+'12.50'.to_money(:USD)
+'12.50'.mint(:BRL)
+```
+
+These return `Mint::Money` instances.
+
+## Development
+
+Clone the repository and install dependencies:
+
+```sh
+bundle install
 ```
 
-## To do
+Run the test suite:
 
-- API Documentation
-- Internationalization
-- Publish 1.0 Beta
+```sh
+bundle exec rake test
+```
+
+The repository includes a dummy Rails application under `test/dummy` for exercising the engine in a Rails environment.
+
+## Releasing
+
+Update the version in `lib/minting/money_attribute/version.rb`, update release notes, and build the gem:
+
+```sh
+gem build minting-rails.gemspec
+```
+
+Publishing is configured for RubyGems.org.
 
 ## Contributing
 
-Contribution directions go here.
+Bug reports and pull requests are welcome on GitHub at [gferraz/minting-rails](https://github.com/gferraz/minting-rails).
+
+Before opening a pull request, please run:
+
+```sh
+bundle exec rake test
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).

data/lib/minting/money_attribute/configuration.rb

@@ -1,26 +1,49 @@
 # frozen_string_literal: true
 
 module Mint
-  include ActiveSupport::Configurable
+  module MoneyAttribute
+    class Configuration
+      attr_accessor :added_currencies, :enabled_currencies, :default_currency,
+                    :rounding_mode, :default_format
 
-  def self.assert_valid_currency!(currency)
-    if currency.is_a? Mint::Currency
-      code = currency.code
-    else
-      code = currency.to_s
-      currency = Mint.currency(code)
+      def initialize
+        @added_currencies = []
+        @enabled_currencies = :all
+        @default_currency = 'USD'
+        @rounding_mode = nil
+        @default_format = nil
+      end
     end
-    return currency if valid_currency_codes.include?(code)
+  end
+
+  def self.config
+    @config ||= MoneyAttribute::Configuration.new
+  end
+
+  def self.configure
+    yield config if block_given?
+    @default_currency = nil
+    config
+  end
+
+  def self.assert_valid_currency!(currency)
+    code = currency.is_a?(Mint::Currency) ? currency.code : currency.to_s
+    currency = Mint.currency(code)
+    return currency if Mint.valid_currency?(currency)
 
-    raise ArgumentError,
-          "Invalid currency '#{code}'. Please select a registered currency: #{valid_currency_codes}"
+    raise ArgumentError, "Invalid currency '#{code}'. Please select a registered currency"
   end
 
   def self.default_currency
     @default_currency ||= Mint.assert_valid_currency!(config.default_currency)
   end
 
-  def self.valid_currency_codes
-    config.enabled_currencies == :all ? Mint.currencies.keys : config.enabled_currencies
+  def self.valid_currency?(currency)
+    return false if currency.nil?
+
+    code = currency.is_a?(Mint::Currency) ? currency.code : currency.to_s
+    currencies = config.enabled_currencies == :all ? Mint.currencies.keys : config.enabled_currencies
+
+    currencies.map(&:to_s).include?(code)
   end
 end

data/lib/minting/money_attribute/money_type.rb

@@ -10,7 +10,7 @@ module Mint
 
     def assert_valid_value(value)
       case value
-      when Numeric, String
+      when NilClass, Numeric, String
         return
       when Mint::Money
         return if value.currency == @currency
@@ -27,7 +27,7 @@ module Mint
     end
 
     def serialize(value)
-      value.to_d
+      value&.to_d
     end
 
     def self.type

data/lib/minting/money_attribute/version.rb

@@ -2,6 +2,6 @@
 
 module Mint
   module MoneyAttribute
-    VERSION = '0.4.0'
+    VERSION = '0.4.3'
   end
 end

data/lib/minting/railties.rb

@@ -7,8 +7,15 @@ module Mint
     end
 
     config.to_prepare do
-      Mint.config.added_currencies do |currency_data|
-        Mint.register_currency(*currency_data)
+      Array(Mint.config.added_currencies).each do |currency_data|
+        if currency_data.respond_to?(:values_at)
+          code = currency_data[:currency] || currency_data['currency']
+          subunit = currency_data[:subunit] || currency_data['subunit']
+          symbol = currency_data[:symbol] || currency_data['symbol']
+        else
+          code, subunit, symbol = *currency_data
+        end
+        Mint.register_currency(code, subunit:, symbol:)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.3
 platform: ruby
 authors:
 - Gilson Ferraz