money_attribute 1.1.0 → 1.2.1

data/lib/money_attribute/migration_extensions/table_definition.rb

@@ -4,34 +4,91 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
-    # :nodoc:
+    # Migration DSL methods for use inside +create_table+ and +change_table+
+    # blocks.
+    #
+    # Included into both +ActiveRecord::ConnectionAdapters::TableDefinition+
+    # and +ActiveRecord::ConnectionAdapters::Table+.
+    #
+    # @example Inside a +create_table+ block
+    #   create_table :products do |t|
+    #     t.string :name
+    #     t.money_attribute :price
+    #     t.money_amount :discount, type: :fiat_integer
+    #   end
+    #
+    # @example Inside a +change_table+ block
+    #   change_table :products do |t|
+    #     t.money_attribute :price, amount: { type: :fiat_integer }
+    #     t.remove_money_attribute :old_price
+    #   end
     module TableDefinition
       include Helper
 
+      # Adds amount and currency columns within a table definition.
+      #
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] migration options
+      # @option options [Hash] :amount amount column options
+      #   (+:column+, +:type+, +:null+, +:default+)
+      # @option options [Hash] :currency currency column options
+      #   (+:column+, +:limit+, +:null+, +:default+)
+      # @return [void]
+      #
+      # @example
+      #   t.money_attribute :price
+      #   t.money_attribute :price, amount: { type: :fiat_integer }
       def money_attribute(accessor, options = {})
-        amount_col, currency_col, amount_opts, currency_opts = parse_money_args(accessor, options)
+        amount_column, currency_column, amount_opts, currency_opts = parse_money_args(accessor, options)
 
-        column(amount_col, amount_opts[:type], **amount_opts.except(:type))
-        column(currency_col, :string, **currency_opts)
+        column(amount_column, amount_opts[:type], **amount_opts.except(:type))
+        column(currency_column, :string, **currency_opts)
       end
 
+      # Removes amount and currency columns within a table definition.
+      #
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] migration options
+      # @option options [Hash] :amount amount column options (+:column+)
+      # @option options [Hash] :currency currency column options (+:column+)
+      # @return [void]
       def remove_money_attribute(accessor, options = {})
-        amount_col, currency_col, = parse_money_args(accessor, options)
+        amount_column, currency_column, = parse_money_args(accessor, options)
 
-        remove_column(amount_col)
-        remove_column(currency_col)
+        remove_column(amount_column)
+        remove_column(currency_column)
       end
 
+      # Adds a single amount column within a table definition.
+      #
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] column options
+      # @option options [Symbol] :column explicit column name override
+      # @option options [Symbol] :type amount type (+:fiat_decimal+,
+      #   +:crypto_decimal+, +:fiat_integer+)
+      # @option options [Boolean] :null whether the column allows NULL
+      # @option options [Object] :default default value for the column
+      # @return [void]
+      #
+      # @example
+      #   t.money_amount :discount
+      #   t.money_amount :bonus, column: :bonus_cents, type: :fiat_integer
       def money_amount(accessor, options = {})
-        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+        amount_column, amount_opts = parse_money_amount_args(accessor, options)
 
-        column(amount_col, amount_opts[:type], **amount_opts.except(:type))
+        column(amount_column, amount_opts[:type], **amount_opts.except(:type))
       end
 
+      # Removes a single amount column within a table definition.
+      #
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] column options
+      # @option options [Symbol] :column explicit column name override
+      # @return [void]
       def remove_money_amount(accessor, options = {})
-        amount_col, = parse_money_amount_args(accessor, options)
+        amount_column, = parse_money_amount_args(accessor, options)
 
-        remove_column(amount_col)
+        remove_column(amount_column)
       end
     end
   end

data/lib/money_attribute/money_amount.rb

