minting 1.9.6 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51f0a76084db98e53f29af4f82f1284f749c9691727a7a84a7f8cc758d1a9f67
-  data.tar.gz: f24a130df454ee80f923aa42fd995e4b3eaf2f4f16d1a6f3a9e84548c08a4988
+  metadata.gz: 20bb9d0f4d0437f84ab790d3fdbd27650bee49d0b9d1231b3ba19888987583b4
+  data.tar.gz: 8787d2359db2b7c75a2054fdcc6d56525e819f25b4d1cc746d2d6bcb01fd03ff
 SHA512:
-  metadata.gz: 42ed5e90ba4a936426344cfd1f8aad69755038704c53b67d8f714ced040661e2f37829aa44d2d67f12575596656b7d9bd5b80058995b57875aaa46b2cf6dd291
-  data.tar.gz: a6490a3356b949df6889e72ee3fc885a4e10af8d14e09591d7bd615ea468371c30b1695b73e996cb91526ab824a610e2667797eb24e94144ec46ddd22dc42395
+  metadata.gz: 29d3c3b52a8f5786587caf516fce6828341ec10ca6dd57f2882b9fb6dda13ae136237d3fe087613d6a832553be05a5bb1fb3e77d54952d030fdca87a879923e2
+  data.tar.gz: f5d8ef6c9bb9bffdbe9b7b84b94badb678d4a04a4648b63fa49b9e0086130d0abf73bd20988c6e544b7b154e671677ae0d06bc3dcc739ce410e034b5fedd53fe

data/README.md

