money_attribute 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb71d942a1dd57ae30fa3d1d8941efacf402d9346192b99cca4d0eabf69246fb
-  data.tar.gz: 70dbb86d5d328e5d42fd09593358445d931261b59212d49f3a8e6a450d275c09
+  metadata.gz: a26cda78a2361b592ca6f90c1afb5f8637792b432038d45b543aa562624d6349
+  data.tar.gz: 0e9d78eaf7c8118942676f81f4dbebe55614663469d0d8f3095622fc0def3dca
 SHA512:
-  metadata.gz: 93e1d50ccda57e7a535fba457e4551525923358b45ef629b381bb04c900eb1fc7b76c1aa11d18410a0669fb96f610a53df1e76e10dcc58860e1d0cd8e3dd19f6
-  data.tar.gz: 55d8b84306bf8988e066d426e525af1d6bfb2b0f202727a9a3a38aa5a52f9461d57edac0d5c003f5996141a5e662439d661109ba6aab975fd420b882ea754a29
+  metadata.gz: 4ba8368b5c3c11be2375368399113b1526b1e2d9f347b2e5d16499a64577dffb5b846a876ba4d04967e8ac8a76fccc717aafb8caaefd25c83bb7dc61ce22839e
+  data.tar.gz: 52dd36ef69c80695f8e22802e5486332d94d5afcc4e48cf671847705b3120de5ecfb636b191fe629077d8f6ebb35a2dcbd5b6a716f031bdb918a35abe32d23fa