@@ -1,36 +1,60 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Declares fixed-currency money attributes on Active Record models.
+  #
+  # Provides the +money_amount+ class method which wires a single backing
+  # column to a +Mint::Money+ value object using a custom attribute type and a
+  # normalizer. The application default currency (or {Current} per-request
+  # override) applies to all rows.
+  #
+  # @example
+  #   class SimpleOffer < ApplicationRecord
+  #     money_amount :price
+  #   end
   module MoneyAmount
     extend ActiveSupport::Concern
 
     class_methods do
+      include ColumnTypeValidations
+
+      # Declares a fixed-currency money attribute backed by a single column.
+      #
+      # The column type determines the storage unit: integer/bigint stores
+      # subunits, decimal stores the unit value. No currency column is created —
+      # the application default currency applies to every row.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @return [void]
+      # @raise [ArgumentError] if the column does not exist or has an
+      #   unsupported type
+      #
+      # @example
+      #   class SimpleOffer < ApplicationRecord
+      #     money_amount :price
+      #   end
       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
+
+        assert_valid_amount_column!(name, name, column)
+
+        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_column: name, amount_type: amount_type)
       end
     end
   end

data/lib/money_attribute/query/amount_condition.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal amount-filter resolution for the +where_amount+ query helper.
+  #
+  # Supports two input forms: a hash of attribute/value pairs resolved to Arel
+  # predicates, and a SQL string with +?+ placeholders where attribute names
+  # are substituted for backing columns and +Mint::Money+ binds are decomposed.
+  #
+  # @api private
+  module AmountCondition
+    ALLOWED_KEYWORDS = %w[and or not is null].to_set.freeze
+
+    # 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
+    # @api private
+    def resolve_amount_condition(attr, value)
+      spec = money_attribute_spec!(attr)
+      col = arel_table[spec.amount_column]
+
+      where(build_amount_predicate(col, spec, value))
+    end
+
+    # Builds an amount filter using a SQL string with +?+ placeholders.
+    #
+    # Only money attribute names, +and+, +or+, +not+, +is+, and +null+ are
+    # allowed as identifiers.  +Mint::Money+ bind values are decomposed to
+    # raw storage values automatically.
+    #
+    # @param sql [String] SQL fragment using attribute names and +?+ placeholders
+    # @param values [Array] bind values
+    # @return [ActiveRecord::Relation]
+    # @raise [ArgumentError] on unknown identifiers or placeholder mismatch
+    # @api private
+    def resolve_amount_condition_from_sql(sql, *values)
+      specs = klass.money_attribute_specs
+      attr_names = klass.money_attribute_names_set
+
+      validate_sql_identifiers!(sql, attr_names)
+      value_specs = map_placeholders_to_specs(sql, specs)
+      decomposed = decompose_values(values, value_specs)
+      substituted = substitute_attribute_names(sql, specs)
+
+      where(substituted, *decomposed)
+    end
+
+    private
+
+    # Builds an Arel predicate for the given amount value.
+    #
+    # @param col [Arel::Attributes::Attribute] the amount column node
+    # @param spec [AttributeSpec] the money attribute spec
+    # @param value [Mint::Money, Numeric, Range, Array] the filter value
+    # @return [Arel::Nodes::Node] the predicate
+    # @api private
+    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.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @param value [Object] the value to normalize
+    # @return [Object] the normalized value
+    # @api private
+    def normalize_amount_value(spec, value)
+      return value unless spec.composite?
+
+      spec.normalize_query_value(value)
+    end
+
+    # Validates that every word in the SQL is a registered attribute name or an
+    # allowed keyword.
+    #
+    # @param sql [String] the SQL fragment
+    # @param attr_names [Set<String>] registered money attribute names
+    # @return [void]
+    # @raise [ArgumentError] on the first unknown identifier
+    # @api private
+    def validate_sql_identifiers!(sql, attr_names)
+      sql.scan(/\b[a-z_]\w*\b/i).each do |word|
+        next if attr_names.include?(word.downcase) || ALLOWED_KEYWORDS.include?(word.downcase)
+
+        raise ArgumentError, "'#{word}' is not a money attribute on #{klass.name}"
+      end
+    end
+
+    # Matches each +?+ placeholder to the nearest preceding money attribute name
+    # and returns the corresponding spec.
+    #
+    # @param sql [String] the SQL fragment
+    # @param specs [Hash{String => AttributeSpec}] the money attribute specs
+    # @return [Array<AttributeSpec>] one spec per +?+ placeholder
+    # @raise [ArgumentError] if a placeholder has no preceding attribute name
+    # @api private
+    def map_placeholders_to_specs(sql, specs)
+      ref_pattern = klass.money_attribute_name_pattern
+
+      placeholder_positions(sql).map { |pos| spec_at_position(sql, pos, ref_pattern, specs) }
+    end
+
+    # Returns character positions of each +?+ in the SQL.
+    #
+    # @param sql [String] the SQL fragment
+    # @return [Array<Integer>] the positions of each +?+
+    # @api private
+    def placeholder_positions(sql)
+      positions = []
+      offset = 0
+
+      while (idx = sql.index('?', offset))
+        positions << idx
+        offset = idx + 1
+      end
+
+      positions
+    end
+
+    # Returns the spec for the +?+ at the given position.
+    #
+    # @param sql [String] the SQL fragment
+    # @param pos [Integer] position of the +?+
+    # @param ref_pattern [Regexp] pre-compiled attribute name pattern
+    # @param specs [Hash{String => AttributeSpec}] the money attribute specs
+    # @return [AttributeSpec] the spec for the nearest preceding attribute name
+    # @raise [ArgumentError] if no attribute name precedes the placeholder
+    # @api private
+    def spec_at_position(sql, pos, ref_pattern, specs)
+      preceding = sql[0...pos]
+      matched = preceding.scan(ref_pattern).flatten.compact
+
+      raise ArgumentError, "No money attribute found before '?' in: #{sql.inspect}" if matched.empty?
+
+      specs[matched.last.downcase]
+    end
+
+    # Decomposes +Mint::Money+ bind values to raw storage values using their
+    # positional specs.  Unlike +normalize_query_value+ (which relies on the
+    # custom type for single-column attributes), this always decomposes since
+    # raw SQL bind parameters don't resolve custom types.
+    #
+    # @param values [Array] the bind values
+    # @param value_specs [Array<AttributeSpec>] one spec per bind value
+    # @return [Array] decomposed bind values
+    # @raise [ArgumentError] if the number of values and specs differs
+    # @api private
+    def decompose_values(values, value_specs)
+      if values.size != value_specs.size
+        raise ArgumentError, "Expected #{value_specs.size} bind value(s), got #{values.size}"
+      end
+
+      values.zip(value_specs).map do |val, spec|
+        if val.is_a?(Mint::Money)
+          spec.integer_amount? ? val.subunits : val.to_d
+        else
+          val
+        end
+      end
+    end
+
+    # Replaces attribute names with their backing amount column names in the SQL.
+    #
+    # Only attributes whose name differs from their amount column are
+    # substituted; the rest are already valid column references.
+    #
+    # @param sql [String] the SQL fragment
+    # @param specs [Hash{String => AttributeSpec}] the money attribute specs
+    # @return [String] the SQL with attribute names replaced by column names
+    # @api private
+    def substitute_attribute_names(sql, specs)
+      to_sub = specs_to_substitute(specs)
+      return sql if to_sub.empty?
+
+      lookup = to_sub.to_h { |s| [s.name.downcase, s.amount_column] }
+      pattern = /\b(#{to_sub.map { |s| Regexp.escape(s.name) }.join('|')})\b/i
+      sql.gsub(pattern) { |match| lookup[match.downcase] }
+    end
+
+    # Returns the specs whose attribute name differs from their amount column.
+    #
+    # @param specs [Hash{String => AttributeSpec}] the money attribute specs
+    # @return [Array<AttributeSpec>] specs needing SQL substitution
+    # @api private
+    def specs_to_substitute(specs)
+      specs.values.reject { |s| s.name == s.amount_column }
+    end
+  end
+end

data/lib/money_attribute/query/amount_order.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal ordering resolution for the +order_by_amount+ query helper.
+  #
+  # @api private
+  module AmountOrder
+    # Builds an amount ordering for the registered money attribute.
+    #
+    # Composite attributes order by currency ASC first, then amount in the
+    # requested direction. Single-column attributes order by amount only.
+    #
+    # @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
+    # @api private
+    def resolve_amount_order(attr, direction)
+      spec = money_attribute_spec!(attr)
+
+      if spec.composite?
+        order(spec.currency_column => :asc, spec.amount_column => direction)
+      else
+        order(spec.amount_column => direction)
+      end
+    end
+  end
+end

data/lib/money_attribute/query/currency_condition.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal currency-filter resolution for the +where_currency+ query helper.
+  #
+  # @api private
+  module CurrencyCondition
+    # Builds a currency filter for the registered money attribute.
+    #
+    # Only composite attributes have a currency column, so single-column
+    # attributes raise.
+    #
+    # @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
+    # @api private
+    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_column => code)
+    end
+  end
+end

