minting-rails 0.4.5 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dddd6623b7e46d60d0e8e29da21afa581d28c6818ae4d37d5a5c1268da04425f
-  data.tar.gz: 4e6c1fa638f4f22c365d0cc5bc6540c9dccbdc770e8550f10c4ce94c4150088d
+  metadata.gz: 205d9eb9b1d27048756b4f65f2e65781ae71f131d1d838a1834ea733349d3bf4
+  data.tar.gz: ea2dfd05351ae59717737a0770480c1eeb6cf484264c9daea064c87ac80dd4a0
 SHA512:
-  metadata.gz: 0e0a4ff1d7dd9a0ccb543545b75740567d0c985e174bd6e1460e44f08a74bd9f0b68a016e42374bcfb83d859bdb253afb2941fcb1d0ac3d4a6507574802b8dc0
-  data.tar.gz: '09b31cae39bb1d85c3f34fe8c077406874fb8ebd429f37bb2347555fa8fef486685601ec45d06791ac8c7ebce1d8d2a87e7efcd8d46e2aad3c519226210799f5'
+  metadata.gz: a3e434d199296b8d9a22db937b2b40af35eec147a7fdc1d4a1c1a387a3a0300b806381f2e98cb3a3dfc40371b1087f1529a3a81b399b91dff4d4f454034f39c4
+  data.tar.gz: 8552a6d4d6c8f6567a4300c6540b04c00ca220b52b3deb0f0ba00af1fb40d0c974110eb97f04d3d0acb8d037f32852d61cd4a55a6b8d2dc17cbc398c9e58c6d4

data/README.md

@@ -2,7 +2,7 @@
 
 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)`.
+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
 
@@ -15,7 +15,7 @@ It adds a `money_attribute` model helper, registers a `:mint_money` Active Recor
 
 - Ruby 3.3 or newer.
 - Rails 7.1.3.2 or newer.
-- Minting 1.0.0 or newer.
+- Minting 1.6.0 or newer.
 
 ## Installation
 
@@ -45,6 +45,7 @@ Configure Minting in `config/initializers/minting.rb`:
 Mint.configure do |config|
   config.enabled_currencies = :all
   config.default_currency = 'USD'
+  config.default_format = '%<symbol>s%<amount>f'
 end
 ```
 
@@ -63,7 +64,7 @@ You can also register custom currencies before enabling or using them:
 Mint.configure do |config|
   config.added_currencies = [
     { currency: 'CRC', subunit: 2, symbol: 'CRC' },
-    { currency: 'NGN', subunit: 2, symbol: 'NGN' }
+    { currency: 'NGN', subunit: 2, symbol: 'NGN' } # subunit is the number of digits after the decimal; USD has 2, JPY has 0, BHD has 3
   ]
 
   config.enabled_currencies = :all
@@ -120,7 +121,7 @@ product.discount
 Assigning a `Mint::Money` with a different currency raises `ArgumentError`:
 
 ```ruby
-Product.new(price: 12.to_money(:EUR))
+Product.new(price: 12.to_money('EUR'))
 # raises ArgumentError because the attribute only accepts USD
 ```
 
@@ -154,7 +155,7 @@ end
 The attribute is composed from `price_amount` and `price_currency`:
 
 ```ruby
-offer = Offer.new(price: 15.to_money(:EUR))
+offer = Offer.new(price: 15.to_money('EUR'))
 
 offer.price
 # => #<Mint::Money ... EUR 15.00>
@@ -166,6 +167,68 @@ offer.price_currency
 # => "EUR"
 ```
 
+### Integer storage
+
+By default, money attributes are stored as `decimal` columns. If you prefer to store amounts as integer subunits (cents, pence, etc.), use a `bigint` or `integer` column instead. Minting::Rails detects the column type automatically and adapts serialization accordingly.
+
+Migration:
+
+```ruby
+class CreateOrders < ActiveRecord::Migration[7.1]
+  def change
+    create_table :orders do |t|
+      t.bigint  :total_amount
+      t.string  :total_currency
+
+      t.timestamps
+    end
+  end
+end
+```
+
+Model:
+
+```ruby
+class Order < ApplicationRecord
+  money_attribute :total
+end
+```
+
+The amount is stored and retrieved in subunits:
+
+```ruby
+order = Order.new(total: 19.99.to_money(:USD))
+
+order.total
+# => #<Mint::Money ... USD 19.99>
+
+order.total_amount
+# => 1999
+
+order.total_currency
+# => "USD"
+```
+
+The same applies to single-column fixed-currency attributes:
+
+```ruby
+class Ticket < ApplicationRecord
+  money_attribute :price, currency: 'USD'
+end
+```
+
+Migration:
+
+```ruby
+t.bigint :price
+```
+
+No model change is needed. The column type drives the behavior.
+
+> **Note:** Integer storage is more efficient for large tables. Use Decimal when you need to stay close to SQL standards for interoperability with other systems
+
+### Default Currency
+
 When you assign a plain number or string, Minting::Rails uses `Mint.default_currency`:
 
 ```ruby
@@ -182,26 +245,26 @@ If your amount and currency columns do not follow the `<name>_amount` and `<name
 ```ruby
 class Invoice < ApplicationRecord
   money_attribute :total, mapping: {
-    total_amount: :amount,
-    currency_code: :currency
+    amount: :total_amount,
+    currency: :currency_code
   }
 end
 ```
 
