money_attribute 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcfa5f42f59d3a7f372ddbff422a4e2aa45faccf4f5bd912fc2509e974bda609
-  data.tar.gz: 173509ac929dc32881a8bae54be2c3a7c0f92632ab8fae0192d84ae9b42433eb
+  metadata.gz: a26cda78a2361b592ca6f90c1afb5f8637792b432038d45b543aa562624d6349
+  data.tar.gz: 0e9d78eaf7c8118942676f81f4dbebe55614663469d0d8f3095622fc0def3dca
 SHA512:
-  metadata.gz: 18598feb924b703ae70e0fe68a76dd93d3ec9f22753d8556616d8c42ebae8460512e9451ed2e80b96feb44d380e8c03e1d2c0a23f22cf956773d001f5e27d83b
-  data.tar.gz: 1178b4b944cbd54b93d8d96f03a55403141086573d5f15f6225a820e65fb9a3e4fae7f0277518563274fa91a7dc7fd6a4ae889e1391dfb69efe72c07de0bb53a
+  metadata.gz: 4ba8368b5c3c11be2375368399113b1526b1e2d9f347b2e5d16499a64577dffb5b846a876ba4d04967e8ac8a76fccc717aafb8caaefd25c83bb7dc61ce22839e
+  data.tar.gz: 52dd36ef69c80695f8e22802e5486332d94d5afcc4e48cf671847705b3120de5ecfb636b191fe629077d8f6ebb35a2dcbd5b6a716f031bdb918a35abe32d23fa

data/README.md

@@ -3,9 +3,9 @@
 [![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)).
+`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)).
 
 ```ruby
 class Product < ApplicationRecord
@@ -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
 
