money_attribute 0.14.5 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd68138109c717791722388f0465c0bbd5296ffe2f30f2cb0521a74585f72483
-  data.tar.gz: 35b179441b1a9e8ef462fffcb0f9c4079929e3a1da6f775e82c67586dd952f2f
+  metadata.gz: cb71d942a1dd57ae30fa3d1d8941efacf402d9346192b99cca4d0eabf69246fb
+  data.tar.gz: 70dbb86d5d328e5d42fd09593358445d931261b59212d49f3a8e6a450d275c09
 SHA512:
-  metadata.gz: '058e831db4a2bf193eda3117e83271c7b8ce7fa0e1be8a24dcd810e988cf7afd24fb7ed05f752a3f2368888f8051e9c117cd7311338a87a011cec80c783d2c12'
-  data.tar.gz: 24346e562f17164b1c1a478eca95b3e4eb38e023112a80bc5e626c6efffaf679c86ebda193fdac5f721f23304c66fcb4c4c54e68cdcb64f990bfaf88f7d9b5ca
+  metadata.gz: 93e1d50ccda57e7a535fba457e4551525923358b45ef629b381bb04c900eb1fc7b76c1aa11d18410a0669fb96f610a53df1e76e10dcc58860e1d0cd8e3dd19f6
+  data.tar.gz: 55d8b84306bf8988e066d426e525af1d6bfb2b0f202727a9a3a38aa5a52f9461d57edac0d5c003f5996141a5e662439d661109ba6aab975fd420b882ea754a29

data/README.md

