money_attribute 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb71d942a1dd57ae30fa3d1d8941efacf402d9346192b99cca4d0eabf69246fb
-  data.tar.gz: 70dbb86d5d328e5d42fd09593358445d931261b59212d49f3a8e6a450d275c09
+  metadata.gz: 4101988f3c8acc6d5a4810519fa74d1fd27feaba2114ee047ecd755da3229c91
+  data.tar.gz: 2a7071882d41791e33c3d189bd5db42ea39b434c597f64a3c5b6ae88facd7e82
 SHA512:
-  metadata.gz: 93e1d50ccda57e7a535fba457e4551525923358b45ef629b381bb04c900eb1fc7b76c1aa11d18410a0669fb96f610a53df1e76e10dcc58860e1d0cd8e3dd19f6
-  data.tar.gz: 55d8b84306bf8988e066d426e525af1d6bfb2b0f202727a9a3a38aa5a52f9461d57edac0d5c003f5996141a5e662439d661109ba6aab975fd420b882ea754a29
+  metadata.gz: eac6fb9ca6ef50c717fc51b8c4aac7977e425787ea98032ae02e66091f74a66158b1f19f401b5b15df3cf8dc7a402aba942e9c7b55f1dc054ec2c617114d2c87
+  data.tar.gz: 2216348ddfa7df7d97ddacfe12d15a895d2e1c9ac28392719c14add69741a177ab5064b5a8da5befde3ec9b28a028e37924b4f3db433a2a70af626af5e619ddc

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.
 
 ```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,23 +61,23 @@ 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.
-- **Currency enforcement** — fixed-currency attributes reject wrong currencies at assignment time.
+- **Normalizes everything** — pass a number, string, or `Money`; always get a `Money` back.
+- **Currency handling** — each record stores its own currency and accepts registered currencies at assignment time.
 - **Built on Rails primitives** — uses `ActiveRecord::Type`, `composed_of`, and `normalizes` under the hood. No monkey-patching of core classes.
 
 ### At a glance — vs money-rails
 
 | Feature | MoneyAttribute | money-rails |
 |---|---|---|
-| **Declare** | `t.money_attribute :price` / `money_attribute :price` or `t.money_amount :price` / `money_amount :price` | `monetize :price_cents` |
+| **Declare** | `t.money_attribute :price` / `money_attribute :price` | `monetize :price_cents` |
 | **Column types** | `integer`, `decimal`, `bigint` — auto-detected | `integer` cents only |
-| **Storage modes** | Composite (amount+currency), single column | Single cents column, composite (cents+currency) |
+| **Storage mode** | Composite (amount+currency) | Single cents column, composite (cents+currency) |
 | **Decimal columns** | Native — `t.decimal :price` | Not supported — must convert to cents manually |
 | **Multi-currency** | `money_attribute :price` (convention: `<name>_amount` + `<name>_currency`) | `monetize :price_cents, with_currency: :price_currency` |
 | **Rails integration** | `ActiveRecord::Type` + `composed_of` — no monkey-patches | `monetize` overrides reader/writer methods |
@@ -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
 
@@ -150,7 +149,33 @@ class AddPriceToProducts < ActiveRecord::Migration[8.1]
 end
 ```
 
-### Naming
+### Default column names
+
+For `money_attribute :price`, the default columns are `price` for the amount
+and `price_currency` for the currency. The migration helper and model macro use
+the same mapping:
+
+```ruby
+create_table :products do |t|
+  t.money_attribute :price
+end
+
+class Product < ApplicationRecord
+  money_attribute :price
+end
+```
+
+This creates and maps to:
+
+```text
+price
+price_currency
+```
+
+The amount column defaults to `decimal(20,4)` and the currency column defaults
+to `string(16)`.
+
+### Naming options
 
 **`money_attribute` (composite):**
 
@@ -159,7 +184,7 @@ end
 | `t.money_attribute :price` | `price` decimal(20,4) + `price_currency` string(16) | `money_attribute :price` |
 | `t.money_attribute :price_amount` | `price_amount` decimal(20,4) + `price_currency` string(16) | `money_attribute :price` |
 | `t.money_attribute :price, amount: { type: :fiat_integer }` | `price` bigint + `price_currency` string(16) | `money_attribute :price` |
-| `t.money_attribute :price, amount: { column: :a }, currency: { column: :c }` | `a` + `c` | `money_attribute :price, mapping: { amount: :a, currency: :c }` |
+| `t.money_attribute :price, amount: { column: :a }, currency: { column: :c }` | `a` + `c` | `money_attribute :price, amount: { column: :a }, currency: { column: :c }` |
 | `t.money_attribute :price, currency: { limit: 5 }` | `price` decimal(20,4) + `price_currency` string(5) | `money_attribute :price` |
 | `t.remove_money_attribute :price` | Removes `price` + `price_currency` | `money_attribute :price` |
 
