money_attribute 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcfa5f42f59d3a7f372ddbff422a4e2aa45faccf4f5bd912fc2509e974bda609
-  data.tar.gz: 173509ac929dc32881a8bae54be2c3a7c0f92632ab8fae0192d84ae9b42433eb
+  metadata.gz: cb71d942a1dd57ae30fa3d1d8941efacf402d9346192b99cca4d0eabf69246fb
+  data.tar.gz: 70dbb86d5d328e5d42fd09593358445d931261b59212d49f3a8e6a450d275c09
 SHA512:
-  metadata.gz: 18598feb924b703ae70e0fe68a76dd93d3ec9f22753d8556616d8c42ebae8460512e9451ed2e80b96feb44d380e8c03e1d2c0a23f22cf956773d001f5e27d83b
-  data.tar.gz: 1178b4b944cbd54b93d8d96f03a55403141086573d5f15f6225a820e65fb9a3e4fae7f0277518563274fa91a7dc7fd6a4ae889e1391dfb69efe72c07de0bb53a
+  metadata.gz: 93e1d50ccda57e7a535fba457e4551525923358b45ef629b381bb04c900eb1fc7b76c1aa11d18410a0669fb96f610a53df1e76e10dcc58860e1d0cd8e3dd19f6
+  data.tar.gz: 55d8b84306bf8988e066d426e525af1d6bfb2b0f202727a9a3a38aa5a52f9461d57edac0d5c003f5996141a5e662439d661109ba6aab975fd420b882ea754a29

data/README.md

@@ -5,7 +5,7 @@
 
 Store and read Active Record attributes as `Mint::Money` objects with no manual serialization.
 