@@ -3,17 +3,38 @@
 [![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 a single `money_attribute` declaration. No manual serialization, no boilerplate.
+Store and read Active Record attributes as `Mint::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)).
 
 ```ruby
 class Product < ApplicationRecord
-  money_attribute :price, currency: 'USD'   # fixed currency, single column
-  money_attribute :total                    # multi-currency, two columns
+  money_attribute :price
 end
 
-Product.new(price: 12).price  # => [USD 12.00]
+p = Product.new(price: 12.44.dollars).price  # => [USD 12.00]
+p.price * 2 # => [USD 24.88]
 ```
 
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Why MoneyAttribute](#why-moneyattribute)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Migration helpers](#migration-helpers)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Column type detection](#column-type-detection)
+- [Custom column names](#custom-column-names)
+- [Column resolution](#column-resolution)
+- [Querying](#querying)
+- [Convenience methods](#convenience-methods)
+- [Form helpers](#form-helpers)
+- [Roadmap](#roadmap)
+- [Development & Contributing](#development)
+- [License](#license)
+
 ## Quick start
 
 ```sh
@@ -27,7 +48,7 @@ class CreateProducts < ActiveRecord::Migration[8.1]
   def change
     create_table :products do |t|
       t.string :name
-      t.money_attribute :price
+      t.money_attribute :price           # price: decimal(20,4), price_currency: string
       t.timestamps
     end
   end
@@ -37,16 +58,15 @@ end
 ```ruby
 # app/models/product.rb
 class Product < ApplicationRecord
-  money_attribute :price, currency: 'USD'
+  money_attribute :price
 end
 ```
 
-That's it. `Product.new(price: 12).price` is a `Mint::Money`.
+That's it. `Product.new(price: 12.dollars).price` is a `Mint::Money`.
 
 ## Why MoneyAttribute?
 
 - **No serialization boilerplate** — declare once, read/write `Mint::Money` everywhere.
-- **Two storage modes** — single column for fixed-currency apps (simpler), amount+currency columns for multi-currency records (more flexible).
 - **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.
@@ -56,16 +76,16 @@ That's it. `Product.new(price: 12).price` is a `Mint::Money`.
 
 | Feature | MoneyAttribute | money-rails |
 |---|---|---|
-| **Declaration** | `money_attribute :price` | `monetize :price_cents` |
+| **Declare** | `t.money_attribute :price` / `money_attribute :price` or `t.money_amount :price` / `money_amount :price` | `monetize :price_cents` |
 | **Column types** | `integer`, `decimal`, `bigint` — auto-detected | `integer` cents only |
-| **Storage modes** | Single column, composite (amount+currency)| Single cents column, composite (cents+currency) |
+| **Storage modes** | Composite (amount+currency), single column | 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 |
 | **Query (fixed)** | `Model.where(price: money)` — `=`, `IN`, `BETWEEN`, `ORDER`, `SUM` | Through cents column (`price_cents`) |
 | **Query (multi)** | `Model.where(price: money)` | `Model.where(price_cents:, price_currency:)` |
-| **Internal amount** | `Rational`  | `BigDecimal` |
-| **Performance** | See [BENCHMARKS.md](BENCHMARKS.md) — wins 9/11 cells |  |
+| **Internal amount** | `Rational` | `BigDecimal` |
+| **Performance** | See [BENCHMARKS.md](BENCHMARKS.md) — wins 9/11 cells | — |
 
 For a detailed side-by-side comparison, see [COMPARISON.md](COMPARISON.md).
 
@@ -73,7 +93,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) 1.8.0+
+- [Minting](https://github.com/gferraz/minting) 2.0+
 
 ## Installation
 
@@ -91,19 +111,32 @@ The generator creates `config/initializers/money_attribute.rb`.
 
 ## Migration helpers
 
-MoneyAttribute adds `add_money_attribute` / `remove_money_attribute` for existing tables and `t.money_attribute` / `t.remove_money_attribute` for `create_table` / `change_table` blocks.
+### `money_attribute` (composite — amount + currency)
+
+Primary migration helper for multi-currency attributes. Creates two columns — amount and currency.
+
+| Method | Action |
+|---|---|
+| `add_money_attribute` / `t.money_attribute` | Amount column + currency column |
+| `remove_money_attribute` / `t.remove_money_attribute` | Drops both columns |
+
+Default columns: `decimal(20,4)` for amount + `string(16)` for currency.
+
+### Column types
 
-By default `t.money_attribute :price` creates a `decimal(16,4)` amount column and a `string` currency column — both nullable, no default. Pass `amount: { type: :integer }` to store subunits instead, or `currency: false` to skip the currency column entirely.
+| Amount type | Column type | Precision/Scale | Maximum | Integer digits |
+|---|---|---|---|---|
+| `:crypto_decimal` | `decimal` | `36/18` | ~1 quintillion | 18 |
+| `:fiat_decimal`   | `decimal` | `20/4`  | ~10 quadrillion | 16 |
+| `:fiat_integer`   | `bigint`  | — | ~922 trillion | ~15 |
 
 ```ruby
 class CreateProducts < ActiveRecord::Migration[8.1]
   def change
     create_table :products do |t|
       t.string :name
-      t.money_attribute :price          # price (decimal) + price_currency (string)
-      t.money_attribute :price_amount   # price_amount + price_currency (strips _amount suffix)
-      t.money_attribute :fee, currency: false             # single column, no currency
-      t.money_attribute :tax, amount: { type: :bigint }   # bigint amount + currency
+      t.money_attribute :multi                             # decimal(20,4) + currency
+      t.money_attribute :tax, amount: { type: :fiat_integer }  # bigint + currency
       t.timestamps
     end
   end
@@ -111,24 +144,23 @@ end
 
 class AddPriceToProducts < ActiveRecord::Migration[8.1]
   def change
-    add_money_attribute :products, :price                 # add price + price_currency
-    add_money_attribute :products, :discount, amount: { type: :integer }
-    remove_money_attribute :products, :obsolete_fee       # reversible in change
+    add_money_attribute :products, :price           # price + price_currency
+    remove_money_attribute :products, :obsolete_fee # reversible in change
   end
 end
 ```
 
 ### Naming
 
+**`money_attribute` (composite):**
+
 | Migration call | Columns created | Model declaration |
 |---|---|---|
-| `t.money_attribute :price` | `price` decimal + `price_currency` string | `money_attribute :price` |
-| `t.money_attribute :price_amount` | `price_amount` decimal + `price_currency` string | `money_attribute :price` |
-| `t.money_attribute :price, currency: false` | `price` decimal | `money_attribute :price` |
-| `t.money_attribute :price, amount: { type: :integer }` | `price` integer + `price_currency` string | `money_attribute :price` |
+| `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, currency: { limit: 3 }` | `price` decimal + `price_currency` string(3) | `money_attribute :price` |
-| `t.money_attribute :price, amount: { precision: 14, scale: 2, null: false }, currency: { limit: 3, default: 'USD' }` | `price` decimal(14,2) NOT NULL + `price_currency` string(3) DEFAULT 'USD' | `money_attribute :price` |
+| `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` |
 
 Inside `change_table`:
@@ -156,13 +188,13 @@ 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).
@@ -186,42 +218,16 @@ 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).
 
 > Formatting respects the currency's own `subunit` for decimal precision — `I18n` locale settings for `precision` are ignored since that is a currency property, not a locale one.
 
