money_attribute 1.2.0 → 1.3.0

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,75 @@
 # 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
+    QueryPlan = Struct.new(:sql, :value_specs, keyword_init: true)
+
     # 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)
+      plan = klass.money_attribute_query_plan_cache.fetch_or_store(sql) do
+        compile_query_plan(sql)
+      end
+      decomposed = decompose_values(values, plan.value_specs)
+
+      where(plan.sql, *decomposed)
+    end
+
     private
 
+    # Compiles a string query into substituted SQL and bind metadata.
+    #
+    # @param sql [String] the SQL fragment
+    # @return [QueryPlan] the compiled query plan
+    # @api private
+    def compile_query_plan(sql)
+      specs = klass.money_attribute_specs
+      value_specs = parse_sql_value_specs(sql, specs)
+
+      QueryPlan.new(
+        sql: substitute_attribute_names(sql, specs),
+        value_specs: value_specs.freeze
+      ).freeze
+    end
+
     # 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 +90,96 @@ 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 identifiers and associates placeholders with the nearest
+    # preceding money attribute in one left-to-right pass.
+    #
+    # @param sql [String] the SQL fragment
+    # @param specs [Hash{String => AttributeSpec}] the money attribute specs
+    # @return [Array<AttributeSpec>] one spec per bind value
+    # @raise [ArgumentError] on an unknown identifier or unassociated placeholder
+    # @api private
+    def parse_sql_value_specs(sql, specs)
+      current_spec = nil
+      value_specs = []
+
+      sql.scan(/[a-z_]\w*|\?/i) do |token|
+        if token == '?'
+          raise ArgumentError, "No money attribute found before '?' in: #{sql.inspect}" unless current_spec
+
+          value_specs << current_spec
+          next
+        end
+
+        word = token.downcase
+        next if ALLOWED_KEYWORDS.include?(word)
+
+        current_spec = specs[word]
+        raise ArgumentError, "'#{token}' is not a money attribute on #{klass.name}" unless current_spec
+      end
+
+      value_specs
+    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

data/lib/money_attribute/query/helpers.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # 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
@@ -15,16 +18,36 @@ module MoneyAttribute
       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
-    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]
+    # @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

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # 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?
 
@@ -17,22 +20,22 @@ module MoneyAttribute
       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
+      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
-      return raw if spec.single?
 
-      spec.build_money(raw[0], raw[1])
+      spec.single? ? raw : spec.build_money(raw[0], raw[1])
     end
   end
 end

data/lib/money_attribute/query/pluck.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Internal pluck resolution for the +pluck_amount+ query helper.
+  #
+  # @api private
   module PluckAmount
     # Plucks money-aware amounts for one or more attributes.
     #
@@ -9,6 +11,7 @@ module MoneyAttribute
     # @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?
 
@@ -22,22 +25,15 @@ module MoneyAttribute
     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_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
+      return pluck(spec.amount_column) if spec.single?
 
-      specs.map do |spec|
-        value, cursor = extract_pick_value(row, spec, cursor)
-        value
-      end
+      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

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # 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?
 
@@ -22,8 +25,13 @@ module MoneyAttribute
     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_col).sum(spec.amount_col)
+      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) }
@@ -31,8 +39,12 @@ module MoneyAttribute
     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_col)
+      total = sum(spec.amount_column)
 
       [spec.build_money(total, MoneyAttribute.default_currency)]
     end

data/lib/money_attribute/query.rb

@@ -35,18 +35,21 @@ module MoneyAttribute
 
       # Filters by amount for one or more money attributes.
       #
-      # Accepts +Mint::Money+ objects, numeric values (decimal columns), Ranges, or Arrays.
+      # Accepts a hash of conditions or a SQL string with +?+ placeholders.
+      # Hash: +{ attr: value }+, supports +Mint::Money+, +Range+, +Array+.
+      # SQL: only money attribute names, +and+, +or+, +not+, +is+, +null+.
       #
-      #   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
+      # @param args [Array] a condition hash, or a SQL string with bind values
       # @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
+      # @raise [ArgumentError] if an identifier is not a registered money attribute
+      def where_amount(*args)
+        if args.first.is_a?(Hash)
+          scope = all
+          args.first.each { |attr, value| scope = scope.resolve_amount_condition(attr, value) }
+          scope
+        else
+          all.resolve_amount_condition_from_sql(*args)
+        end
       end
 
       # Orders by amount for one or more money attributes.
@@ -101,7 +104,9 @@ module MoneyAttribute
     end
   end
 
-  # :nodoc:
+  # Internal mixin combining all query sub-modules onto relations.
+  #
+  # @api private
   module QueryMethods
     include QueryHelpers
     include CurrencyCondition