data/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/gferraz/money-attribute/actions/workflows/ci.yml/badge.svg)](https://github.com/gferraz/money-attribute/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/money_attribute.svg)](https://badge.fury.io/rb/money_attribute)
 
-Store and read Active Record attributes as `Mint::Money` objects with no manual serialization.
+Store and read Active Record attributes as `Money` objects with no manual serialization.
 
 `money_attribute` uses two DB columns (amount + currency) for per-row multi-currency data. A simpler `money_amount` variant is also available for fixed-currency models (see [note](#single-column-mode-money_amount-fixed-currency)).
 
@@ -32,8 +32,7 @@ p.price * 2 # => [USD 24.88]
 - [Convenience methods](#convenience-methods)
 - [Form helpers](#form-helpers)
 - [Roadmap](#roadmap)
-- [Development & Contributing](#development)
-- [License](#license)
+- [Development](#development)
 
 ## Quick start
 
@@ -62,13 +61,13 @@ class Product < ApplicationRecord
 end
 ```
 
-That's it. `Product.new(price: 12.dollars).price` is a `Mint::Money`.
+That's it. `Product.new(price: 12.dollars).price` is a `Money`.
 
 ## Why MoneyAttribute?
 
-- **No serialization boilerplate** — declare once, read/write `Mint::Money` everywhere.
+- **No serialization boilerplate** — declare once, read/write `Money` everywhere.
 - **Integer or decimal columns** — auto-detects the column type and adjusts serialization (e.g. integer stores cents, decimal stores unit value).
-- **Normalizes everything** — pass a number, string, or `Mint::Money`; always get a `Mint::Money` back.
+- **Normalizes everything** — pass a number, string, or `Money`; always get a `Money` back.
 - **Currency enforcement** — fixed-currency attributes reject wrong currencies at assignment time.
 - **Built on Rails primitives** — uses `ActiveRecord::Type`, `composed_of`, and `normalizes` under the hood. No monkey-patching of core classes.
 
@@ -93,7 +92,7 @@ For a detailed side-by-side comparison, see [COMPARISON.md](COMPARISON.md).
 
 - Ruby 3.3+
 - Rails 7.1.3.2+
-- [Minting](https://github.com/gferraz/minting) 2.0+
+- [Minting](https://github.com/gferraz/minting) 2.1+
 
 ## Installation
 
@@ -197,7 +196,7 @@ I18n.locale = :'pt-BR'
 Money.from(1234.56, 'USD').to_s  # => "$1.234,56"
 ```
 
-The locale backend reads `number.currency.format` from your I18n translations and maps Rails format syntax (`%n` for amount, `%u` for unit) to `Mint::Money#to_s`. If the translation key is missing (no locale file for that language), it falls back to hardcoded defaults (`.` decimal, `,` thousand, `%<symbol>s%<amount>f` format).
+The locale backend reads `number.currency.format` from your I18n translations and maps Rails format syntax (`%n` for amount, `%u` for unit) to `Money#to_s`. If the translation key is missing (no locale file for that language), it falls back to hardcoded defaults (`.` decimal, `,` thousand, `%<symbol>s%<amount>f` format).
 
 You can configure per-sign formatting by adding `positive`, `negative`, and `zero` keys to your locale:
 
@@ -304,16 +303,24 @@ end
 
 ## Column resolution
 
-`money_attribute :name` is always composite. It resolves columns in this order:
+`money_attribute :name` is always composite. Columns are resolved in two phases:
 
-| Step | Condition | Columns used |
-|---|---|---|
-| 1 | `mapping:` provided | As specified (missing keys fall back to `<name>_amount` / `<name>_currency`) |
-| 2 | `name_currency` column exists AND `name` column exists | `name` + `name_currency` |
-| 3 | `name == 'amount'` AND `currency` column exists | `amount` + `currency` |
-| 4 | None of the above | `<name>_amount` + `<name>_currency` (convention) |
+**Phase 1 — Default mapping** is determined by which columns exist:
+
+| Condition | Default columns |
+|---|---|
+| `name_currency` exists AND `name` exists | `name` + `name_currency` |
+| `name == 'amount'` AND `currency` exists | `amount` + `currency` |
+| Otherwise | `<name>_amount` + `<name>_currency` |
 
-Step 4 raises `ArgumentError` if the convention columns don't exist. For single-column fixed-currency attributes, see [`money_amount`](#single-column-mode-money_amount-fixed-currency).
+**Phase 2 — Override** via `mapping:` is merged on top of the default. Missing keys inherit from the default mapping:
+
+```ruby
+money_attribute :total, mapping: { amount: :total_amount }
+# currency falls back to default => :total_currency
+```
+
+Raises `ArgumentError` if the resolved columns don't exist. For single-column fixed-currency attributes, see [`money_amount`](#single-column-mode-money_amount-fixed-currency).
 
 **Example**
 
@@ -392,7 +399,7 @@ Offer.create!(price: 50.dollars)
 Offer.where_amount(price: 10..50)           # => both records
 ```
 
-For integer (subunit) columns, pass `Mint::Money` objects directly — subunit conversion is handled automatically:
+For integer (subunit) columns, pass `Money` objects directly — subunit conversion is handled automatically:
 
 ```ruby
 FinancialTransaction.where_amount(amount: [10.dollars, 10.yens])
@@ -456,7 +463,7 @@ SimpleOffer.sum_amount(:price)
 # => [BRL 60.00]  (single-column always returns one Money)
 
 Offer.none.sum_amount(:price)
-# => [Mint::Money(0, 'BRL')]  (empty result returns zero Money)
+# => [BRL 0.00]  (empty result returns zero Money)
 ```
 
 ### Notes
@@ -491,7 +498,7 @@ MoneyAttribute adds `money_field` and `money_amount_field` to Rails form builder
 
 ### Single-column mode — `money_amount` (fixed-currency)
 
-`money_amount` wraps a numeric column as `Mint::Money` using the application's default currency. No per-row currency. A lighter alternative when you don't need multi-currency support.
+`money_amount` wraps a numeric column as `Money` using the application's default currency. No per-row currency. A lighter alternative when you don't need multi-currency support.
 
 The accessor name must match the column name. `money_amount` does not support custom column mapping.
 
@@ -505,9 +512,9 @@ The accessor name must match the column name. `money_amount` does not support cu
 Default column: `decimal(20,4)`. The top-level `type:` shortcut selects the column type:
 
 ```ruby
-t.money_amount :price                       # decimal(20,4)
+t.money_amount :price                               # decimal(20,4)
 t.money_amount :btc_balance, type: :crypto_decimal  # decimal(36,18)
-t.money_amount :qty,        type: :fiat_integer     # bigint
+t.money_amount :qty,         type: :fiat_integer    # bigint
 ```
 
 #### Naming
@@ -564,8 +571,4 @@ The dummy Rails app under `test/dummy` exercises the engine in a full Rails envi
 
 ## Contributing
 
-Bug reports and pull requests welcome at [gferraz/money-attribute](https://github.com/gferraz/money-attribute).
-
-## License
-
-[MIT](MIT-LICENSE)
+Bug reports welcome at [gferraz/money-attribute](https://github.com/gferraz/money-attribute).

data/Rakefile

@@ -15,7 +15,7 @@ Rake::TestTask.new(:test_run) do |t|
 end
 
 desc 'Migrate test database'
-task :test_db_migrate do # rubocop:disable Rails/RakeEnvironment
+task :test_db_migrate do
   sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate', chdir: 'test/dummy', %i[out err] => File::NULL)
 end
 
@@ -27,13 +27,13 @@ task test: %i[test_db_migrate test_run]
 %w[postgresql mysql2].each do |adapter|
   namespace :test do
     desc "Migrate test database (#{adapter})"
-    task "db_migrate:#{adapter}" do # rubocop:disable Rails/RakeEnvironment
+    task "db_migrate:#{adapter}" do
       sh({ 'RAILS_ENV' => 'test', 'DATABASE_ADAPTER' => adapter },
          'bin/rails', 'db:migrate', chdir: 'test/dummy', %i[out err] => File::NULL)
     end
 
     desc "Run tests against #{adapter}"
-    task adapter do # rubocop:disable Rails/RakeEnvironment
+    task adapter do
       Rake::Task[:"test:db_migrate:#{adapter}"].invoke
       sh({ 'DATABASE_ADAPTER' => adapter }, 'bundle', 'exec', 'rake', 'test_run')
     end
@@ -41,7 +41,7 @@ task test: %i[test_db_migrate test_run]
 end
 
 desc 'Run tests against all adapters (sqlite3, postgresql, mysql2)'
-task 'test:all' do # rubocop:disable Rails/RakeEnvironment
+task 'test:all' do
   Rake::Task[:test].invoke
   %w[postgresql mysql2].each do |adapter|
     Rake::Task[:"test:#{adapter}"].invoke
@@ -50,7 +50,7 @@ end
 
 # --- Benchmark ---
 
-desc 'Run money_attribute vs money-rails benchmark'
+desc 'Run money_attribute vs plain Rails vs money-rails benchmark'
 task bench: :test_db_migrate do
   puts
   puts '=' * 80
@@ -59,6 +59,13 @@ task bench: :test_db_migrate do
   sh({ 'RAILS_ENV' => 'test', 'BENCH_SIDE' => 'minting' },
      'bundle', 'exec', 'ruby', 'benchmark/comparison.rb')
 
+  puts
+  puts '=' * 80
+  puts 'plain Rails (raw columns, no monetization)'
+  puts '=' * 80
+  sh({ 'RAILS_ENV' => 'test', 'BENCH_SIDE' => 'plain' },
+     'bundle', 'exec', 'ruby', 'benchmark/comparison.rb')
+
   puts
   puts '=' * 80
   puts 'money-rails (money gem)'
@@ -69,6 +76,12 @@ task bench: :test_db_migrate do
 end
 
 desc 'Generate consolidated benchmark report (markdown)'
-task 'bench:report' do # rubocop:disable Rails/RakeEnvironment
+task 'bench:report' do
   ruby 'benchmark/report.rb'
 end
+
+desc 'Profile hot paths with stackprof (MODE=string_query|pluck|read_cached|multi_record|arithmetic|all)'
+task 'bench:profile' do
+  mode = ENV['MODE'] || 'all'
+  sh({ 'RAILS_ENV' => 'test' }, 'bundle', 'exec', 'ruby', 'benchmark/profile.rb', mode)
+end

data/lib/generators/money_attribute/initializer_generator.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # Generator namespace for money_attribute.
   module Generators
+    # Rails generator that installs the money_attribute initializer.
+    #
+    # @example
+    #   rails generate money_attribute:initializer
+    #
+    # @api private
     class InitializerGenerator < ::Rails::Generators::Base
       source_root File.expand_path('../templates', __dir__)
 
       desc 'Creates MoneyAttribute initializer.'
 
+      # Copies the initializer template into the application.
+      #
+      # @return [void]
       def copy_initializer
         copy_file 'money_attribute.rb', 'config/initializers/money_attribute.rb'
       end

data/lib/money_attribute/attribute_spec.rb

@@ -21,7 +21,9 @@ module MoneyAttribute
   #
   # Created by +money_attribute+ or +money_amount+ and stored in the class-level registry.
   # Used by query helpers to resolve column names, build Money values, and generate SQL.
-  AttributeSpec = Struct.new(:name, :kind, :amount_col, :currency_col, :amount_type, keyword_init: true) do
+  #
+  # @api private
+  AttributeSpec = Struct.new(:name, :kind, :amount_column, :currency_column, :amount_type, keyword_init: true) do
     # @return [Boolean] +true+ when the spec describes a two-column (amount + currency) attribute.
     def composite? = kind == :composite
 
@@ -32,7 +34,7 @@ module MoneyAttribute
     #
     # @return [Array<String>] two-element array for composite, one-element for single.
     def columns
-      @columns ||= (composite? ? [amount_col, currency_col] : [amount_col]).freeze
+      @columns ||= (composite? ? [amount_column, currency_column] : [amount_column]).freeze
     end
 
     # @return [Boolean] +true+ when the amount column stores subunits (bigint).
@@ -42,7 +44,9 @@ module MoneyAttribute
     def amount_extractor = integer_amount? ? :subunits : :to_d
 
     # @return [Hash{String => Symbol}] mapping suitable for +composed_of+.
-    def composed_of_mapping = { amount_col => amount_extractor, currency_col => :currency_code }
+    def composed_of_mapping
+      @composed_of_mapping ||= { amount_column => amount_extractor, currency_column => :currency_code }.freeze
+    end
 
     # @return [Proc] the constructor lambda used by +composed_of+ to instantiate Money values.
     def constructor
@@ -54,6 +58,7 @@ module MoneyAttribute
     # @param amount [Integer, BigDecimal, nil] the raw column value
     # @param currency [String, Mint::Currency, nil] the currency code or object
     # @return [Mint::Money, nil] the resolved money value, or nil when amount is nil
+    # @api private
     def build_money(amount, currency)
       return unless amount
       return amount if amount.is_a?(Mint::Money)
@@ -68,6 +73,7 @@ module MoneyAttribute
     #
     # @param value [Mint::Money, Numeric] the query value
     # @return [Integer, BigDecimal, Mint::Money] the normalized value
+    # @api private
     def normalize_query_value(value)
       return value unless integer_amount?
       return value.subunits if value.is_a?(Mint::Money)

data/lib/money_attribute/attribute_spec_registry.rb

@@ -4,26 +4,33 @@ require 'concurrent/map'
 
 module MoneyAttribute
   # Stores money attribute metadata on the model class.
+  #
+  # Holds a per-model registry of {AttributeSpec} objects plus derived caches
+  # (name set, regex patterns) populated lazily on first access.
+  #
+  # @api private
   module AttributeSpecRegistry
     extend ActiveSupport::Concern
 
     REGISTRY = Concurrent::Map.new
+    PATTERNS = Concurrent::Map.new
 
     class_methods do
       # Registers a money attribute spec for the current model class.
       #
       # @param name [Symbol, String] the attribute name
       # @param kind [Symbol] +:composite+ or +:single+
-      # @param amount_col [Symbol, String] the amount column name
-      # @param currency_col [Symbol, String, nil] the currency column name (composite only)
+      # @param amount_column [Symbol, String] the amount column name
+      # @param currency_column [Symbol, String, nil] the currency column name (composite only)
       # @param amount_type [Symbol, nil] +:integer+ or +:decimal+
       # @return [AttributeSpec]
-      def register_money_attribute_spec(name, kind:, amount_col:, currency_col: nil, amount_type: nil)
+      # @api private
+      def register_money_attribute_spec(name, kind:, amount_column:, currency_column: nil, amount_type: nil)
         spec = MoneyAttribute::AttributeSpec.new(
           name: name.to_s,
           kind: kind,
-          amount_col: amount_col.to_s,
-          currency_col: currency_col&.to_s,
+          amount_column: amount_column.to_s,
+          currency_column: currency_column&.to_s,
           amount_type: amount_type
         )
 
@@ -35,6 +42,7 @@ module MoneyAttribute
       #
       # @param name [Symbol, String] the attribute name
       # @return [AttributeSpec, nil]
+      # @api private
       def money_attribute_spec(name)
         REGISTRY[self]&.fetch(name.to_s, nil)
       end
@@ -42,9 +50,29 @@ module MoneyAttribute
       # Returns the registry hash for the current model class.
       #
       # @return [Hash{String => AttributeSpec}]
+      # @api private
       def money_attribute_specs
         REGISTRY.fetch_or_store(self) { {} }
       end
+
+      # Returns a frozen Set of registered money attribute names.
+      #
+      # @return [Set<String>]
+      # @api private
+      def money_attribute_names_set
+        PATTERNS.fetch_or_store(:"#{self}_name_set") { money_attribute_specs.keys.to_set.freeze }
+      end
+
+      # Returns a pre-compiled regex matching any registered money attribute name.
+      #
+      # @return [Regexp]
+      # @api private
+      def money_attribute_name_pattern
+        PATTERNS.fetch_or_store(:"#{self}_name_pattern") do
+          names = money_attribute_specs.keys.map { |n| Regexp.escape(n) }
+          /\b(#{names.join('|')})\b/i
+        end
+      end
     end
   end
 end

data/lib/money_attribute/column_type_validations.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Shared column-type validation for the +money_attribute+ and +money_amount+
+  # macros.
+  #
+  # Included by {Macro::CompositeClassMethods} and {MoneyAmount}. Raises when a
+  # backing column uses a type that cannot store a money amount or currency code.
+  #
+  # @api private
+  module ColumnTypeValidations
+    VALID_AMOUNT_TYPES = %i[integer bigint decimal].freeze
+    VALID_CURRENCY_TYPES = %i[string text].freeze
+
+    # Validates that a column can store a money amount.
+    #
+    # @param attr_name [Symbol, String] the money attribute accessor name
+    # @param column_name [Symbol, String] the amount column name
+    # @param column [ActiveRecord::ConnectionAdapters::Column] the column metadata
+    # @return [void]
+    # @raise [ArgumentError] if the column type is not numeric
+    # @api private
+    def assert_valid_amount_column!(attr_name, column_name, column)
+      return if VALID_AMOUNT_TYPES.include?(column.type)
+
+      raise ArgumentError,
+            "`:#{attr_name}` amount column `#{column_name}` must be a numeric type " \
+            "(integer, bigint, or decimal), got `#{column.type}`"
+    end
+
+    # Validates that a column can store a currency code.
+    #
+    # @param attr_name [Symbol, String] the money attribute accessor name
+    # @param column_name [Symbol, String] the currency column name
+    # @param column [ActiveRecord::ConnectionAdapters::Column] the column metadata
+    # @return [void]
+    # @raise [ArgumentError] if the column type is not string-like
+    # @api private
+    def assert_valid_currency_column!(attr_name, column_name, column)
+      return if VALID_CURRENCY_TYPES.include?(column.type)
+
+      raise ArgumentError,
+            "`:#{attr_name}` currency column `#{column_name}` must be a string type " \
+            "(string or text), got `#{column.type}`"
+    end
+  end
+end

data/lib/money_attribute/converter.rb

@@ -1,21 +1,36 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Converts raw attribute input into +Mint::Money+ values.
+  #
+  # Used in two roles: as the +:converter+ option of +composed_of+ (composite
+  # attributes) and as the normalizer block for +money_amount+ (single-column
+  # attributes). Accepts +Mint::Money+, numeric, string, and +nil+ input.
   class Converter
     DEFAULT = new.freeze
 
     # Initializes a converter with an optional fixed currency.
+    #
+    # @param currency [String, Symbol, Mint::Currency, nil] the currency to use
+    #   for parsed values; falls back to {MoneyAttribute.default_currency} when nil
+    # @return [Converter]
     def initialize(currency = nil)
       @static_currency = currency
     end
 
     # Returns the shared default converter instance.
+    #
+    # @return [Converter] the frozen, process-wide converter
     def self.default
       DEFAULT
     end
 
-    # Converts raw input into a `Money` value.
+    # Converts raw input into a +Mint::Money+ value.
+    #
+    # @param amount [Mint::Money, Numeric, String, nil] the input value
+    # @return [Mint::Money, nil] +Mint::Money+ for numeric and string input,
+    #   the input itself for +Mint::Money+ and +nil+
+    # @raise [ArgumentError] for unsupported input types
     def parse(amount)
       currency = @static_currency || MoneyAttribute.default_currency
       case amount

data/lib/money_attribute/core_ext/numeric.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
-# :nodoc:
+# Convenience method for converting numeric values to +Mint::Money+.
+#
+# @api private
 class Numeric
   remove_method :to_money if method_defined?(:to_money)
 
+  # Converts the numeric value to a +Mint::Money+ value.
+  #
+  # @param currency [String, Symbol, Mint::Currency, nil] the currency to use;
+  #   falls back to {MoneyAttribute.default_currency}
+  # @return [Mint::Money]
+  # @example
+  #   42.5.to_money('USD') # => Mint::Money(42.5, 'USD')
   def to_money(currency = MoneyAttribute.default_currency) = Money.from(self, currency)
 end

data/lib/money_attribute/core_ext/string.rb

@@ -1,8 +1,18 @@
 # frozen_string_literal: true
 
-# :nodoc:
+# Convenience method for parsing +Mint::Money+ from strings.
+#
+# @api private
 class String
   remove_method :to_money if method_defined?(:to_money)
 
+  # Parses the string into a +Mint::Money+ value.
+  #
+  # @param currency [String, Symbol, Mint::Currency, nil] the currency to use;
+  #   falls back to {MoneyAttribute.default_currency}
+  # @return [Mint::Money]
+  # @raise [ArgumentError] if the string cannot be parsed
+  # @example
+  #   '12.34'.to_money('USD') # => Mint::Money(12.34, 'USD')
   def to_money(currency = MoneyAttribute.default_currency) = Money.parse(self, currency)
 end

data/lib/money_attribute/form_builder_extension.rb

@@ -1,9 +1,39 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Form builder methods for money attributes.
+  #
+  # Included into +ActionView::Helpers::FormBuilder+ by the railtie,
+  # providing two helper methods that mirror Rails' +text_field+ and
+  # +number_field+ but work with +Mint::Money+ attribute values.
+  #
+  # Both helpers render unbound <tt>&lt;input&gt;</tt> tags (not scoped to
+  # the form builder's object name), so the submitted value is accessible
+  # via +params+ directly rather than through +params[object_name]+.
+  #
+  # @example In a view
+  #   <%= form_with model: @product do |f| %>
+  #     <%= f.money_field :price %>
+  #     <%= f.money_amount_field :discount %>
+  #   <% end %>
   module FormBuilderExtension
-    # Renders a text input for a composed money attribute.
+    # Renders a text input for a composed (amount + currency) money attribute.
+    #
+    # Displays the formatted money string (e.g. +"R$ 1.234,56"+) via
+    # {Mint::Money#to_fs}. The raw value is submitted as a string; the
+    # application should parse it on the receiving end, typically using
+    # {MoneyAttribute::Converter#parse}.
+    #
+    # @param method [Symbol] the money attribute accessor name
+    # @param options [Hash] HTML attributes passed through to the input tag
+    # @return [String] an HTML <tt>&lt;input type="text"&gt;</tt> tag
+    #
+    # @example
+    #   f.money_field :price
+    #   # => <input type="text" id="product_price" name="product_price" value="R$ 1.234,56">
+    #
+    # @example With CSS class
+    #   f.money_field :price, class: "form-control"
     def money_field(method, options = {})
       money = object.public_send(method)
       value = money&.to_fs
@@ -12,7 +42,22 @@ module MoneyAttribute
                                { id: field_id(method) }.merge(options))
     end
 
-    # Renders a number input for a single-column money attribute.
+    # Renders a number input for a single-column (fixed-currency) money attribute.
+    #
+    # Displays the raw decimal value (e.g. +"1234.56"+) via
+    # {Mint::Money#to_d}. This is suitable for attributes backed by a single
+    # column where the currency is fixed per application config.
+    #
+    # @param method [Symbol] the money attribute accessor name
+    # @param options [Hash] HTML attributes passed through to the input tag
+    # @return [String] an HTML <tt>&lt;input type="number"&gt;</tt> tag
+    #
+    # @example
+    #   f.money_amount_field :discount
+    #   # => <input type="number" id="product_discount" name="product_discount" value="1234.56">
+    #
+    # @example With step and min
+    #   f.money_amount_field :discount, step: 0.01, min: 0
     def money_amount_field(method, options = {})
       money_from_column = object.public_send(method)
       value = money_from_column&.to_d

data/lib/money_attribute/macro.rb

@@ -1,13 +1,32 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Declares composite money attributes on Active Record models.
+  #
+  # Provides the +money_attribute+ class method which wires a two-column
+  # (amount + currency) backing store to a +Mint::Money+ value object via
+  # +composed_of+.
+  #
+  # @example
+  #   class Product < ApplicationRecord
+  #     money_attribute :price
+  #   end
   module Macro
     extend ActiveSupport::Concern
 
-    # :nodoc:
+    # Class methods backing the +money_attribute+ macro.
+    #
+    # @api private
     module CompositeClassMethods
+      include ColumnTypeValidations
+
       # Normalizes the requested mapping by applying conventions and overrides.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping_override [Hash] the user-supplied +mapping:+ option
+      # @return [Hash{Symbol => String}] resolved +:amount+ and +:currency+ column names
+      # @raise [ArgumentError] if the resolved columns do not exist on the model
+      # @api private
       def resolve_mapping(name, mapping_override)
         override = mapping_override.compact
         override.slice!(:amount, :currency)
@@ -20,6 +39,13 @@ module MoneyAttribute
       end
 
       # Returns the default amount/currency mapping for the attribute name.
+      #
+      # Resolution order: +name_currency+ + +name+ columns, +amount+ + +currency+
+      # for +:amount+, then the +name_amount+ + +name_currency+ convention.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @return [Hash{Symbol => String}] +:amount+ and +:currency+ column names
+      # @api private
       def default_mapping(name)
         name = name.to_s
         names = column_names
@@ -34,18 +60,35 @@ module MoneyAttribute
       end
 
       # Registers the composite money attribute spec for the model.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping [Hash{Symbol => String}] +:amount+ and +:currency+ column names
+      # @return [AttributeSpec] the registered spec
+      # @raise [ArgumentError] if either column has an unsupported type
+      # @api private
       def register_composite_spec(name, mapping)
-        column = column_for_attribute(mapping[:amount])
+        amount_column = column_for_attribute(mapping[:amount])
+        currency_column = column_for_attribute(mapping[:currency])
+
+        assert_valid_amount_column!(name, mapping[:amount], amount_column)
+        assert_valid_currency_column!(name, mapping[:currency], currency_column)
+
         register_money_attribute_spec(
           name,
           kind: :composite,
-          amount_col: mapping[:amount],
-          currency_col: mapping[:currency],
-          amount_type: %i[integer bigint].include?(column.type) ? :integer : :decimal
+          amount_column: mapping[:amount],
+          currency_column: mapping[:currency],
+          amount_type: %i[integer bigint].include?(amount_column.type) ? :integer : :decimal
         )
       end
 
       # Raises when the resolved columns are not present on the model.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping [Hash{Symbol => String}] +:amount+ and +:currency+ column names
+      # @return [void]
+      # @raise [ArgumentError] listing expected vs found columns
+      # @api private
       def assert_columns_exist!(name, mapping)
         missing = mapping.values - column_names
         return if missing.empty?
@@ -59,6 +102,20 @@ module MoneyAttribute
 
     class_methods do
       # Declares a composite money attribute on the model.
+      #
+      # Stores the attribute across two columns (amount + currency). The amount
+      # column type determines the storage unit: integer/bigint stores subunits,
+      # decimal stores the unit value. Currency is resolved per row.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping [Hash] custom column mapping (+:amount+, +:currency+)
+      # @return [void]
+      #
+      # @example
+      #   class Product < ApplicationRecord
+      #     money_attribute :price
+      #     money_attribute :price, mapping: { amount: :base_price, currency: :base_currency }
+      #   end
       def money_attribute(name, mapping: {})
         mapping = resolve_mapping(name, mapping)
         spec = register_composite_spec(name, mapping)