-## Usage — Two modes
-
-### Decision table
-
-| | Fixed currency (single column) | Multi-currency (amount + currency) |
-|---|---|---|
-| **Migration** | `t.money_attribute :price` (or `t.decimal :price`) | `t.money_attribute :price` (or `t.decimal :price_amount` + `t.string :price_currency`) |
-| **Model** | `money_attribute :price, currency: 'USD'` | `money_attribute :price` |
-| **When to use** | Column always holds the same currency | Each row can hold a different currency |
-| **Column type** | `decimal`, `integer`, or `bigint` | `decimal`, `integer`, or `bigint` for amount; `string` for currency |
-| **Query** | `Product.where(price: 10.to_money('USD'))` — full type support | `Offer.where(price: 10.to_money('EUR'))` — equality only |
-
-### Fixed currency
-
-```ruby
-class Product < ApplicationRecord
-  money_attribute :price, currency: 'USD'
-end
-
-product = Product.new(price: 12)
-product.price # => [USD 12.00]
-
-Product.new(price: 12.to_money('EUR'))
-# => ArgumentError: ... has different currency. Only USD allowed.
-```
-
-### Multi-currency
+## Usage
 
 ```ruby
 class Offer < ApplicationRecord
@@ -239,15 +245,29 @@ offer.price.currency.code # => "USD"
 
 Unlike fixed-currency attributes, composite mode does not enforce a specific currency — any registered currency is accepted at assignment.
 
+### Invalid currencies in the database
+
+If the currency column contains a value that is not a registered currency (e.g. a legacy code that was removed, or data corruption), `money_attribute` does not crash. The currency resolves to **XXX** (ISO 4217 "No Currency") and the monetary amount is preserved:
+
+```ruby
+offer = Offer.find(42)
+offer.price # => [XXX 10.00]  # amount preserved, currency flagged
+```
+
+Records with XXX currency are easily queryable for cleanup:
+
+```ruby
+Offer.where(price_currency: 'XXX')
+```
+
 ## Column type detection
 
-Declare the column as `decimal`, `integer`, or `bigint` — the gem adapts:
+Select the amount column type via the `type:` option. The gem adapts serialization accordingly:
 
 ```ruby
 # Migration
 create_table :orders do |t|
-  t.bigint  :total_amount  # stored as cents (subunits)
-  t.string  :total_currency
+  t.money_attribute :total, amount: { type: :fiat_integer }   # bigint — stored as subunits
 end
 
 # Model