-`money_attribute` uses two DB columns (amount + currency) for per-row multi-currency data. A simpler `money_amount` variant is also available for fixed-currency models (see [note](#single-column-mode--money_amount-fixed-currency)).
+`money_attribute` uses two DB columns (amount + currency) for per-row multi-currency data. A simpler `money_amount` variant is also available for fixed-currency models (see [note](#single-column-mode-money_amount-fixed-currency)).
 
 ```ruby
 class Product < ApplicationRecord
@@ -188,13 +188,13 @@ MoneyAttribute integrates with Rails I18n to automatically format money amounts
 
 With `I18n.locale` set to `:en`:
 ```ruby
-Mint.money(1234.56, 'USD').to_s  # => "$1,234.56"
+Money.from(1234.56, 'USD').to_s  # => "$1,234.56"
 ```
 
 Switch to `:'pt-BR'` and the separators change automatically (requires [`rails-i18n`](https://github.com/svenfuchs/rails-i18n) or your own locale file):
 ```ruby
 I18n.locale = :'pt-BR'
-Mint.money(1234.56, 'USD').to_s  # => "$1.234,56"
+Money.from(1234.56, 'USD').to_s  # => "$1.234,56"
 ```
 
 The locale backend reads `number.currency.format` from your I18n translations and maps Rails format syntax (`%n` for amount, `%u` for unit) to `Mint::Money#to_s`. If the translation key is missing (no locale file for that language), it falls back to hardcoded defaults (`.` decimal, `,` thousand, `%<symbol>s%<amount>f` format).
@@ -218,9 +218,9 @@ en:
 When any of `positive`, `negative`, or `zero` is present, a Hash format is built. Missing keys fall back to `format`:
 
 ```ruby
-Mint.money(1234.56, 'USD').to_s  # => "$1,234.56"
-Mint.money(-1234.56, 'USD').to_s # => "($1,234.56)"
-Mint.money(0, 'USD').to_s        # => "--"
+Money.from(1234.56, 'USD').to_s  # => "$1,234.56"
+Money.from(-1234.56, 'USD').to_s # => "($1,234.56)"
+Money.from(0, 'USD').to_s        # => "--"
 ```
 
 If none of those keys are set, `format` is used as a plain string (simple formatting).
@@ -313,7 +313,7 @@ end
 | 3 | `name == 'amount'` AND `currency` column exists | `amount` + `currency` |
 | 4 | None of the above | `<name>_amount` + `<name>_currency` (convention) |
 
-Step 4 raises `ArgumentError` if the convention columns don't exist. For single-column fixed-currency attributes, see [`money_amount`](#single-column-mode--money_amount).
+Step 4 raises `ArgumentError` if the convention columns don't exist. For single-column fixed-currency attributes, see [`money_amount`](#single-column-mode-money_amount-fixed-currency).
 
 **Example**
 
@@ -343,6 +343,8 @@ end
 
 ## Querying
 
+### Rails-native queries
+
 Multi-currency (`money_attribute`) attributes support equality queries via `composed_of`:
 
 ```ruby
@@ -356,7 +358,110 @@ Offer.where(price_amount: 10..20, price_currency: 'EUR')
 Offer.where('price_amount > ? AND price_currency = ?', 10, 'EUR')
 ```
 
-For fixed-currency (`money_amount`) attributes, see the [single-column section](#single-column-mode--money_amount).
+Fixed-currency (`money_amount`) attributes support full Rails-native querying through the custom type — equality, IN, BETWEEN, ordering, and aggregation all work:
+
+```ruby
+Product.where(price: 10.to_money('USD'))                        # equality
+Product.where(price: [10.to_money('USD'), 20.to_money('USD')]) # IN
+Product.where(price: 10.to_money('USD')..20.to_money('USD'))   # BETWEEN
+Product.order(price: :desc)                                     # ordering
+Product.where(price: 10.to_money('USD')).sum(:price)            # aggregation
+```
+
+### Money-aware query helpers
+
+For multi-currency attributes, manually decomposing columns is tedious. The query helpers handle this automatically — just pass Money objects:
+
+#### `where_amount`
+
+Filters by amount value. Accepts a scalar, Range, or Array.
+
+```ruby
+Offer.where_amount(price: 10)               # equality (any currency)
+Offer.where_amount(price: [10, 30])         # IN — matches EUR 10, USD 30
+Offer.where_amount(price: 10..100)          # BETWEEN (inclusive)
+Offer.where_amount(price: 10...100)         # BETWEEN (exclusive upper bound)
+```
+
+Ranges work across currencies — `10..50` matches EUR 10 and USD 50:
+
+```ruby
+Offer.create!(price: 10.euros)
+Offer.create!(price: 50.dollars)
+
+Offer.where_amount(price: 10..50)           # => both records
+```
+
+For integer (subunit) columns, pass `Mint::Money` objects directly — subunit conversion is handled automatically:
+
+```ruby
+FinancialTransaction.where_amount(amount: [10.dollars, 10.yens])
+FinancialTransaction.where_amount(amount: 10.dollars..100.dollars)
+```
+
+For decimal columns, raw numbers work:
+
+```ruby
+SimpleOffer.where_amount(price: 50)
+SimpleOffer.where_amount(price: 10..100)
+```
+
+#### `where_currency`
+
+Filters by currency code. Composite attributes only — raises `ArgumentError` for single-column attributes.
+
+```ruby
+Offer.where_currency(price: 'EUR')
+Offer.where_currency(price: 10.euros.currency)  # also accepts Currency object
+```
+
+#### `order_by_amount`
+
+Orders by amount. Composite attributes sort by currency ASC first, then amount. Single-column attributes sort by amount only.
+
+```ruby
+Offer.order_by_amount(price: :asc)   # EUR 10, EUR 100, USD 50
+Offer.order_by_amount(price: :desc)  # EUR 100, EUR 10, USD 50
+Offer.order_by_amount(price: nil)    # defaults to :asc
+```
+
+#### `pluck_amount`
+
+Returns money-aware amounts. Follows Rails' `pluck` arity — one attribute returns flat values, multiple attributes return row arrays.
+
+```ruby
+Offer.pluck_amount(:price)                  # => [EUR 10.00, USD 20.00]
+Offer.pluck_amount(:amount, :discount)      # => [[USD 100.00, EUR 20.00], ...]
+```
+
+#### `pick_amount`
+
+Returns a single money-aware value. Follows Rails' `pick` arity.
+
+```ruby
+Offer.pick_amount(:price)                   # => EUR 10.00
+Offer.pick_amount(:amount, :discount)       # => [USD 100.00, EUR 20.00]
+Offer.none.pick_amount(:price)              # => nil
+```
+
+#### `sum_amount`
+
+Sums amounts grouped by currency for composite attributes. Accepts a single attribute name only.
+
+```ruby
+Offer.sum_amount(:price)
+# => [EUR 30.00, USD 70.00]  (one Money per currency, sorted by code)
+
+SimpleOffer.sum_amount(:price)
+# => [BRL 60.00]  (single-column always returns one Money)
+
+Offer.none.sum_amount(:price)
+# => [Mint::Money(0, 'BRL')]  (empty result returns zero Money)
+```
+
+### Notes
+
+All query helpers raise `ArgumentError` for non-money attributes. Internally, money attribute metadata is registered per model class. The same attribute name can be used safely in different models, but subclasses do not automatically inherit a parent model's registered money attributes.
 
 ## Convenience methods
 
@@ -368,7 +473,7 @@ MoneyAttribute adds small helpers on `Numeric` and `String`:
 12.euros              # => [EUR 12.00]
 ```
 
-> If you prefer not to extend core classes, use `Mint.money(12, 'USD')` instead.
+> If you prefer not to extend core classes, use `Money.from(12, 'USD')` instead.
 
 ## Form helpers
 
@@ -388,6 +493,8 @@ MoneyAttribute adds `money_field` and `money_amount_field` to Rails form builder
 
 `money_amount` wraps a numeric column as `Mint::Money` using the application's default currency. No per-row currency. A lighter alternative when you don't need multi-currency support.
 
+The accessor name must match the column name. `money_amount` does not support custom column mapping.
+
 #### Migration helpers
 
 | Method | Action |
@@ -438,15 +545,7 @@ money_amount :price
 
 #### Querying
 
-Fixed-currency attributes support Rails-native querying through the custom type:
-
-```ruby
-Product.where(price: 10.to_money('USD'))                        # equality
-Product.where(price: [10.to_money('USD'), 20.to_money('USD')]) # IN
-Product.where(price: 10.to_money('USD')..20.to_money('USD'))   # BETWEEN
-Product.order(price: :desc)                                     # ordering
-Product.where(price: 10.to_money('USD')).sum(:price)            # aggregation
-```
+Fixed-currency attributes support full Rails-native querying — see [Querying](#querying) for examples.
 
 ## Roadmap
 

data/Rakefile

@@ -15,13 +15,41 @@ Rake::TestTask.new(:test_run) do |t|
 end
 
 desc 'Migrate test database'
-task :test_db_migrate do
-  sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate', chdir: 'test/dummy')
+task :test_db_migrate do # rubocop:disable Rails/RakeEnvironment
+  sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate', chdir: 'test/dummy', %i[out err] => File::NULL)
 end
 
 desc 'Run tests (migrates test DB first)'
 task test: %i[test_db_migrate test_run]
 
+# --- Adapter-specific tasks ---
+
+%w[postgresql mysql2].each do |adapter|
+  namespace :test do
+    desc "Migrate test database (#{adapter})"
+    task "db_migrate:#{adapter}" do # rubocop:disable Rails/RakeEnvironment
+      sh({ 'RAILS_ENV' => 'test', 'DATABASE_ADAPTER' => adapter },
+         'bin/rails', 'db:migrate', chdir: 'test/dummy', %i[out err] => File::NULL)
+    end
+
+    desc "Run tests against #{adapter}"
+    task adapter do # rubocop:disable Rails/RakeEnvironment
+      Rake::Task[:"test:db_migrate:#{adapter}"].invoke
+      sh({ 'DATABASE_ADAPTER' => adapter }, 'bundle', 'exec', 'rake', 'test_run')
+    end
+  end
+end
+
+desc 'Run tests against all adapters (sqlite3, postgresql, mysql2)'
+task 'test:all' do # rubocop:disable Rails/RakeEnvironment
+  Rake::Task[:test].invoke
+  %w[postgresql mysql2].each do |adapter|
+    Rake::Task[:"test:#{adapter}"].invoke
+  end
+end
+
+# --- Benchmark ---
+
 desc 'Run money_attribute vs money-rails benchmark'
 task bench: :test_db_migrate do
   puts
@@ -41,6 +69,6 @@ task bench: :test_db_migrate do
 end
 
 desc 'Generate consolidated benchmark report (markdown)'
-task 'bench:report' do
+task 'bench:report' do # rubocop:disable Rails/RakeEnvironment
   ruby 'benchmark/report.rb'
 end

data/lib/generators/templates/money_attribute.rb

@@ -2,21 +2,29 @@
 # frozen_string_literal: true
 
 MoneyAttribute.configure do |config|
+  # To set the default currency
+  #
+  # It must be a registered currency
+  #
+  config.default_currency = 'USD'
+
+  # Register built-in crypto currencies
+  #
+  # 1. Register specific crypto currencies:
+  #   Mint::Currency.register_crypto('BTC', 'ETH')
+  #
+  # 2. Register all built-in crypto currencies at once:
+  #   Mint::Currency.register_all_crypto
+  #
+  # See available crypto currencies:
+  #   Mint::Currency.crypto_currencies
+
   # Register a custom currency
   #
   # Example:
   #   config.added_currencies = [
-  #     {currency: 'CRC', subunit: 2, symbol: '₡'},
-  #    {currency: 'NGN', subunit: 3, symbol: '₦'}
+  #    {currency: 'ZCRC', subunit: 2, symbol: '₡'},
+  #    {currency: 'ZNGN', subunit: 3, symbol: '₦'}
   #   ]
-  config.added_currencies = [
-    { currency: 'XCRC', subunit: 2, symbol: '₡' },
-    { currency: 'XNGN', subunit: 3, symbol: '₦' }
-  ]
-
-  # To set the default currency
-  #
-  # It must be a registered currency
-  #
-  config.default_currency = 'BRL'
+  config.added_currencies = []
 end

data/lib/money_attribute/attribute_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # @private Constructor for integer (subunit) columns used by +composed_of+.
+  INTEGER_CONSTRUCTOR = lambda do |amount, currency|
+    next nil if amount.nil?
+
+    resolved = Money::Currency.resolve(currency.presence || MoneyAttribute.default_currency) || 'XXX'
+    Mint::Money.from_subunits(amount, resolved)
+  end.freeze
+
+  # @private Constructor for decimal (unit value) columns used by +composed_of+.
+  DECIMAL_CONSTRUCTOR = lambda do |amount, currency|
+    next nil if amount.nil?
+
+    resolved = Money::Currency.resolve(currency.presence || MoneyAttribute.default_currency) || 'XXX'
+    Mint::Money.from(amount, resolved)
+  end.freeze
+
+  # Value object holding metadata for a registered money attribute.
+  #
+  # Created by +money_attribute+ or +money_amount+ and stored in the class-level registry.
+  # Used by query helpers to resolve column names, build Money values, and generate SQL.
+  AttributeSpec = Struct.new(:name, :kind, :amount_col, :currency_col, :amount_type, keyword_init: true) do
+    # @return [Boolean] +true+ when the spec describes a two-column (amount + currency) attribute.
+    def composite? = kind == :composite
+
+    # @return [Boolean] +true+ when the spec describes a single-column (fixed currency) attribute.
+    def single? = kind == :single
+
+    # Returns the backing database columns for the attribute.
+    #
+    # @return [Array<String>] two-element array for composite, one-element for single.
+    def columns
+      @columns ||= (composite? ? [amount_col, currency_col] : [amount_col]).freeze
+    end
+
+    # @return [Boolean] +true+ when the amount column stores subunits (bigint).
+    def integer_amount? = amount_type == :integer
+
+    # @return [Symbol] +:subunits+ for integer columns, +:to_d+ for decimal columns.
+    def amount_extractor = integer_amount? ? :subunits : :to_d
+
+    # @return [Hash{String => Symbol}] mapping suitable for +composed_of+.
+    def composed_of_mapping = { amount_col => amount_extractor, currency_col => :currency_code }
+
+    # @return [Proc] the constructor lambda used by +composed_of+ to instantiate Money values.
+    def constructor
+      integer_amount? ? INTEGER_CONSTRUCTOR : DECIMAL_CONSTRUCTOR
+    end
+
+    # Converts a raw amount and currency into a +Mint::Money+ value.
+    #
+    # @param amount [Integer, BigDecimal, nil] the raw column value
+    # @param currency [String, Mint::Currency, nil] the currency code or object
+    # @return [Mint::Money, nil] the resolved money value, or nil when amount is nil
+    def build_money(amount, currency)
+      return unless amount
+      return amount if amount.is_a?(Mint::Money)
+
+      constructor.call(amount, currency)
+    end
+
+    # Normalizes a query value to the column's storage format.
+    #
+    # Composite attributes: decomposes +Mint::Money+ to subunits via +.subunits+.
+    # Single-column attributes: passes through (the registered Type handles serialization).
+    #
+    # @param value [Mint::Money, Numeric] the query value
+    # @return [Integer, BigDecimal, Mint::Money] the normalized value
+    def normalize_query_value(value)
+      return value unless integer_amount?
+      return value.subunits if value.is_a?(Mint::Money)
+
+      value
+    end
+  end
+end

data/lib/money_attribute/attribute_spec_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+
+module MoneyAttribute
+  # Stores money attribute metadata on the model class.
+  module AttributeSpecRegistry
+    extend ActiveSupport::Concern
+
+    REGISTRY = Concurrent::Map.new
+
+    class_methods do
+      # Registers a money attribute spec for the current model class.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @param kind [Symbol] +:composite+ or +:single+
+      # @param amount_col [Symbol, String] the amount column name
+      # @param currency_col [Symbol, String, nil] the currency column name (composite only)
+      # @param amount_type [Symbol, nil] +:integer+ or +:decimal+
+      # @return [AttributeSpec]
+      def register_money_attribute_spec(name, kind:, amount_col:, currency_col: nil, amount_type: nil)
+        spec = MoneyAttribute::AttributeSpec.new(
+          name: name.to_s,
+          kind: kind,
+          amount_col: amount_col.to_s,
+          currency_col: currency_col&.to_s,
+          amount_type: amount_type
+        )
+
+        money_attribute_specs[spec.name] = spec
+        spec
+      end
+
+      # Returns the registered money attribute spec for the given name.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [AttributeSpec, nil]
+      def money_attribute_spec(name)
+        REGISTRY[self]&.fetch(name.to_s, nil)
+      end
+
+      # Returns the registry hash for the current model class.
+      #
+      # @return [Hash{String => AttributeSpec}]
+      def money_attribute_specs
+        REGISTRY.fetch_or_store(self) { {} }
+      end
+    end
+  end
+end

data/lib/money_attribute/configuration.rb

@@ -1,27 +1,55 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  class Configuration
-    attr_accessor :added_currencies, :default_currency
+  # @private
+  CONFIG_MUTEX = Mutex.new
 
-    def initialize
-      @added_currencies = []
-      @default_currency = 'USD'
+  class << self
+    # Returns the lazily initialized gem configuration.
+    #
+    # @return [Config]
+    def config
+      CONFIG_MUTEX.synchronize { @config ||= Config.new }
     end
-  end
 
-  cfg = Configuration.new
-  cached_default = nil
+    # Yields the current configuration object for mutation.
+    #
+    # @yield [config] the current configuration
+    # @return [void]
+    def configure = yield config
+
+    # Returns the current request or default currency as a resolved currency.
+    # Memoized per-thread — within a request, Current.currency is stable.
+    #
+    # @return [Mint::Currency]
+    def default_currency
+      code = MoneyAttribute::Current.currency.presence || config.default_currency
 
-  define_singleton_method(:config) { cfg }
+      last_code, last_currency = Thread.current[:money_attribute_default_currency]
+      return last_currency if last_code == code
 
-  define_singleton_method(:configure) do |&block|
-    block&.call(cfg)
-    cached_default = nil
-    cfg
+      currency = Money::Currency.resolve!(code)
+      Thread.current[:money_attribute_default_currency] = [code, currency]
+      currency
+    end
   end
 
-  define_singleton_method(:default_currency) do
-    cached_default ||= ::Mint::Currency.resolve!(cfg.default_currency)
+  # Gem configuration holding the default currency and registered custom currencies.
+  #
+  #   MoneyAttribute.configure do |config|
+  #     config.default_currency = 'BRL'
+  #   end
+  class Config
+    # @return [String] ISO 4217 currency code used when no per-request or per-row currency is set.
+    attr_accessor :default_currency
+
+    # @return [Array<Hash>] custom currencies registered via +register_custom_currencies!+.
+    attr_accessor :added_currencies
+
+    # Initializes the default gem configuration values.
+    def initialize
+      @default_currency = 'USD'
+      @added_currencies = []
+    end
   end
 end

data/lib/money_attribute/converter.rb

@@ -3,15 +3,25 @@
 module MoneyAttribute
   # :nodoc:
   class Converter
-    def initialize(currency = MoneyAttribute.default_currency)
-      @default_currency = currency
+    DEFAULT = new.freeze
+
+    # Initializes a converter with an optional fixed currency.
+    def initialize(currency = nil)
+      @static_currency = currency
+    end
+
+    # Returns the shared default converter instance.
+    def self.default
+      DEFAULT
     end
 
+    # Converts raw input into a `Money` value.
     def parse(amount)
+      currency = @static_currency || MoneyAttribute.default_currency
       case amount
       when Money, NilClass      then amount
-      when Numeric              then Money.from(amount, @default_currency)
-      when String               then Money.parse(amount, @default_currency)
+      when Numeric              then Money.from(amount, currency)
+      when String               then Money.parse(amount, currency)
       else raise ArgumentError, "Cannot convert #{amount.inspect} (#{amount.class}) to Money"
       end
     end

data/lib/money_attribute/{core_ext.rb → core_ext/numeric.rb}

@@ -4,5 +4,5 @@
 class Numeric
   remove_method :to_money if method_defined?(:to_money)
 
-  def to_money(currency = MoneyAttribute.default_currency) = Mint.money(self, currency)
+  def to_money(currency = MoneyAttribute.default_currency) = Money.from(self, currency)
 end

data/lib/money_attribute/current.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module MoneyAttribute
+  # Per-request currency container. Set MoneyAttribute::Current.currency in your
+  # controller (or a before_action) to override the configured default for that request.
+  # Automatically reset after each request by MoneyAttribute::Middleware.
+  class Current < ::ActiveSupport::CurrentAttributes
+    # @return [String, nil] per-request ISO 4217 currency code override.
+    attribute :currency
+  end
+end

data/lib/money_attribute/form_builder_extension.rb

@@ -3,6 +3,7 @@
 module MoneyAttribute
   # :nodoc:
   module FormBuilderExtension
+    # Renders a text input for a composed money attribute.
     def money_field(method, options = {})
       money = object.public_send(method)
       value = money&.to_fs
@@ -11,6 +12,7 @@ module MoneyAttribute
                                { id: field_id(method) }.merge(options))
     end
 
+    # Renders a number input for a single-column money attribute.
     def money_amount_field(method, options = {})
       money_from_column = object.public_send(method)
       value = money_from_column&.to_d