-The mapping keys are your database columns. The values must identify which column stores the `:amount` and which stores the `:currency`.
+The mapping keys are `:amount` and `:currency`. The values are your database columns.
 
 ## Querying
 
 Fixed-currency attributes can be queried with `Mint::Money` values:
 
 ```ruby
-Product.where(price: 15.to_money(:USD))
+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))
+Offer.where(price: 15.to_money('EUR'))
 ```
 
 You can still query the backing columns directly when that is clearer:
@@ -215,12 +278,14 @@ Offer.where(price_amount: 15, price_currency: 'EUR')
 Minting::Rails adds a few small helpers:
 
 ```ruby
-12.to_money(:USD)
-12.mint(:BRL)
+12.to_money('USD')
+12.mint('BRL')
 12.dollars
+1.dollar
+1.euro
 12.euros
-'12.50'.to_money(:USD)
-'12.50'.mint(:BRL)
+'12.50'.to_money('USD')
+'12.50'.mint('BRL')
 ```
 
 These return `Mint::Money` instances.
@@ -241,16 +306,6 @@ 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
 
 Bug reports and pull requests are welcome on GitHub at [gferraz/minting-rails](https://github.com/gferraz/minting-rails).

data/lib/generators/templates/minting.rb

@@ -27,22 +27,6 @@ Mint.configure do |config|
   #
   config.default_currency = 'BRL'
 
-  # Specify a rounding mode (not yet implemented)
-  # Any one of:
-  #
-  # BigDecimal::ROUND_UP,
-  # BigDecimal::ROUND_DOWN,
-  # BigDecimal::ROUND_HALF_UP,
-  # BigDecimal::ROUND_HALF_DOWN,
-  # BigDecimal::ROUND_HALF_EVEN,
-  # BigDecimal::ROUND_CEILING,
-  # BigDecimal::ROUND_FLOOR
-  #
-  # set to BigDecimal::ROUND_HALF_EVEN by default
-  #
-  # config.rounding_mode = BigDecimal::ROUND_HALF_UP
-
-  # Set default money format globally.
   # Default value is nil meaning "ignore this option".
   # Example:
   #

data/lib/minting/money_attribute/configuration.rb

@@ -27,11 +27,10 @@ module Mint
   end
 
   def self.assert_valid_currency!(currency)
-    code = currency.is_a?(Mint::Currency) ? currency.code : currency.to_s
-    currency = Mint.currency(code)
+    currency = Mint.currency(currency)
     return currency if Mint.valid_currency?(currency)
 
-    raise ArgumentError, "Invalid currency '#{code}'. Please select a registered currency"
+    raise ArgumentError, "Invalid currency '#{currency}'. Please select a registered currency"
   end
 
   def self.default_currency
@@ -39,11 +38,7 @@ module Mint
   end
 
   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)
+    enabled = config.enabled_currencies
+    currency && (enabled == :all || enabled.include?(currency.code))
   end
 end

data/lib/minting/money_attribute/money_attribute.rb

@@ -9,7 +9,7 @@ module Mint
       # Money attribute
       def money_attribute(name, currency: Mint.default_currency, mapping: nil)
         currency = Mint.assert_valid_currency!(currency)
-        parser = proc { |amount, code = currency| MoneyAttribute.parse(amount, code) }
+        parser = Parser.new(currency)
         if attribute_names.include? name.to_s
           attribute(name, :mint_money, currency:)
           normalizes(name, with: parser)
@@ -18,15 +18,31 @@ module Mint
           options = {
             allow_nil: true, class_name: 'Mint::Money',
             constructor: parser, converter: parser,
-            mapping: { aggregated[:amount] => :to_i, aggregated[:currency] => :currency_code }
+            mapping: {
+              aggregated[:amount] => amount_extractor_for(aggregated[:amount]),
+              aggregated[:currency] => :currency_code
+            }
           }
           composed_of(name, options)
         end
       end
 
+      def amount_extractor_for(column_name)
+        col = columns.find { |c| c.name == column_name.to_s }
+
+        case col&.type
+        when :bigint, :integer
+          :fractional
+        when :decimal, :numeric
+          :to_d
+        else
+          :to_d # :decimal, :numeric, unknown
+        end
+      end
+
       def find_money_attributes(name, mapping:)
         composite = if mapping.present?