@@ -258,17 +278,7 @@ end
 Order.new(total: 19.99.to_money('USD')).total_amount # => 1999
 ```
 
-Same for fixed-currency attributes:
-
-```ruby
-# Migration
-t.bigint :price
-
-# Model (no change needed)
-money_attribute :price, currency: 'USD'
-```
-
-> Use `integer`/`bigint` for large tables (faster, smaller). Use `decimal` when SQL-level readability matters.
+> Use `:fiat_integer` (bigint) for large tables — smaller and sufficient for most fiat use cases (~922 trillion max). Use `:fiat_decimal` (decimal) when SQL-level readability matters. For cryto currencies support, `:crypto_decimal` is mandatory.
 
 ## Custom column names
 
@@ -294,17 +304,16 @@ end
 
 ## Column resolution
 
-When you declare `money_attribute :name`, the gem resolves which database columns to use by checking the table schema in this order:
+`money_attribute :name` is always composite. It resolves columns in this order:
 
-| Step | Condition | Columns used | Mode |
-|---|---|---|---|
-| 1 | `mapping:` provided | As specified | Explicit composite |
-| 2 | `name_currency` column exists | `name` + `name_currency` | Composite (multi-currency) |
-| 3 | `name == 'amount'` AND `currency` column exists | `amount` + `currency` | Composite (multi-currency) |
-| 4 | `name` column exists (no currency partner) | `name` alone | Single-column (fixed-currency) |
-| 5 | None of the above (name column missing) | `name_amount` + `name_currency` (convention) | Composite (multi-currency) |
+| 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) |
 
-Step 5 raises `ArgumentError` if the convention columns don't exist in the table.
+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).
 
 **Example**
 
@@ -316,7 +325,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  :surplus
   t.bigint  :tax
   t.decimal :total_amount
   t.string  :currency_code, limit: 3
@@ -327,47 +335,134 @@ end
 class FinancialTransaction < ApplicationRecord
   money_attribute :amount                   # step 3: amount(int) + currency
   money_attribute :discount                 # step 2: discount(int) + discount_currency
-  money_attribute :price                    # step 4: price_amount(dec) + price_currency
-  money_attribute :surplus, currency: 'EUR' # step 5: surplus(int) (single-column, will use EUR)
-  money_attribute :tax                      # step 5: tax(int) (single-column, will use default 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
 ```
 
 ## Querying
 
-Fixed-currency attributes support Rails-native querying through the custom type:
+### Rails-native queries
+
+Multi-currency (`money_attribute`) attributes support equality queries via `composed_of`:
+
+```ruby
+Offer.where(price: 10.to_money('EUR'))
+```
+
+For comparisons, use the backing columns directly:
+
+```ruby
+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:
 
 ```ruby
-# Equality
-Product.where(price: 10.to_money('USD'))
+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:
 
-# IN clause
-Product.where(price: [10.to_money('USD'), 20.to_money('USD')])
+#### `where_amount`
 
-# BETWEEN
-Product.where(price: 10.to_money('USD')..20.to_money('USD'))
+Filters by amount value. Accepts a scalar, Range, or Array.
 
-# Ordering
-Product.order(price: :desc)
+```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)
 
-# Aggregation
-Product.where(price: 10.to_money('USD')).sum(:price)
+Offer.where_amount(price: 10..50)           # => both records
 ```
 
-Multi-currency attributes support equality queries via `composed_of`:
+For integer (subunit) columns, pass `Mint::Money` objects directly — subunit conversion is handled automatically:
 
 ```ruby
-Offer.where(price: 10.to_money('EUR'))
+FinancialTransaction.where_amount(amount: [10.dollars, 10.yens])
+FinancialTransaction.where_amount(amount: 10.dollars..100.dollars)
 ```
 
-For comparisons on multi-currency attributes, use the backing columns directly:
+For decimal columns, raw numbers work:
 
 ```ruby
-Offer.where(price_amount: 10..20, price_currency: 'EUR')
-Offer.where('price_amount > ? AND price_currency = ?', 10, 'EUR')
+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)
+# => [Mint::Money(0, 'BRL')]  (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
 
 MoneyAttribute adds small helpers on `Numeric` and `String`:
@@ -378,7 +473,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
 
@@ -394,10 +489,67 @@ MoneyAttribute adds `money_field` and `money_amount_field` to Rails form builder
 <% end %>
 ```
 