@@ -1,41 +1,68 @@
-# Minting
-
-Fast, precise, and developer-friendly money handling for Ruby.
-
 [![Gem Version](https://badge.fury.io/rb/minting.svg)](https://badge.fury.io/rb/minting)
 [![CI](https://github.com/gferraz/minting/actions/workflows/ci.yml/badge.svg)](https://github.com/gferraz/minting/actions/workflows/ci.yml)
 [![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/gferraz/minting)
 [![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://www.rubydoc.info/gems/minting/frames)
 
-## Quick start
+# Minting
 
-```ruby
-require 'minting'
+**Fast, precise, and developer-friendly money handling for Ruby.**
 
-price = Mint.money(19.99, 'USD')       #=> [USD 19.99]
+
+
+> **Status:** Minting 2.0 is released. The core API (`Money`, `Currency`, formatting, parsing) is stable.
+
+```ruby
+price = Money.from(19.99, 'USD')       #=> [USD 19.99]
 tax   = price * 0.08                   #=> [USD 1.60]
 total = price + tax                    #=> [USD 21.59]
 
 total.to_s                             #=> "$21.59"
-total.currency_code                    #=> "USD"
 ```
 
-### Exact precision
-Amounts are stored as `Rational` and rounded to the currency subunit. No floating-point surprises, ever.
+Amounts are stored as `Rational`, so there's no floating-point drift — `0.1 + 0.2` problems simply don't happen here, at any scale.
+
+## Table of contents
 
-### Blazing performance
-Minting is faster than the Money gem for everyday operations and **over 10× faster for formatting**. See full benchmarks in the [Performance Guide](test/performance/BENCHMARKS.md).
+- [Why Minting](#why-minting)
+- [How it compares](#how-it-compares)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Creating & comparing money](#creating--comparing-money)
+  - [Formatting](#formatting)
+  - [Integral & fractional parts](#integral--fractional-parts)
+  - [Parsing strings](#parsing-strings)
+  - [Currency lookup](#currency-lookup)
+  - [Crypto currencies](#crypto-currencies)
+  - [Locale formatting](#locale-formatting)
+- [API notes](#api-notes)
+- [Optional top-level `Money` and `Currency`](#optional-top-level-money-and-currency)
+- [Rails integration](#rails-integration)
+- [Roadmap](#roadmap)
+- [License](#license)
 
-### Clean, modern API
-Intuitive interface, descriptive error messages, and sensible defaults. Works the way you expect.
+## Why Minting
 
-### Rails-ready
-Use with the [attribute-money](https://github.com/gferraz/attribute-money) companion gem for drop-in ActiveRecord type casting, validators, and form helpers.
+Minting started as a personal project to learn what it actually takes to build and maintain a real open source Ruby gem — not exactly as a reaction against any existing library. That origin shows in how it's built: it's grown deliberately, with an emphasis on correctness and a clean API.
 
-### Quality code
-- **100% test coverage** — every line exercised
-- **94/100 RubyCritic score** — clean, maintainable code
-- **CI-tested on Ruby 3.3 and 4.0**
+What it's become along the way:
+
+- **Exact by construction** — amounts are `Rational` internally, rounded to the currency's subunit only when needed. No silent precision loss from repeated arithmetic.
+- **No Rails dependency** — Minting is a plain Ruby gem. Use it in a script, a Sinatra app, a background job runner, or a Rails app — your choice, not the gem's.
+- **Formatting that doesn't fight you** — `Kernel.format`-style templates, named presets (`:accounting`, `:european`), per-sign formats (parentheses for negatives), and a pluggable locale hook.
+- **Built for real-world currency handling** — 150+ ISO-4217 currencies, correct subunit handling (JPY has none, KWD has three), proportional allocation/split that doesn't lose cents to rounding.
+- **Measured, not assumed, performance** — see the [Performance Guide](bench/BENCHMARKS.md) for actual benchmarks rather than claims.
+- **Rails-ready without being Rails-only** — pair with the companion [MoneyAttribute](https://github.com/gferraz/money-attribute) gem for `ActiveRecord` type casting, validators, and form helpers.
+
+## How it compares
+
+A few structural differences from the `money` gem (and `money-rails`), for anyone evaluating both:
+
+| | **Minting** | **Money** |
+|---|---|---|
+| Internal representation | `Rational` | `BigDecimal` (float-backed input coercion) |
+| Rails integration | via `money_attribute` gem | via `money-rails` gem |
+| Exchange rates | Pluggable provider architecture *(planned)* | Built-in bank/exchange abstraction |
+| Currency data | Ships with the gem | Ships with the gem |
 
 ## Installation
 
@@ -51,172 +78,259 @@ gem 'minting'
 
 ## Usage
 
+### Creating & comparing money
+
 ```ruby
 require 'minting'
 
-# Create money
-ten = Mint.money(10, 'USD')            #=> [USD 10.00]
+ten = Money.from(10, 'USD')            #=> [USD 10.00]
 
-1.dollar == Mint.money(1, 'USD') #=> true
-ten = 10.dollars                 #=> [USD 10.00]
-4.to_money('USD')                #=> [USD 4.00]
+1.dollar == Money.from(1, 'USD')       #=> true
+ten = 10.dollars                       #=> [USD 10.00]
+4.to_money('USD')                      #=> [USD 4.00]
 
 # Comparisons
-ten == 10.dollars                #=> true
-ten == Mint.money(10, 'EUR')     #=> false
-ten > Mint.money(9.99, 'USD')    #=> true
+ten == 10.dollars                      #=> true
+ten == Money.from(10, 'EUR')           #=> false
+ten > Money.from(9.99, 'USD')          #=> true
 
 # Zero equality semantics
 # Any zero amount is treated as equal, regardless of currency
-Mint.money(0, 'USD') == Mint.money(0, 'EUR')   #=> true
-Mint.money(0, 'USD') == 0                      #=> true
-Mint.money(0, 'USD') == 0.0                    #=> true
+Money.from(0, 'USD') == Money.from(0, 'EUR')   #=> true
+Money.from(0, 'USD') == 0                      #=> true
+Money.from(0, 'USD') == 0.0                    #=> true
 
 # Non-zero numerics are not equal to Money objects
-Mint.money(10, 'USD') == 10                    #=> false
+Money.from(10, 'USD') == 10                    #=> false
 
-# Format (uses Kernel.format syntax)
-price = Mint.money(9.99, 'USD')
-loss  = Mint.money(-1234.56, 'USD')
+# Ranges and enumeration are supported
+1.dollar..10.dollars                      #=> [USD 1.00]..[USD 10.00]
+(1.dollar..3.dollars).step(1.dollar).to_a #=> [[USD 1.00], [USD 2.00], [USD 3.00]]
 
-# Built-in named presets
-loss.format(:accounting)                      #=> "($1,234.56)"
-Mint.money(1234.56, 'EUR').format(:european)  #=> "1.234,56 €"
-price.format(:amount)                         #=> "9.99"
-price.format(:currency)                       #=> "USD 9.99"
+# Clamping to a range
+price = Money.from(50, 'USD')
+min_price = Money.from(75, 'USD')
 
-# Presets can be overridden with explicit kwargs
-Mint.money(1234.56, 'EUR').format(:european, format: '%<amount>f %<currency>s')
-#=> "1.234,56 EUR"
+price.clamp(0, 100)          #=> [USD 50.00]  (returns self, no new object)
+price.clamp(0, 25)           #=> [USD 25.00]  (clamped to max)
+price.clamp(min_price, 100)  #=> [USD 75.00]  (clamped to min, Money or Numeric bounds both work)
+```
 
-# Or use direct format strings
-price.format                                  #=> "$9.99",
-price.format(format: '%<amount>d')            #=> "9",
-price.format(format: '%<symbol>s%<amount>f')  #=> "$9.99",
-price.format(format: '%<symbol>s%<amount>+f') #=> "$+9.99",
-(-price).format(format: '%<amount>f')         #=> "-9.99",
+### Formatting
 
-# Format with padding
-price_in_euros = Mint.money(12.34, 'EUR')
+```ruby
+price = Money.from(9.99, 'USD')
+
+# Use direct format strings
+price.format                                  #=> "$9.99"
+price.format('%<amount>d')            #=> "9"
+price.format('%<symbol>s%<amount>f')  #=> "$9.99"
+price.format('%<symbol>s%<amount>+f') #=> "$+9.99"
+(-price).format('%<amount>f')         #=> "-9.99"
 
-price.format(format: '--%<amount>7d')               #=> "--      9"
-price.format(format: '  %<amount>10f %<currency>s') #=> "        9.99 USD"
-(-price).format(format: '  %<amount>10f')           #=> "       -9.99"
+# Format with padding
+price_in_euros = Money.from(12.34, 'EUR')
 
-price_in_euros.format(format: '%<symbol>2s%<amount>+10f')    #=> " €    +12.34"
+price.format('--%<amount>7d')               #=> "--      9"
+price.format('  %<amount>10f %<currency>s') #=> "        9.99 USD"
+(-price).format('  %<amount>10f')           #=> "       -9.99"
+price_in_euros.format('%<symbol>2s%<amount>+10f')    #=> " €    +12.34"
 
 # Integral & fractional parts
-price.format(format: '%<integral>d %<fractional>d/100')        #=> "9 99/100"
-Mint.money(0.99, 'USD').format(format: '%<integral>d dollars and %<fractional>02d cents')
+price.format('%<integral>d %<fractional>d/100')        #=> "9 99/100"
+Money.from(0.99, 'USD').format('%<integral>d dollars and %<fractional>02d cents')
 #=> "0 dollars and 99 cents"
 
 # Per-sign Hash format (e.g. accounting parentheses for losses)
-loss = Mint.money(-1234.56, 'USD')
-loss.format(format: { negative: '(%<symbol>s%<amount>f)' })  #=> "($1,234.56)"
-Mint.money(0, 'BRL').format(format: { zero: '--' })          #=> "--"
-# All three keys at once:
+loss.format( { negative: '(%<symbol>s%<amount>f)' })  #=> "($1,234.56)"
+Money.from(0, 'BRL').format( { zero: '--' })          #=> "--"
 fmt = { positive: '%<symbol>s%<amount>f', negative: '(%<symbol>s%<amount>f)', zero: '--' }
-Mint.money(1234.56, 'USD').format(format: fmt)               #=> "$1,234.56"
+Money.from(1234.56, 'USD').format( fmt)               #=> "$1,234.56"
 
-# Json serialization
+# Disambiguated symbol (e.g. "US$" vs "C$" vs "A$")
+Money.from(10, 'USD').format('%<dsymbol>s%<amount>f')  #=> "US$10.00"
+Money.from(10, 'CAD').format('%<dsymbol>s%<amount>f')  #=> "C$10.00"
+Money.from(10, 'EUR').format('%<dsymbol>s%<amount>f')  #=> "€10.00" (falls back to symbol)
 
-price.to_json # => "{\"currency\": \"USD\", \"amount\": \"9.99\"}"
-
-# Hash conversion
-
-price.to_hash #=> {currency: "USD", amount: "9.99"}
+# Hash serialization
+price.to_hash   #=> {currency: "USD", amount: "9.99"}
+```
 
+### Integral & fractional parts
 
-# Fractional units (inverse of #fractional) - exact integer arithmetic
+```ruby
+price.integral    #=> 9         # whole-unit part
+price.fractional  #=> 99        # fractional part (subunits within one unit)
+price.subunits    #=> 999       # total amount in smallest unit
+price.to_i        #=> 9         # alias of integral
 
-price.subunits                        #=> 999
-Mint::Money.from_subunits(999, 'USD') #=> [USD 9.99]
+Mint::Money.from_subunits(999, 'USD')  #=> [USD 9.99]
 Mint::Money.from_subunits(1234, 'JPY') #=> [JPY 1234]  # subunit 0 -> no scaling
 
-
 # No currency (ISO 4217 XXX)
-
 Mint::Money.no_currency(100) #=> [XXX 100]
 Mint::Money.no_currency(0)   #=> [XXX 0]
 
-
 # Proportional allocation and split
+ten = 10.dollars
+ten.split(3)                 #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
+ten.allocate([1, 2, 3])       #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
+```
 
-ten.split(3)                           #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
-ten.allocate([1, 2, 3])                #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
+### Parsing strings
 
-# Clamping to a range
+```ruby
+Money.parse('$19.99')           #=> [USD 19.99]
+Money.parse('19,99 €')          #=> [EUR 19.99]
+Money.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
+Money.parse('USD 1,234.56')     #=> [USD 1234.56]
+```
 
-price = Mint.money(50, 'USD')
-min_price = Mint.money(75, 'USD')
+Notes:
+- Pass a currency code when the string has no symbol or code.
+- `1,234` means 1234, not 1.234, and `1,23` means 1.23, not 123.
+- `1,234.00` is unambiguous (thousands + decimal).
+- Accounting negatives like `($1.23)` or `(USD 10.00)` are supported — the parser detects parentheses and negates the amount.
+- Ambiguous symbols like `$` resolve by currency priority (currently USD).
+- The parser scans all uppercase words for registered codes, so spurious non-currency words before the real code are correctly ignored: `Money.parse("MAX 10.00 USD")` yields `[USD 10.00]`.
 
-price.clamp(0, 100)                    #=> [USD 50.00]  (returns self, no new object)
-price.clamp(0, 25)                     #=> [USD 25.00]  (clamped to max)
-price.clamp(min_price, 100)                   #=> [USD 75.00]  (clamped to min)
+### Currency lookup
 
-# Clamp accepts Money bounds or Numeric amounts
-price.clamp(min_price, 100) #=> [USD 75.00]
+```ruby
+# All registered currencies (150+ ISO 4217 + custom)
+Money::Currency.registered_currencies.size                 #=> 154
+Money::Currency.registered_currencies.each { |code, c| puts "#{code}: #{c.name}" }
 
-# Ranges and enumeration are supported
+# Built-in ISO 4217 currencies (before custom registrations)
+Money::Currency.world_currencies.size    #=> 154
 
-1.dollar..10.dollars                      #=> [USD 1.00]..[USD 10.00]
-(1.dollar..3.dollars).step(1.dollar).to_a #=> [[USD 1.00], [USD 2.00], [USD 3.00]]
+# By ISO code (direct hash lookup, string only)
+Money::Currency.for_code('USD')        #=> #<Currency code="USD" ...>
 
+# By display symbol (highest-priority currency for ambiguous symbols)
+Money::Currency.for_symbol('$')        #=> #<Currency code="USD" ...>
+Money::Currency.for_symbol('R$')       #=> #<Currency code="BRL" ...>
+Money::Currency.for_symbol('€')        #=> #<Currency code="EUR" ...>
 ```
 
-## Parsing strings
+**Polymorphic currency resolution** — `Currency.resolve` also accepts objects that implement `#to_currency` or `#currency_code`:
 
 ```ruby
-Mint.parse('$19.99')           #=> [USD 19.99]
-Mint.parse('19,99 €')          #=> [EUR 19.99]
-Mint.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
-Mint.parse('USD 1,234.56')     #=> [USD 1234.56]
+class Product
+  def currency_code = 'USD'
+end
+
+Money::Currency.resolve(Product.new)  #=> #<Currency code="USD" ...>
+Money::Currency.resolve!(Product.new) # raises Mint::UnknownCurrency if code is unknown
 ```
 
-Notes:
-- Pass a currency code when the string has no symbol or code.
-- `1,234` means 1234, not 1.234 and `1,23` means 1.23, not 123
-- `1,234.00` is unambiguous (thousands + decimal).
-- Accounting negatives like `($1.23)` or `(USD 10.00)` are supported — the parser detects parentheses and negates the amount.
-- Ambiguous symbols like `$` resolve by currency priority (currently USD).
-- The parser scans all uppercase words for registered codes, so spurious non-currency words before the real code are correctly ignored: `Mint.parse("MAX 10.00 USD")` yields `[USD 10.00]`.
+`#to_currency` takes precedence when both methods exist. It must return a `Currency` object; `#currency_code` must return a `String`. Wrong types raise `ArgumentError`.
 
-## Currency lookup
+### Crypto currencies
+
+Minting ships with opt-in definitions for ~25 popular crypto currencies (BTC, ETH, SOL, ...). They are not registered by default — use `register_crypto` to enable them:
 
 ```ruby
-# By ISO code (direct hash lookup, string only)
-Mint::Currency.for_code('USD')        #=> #<Currency code="USD" ...>
+Currency.register_crypto('BTC', 'ETH', 'SOL')
 
-# By display symbol (highest-priority currency for ambiguous symbols)
-Mint::Currency.for_symbol('$')        #=> #<Currency code="USD" ...>
-Mint::Currency.for_symbol('R$')       #=> #<Currency code="BRL" ...>
-Mint::Currency.for_symbol('€')        #=> #<Currency code="EUR" ...>
+Money.parse("0.01 BTC")    #=> [BTC 0.01000000]
+Mint.money(1, 'ETH')      #=> [ETH 1.000000000000000000]
+```
+
+`Currency.crypto_currencies` lists all available definitions without registering:
 
+```ruby
+Currency.crypto_currencies.each { |c| puts "#{c.code}: #{c.name}" }
+# BTC: Bitcoin
+# ETH: Ethereum
+# SOL: Solana
+# ...
+```
+
+`register_crypto` raises `KeyError` on duplicate codes and `ArgumentError` on unknown codes. Register all at once:
+
+```ruby
+# Register all at once:
+Currency.register_all_crypto   # raises KeyError on any conflict
+```
+
+`Currency.crypto_currencies` lists all available definitions without registering:
+
+```ruby
+Currency.crypto_currencies.each { |c| puts "#{c.code}: #{c.name}" }
+# BTC: Bitcoin
+# ETH: Ethereum
+# SOL: Solana
+# ...
+```
+
+### Locale formatting
+
+Minting doesn't ship built-in locale data, but the `Mint.locale_backend` hook lets you wire in locale-specific decimal/thousand separators and format templates:
+
+```ruby
+LOCALE_DATA = {
+  'en'    => { decimal: '.', thousand: ',', format: '%<symbol>s%<amount>f' },
+  'pt'    => { decimal: ',', thousand: '.', format: '%<symbol>s%<amount>f' },
+  'pt-BR' => { decimal: ',', thousand: '.', format: '%<symbol>s%<amount>f' },
+  'de'    => { decimal: ',', thousand: '.', format: '%<amount>f %<currency>s' },
+  'fr'    => { decimal: ',', thousand: ' ', format: '%<amount>f %<symbol>s' },
+  'ja'    => { decimal: '.', thousand: ',', format: '%<symbol>s%<amount>f' },
+}.freeze
+
+Mint.locale_backend = ->(locale) { LOCALE_DATA[locale.to_s] || {} }
+
+Mint.money(1234.56, 'USD').format(locale: :en)  #=> "$1,234.56"
+Mint.money(9.99, 'BRL').format(locale: 'pt')    #=> "R$9,99"
+Mint.money(9.99, 'EUR').format(locale: :de)     #=> "9,99 EUR"
+Mint.money(9.99, 'EUR').format(locale: 'fr')    #=> "9,99 €"
+Mint.money(9.99, 'USD').format(locale: :ja)     #=> "$9.99"
+```
+
+Pass `locale:` as a keyword to `format` / `to_fs`. Accepts both symbols (`:en`, `:'pt-BR'`) and strings (`'pt-BR'`, `'en-US'`) — passed through as-is, matching Rails' `I18n.locale` convention. The backend returns a hash with `:decimal`, `:thousand`, and optionally `:format` (defaults to `'%<symbol>s%<amount>f'`). String and symbol keys are interchangeable. Return `{}` or `nil` for unknown locales — defaults apply.
+
+Rails I18n key names (`:separator`, `:delimiter`) are also accepted — no mapping needed:
+
+```ruby
+Mint.locale_backend = ->(locale = nil) {
+  I18n.with_locale(locale || I18n.default_locale) do
+    I18n.t('number.currency.format', default: {})
+  end
+}
+```
+
+Minting names take precedence when both are present (e.g. `{ decimal: '.', separator: ',' }` uses `'.'`).
+
+Arity-0 callables (`-> { ... }`) are called without arguments and work unchanged:
+
+```ruby
+Mint.locale_backend = -> { { decimal: ',', thousand: '.' } }
+Mint.money(9.99, 'BRL').format  #=> "R$9,99"
 ```
 
 ## API notes
 
 **Exact amounts** — Amounts are stored as `Rational` and rounded to the currency subunit.
 
-**Rounding modes** — Wrap operations in `Mint.with_rounding(mode)` to change how amounts are rounded to the subunit:
+**Rounding modes** — Wrap operations in `Money.with_rounding(mode)` to change how amounts are rounded to the subunit:
 
 ```ruby
-Mint.with_rounding(:half_down) { Mint.money(1.005, 'USD') }  #=> [USD 1.00]
-Mint.with_rounding(:ceil)      { Mint.money(1.001, 'USD') }  #=> [USD 1.01]
-Mint.with_rounding(:floor)     { Mint.parse('1.009', 'USD') } #=> [USD 1.00]
+Money.with_rounding(:half_down) { Money.from(1.005, 'USD') }   #=> [USD 1.00]
+Money.with_rounding(:ceil)      { Money.from(1.001, 'USD') }   #=> [USD 1.01]
+Money.with_rounding(:floor)     { Money.parse('1.009', 'USD') } #=> [USD 1.00]
 ```
 
 Modes: `:half_up` (default), `:half_down`, `:floor`, `:ceil`, `:truncate`, `:down`. Applies to construction, parsing, `change`, `split`, and `allocate`. Restores the previous mode when the block exits, even on exception.
 
-> **Performance note:** Rounding-mode support is not loaded by default — `require 'minting'` uses the fastest possible rounding (equivalent to `:half_up`) with zero dispatch overhead. The first call to `Mint.with_rounding` loads the rounding module and patches `Currency#normalize_amount`, adding ~10–35 ns per money creation or mutation. If your application never uses custom rounding modes (the common case), there is **no performance cost**.
+> **Performance note:** Rounding-mode support is not loaded by default — `require 'minting'` uses the fastest possible rounding (equivalent to `:half_up`) with zero dispatch overhead. The first call to `Money.with_rounding` loads the rounding module and patches `Currency#normalize_amount`, adding ~10–35 ns per money creation or mutation. If your application never uses custom rounding modes, there is **no performance cost**.
 
 **Division** — `money / 5` returns new `Money`; `money / other_money` returns a numeric ratio, not money.
 
-**Zero equality** — Any zero amount is considered equal across currencies and to numeric zero (`Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`). Non-zero amounts must match currency and value.
+**Zero equality** — Any zero amount is considered equal across currencies and to numeric zero (`Money.from(0, 'USD') == Money.from(0, 'EUR')` is intentionally `true`). Non-zero amounts must match currency and value.
 
-**Zero helper** — `Currency.zero('USD')` returns a frozen zero-Money, useful as a default value for discounts, totals, or counters.
 
-**Registered currencies** — `Currency.register(code:, subunit:, symbol:, priority:)` adds custom currencies. Only registered codes and symbols are recognized by the parser or searches. Nonetheless, you don't need to register a currency to use it with most of the features.
+
+**Registered currencies** — `Currency.register(code:, subunit:, symbol:, priority:)` adds custom currencies. Only registered codes and symbols are recognized by the parser or searches. You don't need to register a currency to use it with most features.
 
 **Built-in currencies** — 150+ ISO-4217 world currencies ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
 
@@ -227,7 +341,7 @@ By default, `require "minting"` exposes `Mint::Money` as the top-level `Money` c
 ```ruby
 require "minting"
 
-price = Money.from(10, "USD")                   # equivalent to Mint::Money.from
+price = Money.from(10, "USD")   # equivalent to Mint::Money.from
 tax   = Money.from(2.50, "USD")
 ```
 
@@ -235,26 +349,35 @@ tax   = Money.from(2.50, "USD")
 
 ```ruby
 require "minting"
-require "minting/mint/aliases"  # opt-in top-level Currency
+require "minting/aliases"  # opt-in top-level Currency
 
 cur = Currency.new(code: "EUR", symbol: "€", subunit: 2, priority: 0)
 ```
 
-For Rails applications, you can enable the top-level `Currency` constant in an initializer:
+For Rails applications, enable it in an initializer:
 
 ```ruby
 # config/initializers/minting.rb
-require "minting/mint/aliases"
+require "minting/aliases"
 ```
 
-If another `Money` is already defined when `require "minting"` runs (e.g. the `money` gem was loaded first), Minting warns and skips the auto-bind — use `Mint::Money` in that case. The same applies to `Currency` via `minting/mint/aliases`.
+If another `Money` is already defined when `require "minting"` runs (e.g. the `money` gem was loaded first), Minting warns and skips the auto-bind — use `Mint::Money` in that case. The same applies to `Currency` via `minting/aliases`.
 
 **Good fit:** Application code, especially Rails apps.
 **Not recommended:** Reusable gems/libraries — stick to `Mint::Money` to avoid conflicts.
 
+## Rails integration
+
+Minting itself has no Rails dependency. For `ActiveRecord` type casting, validators, and form helpers, pair it with the companion gem:
+
+- **[MoneyAttribute](https://github.com/gferraz/money-attribute)** — a `money_attribute` macro for models, with `ActiveRecord::Type` integration and `composed_of`-based support for multi-column (amount + currency) attributes.
+
 ## Roadmap
 
-- Exchange-rate conversion infrastructure
+Toward a stable 2.0: (no later than August 2026)
+
+- Exchange-rate conversion infrastructure (provider abstraction, stateless injection)
+- API surface review — locking in the public interface for `Money`, `Currency`, and formatting before the tag
 
 ## License
 

data/Rakefile

@@ -2,10 +2,9 @@ require 'bundler/audit/task'
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubocop/rake_task'
-require 'rubycritic/rake_task'
 require 'yard'
 
-CLOBBER.include %w[doc/css doc/js doc/Mint doc/*.html tmp .yardoc]
+CLOBBER.include %w[doc/css doc/js doc/Mint doc/*.html tmp .yardoc pkg tmp/*]
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
@@ -15,46 +14,42 @@ Rake::TestTask.new(:test) do |t|
 end
 
 Rake::TestTask.new('bench:all') do |t|
-  t.libs = %w[lib test]
-  t.pattern = 'test/performance/{core,memory,regression,competitive/money}/*_benchmark.rb'
+  t.libs = %w[lib bench]
+  t.pattern = 'bench/{core,memory,regression}/*_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:core') do |t|
-  t.libs = %w[lib test]
-  t.pattern = 'test/performance/core/parse_benchmark.rb'
+  t.libs = %w[lib bench]
+  t.pattern = 'bench/core/parse_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:memory') do |t|
-  t.libs = %w[lib test]
-  t.pattern = 'test/performance/memory/*_benchmark.rb'
+  t.libs = %w[lib bench]
+  t.pattern = 'bench/memory/*_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:regression') do |t|
-  t.libs = %w[lib test]
-  t.pattern = 'test/performance/regression/*_benchmark.rb'
+  t.libs = %w[lib bench]
+  t.pattern = 'bench/regression/*_benchmark.rb'
 end
 
 desc 'Run competitive benchmarks (Money gem)'
-task 'bench:competitive' do
-  sh 'bundle exec ruby -Ilib -Itest -e "Dir[File.join(__dir__, \"test/performance/competitive/money/**/*_benchmark.rb\")].each { |f| require f }"'
+task 'bench:against:money' do
+  dir = 'bench/competitive/money'
+  sh "BUNDLE_GEMFILE=#{dir}/Gemfile bundle exec ruby -Ilib -I#{dir} -Ibench -e \"Dir[File.join(__dir__, '#{dir}/**/*_benchmark.rb')].each { |f| require f }\""
 end
 
 desc 'Run competitive benchmarks (Shopify Money)'
-task 'bench:competitive:shopify' do
-  sh 'BUNDLE_WITHOUT=money_bench bundle exec ruby -Ilib -Itest -e "Dir[File.join(__dir__, \"test/performance/competitive/shopify/**/*_benchmark.rb\")].each { |f| require f }"'
-end
-
-desc 'Run all competitive benchmarks (both Money and Shopify)'
-task 'bench:competitive:all' do
-  sh 'bundle exec ruby -Ilib -Itest -e "Dir[File.join(__dir__, \"test/performance/competitive/money/**/*_benchmark.rb\")].each { |f| require f }"'
-  sh 'BUNDLE_WITHOUT=money_bench bundle exec ruby -Ilib -Itest -e "Dir[File.join(__dir__, \"test/performance/competitive/shopify/**/*_benchmark.rb\")].each { |f| require f }"'
+task 'bench:against:shopify' do
+  dir = 'bench/competitive/shopify'
+  sh "BUNDLE_GEMFILE=#{dir}/Gemfile bundle exec ruby -Ilib -I#{dir} -Ibench -e \"Dir[File.join(__dir__, '#{dir}/**/*_benchmark.rb')].each { |f| require f }\""
 end
 
 desc 'Run core benchmarks and update the baseline'
 task 'bench:baseline' do
   platform = RUBY_PLATFORM
-  baseline = "test/performance/check/results/baseline-#{platform}.json"
-  sh "ruby test/performance/check/runner.rb #{baseline}"
+  baseline = "bench/check/results/baseline-#{platform}.json"
+  sh "bundle exec ruby bench/check/runner.rb #{baseline}"
   puts "Baseline updated for #{platform}."
 end
 
@@ -69,10 +64,6 @@ RuboCop::RakeTask.new(:cop) do |task|
   task.patterns = ['lib']
 end
 
-RubyCritic::RakeTask.new do |task|
-  task.name = 'critic'
-end
-
 YARD::Rake::YardocTask.new do |t|
   t.files   = ['lib/**/*.rb']
   t.stats_options = ['--list-undoc']

data/bin/bench_check

@@ -5,7 +5,7 @@ require 'json'
 require 'tempfile'
 
 platform = RUBY_PLATFORM
-results_dir = File.expand_path('../test/performance/check/results', __dir__)
+results_dir = File.expand_path('../bench/check/results', __dir__)
 baseline_path = File.join(results_dir, "baseline-#{platform}.json")
 threshold = (ARGV[0] || 0.80).to_f
 
@@ -17,7 +17,7 @@ end
 baseline = JSON.parse(File.read(baseline_path))
 current_json = Tempfile.new(%w[bench_current .json])
 
-unless system("bundle exec ruby test/performance/check/runner.rb #{current_json.path}")
+unless system("bundle exec ruby bench/check/runner.rb #{current_json.path}")
   puts 'Benchmark runner failed.'
   exit 1
 end

data/doc/agents/api_review-2026-06-15.md

@@ -127,7 +127,7 @@ This is odd: the param type is a `Currency` in the docs, but you call `other.cur
       other_currency =
         case other
         when Mint::Money   then other.currency
-        when Mint::Currency then other
+        when Money::Currency then other
         else
           Currency.resolve!(other)
         end