money_attribute 1.1.0 → 1.2.0

data/lib/money_attribute/macro.rb

@@ -7,95 +7,72 @@ module MoneyAttribute
 
     # :nodoc:
     module CompositeClassMethods
-      def resolve_composite_mapping(name)
-        columns = attribute_names
-        if columns.include?("#{name}_currency")
-          return { amount: name, currency: :"#{name}_currency" } if columns.include?(name)
+      # Normalizes the requested mapping by applying conventions and overrides.
+      def resolve_mapping(name, mapping_override)
+        override = mapping_override.compact
+        override.slice!(:amount, :currency)
+        override.transform_values!(&:to_s)
 
-          nil
-        elsif name == 'amount' && columns.include?('currency')
-          { amount: name, currency: :currency }
-        end
+        mapping = default_mapping(name).merge(override)
+
+        assert_columns_exist!(name, mapping)
+        mapping
       end
 
-      def resolve_composite_for(name, mapping:)
-        composite = { amount: "#{name}_amount", currency: "#{name}_currency" }
+      # Returns the default amount/currency mapping for the attribute name.
+      def default_mapping(name)
+        name = name.to_s
+        names = column_names
 
-        composite[:amount]   = mapping[:amount].to_s if mapping&.key?(:amount)
-        composite[:currency] = mapping[:currency].to_s if mapping&.key?(:currency)
+        if names.include?("#{name}_currency") && names.include?(name)
+          { amount: name, currency: "#{name}_currency" }
+        elsif name == 'amount' && names.include?('currency')
+          { amount: name, currency: 'currency' }
+        else
+          { amount: "#{name}_amount", currency: "#{name}_currency" }
+        end
+      end
 
-        assert_columns_exist!(name, composite)
-        composite
+      # Registers the composite money attribute spec for the model.
+      def register_composite_spec(name, mapping)
+        column = column_for_attribute(mapping[:amount])
+        register_money_attribute_spec(
+          name,
+          kind: :composite,
+          amount_col: mapping[:amount],
+          currency_col: mapping[:currency],
+          amount_type: %i[integer bigint].include?(column.type) ? :integer : :decimal
+        )
       end
 
-      def assert_columns_exist!(name, composite)
-        missing = composite.values - attribute_names
+      # Raises when the resolved columns are not present on the model.
+      def assert_columns_exist!(name, mapping)
+        missing = mapping.values - column_names
         return if missing.empty?
 
         raise ArgumentError,
               "Could not find columns for :#{name} money attribute. " \
-              "Expected: #{composite.values.join(', ')}, " \
+              "Expected: #{mapping.values.join(', ')}, " \
               "Found: #{attribute_names.join(', ')}"
       end
+    end
 
-      def amount_extractor_for(column_name) = integer_column?(column_name) ? :subunits : :to_d
-
-      def money_constructor_for(amount_column)
-        default = MoneyAttribute.default_currency
-        if integer_column?(amount_column)
-          build_money_constructor(:from_subunits, default)
-        else
-          build_money_constructor(:from, default)
-        end
-      end
-
-      def build_money_constructor(method, default)
-        lambda do |amount, currency|
-          next nil if amount.nil?
-
-          resolved = Mint::Currency.resolve(currency.presence || default) || 'XXX'
-          Mint::Money.public_send(method, amount, resolved)
-        end
-      end
-
-      def integer_column?(column_name)
-        col = columns.find { |c| c.name == column_name }
-        %i[integer bigint].include?(col&.type)
-      end
-
-      def define_composite_money_attribute(name, mapping, currency)
-        aggregated = resolve_composite_for(name, mapping:)
+    class_methods do
+      # Declares a composite money attribute on the model.
+      def money_attribute(name, mapping: {})
+        mapping = resolve_mapping(name, mapping)
+        spec = register_composite_spec(name, mapping)
 