@@ -197,7 +222,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:
 
@@ -282,38 +307,55 @@ Order.new(total: 19.99.to_money('USD')).total_amount # => 1999
 
 ## Custom column names
 
-If your columns don't follow the `<name>_amount` / `<name>_currency` convention:
+If your columns do not follow the default mapping, use the same nested column
+options as the migration helper:
 
 ```ruby
 class Invoice < ApplicationRecord
-  money_attribute :total, mapping: {
-    amount:   :total_amount,
-    currency: :currency_code
-  }
+  money_attribute :total,
+    amount: { column: :total_amount },
+    currency: { column: :currency_code }
 end
 ```
 
-The mapping keys are `:amount` and `:currency`; values are your database column names. You can provide only one key — the other falls back to the `<name>_amount` / `<name>_currency` convention:
+You can provide only one nested option; the other falls back to the default
+mapping. The older `mapping:` syntax remains supported (but it will eventually be deprecated):
 
 ```ruby
 class Invoice < ApplicationRecord
-  money_attribute :total, mapping: { amount: :total_amount }
-  # currency column inferred as `total_currency`
+  money_attribute :total, amount: { column: :total_amount }
+  money_attribute :subtotal, mapping: { amount: :subtotal }
 end
 ```
 
+Model declarations accept only the nested `:column` option. Migration-only
+options such as `:type`, `:null`, and `:default` belong in the migration.
+
 ## 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).
+The first row is the canonical mapping used by the migration helpers. The
+final row supports existing schemas that use the `<name>_amount` /
+`<name>_currency` convention. For example, `money_attribute :price` also maps
+to `price_amount` + `price_currency` when those are the available columns.
+
+**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 the [advanced `money_amount` section](#advanced-money_amount-single-column-fixed-currency).
 
 **Example**
 
@@ -325,7 +367,6 @@ create_table :financial_transactions do |t|
   t.string  :discount_currency, limit: 3
   t.decimal :price_amount
   t.string  :price_currency, limit: 3
-  t.bigint  :tax
   t.decimal :total_amount
   t.string  :currency_code, limit: 3
 end
@@ -337,7 +378,6 @@ class FinancialTransaction < ApplicationRecord
   money_attribute :discount                 # step 2: discount(int) + discount_currency
   money_attribute :price                    # step 4: price_amount + price_currency
   money_attribute :total, mapping: { amount: :total_amount, currency: :currency_code }  # step 1: explicit
-  money_amount  :tax                        # single-column, fixed-currency (uses default currency)
 end
 ```
 
@@ -348,7 +388,7 @@ end
 Multi-currency (`money_attribute`) attributes support equality queries via `composed_of`:
 
 ```ruby
-Offer.where(price: 10.to_money('EUR'))
+Offer.where(price: 10.euros)
 ```
 
 For comparisons, use the backing columns directly:
@@ -358,15 +398,25 @@ Offer.where(price_amount: 10..20, price_currency: 'EUR')
 Offer.where('price_amount > ? AND price_currency = ?', 10, 'EUR')
 ```
 
-Fixed-currency (`money_amount`) attributes support full Rails-native querying through the custom type — equality, IN, BETWEEN, ordering, and aggregation all work:
+### Composite query matrix
 
-```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
-```
+For `money_attribute`, use native Rails queries for simple equality. Use the
+money-aware helpers when working with `Money` objects or when you need an
+explicit currency filter alongside an amount query:
+
+| Operation | Native Rails | Money-aware helper |
+|---|---|---|
+| Equality | `where(price: 10.euros)` | `where_amount(price: 10.euros)` |
+| `IN` | Query backing columns directly | `where_amount(price: [10.euros, 20.euros])` |
+| Range/comparison | Query backing columns directly | `where_currency(price: 'EUR').where_amount(price: 10.euros..20.euros)` |
+| Currency filter | `where(price_currency: 'EUR')` | `where_currency(price: 'EUR')` |
+| Ordering | Query backing columns directly | `order_by_amount(price: :desc)` |
+| Pluck | Returns backing column values | `pluck_amount(:price)` returns `Money` |
+| Pick | Returns backing column values | `pick_amount(:price)` returns `Money` |
+| Sum | Group and sum backing columns directly | `sum_amount(:price)` groups by currency |
+
+`where_amount` accepts `Money` values and converts them to the backing amount
+unit. Pair it with `where_currency` when the currency must be constrained.
 
 ### Money-aware query helpers
 
@@ -377,35 +427,28 @@ For multi-currency attributes, manually decomposing columns is tedious. The quer
 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)
+Offer.where_amount(price: 10.euros)                    # equality
+Offer.where_amount(price: [10.euros, 30.euros])        # IN
+Offer.where_amount(price: 10.euros..100.euros)         # BETWEEN (inclusive)
+Offer.where_amount(price: 10.euros...100.euros)        # BETWEEN (exclusive upper bound)
 ```
 
-Ranges work across currencies — `10..50` matches EUR 10 and USD 50:
+For a currency-specific range, constrain the currency explicitly:
 
 ```ruby
 Offer.create!(price: 10.euros)
