money_attribute 1.2.0 → 1.2.1

data/lib/money_attribute/migration_extensions/helper.rb

@@ -2,7 +2,19 @@
 
 module MoneyAttribute
   module MigrationExtensions
-    # :nodoc:
+    # Shared argument-parsing logic for migration helpers.
+    #
+    # Resolves accessor names, column overrides, and amount type configuration
+    # into concrete column definitions. Included by both {SchemaStatements} and
+    # {TableDefinition}.
+    #
+    # @!attribute [rw] AMOUNT_CONFIG
+    #   @return [Hash{Symbol => Hash}] mapping of symbolic type names to
+    #     column type/hash pairs
+    # @!attribute [rw] CURRENCY_MIN_LIMIT
+    #   @return [Integer] minimum allowed currency column string limit (8)
+    # @!attribute [rw] CURRENCY_DEFAULT_LIMIT
+    #   @return [Integer] default currency column string limit (20)
     module Helper
       AMOUNT_CONFIG = {
         crypto_decimal: { type: :decimal, precision: 36, scale: 18 },
@@ -15,6 +27,19 @@ module MoneyAttribute
 
       private
 
+      # Parses arguments for a single-column (amount-only) migration.
+      #
+      # @param accessor [Symbol, String] the money attribute 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 [Array(String, Hash)] column name and merged options hash
+      # @raise [ArgumentError] if +precision:+ or +scale:+ are given, or
+      #   type is unrecognized
+      # @api private
       def parse_money_amount_args(accessor, options)
         options ||= {}
         if options.key?(:precision) || options.key?(:scale)
@@ -35,6 +60,17 @@ module MoneyAttribute
         [column, config.merge(options)]
       end
 
+      # Parses arguments for the currency column in a composite migration.
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param options [Hash] currency column options
+      # @option options [Symbol] :column explicit currency column name override
+      # @option options [Integer] :limit string limit for the column
+      # @option options [Boolean] :null whether the column allows NULL
+      # @option options [Object] :default default value for the column
+      # @return [Array(String, Hash)] column name and merged options hash
+      # @raise [ArgumentError] if limit is below {CURRENCY_MIN_LIMIT}
+      # @api private
       def parse_currency_args(accessor, options)
         options ||= {}
         limit = (options[:limit] || CURRENCY_DEFAULT_LIMIT).to_i
@@ -49,6 +85,18 @@ module MoneyAttribute
         [column, { limit:, null: options[:null], default: options[:default] }.compact]
       end
 
+      # Resolves the currency column name for the given accessor.
+      #
+      # Resolution order:
+      # 1. Explicit +column_override+ → returned as-is
+      # 2. Accessor is +:amount+ → +currency+
+      # 3. Accessor ends with +_amount+ → strips suffix and appends +_currency+
+      # 4. Otherwise → +<accessor>_currency+
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param column_override [Symbol, String, nil] explicit column name
+      # @return [String] the resolved currency column name
+      # @api private
       def currency_column_name(accessor, column_override)
         return column_override.to_s if column_override
 
@@ -59,6 +107,18 @@ module MoneyAttribute
         "#{radical}_currency"
       end
 
+      # Parses arguments for a composite (amount + currency) migration.
+      #
+      # Delegates to {#parse_money_amount_args} and {#parse_currency_args}
+      # using the nested +:amount+ and +:currency+ option keys.
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param options [Hash] migration options
+      # @option options [Hash] :amount amount column options
+      # @option options [Hash] :currency currency column options
+      # @return [Array(String, String, Hash, Hash)] amount column name,
+      #   currency column name, amount options, currency options
+      # @api private
       def parse_money_args(accessor, options = {})
         amount_column, amount_options = parse_money_amount_args(accessor, options[:amount])
         currency_column, currency_options = parse_currency_args(accessor, options[:currency])

data/lib/money_attribute/migration_extensions/schema_statements.rb

@@ -4,32 +4,112 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
-    # :nodoc:
+    # Migration helper methods for +ActiveRecord::Migration+.
+    #
+    # Provides reversible methods to add and remove money attribute columns
+    # from within a +change+ migration block.
+    #
+    # @example Adding a composite money attribute
+    #   class AddPriceToProducts < ActiveRecord::Migration[8.0]
+    #     def change
+    #       add_money_attribute :products, :price
+    #     end
+    #   end
+    #
+    # @example Adding a single-column money amount
+    #   class AddDiscountToProducts < ActiveRecord::Migration[8.0]
+    #     def change
+    #       add_money_amount :products, :discount, type: :fiat_integer
+    #     end
+    #   end
     module SchemaStatements
       include Helper
 
+      # Adds an amount column and a currency column for a composite money attribute.
+      #
+      # The amount column type is determined by the +:type+ option inside
+      # +amount: { type: }+ (defaults to +:fiat_decimal+). The currency column
+      # is a string with a configurable limit.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @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 Default naming and type
+      #   add_money_attribute :products, :price
+      #   # => add_column :products, :price, :decimal, precision: 20, scale: 4
+      #   # => add_column :products, :price_currency, :string, limit: 20
+      #
+      # @example Custom columns and integer type
+      #   add_money_attribute :products, :price,
+      #     amount: { column: :base_price, type: :fiat_integer },
+      #     currency: { column: :base_currency, limit: 3 }
       def add_money_attribute(table_name, 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)
 
         type = amount_opts.delete(:type)
-        add_column(table_name, amount_col, type, **amount_opts)
-        add_column(table_name, currency_col, :string, **currency_opts)
+        add_column(table_name, amount_column, type, **amount_opts)
+        add_column(table_name, currency_column, :string, **currency_opts)
       end
 
+      # Removes the amount and currency columns for a composite money attribute.
+      #
+      # Accepts the same +:amount+ and +:currency+ options as
+      # {#add_money_attribute} to identify the columns.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @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(table_name, accessor, options = {})
-        amount_col, currency_col, = parse_money_args(accessor, options)
+        amount_column, currency_column, = parse_money_args(accessor, options)
 
-        remove_column(table_name, amount_col)
-        remove_column(table_name, currency_col)
+        remove_column(table_name, amount_column)
+        remove_column(table_name, currency_column)
       end
 
+      # Adds a single amount column for a fixed-currency money attribute.
+      #
+      # No currency column is created — the application default currency is
+      # used for all rows.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @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 Default naming and type
+      #   add_money_amount :products, :discount
+      #   # => add_column :products, :discount, :decimal, precision: 20, scale: 4
+      #
+      # @example Integer column with explicit name
+      #   add_money_amount :products, :bonus, column: :bonus_cents, type: :fiat_integer
       def add_money_amount(table_name, accessor, options = {})
-        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+        amount_column, amount_opts = parse_money_amount_args(accessor, options)
 
         type = amount_opts.delete(:type)
-        add_column(table_name, amount_col, type, **amount_opts)
+        add_column(table_name, amount_column, type, **amount_opts)
       end
 
+      # Removes the amount column for a fixed-currency money attribute.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @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(table_name, accessor, options = {})
         remove_column(table_name, (options[:column] || accessor).to_s)
       end

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,12 +1,38 @@
 # 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)
         column = column_for_attribute(name)
 
@@ -16,6 +42,8 @@ module MoneyAttribute
                 "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
@@ -26,7 +54,7 @@ module MoneyAttribute
 
         attribute(name, type_class.new)
         normalizes(name, with: Converter.default)
-        register_money_attribute_spec(name, kind: :single, amount_col: name, amount_type: amount_type)
+        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

@@ -1,24 +1,62 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # 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_col]
+      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
@@ -39,10 +77,131 @@ module MoneyAttribute
     # 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

@@ -1,21 +1,27 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # 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_col => :asc, spec.amount_col => direction)
+        order(spec.currency_column => :asc, spec.amount_column => direction)
       else
-        order(spec.amount_col => direction)
+        order(spec.amount_column => direction)
       end
     end
   end

data/lib/money_attribute/query/currency_condition.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # 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)
 
@@ -17,7 +23,7 @@ module MoneyAttribute
       end
 
       code = currency.is_a?(Mint::Currency) ? currency.code : currency.to_s
-      where(spec.currency_col => code)
+      where(spec.currency_column => code)
     end
   end
 end