-        composed_of(name.to_sym, {
+        composed_of(name, {
                       allow_nil: true,
                       class_name: 'Mint::Money',
-                      constructor: money_constructor_for(aggregated[:amount]),
-                      converter: Converter.new(currency),
-                      mapping: {
-                        aggregated[:amount] => amount_extractor_for(aggregated[:amount]),
-                        aggregated[:currency] => :currency_code
-                      }
+                      constructor: spec.constructor,
+                      converter: Converter.default,
+                      mapping: spec.composed_of_mapping
                     })
       end
     end
 
-    class_methods do
-      def money_attribute(name, currency: MoneyAttribute.default_currency, mapping: nil)
-        name = name.to_s
-        currency = ::Mint::Currency.resolve!(currency)
-        resolved_mapping = mapping || resolve_composite_mapping(name)
-
-        if resolved_mapping.nil? && attribute_names.include?(name)
-          raise ArgumentError,
-                "Column '#{name}' exists but no '#{name}_currency' column was found. " \
-                'For single-column fixed-currency attributes, use `money_amount` ' \
-                'instead of `money_attribute`.'
-        end
-
-        define_composite_money_attribute(name, resolved_mapping || {}, currency)
-      end
-    end
-
     included do
       extend CompositeClassMethods
     end

data/lib/money_attribute/migration_extensions/helper.rb

@@ -28,8 +28,7 @@ module MoneyAttribute
 
         config = AMOUNT_CONFIG[options[:type] || :fiat_decimal]
         unless config
-          raise ArgumentError,
-                "Invalid money amount type #{options[:type]}. Use :crypto_decimal, :fiat_decimal or :fiat_integer"
+          raise ArgumentError, "Invalid type #{options[:type]}. Use :crypto_decimal, :fiat_decimal or :fiat_integer"
         end
 
         options = { null: options[:null], default: options[:default] }.compact

data/lib/money_attribute/money_amount.rb

@@ -6,31 +6,27 @@ module MoneyAttribute
     extend ActiveSupport::Concern
 
     class_methods do
+      # Declares a fixed-currency money attribute backed by a single column.
       def money_amount(name)
-        name = name.to_s
-
-        assert_column_exists!(name)
-
-        currency = ::Mint::Currency.resolve!(MoneyAttribute.default_currency)
-        column_type = detect_column_type(name)
-
-        attribute(name.to_sym, MoneyAttribute::Type.new(currency:, column_type:))
-        normalizes(name.to_sym, with: Converter.new)
-      end
-
-      private
-
-      def assert_column_exists!(name)
-        return if attribute_names.include?(name)
-
-        raise ArgumentError,
-              "Column '#{name}' does not exist on this table. " \
-              "Add a column named '#{name}' or use a different accessor name."
-      end
-
-      def detect_column_type(name)
-        col = columns.find { |c| c.name == name }
-        %i[integer bigint].include?(col&.type) ? ActiveRecord::Type::Integer.new : ActiveRecord::Type::Decimal.new
+        column = column_for_attribute(name)
+
+        unless column
+          raise ArgumentError,
+                "Column '#{name}' does not exist on this table. " \
+                "Add a column named '#{name}' or use a different accessor name."
+        end
+
+        if %i[integer bigint].include?(column.type)
+          amount_type = :integer
+          type_class = IntegerAmountType
+        else
+          amount_type = :decimal
+          type_class = DecimalAmountType
+        end
+
+        attribute(name, type_class.new)
+        normalizes(name, with: Converter.default)
+        register_money_attribute_spec(name, kind: :single, amount_col: name, amount_type: amount_type)
       end
     end
   end

data/lib/money_attribute/query/amount_condition.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module AmountCondition
+    # Builds an amount filter for the registered money attribute.
+    #
+    # @param attr [Symbol] the money attribute name
+    # @param value [Mint::Money, Numeric, Range, Array] the filter value
+    # @return [ActiveRecord::Relation]
+    # @raise [ArgumentError] if the attribute is not a registered money attribute
+    def resolve_amount_condition(attr, value)
+      spec = money_attribute_spec!(attr)
+      col = arel_table[spec.amount_col]
+
+      where(build_amount_predicate(col, spec, value))
+    end
+
+    private
+
+    # Builds an Arel predicate for the given amount value.
+    def build_amount_predicate(col, spec, value)
+      case value
+      when Range
+        low = normalize_amount_value(spec, value.begin)
+        high = normalize_amount_value(spec, value.end)
+        pred = col.gteq(low)
+        value.exclude_end? ? pred.and(col.lt(high)) : pred.and(col.lteq(high))
+      when Array
+        col.in(value.map { |v| normalize_amount_value(spec, v) })
+      else
+        col.eq(normalize_amount_value(spec, value))
+      end
+    end
+
+    # Normalizes a scalar value for Arel comparison.
+    #
+    # Composite attributes: the amount column is a plain column with no custom Type,
+    # so we must pre-normalize Money to the raw storage value (subunits or decimal).
+    # Single-column attributes: the column has a registered Type that handles
+    # serialization, so we pass Money objects through directly to avoid double conversion.
+    def normalize_amount_value(spec, value)
+      return value unless spec.composite?
+
+      spec.normalize_query_value(value)
+    end
+  end
+end

data/lib/money_attribute/query/amount_order.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module AmountOrder
+    # Builds an amount ordering for the registered money attribute.
+    #
+    # @param attr [Symbol] the money attribute name
+    # @param direction [Symbol] +:asc+ or +:desc+
+    # @return [ActiveRecord::Relation]
+    # @raise [ArgumentError] if the attribute is not a registered money attribute
+    def resolve_amount_order(attr, direction)
+      spec = money_attribute_spec!(attr)
+
+      if spec.composite?
+        order(spec.currency_col => :asc, spec.amount_col => direction)
+      else
+        order(spec.amount_col => direction)
+      end
+    end
+  end
+end

data/lib/money_attribute/query/currency_condition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module CurrencyCondition
+    # Builds a currency filter for the registered money attribute.
+    #
+    # @param attr [Symbol] the money attribute name
+    # @param currency [String, Mint::Currency] the currency code or object
+    # @return [ActiveRecord::Relation]
+    # @raise [ArgumentError] if the attribute is not a composite money attribute
+    def resolve_currency_condition(attr, currency)
+      spec = money_attribute_spec!(attr)
+
+      unless spec.composite?
+        raise ArgumentError, "#{klass.name}.#{attr} is a money_amount attribute with no currency column"
+      end
+
+      code = currency.is_a?(Mint::Currency) ? currency.code : currency.to_s
+      where(spec.currency_col => code)
+    end
+  end
+end

data/lib/money_attribute/query/helpers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module QueryHelpers
+    # Returns the registered money attribute spec or raises when missing.
+    #
+    # @param attr [Symbol, String] the money attribute name
+    # @return [AttributeSpec]
+    # @raise [ArgumentError] if the attribute is not registered
+    def money_attribute_spec!(attr)
+      spec = klass.money_attribute_spec(attr)
+      raise ArgumentError, "#{attr} is not a money attribute on #{klass.name}" unless spec
+
+      spec
+    end
+
+    # Extracts a single value from a flat row at the given cursor position.
+    #
+    # @param row [Array] the flat row from +pluck+ or +pick+
+    # @param spec [AttributeSpec] the money attribute spec
+    # @param cursor [Integer] current position in the row array
+    # @return [Array(Object, Integer)] the extracted value and updated cursor
+    def extract_pick_value(row, spec, cursor)
+      return [row[cursor], cursor + 1] if spec.single?
+
+      [spec.build_money(row[cursor], row[cursor + 1]), cursor + 2]
+    end
+  end
+end

data/lib/money_attribute/query/pick.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module PickAmount
+    # Picks money-aware amounts for one or more attributes.
+    #
+    # @param attrs [Array<Symbol>] one or more registered money attribute names
+    # @return [Mint::Money, Array, nil] Money for a single attribute, row array for multiple, nil if empty
+    # @raise [ArgumentError] if any attribute is not a registered money attribute
+    def pick_amount(*attrs)
+      raise ArgumentError, 'No attribute specified' if attrs.empty?
+
+      specs = attrs.map { |attr| money_attribute_spec!(attr) }
+      return pick_single_amount(specs.first) if specs.length == 1
+
+      raw = pick(*specs.flat_map(&:columns))
+      return unless raw
+
+      cursor = 0
+      specs.map do |spec|
+        value, cursor = extract_pick_value(raw, spec, cursor)
+        value
+      end
+    end
+
+    private
+
+    # Picks a single money-aware attribute and returns a single value.
+    def pick_single_amount(spec)
+      raw = pick(*spec.columns)
+      return unless raw
+      return raw if spec.single?
+
+      spec.build_money(raw[0], raw[1])
+    end
+  end
+end

data/lib/money_attribute/query/pluck.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module PluckAmount
+    # Plucks money-aware amounts for one or more attributes.
+    #
+    # @param attrs [Array<Symbol>] one or more registered money attribute names
+    # @return [Array<Mint::Money>] for a single attribute
+    # @return [Array<Array>] for multiple attributes, one row array per attribute
+    # @raise [ArgumentError] if any attribute is not a registered money attribute
+    def pluck_amount(*attrs)
+      raise ArgumentError, 'No attribute specified' if attrs.empty?
+
+      specs = attrs.map { |attr| money_attribute_spec!(attr) }
+      return pluck_single_amount(specs.first) if specs.length == 1
+
+      raw = pluck(*specs.flat_map(&:columns))
+      raw.map { |row| extract_money_row(row, specs) }
+    end
+
+    private
+
+    # Plucks a single money-aware attribute and returns money values.
+    def pluck_single_amount(spec)
+      return pluck(spec.amount_col) if spec.single?
+
+      pluck(spec.amount_col, spec.currency_col).map do |amount, currency|
+        spec.build_money(amount, currency)
+      end
+    end
+
+    # Rebuilds a result row for multi-attribute plucks.
+    def extract_money_row(row, specs)
+      cursor = 0
+
+      specs.map do |spec|
+        value, cursor = extract_pick_value(row, spec, cursor)
+        value
+      end
+    end
+  end
+end

data/lib/money_attribute/query/sum.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module SumAmount
+    # Sums money-aware amounts for a single attribute.
+    #
+    # @param attr [Symbol] a registered money attribute name
+    # @return [Array<Mint::Money>] one Money per currency (or one for single-column attributes)
+    # @raise [ArgumentError] if the attribute is not a registered money attribute
+    def sum_amount(attr)
+      raise ArgumentError, 'No attribute specified' if attr.nil?
+
+      spec = money_attribute_spec!(attr)
+      if spec.composite?
+        resolve_composite_sum(spec)
+      else
+        resolve_single_sum(spec)
+      end
+    end
+
+    private
+
+    # Sums a composite attribute grouped by currency.
+    def resolve_composite_sum(spec)
+      totals = group(spec.currency_col).sum(spec.amount_col)
+      return [spec.build_money(0, MoneyAttribute.default_currency)] if totals.empty?
+
+      totals.map { |code, amount| spec.build_money(amount, code) }
+            .sort_by(&:currency_code)
+    end
+
+    # Sums a fixed-currency single-column attribute.
+    def resolve_single_sum(spec)
+      total = sum(spec.amount_col)
+
+      [spec.build_money(total, MoneyAttribute.default_currency)]
+    end
+  end
+end

data/lib/money_attribute/query.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative 'query/helpers'
+require_relative 'query/currency_condition'
+require_relative 'query/amount_condition'
+require_relative 'query/amount_order'
+require_relative 'query/pluck'
+require_relative 'query/pick'
+require_relative 'query/sum'
+
+module MoneyAttribute
+  # Money-aware query helpers for ActiveRecord.
+  #
+  #   Offer.where_currency(price: 'EUR')
+  #   Offer.where_amount(price: 10..100)
+  #   Offer.order_by_amount(price: :desc)
+  #   Offer.pluck_amount(:price)
+  #   Offer.pick_amount(:price)
+  #   Offer.sum_amount(:price)
+  #
+  module Query
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Filters by currency for one or more money attributes.
+      #
+      # @param conditions [Hash{Symbol => String}] attribute name to currency code
+      # @return [ActiveRecord::Relation]
+      # @raise [ArgumentError] if the attribute is not a composite money attribute
+      def where_currency(conditions)
+        scope = all
+        conditions.each { |attr, value| scope = scope.resolve_currency_condition(attr, value) }
+        scope
+      end
+
+      # Filters by amount for one or more money attributes.
+      #
+      # Accepts +Mint::Money+ objects, numeric values (decimal columns), Ranges, or Arrays.
+      #
+      #   Offer.where_amount(price: 10.dollars..100.dollars)
+      #   Offer.where_amount(total: [10, 20, 30])
+      #
+      # @param conditions [Hash{Symbol => Numeric, Range, Array}] attribute name to filter value
+      # @return [ActiveRecord::Relation]
+      # @raise [ArgumentError] if the attribute is not a registered money attribute
+      def where_amount(conditions)
+        scope = all
+        conditions.each { |attr, value| scope = scope.resolve_amount_condition(attr, value) }
+        scope
+      end
+
+      # Orders by amount for one or more money attributes.
+      #
+      # Composite attributes sort by currency ASC first, then amount.
+      #
+      # @param conditions [Hash{Symbol => Symbol}] attribute name to +:asc+ or +:desc+
+      # @return [ActiveRecord::Relation]
+      # @raise [ArgumentError] if the attribute is not a registered money attribute
+      def order_by_amount(conditions)
+        scope = all
+        conditions.each { |attr, dir| scope = scope.resolve_amount_order(attr, dir || :asc) }
+        scope
+      end
+
+      # Plucks money-aware amounts from the current relation.
+      #
+      #   Offer.pluck_amount(:price)
+      #   # => [Mint::Money(10.0, 'EUR'), Mint::Money(20.0, 'USD')]
+      #
+      # @param attrs [Array<Symbol>] one or more registered money attribute names
+      # @return [Array<Mint::Money>] for a single attribute
+      # @return [Array<Array>] for multiple attributes, one row array per attribute
+      # @raise [ArgumentError] if any attribute is not a registered money attribute
+      def pluck_amount(*attrs)
+        all.pluck_amount(*attrs)
+      end
+
+      # Picks a single money-aware value from the current relation.
+      #
+      #   Offer.pick_amount(:price)
+      #   # => Mint::Money(10.0, 'EUR')
+      #
+      # @param attrs [Array<Symbol>] one or more registered money attribute names
+      # @return [Mint::Money, Array, nil] Money for a single attribute, row array for multiple, nil if empty
+      # @raise [ArgumentError] if any attribute is not a registered money attribute
+      def pick_amount(*attrs)
+        all.pick_amount(*attrs)
+      end
+
+      # Sums money-aware amounts, grouping by currency for composite attributes.
+      #
+      #   Offer.sum_amount(:price)
+      #   # => [Mint::Money(30.0, 'EUR'), Mint::Money(50.0, 'USD')]
+      #
+      # @param attr [Symbol] a registered money attribute name
+      # @return [Array<Mint::Money>] one Money per currency (or one for single-column attributes)
+      # @raise [ArgumentError] if the attribute is not a registered money attribute
+      def sum_amount(attr)
+        all.sum_amount(attr)
+      end
+    end
+  end
+
+  # :nodoc:
+  module QueryMethods
+    include QueryHelpers
+    include CurrencyCondition
+    include AmountCondition
+    include AmountOrder
+    include PluckAmount
+    include PickAmount
+    include SumAmount
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include MoneyAttribute::AttributeSpecRegistry
+  include MoneyAttribute::Query
+  ActiveRecord::Relation.include(MoneyAttribute::QueryMethods)
+end

data/lib/money_attribute/railtie.rb

@@ -20,15 +20,18 @@ module MoneyAttribute
       register_custom_currencies!
     end
 
+    # Configures Mint to use the Rails locale currency format.
     def self.setup_locale_backend!
       ::Mint.locale_backend = method(:build_locale_format).to_proc
     end
 
+    # Builds the locale-aware currency formatting hash.
     def self.build_locale_format
       fmt = I18n.t('number.currency.format', default: {})
       { decimal: fmt[:separator], thousand: fmt[:delimiter], format: build_format(fmt) }
     end
 
+    # Builds the final currency format string or hash for Mint.
     def self.build_format(fmt)
       if %i[positive negative zero].any? { |k| fmt.key?(k) }
         build_hash_format(fmt)
@@ -37,6 +40,7 @@ module MoneyAttribute
       end
     end
 
+    # Builds a per-sign currency format hash.
     def self.build_hash_format(fmt)
       {
         positive: translate_format(fmt[:positive] || fmt[:format]),
@@ -45,10 +49,12 @@ module MoneyAttribute
       }
     end
 
+    # Translates Rails currency placeholders into Mint placeholders.
     def self.translate_format(str)
       str.to_s.gsub('%n', '%<amount>f').gsub('%u', '%<symbol>s')
     end
 
+    # Registers custom currencies configured by the application.
     def self.register_custom_currencies!
       Array(MoneyAttribute.config.added_currencies).each do |currency_data|
         if currency_data.respond_to?(:values_at)
@@ -58,7 +64,7 @@ module MoneyAttribute
         else
           code, subunit, symbol = *currency_data
         end
-        ::Mint::Currency.register(code:, subunit:, symbol:)
+        Money::Currency.register(code:, subunit:, symbol:)
       rescue KeyError => e
         unless e.message.include?('already registered')
           raise ArgumentError,