@@ -188,16 +187,16 @@ MoneyAttribute integrates with Rails I18n to automatically format money amounts
 
 With `I18n.locale` set to `:en`:
 ```ruby
-Mint.money(1234.56, 'USD').to_s  # => "$1,234.56"
+Money.from(1234.56, 'USD').to_s  # => "$1,234.56"
 ```
 
 Switch to `:'pt-BR'` and the separators change automatically (requires [`rails-i18n`](https://github.com/svenfuchs/rails-i18n) or your own locale file):
 ```ruby
 I18n.locale = :'pt-BR'
-Mint.money(1234.56, 'USD').to_s  # => "$1.234,56"
+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:
 
@@ -218,9 +217,9 @@ en:
 When any of `positive`, `negative`, or `zero` is present, a Hash format is built. Missing keys fall back to `format`:
 
 ```ruby
-Mint.money(1234.56, 'USD').to_s  # => "$1,234.56"
-Mint.money(-1234.56, 'USD').to_s # => "($1,234.56)"
-Mint.money(0, 'USD').to_s        # => "--"
+Money.from(1234.56, 'USD').to_s  # => "$1,234.56"
+Money.from(-1234.56, 'USD').to_s # => "($1,234.56)"
+Money.from(0, 'USD').to_s        # => "--"
 ```
 
 If none of those keys are set, `format` is used as a plain string (simple formatting).
@@ -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` |
+
+**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
+```
 
-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).
+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**
 
@@ -343,6 +350,8 @@ end
 
 ## Querying
 
+### Rails-native queries
+
 Multi-currency (`money_attribute`) attributes support equality queries via `composed_of`:
 
 ```ruby
@@ -356,7 +365,110 @@ Offer.where(price_amount: 10..20, price_currency: 'EUR')
 Offer.where('price_amount > ? AND price_currency = ?', 10, 'EUR')
 ```
 
-For fixed-currency (`money_amount`) attributes, see the [single-column section](#single-column-mode--money_amount).
+Fixed-currency (`money_amount`) attributes support full Rails-native querying through the custom type — equality, IN, BETWEEN, ordering, and aggregation all work:
+
+```ruby
+Product.where(price: 10.to_money('USD'))                        # equality
+Product.where(price: [10.to_money('USD'), 20.to_money('USD')]) # IN
+Product.where(price: 10.to_money('USD')..20.to_money('USD'))   # BETWEEN
+Product.order(price: :desc)                                     # ordering
+Product.where(price: 10.to_money('USD')).sum(:price)            # aggregation
+```
+
+### Money-aware query helpers
+
+For multi-currency attributes, manually decomposing columns is tedious. The query helpers handle this automatically — just pass Money objects:
+
+#### `where_amount`
+
+Filters by amount value. Accepts a scalar, Range, or Array.
+
+```ruby
+Offer.where_amount(price: 10)               # equality (any currency)
+Offer.where_amount(price: [10, 30])         # IN — matches EUR 10, USD 30
+Offer.where_amount(price: 10..100)          # BETWEEN (inclusive)
+Offer.where_amount(price: 10...100)         # BETWEEN (exclusive upper bound)
+```
+
+Ranges work across currencies — `10..50` matches EUR 10 and USD 50:
+
+```ruby
+Offer.create!(price: 10.euros)
+Offer.create!(price: 50.dollars)
+
+Offer.where_amount(price: 10..50)           # => both records
+```
+
+For integer (subunit) columns, pass `Money` objects directly — subunit conversion is handled automatically:
+
+```ruby
+FinancialTransaction.where_amount(amount: [10.dollars, 10.yens])
+FinancialTransaction.where_amount(amount: 10.dollars..100.dollars)
+```
+
+For decimal columns, raw numbers work:
+
+```ruby
+SimpleOffer.where_amount(price: 50)
+SimpleOffer.where_amount(price: 10..100)
+```
+
+#### `where_currency`
+
+Filters by currency code. Composite attributes only — raises `ArgumentError` for single-column attributes.
+
+```ruby
+Offer.where_currency(price: 'EUR')
+Offer.where_currency(price: 10.euros.currency)  # also accepts Currency object
+```
+
+#### `order_by_amount`
+
+Orders by amount. Composite attributes sort by currency ASC first, then amount. Single-column attributes sort by amount only.
+
+```ruby
+Offer.order_by_amount(price: :asc)   # EUR 10, EUR 100, USD 50
+Offer.order_by_amount(price: :desc)  # EUR 100, EUR 10, USD 50
+Offer.order_by_amount(price: nil)    # defaults to :asc
+```
+
+#### `pluck_amount`
+
+Returns money-aware amounts. Follows Rails' `pluck` arity — one attribute returns flat values, multiple attributes return row arrays.
+
+```ruby
+Offer.pluck_amount(:price)                  # => [EUR 10.00, USD 20.00]
+Offer.pluck_amount(:amount, :discount)      # => [[USD 100.00, EUR 20.00], ...]
+```
+
+#### `pick_amount`
+
+Returns a single money-aware value. Follows Rails' `pick` arity.
+
+```ruby
+Offer.pick_amount(:price)                   # => EUR 10.00
+Offer.pick_amount(:amount, :discount)       # => [USD 100.00, EUR 20.00]
+Offer.none.pick_amount(:price)              # => nil
+```
+
+#### `sum_amount`
+
+Sums amounts grouped by currency for composite attributes. Accepts a single attribute name only.
+
+```ruby
+Offer.sum_amount(:price)
+# => [EUR 30.00, USD 70.00]  (one Money per currency, sorted by code)
+
+SimpleOffer.sum_amount(:price)
+# => [BRL 60.00]  (single-column always returns one Money)
+
+Offer.none.sum_amount(:price)
+# => [BRL 0.00]  (empty result returns zero Money)
+```
+
+### Notes
+
+All query helpers raise `ArgumentError` for non-money attributes. Internally, money attribute metadata is registered per model class. The same attribute name can be used safely in different models, but subclasses do not automatically inherit a parent model's registered money attributes.
 
 ## Convenience methods
 
@@ -368,7 +480,7 @@ MoneyAttribute adds small helpers on `Numeric` and `String`:
 12.euros              # => [EUR 12.00]
 ```
 
-> If you prefer not to extend core classes, use `Mint.money(12, 'USD')` instead.
+> If you prefer not to extend core classes, use `Money.from(12, 'USD')` instead.
 
 ## Form helpers
 
@@ -386,7 +498,9 @@ 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.
 
 #### Migration helpers
 
@@ -398,9 +512,9 @@ MoneyAttribute adds `money_field` and `money_amount_field` to Rails form builder
 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
@@ -438,15 +552,7 @@ money_amount :price
 
 #### Querying
 
-Fixed-currency attributes support Rails-native querying through the custom type:
-
-```ruby
-Product.where(price: 10.to_money('USD'))                        # equality
-Product.where(price: [10.to_money('USD'), 20.to_money('USD')]) # IN
-Product.where(price: 10.to_money('USD')..20.to_money('USD'))   # BETWEEN
-Product.order(price: :desc)                                     # ordering
-Product.where(price: 10.to_money('USD')).sum(:price)            # aggregation
-```
+Fixed-currency attributes support full Rails-native querying — see [Querying](#querying) for examples.
 
 ## Roadmap
 
@@ -465,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

@@ -16,13 +16,41 @@ end
 
 desc 'Migrate test database'
 task :test_db_migrate do
-  sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate', chdir: 'test/dummy')
+  sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate', chdir: 'test/dummy', %i[out err] => File::NULL)
 end
 
 desc 'Run tests (migrates test DB first)'
 task test: %i[test_db_migrate test_run]
 
-desc 'Run money_attribute vs money-rails benchmark'
+# --- Adapter-specific tasks ---
+
+%w[postgresql mysql2].each do |adapter|
+  namespace :test do
+    desc "Migrate test database (#{adapter})"
+    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
+      Rake::Task[:"test:db_migrate:#{adapter}"].invoke
+      sh({ 'DATABASE_ADAPTER' => adapter }, 'bundle', 'exec', 'rake', 'test_run')
+    end
+  end
+end
+
+desc 'Run tests against all adapters (sqlite3, postgresql, mysql2)'
+task 'test:all' do
+  Rake::Task[:test].invoke
+  %w[postgresql mysql2].each do |adapter|
+    Rake::Task[:"test:#{adapter}"].invoke
+  end
+end
+
+# --- Benchmark ---
+
+desc 'Run money_attribute vs plain Rails vs money-rails benchmark'
 task bench: :test_db_migrate do
   puts
   puts '=' * 80
@@ -31,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)'
@@ -44,3 +79,9 @@ desc 'Generate consolidated benchmark report (markdown)'
 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/generators/templates/money_attribute.rb

@@ -2,21 +2,29 @@
 # frozen_string_literal: true
 
 MoneyAttribute.configure do |config|
+  # To set the default currency
+  #
+  # It must be a registered currency
+  #
+  config.default_currency = 'USD'
+
+  # Register built-in crypto currencies
+  #
+  # 1. Register specific crypto currencies:
+  #   Mint::Currency.register_crypto('BTC', 'ETH')
+  #
+  # 2. Register all built-in crypto currencies at once:
+  #   Mint::Currency.register_all_crypto
+  #
+  # See available crypto currencies:
+  #   Mint::Currency.crypto_currencies
+
   # Register a custom currency
   #
   # Example:
   #   config.added_currencies = [
-  #     {currency: 'CRC', subunit: 2, symbol: '₡'},
-  #    {currency: 'NGN', subunit: 3, symbol: '₦'}
+  #    {currency: 'ZCRC', subunit: 2, symbol: '₡'},
+  #    {currency: 'ZNGN', subunit: 3, symbol: '₦'}
   #   ]
-  config.added_currencies = [
-    { currency: 'XCRC', subunit: 2, symbol: '₡' },
-    { currency: 'XNGN', subunit: 3, symbol: '₦' }
-  ]
-
-  # To set the default currency
-  #
-  # It must be a registered currency
-  #
-  config.default_currency = 'BRL'
+  config.added_currencies = []
 end

data/lib/money_attribute/attribute_spec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # @private Constructor for integer (subunit) columns used by +composed_of+.
+  INTEGER_CONSTRUCTOR = lambda do |amount, currency|
+    next nil if amount.nil?
+
+    resolved = Money::Currency.resolve(currency.presence || MoneyAttribute.default_currency) || 'XXX'
+    Mint::Money.from_subunits(amount, resolved)
+  end.freeze
+
+  # @private Constructor for decimal (unit value) columns used by +composed_of+.
+  DECIMAL_CONSTRUCTOR = lambda do |amount, currency|
+    next nil if amount.nil?
+
+    resolved = Money::Currency.resolve(currency.presence || MoneyAttribute.default_currency) || 'XXX'
+    Mint::Money.from(amount, resolved)
+  end.freeze
+
+  # Value object holding metadata for a registered money attribute.
+  #
+  # 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.
+  #
+  # @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
+
+    # @return [Boolean] +true+ when the spec describes a single-column (fixed currency) attribute.
+    def single? = kind == :single
+
+    # Returns the backing database columns for the attribute.
+    #
+    # @return [Array<String>] two-element array for composite, one-element for single.
+    def columns
+      @columns ||= (composite? ? [amount_column, currency_column] : [amount_column]).freeze
+    end
+
+    # @return [Boolean] +true+ when the amount column stores subunits (bigint).
+    def integer_amount? = amount_type == :integer
+
+    # @return [Symbol] +:subunits+ for integer columns, +:to_d+ for decimal columns.
+    def amount_extractor = integer_amount? ? :subunits : :to_d
+
+    # @return [Hash{String => Symbol}] mapping suitable for +composed_of+.
+    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
+      integer_amount? ? INTEGER_CONSTRUCTOR : DECIMAL_CONSTRUCTOR
+    end
+
+    # Converts a raw amount and currency into a +Mint::Money+ value.
+    #
+    # @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)
+
+      constructor.call(amount, currency)
+    end
+
+    # Normalizes a query value to the column's storage format.
+    #
+    # Composite attributes: decomposes +Mint::Money+ to subunits via +.subunits+.
+    # Single-column attributes: passes through (the registered Type handles serialization).
+    #
+    # @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)
+
+      value
+    end
+  end
+end

data/lib/money_attribute/attribute_spec_registry.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+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_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]
+      # @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_column: amount_column.to_s,
+          currency_column: currency_column&.to_s,
+          amount_type: amount_type
+        )
+
+        money_attribute_specs[spec.name] = spec
+        spec
+      end
+
+      # Returns the registered money attribute spec for the given name.
+      #
+      # @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
+
+      # 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