money_attribute 0.14.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd68138109c717791722388f0465c0bbd5296ffe2f30f2cb0521a74585f72483
-  data.tar.gz: 35b179441b1a9e8ef462fffcb0f9c4079929e3a1da6f775e82c67586dd952f2f
+  metadata.gz: bcfa5f42f59d3a7f372ddbff422a4e2aa45faccf4f5bd912fc2509e974bda609
+  data.tar.gz: 173509ac929dc32881a8bae54be2c3a7c0f92632ab8fae0192d84ae9b42433eb
 SHA512:
-  metadata.gz: '058e831db4a2bf193eda3117e83271c7b8ce7fa0e1be8a24dcd810e988cf7afd24fb7ed05f752a3f2368888f8051e9c117cd7311338a87a011cec80c783d2c12'
-  data.tar.gz: 24346e562f17164b1c1a478eca95b3e4eb38e023112a80bc5e626c6efffaf679c86ebda193fdac5f721f23304c66fcb4c4c54e68cdcb64f990bfaf88f7d9b5ca
+  metadata.gz: 18598feb924b703ae70e0fe68a76dd93d3ec9f22753d8556616d8c42ebae8460512e9451ed2e80b96feb44d380e8c03e1d2c0a23f22cf956773d001f5e27d83b
+  data.tar.gz: 1178b4b944cbd54b93d8d96f03a55403141086573d5f15f6225a820e65fb9a3e4fae7f0277518563274fa91a7dc7fd6a4ae889e1391dfb69efe72c07de0bb53a

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 |
 
-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.
+Default columns: `decimal(20,4)` for amount + `string(16)` for currency.
+
+### Column types
+
+| 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`:
@@ -195,33 +227,7 @@ If none of those keys are set, `format` is used as a plain string (simple format
 
 > 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).
 
 **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,29 @@ 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:
-
-```ruby
-# Equality
-Product.where(price: 10.to_money('USD'))
-
-# IN clause
-Product.where(price: [10.to_money('USD'), 20.to_money('USD')])
-
-# BETWEEN
-Product.where(price: 10.to_money('USD')..20.to_money('USD'))
-
-# Ordering
-Product.order(price: :desc)
-
-# Aggregation
-Product.where(price: 10.to_money('USD')).sum(:price)
-```
-
-Multi-currency attributes support equality queries via `composed_of`:
+Multi-currency (`money_attribute`) attributes support equality queries via `composed_of`:
 
 ```ruby
 Offer.where(price: 10.to_money('EUR'))
 ```
 
-For comparisons on multi-currency attributes, use the backing columns directly:
+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')
 ```
 