+### 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.
+
+The accessor name must match the column name. `money_amount` does not support custom column mapping.
+
+#### Migration helpers
+
+| Method | Action |
+|---|---|
+| `add_money_amount` / `t.money_amount` | Amount column only |
+| `remove_money_amount` / `t.remove_money_amount` | Drops the column |
+
+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 :btc_balance, type: :crypto_decimal  # decimal(36,18)
+t.money_amount :qty,        type: :fiat_integer     # bigint
+```
+
+#### Naming
+
+| Migration call | Columns created | Model declaration |
+|---|---|---|
+| `t.money_amount :price` | `price` decimal(20,4) | `money_amount :price` |
+| `t.money_amount :btc, type: :crypto_decimal` | `btc` decimal(36,18) | `money_amount :btc` |
+| `t.money_amount :price, type: :fiat_integer` | `price` bigint | `money_amount :price` |
+| `t.money_amount :price, type: :fiat_decimal` | `price` decimal(20,4) | `money_amount :price` |
+
+#### Usage
+
+```ruby
+class Product < ApplicationRecord
+  money_amount :price
+end
+
+product = Product.new(price: 12)
+product.price # => [USD 12.00]
+
+Product.new(price: 12.to_money('EUR'))
+# => ArgumentError: ... has different currency. Only USD allowed.
+```
+
+#### Column type shortcut
+
+```ruby
+# Migration
+t.money_amount :price, type: :fiat_integer  # bigint column
+
+# Model
+money_amount :price
+```
+
+#### Querying
+
+Fixed-currency attributes support full Rails-native querying — see [Querying](#querying) for examples.
+
 ## Roadmap
 
 1. **Method-level currency** — lambda-based currency resolution for multi-tenant and instance-level scenarios
-2. Prepare to official 1.0 launh
 
 Contributions and suggestions are welcome — open an issue or PR at [gferraz/money-attribute](https://github.com/gferraz/money-attribute).
 

data/Rakefile

@@ -15,16 +15,60 @@ Rake::TestTask.new(:test_run) do |t|
 end
 
 desc 'Migrate test database'
-task :test_db_migrate do
-  Dir.chdir('test/dummy') do
-    sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate')
-  end
+task :test_db_migrate do # rubocop:disable Rails/RakeEnvironment
+  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]
 
+# --- Adapter-specific tasks ---
+
+%w[postgresql mysql2].each do |adapter|
+  namespace :test do
+    desc "Migrate test database (#{adapter})"
+    task "db_migrate:#{adapter}" do # rubocop:disable Rails/RakeEnvironment
+      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
+      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 # rubocop:disable Rails/RakeEnvironment
+  Rake::Task[:test].invoke
+  %w[postgresql mysql2].each do |adapter|
+    Rake::Task[:"test:#{adapter}"].invoke
+  end
+end
+
+# --- Benchmark ---
+
 desc 'Run money_attribute vs money-rails benchmark'
-task :bench do
-  sh({ 'RAILS_ENV' => 'test' }, 'bundle', 'exec', 'ruby', 'benchmark/comparison.rb')
+task bench: :test_db_migrate do
+  puts
+  puts '=' * 80
+  puts 'money_attribute (minting gem)'
+  puts '=' * 80
+  sh({ 'RAILS_ENV' => 'test', 'BENCH_SIDE' => 'minting' },
+     'bundle', 'exec', 'ruby', 'benchmark/comparison.rb')
+
+  puts
+  puts '=' * 80
+  puts 'money-rails (money gem)'
+  puts '=' * 80
+  sh({ 'RAILS_ENV' => 'test', 'BENCH_SIDE' => 'money_rails',
+       'BUNDLE_GEMFILE' => 'Gemfile.benchmark' },
+     'bundle', 'exec', 'ruby', 'benchmark/comparison.rb')
+end
+
+desc 'Generate consolidated benchmark report (markdown)'
+task 'bench:report' do # rubocop:disable Rails/RakeEnvironment
+  ruby 'benchmark/report.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