-Offer.create!(price: 50.dollars)
+Offer.create!(price: 50.euros)
 
-Offer.where_amount(price: 10..50)           # => both records
+Offer.where_currency(price: 'EUR').where_amount(price: 10.euros..50.euros) # => 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])
+FinancialTransaction.where_amount(amount: [10.dollars, 20.dollars])
 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.
@@ -456,13 +499,27 @@ 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
 
 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.
 
+### Introspection
+
+Use `money_attribute?` and `money_attribute_kind` when building generic model
+or form code:
+
+```ruby
+Product.money_attribute?(:price)       # => true
+Product.money_attribute_kind(:price)   # => :composite or :single
+Product.money_attribute?(:unknown)     # => false
+```
+
+`money_attribute_kind` returns `:composite` for `money_attribute`, `:single`
+for `money_amount`, and `nil` for undeclared attributes.
+
 ## Convenience methods
 
 MoneyAttribute adds small helpers on `Numeric` and `String`:
@@ -477,24 +534,53 @@ MoneyAttribute adds small helpers on `Numeric` and `String`:
 
 ## Form helpers
 
-MoneyAttribute adds `money_field` and `money_amount_field` to Rails form builders. `money_field` renders a text input with the locale-formatted money string; `money_amount_field` renders a number input with the raw decimal value.
+MoneyAttribute adds `money_field` to Rails form builders for composite money attributes. It renders a text input with the locale-formatted money string.
 
 ```erb
 <%= form_with model: @product do |form| %>
   <%= form.label :price %>
   <%= form.money_field :price %>       <!-- text input, e.g. "$1,234.56" -->
-
-  <%= form.label :tax %>
-  <%= form.money_amount_field :tax %>  <!-- number input, e.g. "1234.56" -->
 <% end %>
 ```
 
-### Single-column mode — `money_amount` (fixed-currency)
+The field submits a locale-formatted string under the normal model parameter:
 
-`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.
+```ruby
+# app/controllers/products_controller.rb
+def create
+  @product = Product.new(product_params)
+
+  if @product.save
+    redirect_to @product
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+
+private
+
+def product_params
+  params.require(:product).permit(:name, :price)
+end
+```
+
+The model normalizes the submitted string through `MoneyAttribute::Converter`.
+For a composite attribute, provide a separate currency input or set the
+currency explicitly when the form must accept a currency different from the
+configured default.
+
+### Advanced: `money_amount` (single-column, fixed-currency)
+
+`money_amount` is an advanced compatibility utility for schemas where one
+numeric column stores amounts in one fixed currency. It is not suitable for
+per-row or multi-currency data. New applications should normally use
+`money_attribute`.
 
 The accessor name must match the column name. `money_amount` does not support custom column mapping.
 
+Use `money_amount_field` when rendering a form for this mode; it renders a
+number input with the raw decimal value.
+
 #### Migration helpers
 
 | Method | Action |
@@ -505,9 +591,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
@@ -545,7 +631,19 @@ money_amount :price
 
 #### Querying
 
-Fixed-currency attributes support full Rails-native querying — see [Querying](#querying) for examples.
+Fixed-currency attributes support full Rails-native querying. The helper methods
+are also available when a consistent query interface is useful:
+
+| Operation | Native Rails | Money-aware helper |
+|---|---|---|
+| Equality | `where(price: 10.reais)` | `where_amount(price: 10.reais)` |
+| `IN` | `where(price: [10.reais, 20.reais])` | `where_amount(price: [10.reais, 20.reais])` |
+| Range/comparison | `where(price: 10.reais..20.reais)` | `where_amount(price: 10.reais..20.reais)` |
+| Currency filter | Not applicable | Raises `ArgumentError` |
+| Ordering | `order(price: :desc)` | `order_by_amount(price: :desc)` |
+| Pluck | `pluck(:price)` | `pluck_amount(:price)` |
+| Pick | `pick(:price)` | `pick_amount(:price)` |
+| Sum | `sum(:price)` | `sum_amount(:price)` |
 
 ## Roadmap
 
@@ -564,8 +662,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,24 @@ 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
+
+desc 'Run focused performance roadmap benchmarks'
+task 'bench:performance' do
+  sh({ 'RAILS_ENV' => 'test' }, 'bundle', 'exec', 'ruby', 'benchmark/performance.rb')
+end
+
+desc 'Compare two focused performance benchmark result files'
+task 'bench:performance:compare' do
+  baseline = ENV.fetch('BASELINE')
+  current = ENV.fetch('CURRENT')
+  sh 'bundle', 'exec', 'ruby', 'benchmark/compare_performance.rb', baseline, current
+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)