money_attribute 0.14.5 → 1.2.0

data/lib/money_attribute/money_amount.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module MoneyAmount
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declares a fixed-currency money attribute backed by a single column.
+      def money_amount(name)
+        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
+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,25 +20,41 @@ module MoneyAttribute
       register_custom_currencies!
     end
 
+    # Configures Mint to use the Rails locale currency format.
     def self.setup_locale_backend!
-      ::Mint.locale_backend = lambda {
-        fmt = I18n.t('number.currency.format', default: {})
-        translator = ->(s) { s&.gsub('%n', '%<amount>f')&.gsub('%u', '%<symbol>s') }
-
-        format = if fmt.key?(:positive) || fmt.key?(:negative) || fmt.key?(:zero)
-                   {
-                     positive: translator.call(fmt[:positive] || fmt[:format]),
-                     negative: translator.call(fmt[:negative] || fmt[:format]),
-                     zero: translator.call(fmt[:zero] || fmt[:format])
-                   }
-                 else
-                   translator.call(fmt[:format])
-                 end
-
-        { decimal: fmt[:separator], thousand: fmt[:delimiter], format: format }
+      ::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)
+      else
+        translate_format(fmt[:format])
+      end
+    end
+
+    # Builds a per-sign currency format hash.
+    def self.build_hash_format(fmt)
+      {
+        positive: translate_format(fmt[:positive] || fmt[:format]),
+        negative: translate_format(fmt[:negative] || fmt[:format]),
+        zero: translate_format(fmt[:zero] || fmt[:format])
       }
     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)
@@ -48,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,

data/lib/money_attribute/type.rb

@@ -1,60 +1,66 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # Type
-  class Type < ActiveRecord::Type::Value
-    def initialize(currency:, column_type: ActiveRecord::Type::Decimal.new)
-      @currency = currency
-      @column_type = column_type
-      super()
-    end
-
-    def cast(value)
-      case value
-      when String then Mint::Money.parse(value, @currency)
-      else             super
-      end
-    end
+  # Base type for money amount attributes. Handles casting and validation.
+  class AmountType < ActiveRecord::Type::Value
+    # Casts string input into a +Mint::Money+ value.
+    #
+    # @param value [String, Numeric, Mint::Money, nil] the input value
+    # @return [Mint::Money, Numeric, nil] a Money value for strings, otherwise delegates to super
+    def cast(value) = value.is_a?(String) ? Money.parse(value, MoneyAttribute.default_currency) : super
 
+    # Validates that the value is compatible with the fixed currency type.
+    #
+    # @param value [Object] the value to validate
+    # @return [void]
+    # @raise [ArgumentError] when the value has a mismatched currency or is an unsupported type
     def assert_valid_value(value)
       case value
       when NilClass, Numeric, String then return
       when Mint::Money
-        return if value.currency == @currency
+        currency = MoneyAttribute.default_currency
+        return if value.currency == currency
 
-        message = "'#{value.inspect}' has different currency. Only #{@currency.code} allowed."
+        message = "'#{value.inspect}' has different currency. Only #{currency.code} allowed."
       else
         message = "'#{value.inspect}' is not a valid type for the attribute."
       end
       raise ArgumentError, message
     end
+  end
 
-    def deserialize(value)
-      return nil unless value
+  # Type for integer columns storing subunits (e.g. cents).
+  class IntegerAmountType < AmountType
+    # Deserializes a subunit integer into a +Mint::Money+ value.
+    #
+    # @param value [Integer, nil] the raw database value
+    # @return [Mint::Money, nil]
+    def deserialize(value) = value && Money.from_subunits(value.to_i, MoneyAttribute.default_currency)
 
-      if @column_type.is_a?(ActiveRecord::Type::Integer)
-        Mint::Money.from_subunits(value, @currency)
-      else
-        Mint::Money.from(value, @currency)
-      end
-    end
+    # Serializes a +Mint::Money+ value into subunits.
+    #
+    # @param value [Mint::Money, nil]
+    # @return [Integer, nil]
+    def serialize(value) = value&.subunits
+  end
 
-    def serialize(value)
-      return nil unless value
+  # Type for decimal columns storing unit values (e.g. 12.34).
+  class DecimalAmountType < AmountType
+    # Deserializes a decimal value into a +Mint::Money+ value.
+    #
+    # @param value [BigDecimal, nil] the raw database value
+    # @return [Mint::Money, nil]
+    def deserialize(value) = value && Money.from(value, MoneyAttribute.default_currency)
 
-      if @column_type.is_a?(ActiveRecord::Type::Integer)
-        value.subunits
-      else
-        value.to_d
-      end
-    end
-
-    def self.type = :mint_money
+    # Serializes a +Mint::Money+ value into a decimal.
+    #
+    # @param value [Mint::Money, nil]
+    # @return [BigDecimal, nil]
+    def serialize(value) = value&.to_d
   end
 end
 
 ActiveSupport.on_load(:active_record) do
   include MoneyAttribute::Macro
-
-  ActiveRecord::Type.register(:mint_money, MoneyAttribute::Type)
+  include MoneyAttribute::MoneyAmount
 end

data/lib/money_attribute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  VERSION = '0.14.5'
+  VERSION = '1.2.0'
 end

data/lib/money_attribute.rb

@@ -1,11 +1,27 @@
 # frozen_string_literal: true
 
+# MoneyAttribute provides ActiveRecord integrations for the Minting money gem.
+#
+# Two storage modes:
+#
+# - +money_attribute :price+ — composite (amount + currency columns)
+# - +money_amount :price+    — single column (fixed currency)
+#
+# @see MoneyAttribute::Macro
+# @see MoneyAttribute::MoneyAmount
+
 require 'minting'
-require 'money_attribute/core_ext'
+require 'money_attribute/core_ext/numeric'
+require 'money_attribute/core_ext/string'
 require 'money_attribute/configuration'
+require 'money_attribute/current'
+require 'money_attribute/attribute_spec'
+require 'money_attribute/attribute_spec_registry'
 require 'money_attribute/macro'
+require 'money_attribute/money_amount'
 require 'money_attribute/converter'
 require 'money_attribute/type'
 require 'money_attribute/form_builder_extension'
+require 'money_attribute/query'
 require 'money_attribute/railtie'
 require 'money_attribute/version'