data/lib/money_attribute/query/helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal helpers shared by the query sub-modules.
+  #
+  # @api private
+  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
+    # @api private
+    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 money values for all specs from a single result row.
+    #
+    # @param row [Array] the flat row from +pluck+ or +pick+
+    # @param specs [Array<AttributeSpec>] the money attribute specs
+    # @return [Array] the extracted money values
+    # @api private
+    def extract_money_row(row, specs)
+      cursor = 0
+
+      specs.map do |spec|
+        value, cursor = extract_attribute_value(row, spec, cursor)
+        value
+      end
+    end
+
+    private
+
+    # 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
+    # @api private
+    def extract_attribute_value(row, spec, cursor)
+      if spec.single?
+        [row[cursor], cursor + 1]
+      else
+        [spec.build_money(row[cursor], row[cursor + 1]), cursor + 2]
+      end
+    end
+  end
+end

data/lib/money_attribute/query/pick.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal pick resolution for the +pick_amount+ query helper.
+  #
+  # @api private
+  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
+    # @api private
+    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
+
+      extract_money_row(raw, specs)
+    end
+
+    private
+
+    # Picks a single money-aware attribute and returns a single value.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Mint::Money, Object, nil] the composed Money, the raw value for
+    #   single-column attributes, or nil when the relation is empty
+    # @api private
+    def pick_single_amount(spec)
+      raw = pick(*spec.columns)
+      return unless raw
+
+      spec.single? ? raw : spec.build_money(raw[0], raw[1])
+    end
+  end
+end

data/lib/money_attribute/query/pluck.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal pluck resolution for the +pluck_amount+ query helper.
+  #
+  # @api private
+  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
+    # @api private
+    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.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Array] raw values for single-column attributes, composed
+    #   +Mint::Money+ values for composite attributes
+    # @api private
+    def pluck_single_amount(spec)
+      return pluck(spec.amount_column) if spec.single?
+
+      pluck(spec.amount_column, spec.currency_column).map { |amount, currency| spec.build_money(amount, currency) }
+    end
+  end
+end

data/lib/money_attribute/query/sum.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Internal sum resolution for the +sum_amount+ query helper.
+  #
+  # @api private
+  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
+    # @api private
+    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.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Array<Mint::Money>] one +Mint::Money+ per currency, sorted by
+    #   currency code, or a single zero-value Money when no rows match
+    # @api private
+    def resolve_composite_sum(spec)
+      totals = group(spec.currency_column).sum(spec.amount_column)
+      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.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Array<Mint::Money>] a single +Mint::Money+ in the default currency
+    # @api private
+    def resolve_single_sum(spec)
+      total = sum(spec.amount_column)
+
+      [spec.build_money(total, MoneyAttribute.default_currency)]
+    end
+  end
+end