-                      { amount: mapping.key(:amount).to_s, currency: mapping.key(:currency).to_s }
+                      { amount: mapping[:amount].to_s, currency: mapping[:currency].to_s }
                     else
                       { amount: "#{name}_amount", currency: "#{name}_currency" }
                     end
@@ -37,25 +53,5 @@ module Mint
         composite
       end
     end
-
-    def self.parse(amount, currency)
-      money = case amount
-              when NilClass
-                nil
-              when Mint::Money
-                amount
-              when Numeric
-                Mint.money(amount, currency)
-              else
-                if amount.respond_to? :to_money
-                  amount.to_money(currency)
-                else
-                  Mint.money(amount.to_s.split[0].to_r, currency)
-                end
-              end
-      # puts "parse(#{amount}, #{currency.inspect}) => #{money.inspect}"
-      Mint.assert_valid_currency!(currency)
-      money
-    end
   end
 end

data/lib/minting/money_attribute/money_type.rb

@@ -3,31 +3,43 @@
 module Mint
   # MintMoneyType
   class MintMoneyType < ActiveRecord::Type::Value
-    def initialize(currency:)
-      @currency = Mint.currency currency
+    def initialize(currency:, column_type: ActiveRecord::Type::Decimal.new)
+      @currency = currency
+      @column_type = column_type
       super()
     end
 
     def assert_valid_value(value)
       case value
-      when NilClass, Numeric, String
-        return
+      when NilClass, Numeric, String then return
       when Mint::Money
         return if value.currency == @currency
 
         message = "'#{value.inspect}' has different currency. Only #{@currency.code} allowed."
       else
-        message = "'#{value}' is not a valid type for the attribute."
+        message = "'#{value.inspect}' is not a valid type for the attribute."
       end
       raise ArgumentError, message
     end
 
     def deserialize(value)
-      value && Mint.money(value, @currency)
+      return nil unless value
+
+      if @column_type.is_a?(ActiveRecord::Type::Integer)
+        Mint.money(value * @currency.multiplier, @currency)
+      else
+        Mint.money(value, @currency)
+      end
     end
 
     def serialize(value)
-      value&.to_d
+      return nil unless value
+
+      if @column_type.is_a?(ActiveRecord::Type::Integer)
+        value.fractional
+      else
+        value.to_d
+      end
     end
 
     def self.type

data/lib/minting/money_attribute/parser.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mint
+  # MoneyAttribute
+  module MoneyAttribute
+    class Parser
+      def initialize(currency = Mint.default_currency)
+        @default_currency = currency
+      end
+
+      def parse(amount, currency = @default_currency)
+        currency = Mint.assert_valid_currency!(currency)
+        case amount
+        when NilClass    then nil
+        when Numeric     then Mint::Money.create(amount, currency)
+        when String      then Mint::Money.create(amount.to_r, currency)
+        when Mint::Money
+         return amount if amount.currency == currency
+         raise TypeError, "Cannot automatically convert #{amount} to #{currency.code}"
+        else
+          Mint.parse(amount, currency)
+        end
+      end
+      alias_method  :call, :parse
+    end
+  end
+end

data/lib/minting/money_attribute/version.rb

@@ -2,6 +2,6 @@
 
 module Mint
   module MoneyAttribute
-    VERSION = '0.4.5'
+    VERSION = '0.7.0'
   end
 end

data/lib/minting/rails.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 require 'minting'
-require 'minting/money_attribute/core_ext'
+require 'minting/core_ext'
 require 'minting/money_attribute/configuration'
 require 'minting/money_attribute/money_attribute'
 require 'minting/money_attribute/money_type'
+require 'minting/money_attribute/parser'
 require 'minting/money_attribute/version'
 require 'minting/railties'

data/lib/minting/railties.rb

@@ -15,7 +15,7 @@ module Mint
         else
           code, subunit, symbol = *currency_data
         end
-        Mint.register_currency(code:, subunit:, symbol:)
+        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.5
+  version: 0.7.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.6.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -49,10 +49,11 @@ files:
 - Rakefile
 - lib/generators/minting/initializer_generator.rb
 - lib/generators/templates/minting.rb
+- lib/minting/core_ext.rb
 - lib/minting/money_attribute/configuration.rb
-- lib/minting/money_attribute/core_ext.rb
 - lib/minting/money_attribute/money_attribute.rb
 - lib/minting/money_attribute/money_type.rb
+- lib/minting/money_attribute/parser.rb
 - lib/minting/money_attribute/version.rb
 - lib/minting/rails.rb
 - lib/minting/railties.rb