+For fixed-currency (`money_amount`) attributes, see the [single-column section](#single-column-mode--money_amount).
+
 ## Convenience methods
 
 MoneyAttribute adds small helpers on `Numeric` and `String`:
@@ -394,10 +384,73 @@ 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.
+
+#### 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 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
+```
+
 ## 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

@@ -16,15 +16,31 @@ end
 
 desc 'Migrate test database'
 task :test_db_migrate do
-  Dir.chdir('test/dummy') do
-    sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate')
-  end
+  sh({ 'RAILS_ENV' => 'test' }, 'bin/rails', 'db:migrate', chdir: 'test/dummy')
 end
 
 desc 'Run tests (migrates test DB first)'
 task test: %i[test_db_migrate test_run]
 
 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
+  ruby 'benchmark/report.rb'
 end

data/lib/money_attribute/configuration.rb

@@ -10,19 +10,18 @@ module MoneyAttribute
     end
   end
 
-  # Class-level caches — written during Rails boot (single-threaded),
-  # read-only during request handling. Safe without synchronization.
-  def self.config
-    @config ||= Configuration.new
-  end
+  cfg = Configuration.new
+  cached_default = nil
+
+  define_singleton_method(:config) { cfg }
 
-  def self.configure
-    yield config if block_given?
-    @default_currency = nil
-    config
+  define_singleton_method(:configure) do |&block|
+    block&.call(cfg)
+    cached_default = nil
+    cfg
   end
 
-  def self.default_currency
-    @default_currency ||= ::Mint::Currency.resolve!(config.default_currency)
+  define_singleton_method(:default_currency) do
+    cached_default ||= ::Mint::Currency.resolve!(cfg.default_currency)
   end
 end

data/lib/money_attribute/converter.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # :nodoc:
   class Converter
     def initialize(currency = MoneyAttribute.default_currency)
       @default_currency = currency
     end
 
-    def parse(amount, currency = @default_currency)
+    def parse(amount)
       case amount
-      when Mint::Money, NilClass then amount
-      when Numeric               then Mint::Money.from(amount, currency)
-      when String                then Mint.parse(amount, currency)
+      when Money, NilClass      then amount
+      when Numeric              then Money.from(amount, @default_currency)
+      when String               then Money.parse(amount, @default_currency)
       else raise ArgumentError, "Cannot convert #{amount.inspect} (#{amount.class}) to Money"
       end
     end
+
     alias call parse
   end
 end

data/lib/money_attribute/core_ext/string.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# :nodoc:
+class String
+  remove_method :to_money if method_defined?(:to_money)
+
+  def to_money(currency = MoneyAttribute.default_currency) = Money.parse(self, currency)
+end

data/lib/money_attribute/core_ext.rb

@@ -1,15 +1,8 @@
 # frozen_string_literal: true
 
-# :nodoc
+# :nodoc:
 class Numeric
-  remove_method :to_money
+  remove_method :to_money if method_defined?(:to_money)
 
   def to_money(currency = MoneyAttribute.default_currency) = Mint.money(self, currency)
 end
-
-# :nodoc
-class String
-  remove_method :to_money
-
-  def to_money(currency = MoneyAttribute.default_currency) = Mint.parse(self, currency)
-end

data/lib/money_attribute/form_builder_extension.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # :nodoc:
   module FormBuilderExtension
     def money_field(method, options = {})
       money = object.public_send(method)
-      value = money&.to_fs(:currency)
+      value = money&.to_fs
 
       @template.text_field_tag(field_name(method), value,
                                { id: field_id(method) }.merge(options))

data/lib/money_attribute/macro.rb

@@ -1,33 +1,19 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # :nodoc:
   module Macro
     extend ActiveSupport::Concern
 
-    class_methods do
-      def money_attribute(name, currency: MoneyAttribute.default_currency, mapping: nil)
+    # :nodoc:
+    module CompositeClassMethods
+      def resolve_composite_mapping(name)
         columns = attribute_names
-        currency = ::Mint::Currency.resolve!(currency)
-        name = name.to_s
-        resolved_mapping = mapping || resolve_mapping(name, columns)
-
-        if columns.include?(name) && resolved_mapping.nil?
-          define_single_column_money_attribute(name, currency)
-        else
-          define_composite_money_attribute(name, resolved_mapping, currency)
-        end
-      end
-
-      private
-
-      # --- Preparation (no side effects) ---
-
-      def resolve_mapping(name, columns)
-        return nil unless columns.include?(name)
-
         if columns.include?("#{name}_currency")
-          { amount: name, currency: :"#{name}_currency" }
-        elsif columns.include?('currency') && name == 'amount'
+          return { amount: name, currency: :"#{name}_currency" } if columns.include?(name)
+
+          nil
+        elsif name == 'amount' && columns.include?('currency')
           { amount: name, currency: :currency }
         end
       end
@@ -35,8 +21,8 @@ module MoneyAttribute
       def resolve_composite_for(name, mapping:)
         composite = { amount: "#{name}_amount", currency: "#{name}_currency" }
 
-        composite[:amount]    = mapping[:amount].to_s   if mapping&.key?(:amount)
-        composite[:currency]  = mapping[:currency].to_s if mapping&.key?(:currency)
+        composite[:amount]   = mapping[:amount].to_s if mapping&.key?(:amount)
+        composite[:currency] = mapping[:currency].to_s if mapping&.key?(:currency)
 
         assert_columns_exist!(name, composite)
         composite
@@ -57,17 +43,18 @@ module MoneyAttribute
       def money_constructor_for(amount_column)
         default = MoneyAttribute.default_currency
         if integer_column?(amount_column)
-          lambda { |amount, currency|
-            return nil if amount.nil?
-
-            Mint::Money.from_subunits(amount, currency.presence || default)
-          }
+          build_money_constructor(:from_subunits, default)
         else
-          lambda { |amount, currency|
-            return nil if amount.nil?
+          build_money_constructor(:from, default)
+        end
+      end
 
-            Mint::Money.from(amount, currency.presence || default)
-          }
+      def build_money_constructor(method, default)
+        lambda do |amount, currency|
+          next nil if amount.nil?
+
+          resolved = Mint::Currency.resolve(currency.presence || default) || 'XXX'
+          Mint::Money.public_send(method, amount, resolved)
         end
       end
 
@@ -76,14 +63,6 @@ module MoneyAttribute
         %i[integer bigint].include?(col&.type)
       end
 
-      # --- Configuration (registers types, normalizers, composed_of) ---
-
-      def define_single_column_money_attribute(name, currency)
-        column_type = integer_column?(name) ? ActiveRecord::Type::Integer.new : ActiveRecord::Type::Decimal.new
-        attribute(name.to_sym, :mint_money, currency:, column_type: column_type)
-        normalizes(name.to_sym, with: Converter.new(currency))
-      end
-
       def define_composite_money_attribute(name, mapping, currency)
         aggregated = resolve_composite_for(name, mapping:)
 
@@ -99,5 +78,26 @@ module MoneyAttribute
                     })
       end
     end
+
+    class_methods do
+      def money_attribute(name, currency: MoneyAttribute.default_currency, mapping: nil)
+        name = name.to_s
+        currency = ::Mint::Currency.resolve!(currency)
+        resolved_mapping = mapping || resolve_composite_mapping(name)
+
+        if resolved_mapping.nil? && attribute_names.include?(name)
+          raise ArgumentError,
+                "Column '#{name}' exists but no '#{name}_currency' column was found. " \
+                'For single-column fixed-currency attributes, use `money_amount` ' \
+                'instead of `money_attribute`.'
+        end
+
+        define_composite_money_attribute(name, resolved_mapping || {}, currency)
+      end
+    end
+
+    included do
+      extend CompositeClassMethods
+    end
   end
 end

data/lib/money_attribute/migration_extensions/helper.rb

@@ -2,61 +2,69 @@
 
 module MoneyAttribute
   module MigrationExtensions
+    # :nodoc:
     module Helper
-      private
+      AMOUNT_CONFIG = {
+        crypto_decimal: { type: :decimal, precision: 36, scale: 18 },
+        fiat_decimal: { type: :decimal, precision: 20, scale: 4 },
+        fiat_integer: { type: :bigint }
+      }.freeze
 
-      def parse_money_args(accessor, options = {})
-        name = accessor.to_s
+      CURRENCY_MIN_LIMIT = 8
+      CURRENCY_DEFAULT_LIMIT = 20
+
+      private
 
-        if options.key?(:amount) && options[:amount].is_a?(Hash)
-          amount_col = options[:amount][:column]&.to_s || name
-          opts = options[:amount]
-          amount_opts = {
-            type: opts[:type],
-            null: opts[:null],
-            default: opts[:default],
-            precision: opts[:precision],
-            scale: opts[:scale]
-          }.compact
-        else
-          amount_col = name
-          amount_opts = {}
+      def parse_money_amount_args(accessor, options)
+        options ||= {}
+        if options.key?(:precision) || options.key?(:scale)
+          raise ArgumentError,
+                'precision:/scale: are not configurable — money_attribute uses fixed, ' \
+                'vetted values per type (:crypto_decimal, :fiat_decimal, :fiat_integer) ' \
+                'to prevent under-precision bugs, particularly for crypto amounts.'
         end
 
-        amount_opts[:type] ||= :decimal
+        column = (options[:column] || accessor).to_s
 
-        if amount_opts[:type] == :decimal && !amount_opts.key?(:precision) && !amount_opts.key?(:scale)
-          amount_opts[:precision] = 16
-          amount_opts[:scale]     = 4
-        elsif amount_opts[:type] != :decimal
-          amount_opts.delete(:precision)
-          amount_opts.delete(:scale)
+        config = AMOUNT_CONFIG[options[:type] || :fiat_decimal]
+        unless config
+          raise ArgumentError,
+                "Invalid money amount type #{options[:type]}. Use :crypto_decimal, :fiat_decimal or :fiat_integer"
         end
 
-        stripped = name.end_with?('_amount') ? name.sub(/_amount$/, '') : name
-        default_currency_col = if name == 'amount' && !(options[:currency].is_a?(Hash) && options[:currency][:column])
-                                 'currency'
-                               else
-                                 "#{stripped}_currency"
-                               end
-
-        if options.key?(:currency) && options[:currency].is_a?(Hash)
-          currency_col = options[:currency][:column]&.to_s || default_currency_col
-          opts = options[:currency]
-          currency_opts = {
-            limit: opts[:limit],
-            null: opts[:null],
-            default: opts[:default]
-          }.compact
-        elsif options[:currency] == false
-          currency_col = nil
-          currency_opts = {}
-        else
-          currency_col = default_currency_col
-          currency_opts = {}
+        options = { null: options[:null], default: options[:default] }.compact
+        [column, config.merge(options)]
+      end
+
+      def parse_currency_args(accessor, options)
+        options ||= {}
+        limit = (options[:limit] || CURRENCY_DEFAULT_LIMIT).to_i
+        if limit < CURRENCY_MIN_LIMIT
+          raise ArgumentError,
+                "currency limit: #{limit} is too small to hold an ISO 4217 code and crypto popular codes" \
+                "(minimum #{CURRENCY_MIN_LIMIT}). Omit limit: to use the default of #{CURRENCY_DEFAULT_LIMIT}, " \
+                "or pass a value >= #{CURRENCY_MIN_LIMIT}."
         end
 
-        [amount_col, currency_col, amount_opts, currency_opts]
+        column = currency_column_name(accessor, options[:column])
+        [column, { limit:, null: options[:null], default: options[:default] }.compact]
+      end
+
+      def currency_column_name(accessor, column_override)
+        return column_override.to_s if column_override
+
+        name = accessor.to_s
+        return 'currency' if name == 'amount'
+
+        radical = name.end_with?('_amount') ? name.sub(/_amount$/, '') : name
+        "#{radical}_currency"
+      end
+
+      def parse_money_args(accessor, options = {})
+        amount_column, amount_options = parse_money_amount_args(accessor, options[:amount])
+        currency_column, currency_options = parse_currency_args(accessor, options[:currency])
+
+        [amount_column, currency_column, amount_options, currency_options]
       end
     end
   end

data/lib/money_attribute/migration_extensions/schema_statements.rb

@@ -4,21 +4,34 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
+    # :nodoc:
     module SchemaStatements
       include Helper
 
       def add_money_attribute(table_name, accessor, options = {})
         amount_col, currency_col, amount_opts, currency_opts = parse_money_args(accessor, options)
 
-        add_column(table_name, amount_col, amount_opts[:type], **amount_opts.except(:type))
-        add_column(table_name, currency_col, :string, **currency_opts) if currency_col
+        type = amount_opts.delete(:type)
+        add_column(table_name, amount_col, type, **amount_opts)
+        add_column(table_name, currency_col, :string, **currency_opts)
       end
 
       def remove_money_attribute(table_name, accessor, options = {})
         amount_col, currency_col, = parse_money_args(accessor, options)
 
         remove_column(table_name, amount_col)
-        remove_column(table_name, currency_col) if currency_col
+        remove_column(table_name, currency_col)
+      end
+
+      def add_money_amount(table_name, accessor, options = {})
+        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+
+        type = amount_opts.delete(:type)
+        add_column(table_name, amount_col, type, **amount_opts)
+      end
+
+      def remove_money_amount(table_name, accessor, options = {})
+        remove_column(table_name, (options[:column] || accessor).to_s)
       end
     end
   end

data/lib/money_attribute/migration_extensions/table_definition.rb

@@ -4,6 +4,7 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
+    # :nodoc:
     module TableDefinition
       include Helper
 
@@ -11,14 +12,26 @@ module MoneyAttribute
         amount_col, currency_col, amount_opts, currency_opts = parse_money_args(accessor, options)
 
         column(amount_col, amount_opts[:type], **amount_opts.except(:type))
-        column(currency_col, :string, **currency_opts) if currency_col
+        column(currency_col, :string, **currency_opts)
       end
 
       def remove_money_attribute(accessor, options = {})
         amount_col, currency_col, = parse_money_args(accessor, options)
 
         remove_column(amount_col)
-        remove_column(currency_col) if currency_col
+        remove_column(currency_col)
+      end
+
+      def money_amount(accessor, options = {})
+        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+
+        column(amount_col, amount_opts[:type], **amount_opts.except(:type))
+      end
+
+      def remove_money_amount(accessor, options = {})
+        amount_col, = parse_money_amount_args(accessor, options)
+
+        remove_column(amount_col)
       end
     end
   end

data/lib/money_attribute/money_amount.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # :nodoc:
+  module MoneyAmount
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def money_amount(name)
+        name = name.to_s
+
+        assert_column_exists!(name)
+
+        currency = ::Mint::Currency.resolve!(MoneyAttribute.default_currency)
+        column_type = detect_column_type(name)
+
+        attribute(name.to_sym, MoneyAttribute::Type.new(currency:, column_type:))
+        normalizes(name.to_sym, with: Converter.new)
+      end
+
+      private
+
+      def assert_column_exists!(name)
+        return if attribute_names.include?(name)
+
+        raise ArgumentError,
+              "Column '#{name}' does not exist on this table. " \
+              "Add a column named '#{name}' or use a different accessor name."
+      end
+
+      def detect_column_type(name)
+        col = columns.find { |c| c.name == name }
+        %i[integer bigint].include?(col&.type) ? ActiveRecord::Type::Integer.new : ActiveRecord::Type::Decimal.new
+      end
+    end
+  end
+end

data/lib/money_attribute/railtie.rb

@@ -21,24 +21,34 @@ module MoneyAttribute
     end
 
     def self.setup_locale_backend!
-      ::Mint.locale_backend = lambda {
-        fmt = I18n.t('number.currency.format', default: {})
-        translator = ->(s) { s&.gsub('%n', '%<amount>f')&.gsub('%u', '%<symbol>s') }
-
-        format = if fmt.key?(:positive) || fmt.key?(:negative) || fmt.key?(:zero)
-                   {
-                     positive: translator.call(fmt[:positive] || fmt[:format]),
-                     negative: translator.call(fmt[:negative] || fmt[:format]),
-                     zero: translator.call(fmt[:zero] || fmt[:format])
-                   }
-                 else
-                   translator.call(fmt[:format])
-                 end
-
-        { decimal: fmt[:separator], thousand: fmt[:delimiter], format: format }
+      ::Mint.locale_backend = method(:build_locale_format).to_proc
+    end
+
+    def self.build_locale_format
+      fmt = I18n.t('number.currency.format', default: {})
+      { decimal: fmt[:separator], thousand: fmt[:delimiter], format: build_format(fmt) }
+    end
+
+    def self.build_format(fmt)
+      if %i[positive negative zero].any? { |k| fmt.key?(k) }
+        build_hash_format(fmt)
+      else
+        translate_format(fmt[:format])
+      end
+    end
+
+    def self.build_hash_format(fmt)
+      {
+        positive: translate_format(fmt[:positive] || fmt[:format]),
+        negative: translate_format(fmt[:negative] || fmt[:format]),
+        zero: translate_format(fmt[:zero] || fmt[:format])
       }
     end
 
+    def self.translate_format(str)
+      str.to_s.gsub('%n', '%<amount>f').gsub('%u', '%<symbol>s')
+    end
+
     def self.register_custom_currencies!
       Array(MoneyAttribute.config.added_currencies).each do |currency_data|
         if currency_data.respond_to?(:values_at)

data/lib/money_attribute/type.rb

@@ -10,9 +10,10 @@ module MoneyAttribute
     end
 
     def cast(value)
-      case value
-      when String then Mint::Money.parse(value, @currency)
-      else             super
+      if value.is_a?(String)
+        Mint::Money.parse(value, @currency)
+      else
+        super
       end
     end
 
@@ -48,13 +49,10 @@ module MoneyAttribute
         value.to_d
       end
     end
-
-    def self.type = :mint_money
   end
 end
 
 ActiveSupport.on_load(:active_record) do
   include MoneyAttribute::Macro
-
-  ActiveRecord::Type.register(:mint_money, MoneyAttribute::Type)
+  include MoneyAttribute::MoneyAmount
 end

data/lib/money_attribute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  VERSION = '0.14.5'
+  VERSION = '1.1.0'
 end

data/lib/money_attribute.rb

@@ -2,8 +2,10 @@
 
 require 'minting'
 require 'money_attribute/core_ext'
+require 'money_attribute/core_ext/string'
 require 'money_attribute/configuration'
 require 'money_attribute/macro'
+require 'money_attribute/money_amount'
 require 'money_attribute/converter'
 require 'money_attribute/type'
 require 'money_attribute/form_builder_extension'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: money_attribute
 version: !ruby/object:Gem::Version
-  version: 0.14.5
+  version: 1.1.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.9.0
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.9.0
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.3.2
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.3.2
+        version: '7.1'
 description: Easily add money attributes to your Rails models
 email:
 - gilson@cesar.etc.br
@@ -53,11 +53,13 @@ files:
 - lib/money_attribute/configuration.rb
 - lib/money_attribute/converter.rb
 - lib/money_attribute/core_ext.rb
+- lib/money_attribute/core_ext/string.rb
 - lib/money_attribute/form_builder_extension.rb
 - lib/money_attribute/macro.rb
 - lib/money_attribute/migration_extensions/helper.rb
 - lib/money_attribute/migration_extensions/schema_statements.rb
 - lib/money_attribute/migration_extensions/table_definition.rb
+- lib/money_attribute/money_amount.rb
 - lib/money_attribute/railtie.rb
 - lib/money_attribute/type.rb
 - lib/money_attribute/version.rb