minting 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20bb9d0f4d0437f84ab790d3fdbd27650bee49d0b9d1231b3ba19888987583b4
-  data.tar.gz: 8787d2359db2b7c75a2054fdcc6d56525e819f25b4d1cc746d2d6bcb01fd03ff
+  metadata.gz: 851c39a123584b8a782ef0c610c5e271239e0f20b948963bf926daf11defa269
+  data.tar.gz: 9d9c5aab7a6acc499308b2850157f6e8d4eef8ad01f4b0db4aa75e89067162fb
 SHA512:
-  metadata.gz: 29d3c3b52a8f5786587caf516fce6828341ec10ca6dd57f2882b9fb6dda13ae136237d3fe087613d6a832553be05a5bb1fb3e77d54952d030fdca87a879923e2
-  data.tar.gz: f5d8ef6c9bb9bffdbe9b7b84b94badb678d4a04a4648b63fa49b9e0086130d0abf73bd20988c6e544b7b154e671677ae0d06bc3dcc739ce410e034b5fedd53fe
+  metadata.gz: d6cca508a6ec6690436d67f70720db03bcebabeb7b561a4769aca306d9350f1d40ba07af63500316c236094dca13b7a6c181d49b324729e7439deff05f69513a
+  data.tar.gz: 419ce736af2fd00d90834dc6b82e5459ff83873922871a40d89d62dda69603ce31a5456918fa61ba21564489019eba6c80b1589cefce19841410a6e328ee45fa

data/README.md

@@ -1,7 +1,10 @@
 [![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)
+[![Test Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)](https://github.com/gferraz/minting)
 [![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://www.rubydoc.info/gems/minting/frames)
+[![RubyCritic Score](https://img.shields.io/badge/RubyCritic-93/100-brightgreen)](https://github.com/gferraz/minting)
+[![GitHub last commit](https://img.shields.io/github/last-commit/gferraz/minting)](https://github.com/gferraz/minting/commits/main)
+[![License](https://img.shields.io/github/license/gferraz/minting)](https://github.com/gferraz/minting/blob/main/LICENSE)
 
 # Minting
 
@@ -9,7 +12,7 @@
 
 
 
-> **Status:** Minting 2.0 is released. The core API (`Money`, `Currency`, formatting, parsing) is stable.
+> **Status:** Minting 2.1 is released. The core API (`Money`, `Currency`, formatting, parsing) is stable.
 
 ```ruby
 price = Money.from(19.99, 'USD')       #=> [USD 19.99]
@@ -19,11 +22,84 @@ total = price + tax                    #=> [USD 21.59]
 total.to_s                             #=> "$21.59"
 ```
 
+## Quickstart
+
+Get started in 60 seconds:
+
+```ruby
+# Add to your Gemfile
+gem "minting"
+
+# Or install directly
+# gem install minting
+
+# Require the gem
+require "minting"
+
+# Create money objects
+price = Money.from(19.99, "USD")
+tax_rate = 0.08
+tax = price * tax_rate
+total = price + tax
+
+# Format as a string
+puts total.to_s # => "$21.59"
+
+# Parse from a string
+money = Money.parse("$15.99")
+puts money # => "$15.99"
+
+# Allocate money proportionally
+total = Money.from(100, "USD")
+shares = total.allocate([1, 2, 3]) # => [16.67, 33.33, 50.00]
+
+# Split into N equal parts
+parts = total.split(3) # => [33.34, 33.33, 33.33]
+```
+
+## What's New in 2.1
+
+### Breaking Changes
+- Rounding mode symbols renamed to match `Rational#round` `half:` parameter: `:half_up` → `:up`, `:half_down` → `:down`, `:half_even` → `:even`
+
+## What's New in 2.0
+
+### Breaking Changes
+- `Mint.parse` and `Mint.parse!` removed — use `Money.parse` and `Money.parse!`
+- `Mint.with_rounding` removed — use `Money.with_rounding`
+- `Mint.world_currencies` removed — use `Currency.world_currencies`
+- `Money#mint` removed — use `Money#copy_with`
+- `Money::Currency` is the canonical name to access the `Currency` class
+- `minting/mint/aliases` abbreviated to `minting/aliases`
+- `Money#format` `formatter_class:` kwarg removed — `Formatter` is now the sole formatter implementation
+- `Money#to_json` and `Money.from_json` — moved to `attribute-money` companion gem
+
+### New Features
+- **Crypto currency support**: Opt-in YAML-backed definitions for ~25 popular coins (BTC, ETH, SOL, ...). Use `Currency.register_crypto('BTC', 'ETH')` to register, or `Currency.crypto_currencies` to inspect available definitions.
+- `Currency.registered_currencies` — public access to all registered currencies (frozen hash)
+- `Money.from_hash(hash)` — deserializer symmetric with `to_hash`, accepts `{ currency:, amount: }`
+- `Money#integral` — returns the whole-unit part of the amount (complement to `#fractional`). `#to_i` is now an alias of `#integral`.
+- `%<dsymbol>s` format placeholder — uses `currency.disambiguate_symbol` (e.g. "US$", "C$", "A$") when available, falling back to the primary symbol.
+- **Compiled formatting**: Formatting is now compiled into reusable lambdas at the class level — 1.4–2.2x formatting speedup depending on scenario.
+- **Locale-aware formatting**: `locale:` kwarg on `Money#format` / `#to_fs`, supports per-locale decimal/thousand separators and format templates via `Mint.locale_backend`. Works seamlessly with Rails I18n.
+- **Faster startup**: World currencies are now preloaded at gem initialization, eliminating lazy-loading overhead and mutex contention.
+
+### Bugfixes
+- `Money#fractional` now returns a signed value matching the amount's sign (previously always positive for negative amounts). The invariant `integral * multiplier + fractional == subunits` now holds for all amounts.
+- `Money#initialize` now calls `.to_r` on the amount, guaranteeing `@amount` is always a `Rational`. Fixes a hash/`eql?` contract violation for zero-subunit currencies and an `ArgumentError` in `Integer#to_d`.
+
+### Removed
+- `Money::Formatter2` — removed; `Formatter` is the sole implementation
+- `Money#to_json` and `Money.from_json` — moved to `attribute-money` companion gem
+
 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
 
+- [Quickstart](#quickstart)
 - [Why Minting](#why-minting)
+- [What's New in 2.1](#whats-new-in-21)
+- [What's New in 2.0](#whats-new-in-20)
 - [How it compares](#how-it-compares)
 - [Installation](#installation)
 - [Usage](#usage)
@@ -198,7 +274,7 @@ Notes:
 
 ```ruby
 # All registered currencies (150+ ISO 4217 + custom)
-Money::Currency.registered_currencies.size                 #=> 154
+Money::Currency.registered_currencies.size                 #=> 164
 Money::Currency.registered_currencies.each { |code, c| puts "#{code}: #{c.name}" }
 
 # Built-in ISO 4217 currencies (before custom registrations)
@@ -254,16 +330,6 @@ Currency.crypto_currencies.each { |c| puts "#{c.code}: #{c.name}" }
 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:
@@ -315,14 +381,14 @@ Mint.money(9.99, 'BRL').format  #=> "R$9,99"
 **Rounding modes** — Wrap operations in `Money.with_rounding(mode)` to change how amounts are rounded to the subunit:
 
 ```ruby
-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]
+Money.with_rounding(:down) { Money.from(1.005, 'USD') }   #=> [USD 1.00]
+Money.with_rounding(:even) { Money.from(1.015, 'USD') }   #=> [USD 1.02]
+Money.with_rounding(:up)   { Money.from(1.005, 'USD') }   #=> [USD 1.01]
 ```
 
-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.
+Modes: `:up` (default), `:down`, `:even`. 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 `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**.
+> **Performance note:** Rounding-mode support is not loaded by default — `require 'minting'` uses the fastest possible rounding (equivalent to `:up`) with zero dispatch overhead. The first call to `Money.with_rounding` activates the rounding dispatch in `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.
 
@@ -332,12 +398,11 @@ Modes: `:half_up` (default), `:half_down`, `:floor`, `:ceil`, `:truncate`, `:dow
 
 **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.
+**Built-in currencies** — 150+ ISO-4217 world currencies ship in `lib/minting/data/world-currencies.yaml` and are preloaded at gem initialization.
 
-## Optional top-level `Money` and `Currency`
+## Optional top-level `Money` (opt-out) and `Currency` (opt-in)
 
 By default, `require "minting"` exposes `Mint::Money` as the top-level `Money` constant, so you can write `Money.from(10, "USD")` directly:
-
 ```ruby
 require "minting"
 
@@ -372,13 +437,6 @@ Minting itself has no Rails dependency. For `ActiveRecord` type casting, validat
 
 - **[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
-
-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
 
 MIT

data/lib/minting/currency/currency.rb

@@ -6,19 +6,40 @@ module Mint
   # Currency objects are immutable and define the properties of a monetary unit
   # including its subunit precision, display symbol, and formatting rules.
   #
+  # Currency identity is defined by its ISO code — two Currency objects with
+  # the same +code+ are considered equal regardless of other attributes.
+  # The Registry guarantees that only one canonical Currency exists per code.
+  #
   # @see https://www.iso.org/iso-4217-currency-codes.html
-  # @attr_reader code [String] ISO 4217 currency code (e.g., "USD", "EUR")
-  # @attr_reader subunit [Integer] Number of decimal places (0 for JPY, 2 for USD, 3 for IQD)
-  # @attr_reader symbol [String] Display symbol (e.g., "$", "€", "R$")
-  # @attr_reader priority [Integer] Parser precedence for symbol detection
-  # @attr_reader country [String, nil] Associated country code
-  # @attr_reader name [String, nil] Currency name
-  # @attr_reader fractional_multiplier [Integer] 10^subunit, used for fractional conversions
-  # @attr_reader minimum_amount [Rational] Smallest representable amount (1/fractional_multiplier)
-  # @attr_reader disambiguate_symbol [String, nil] A longer, code-prefixed variant to distinguish
-  #   currencies that share the same primary symbol (e.g. "US$" for USD, "C$" for CAD).
-  Currency = Data.define(:code, :subunit, :symbol, :priority, :country, :name,
-                         :fractional_multiplier, :disambiguate_symbol) do
+  class Currency
+    # @return [String] ISO 4217 currency code (e.g., "USD", "EUR")
+    attr_reader :code
+
+    # @return [String, nil] Associated country code
+    attr_reader :country
+
+    # @return [String, nil] A longer, code-prefixed variant to distinguish
+    #   currencies that share the same primary symbol (e.g. "US$" for USD, "C$" for CAD).
+    attr_reader :disambiguate_symbol
+
+    # @return [Integer] 10^subunit, used for fractional conversions
+    attr_reader :fractional_multiplier
+
+    # @return [Rational] Smallest representable amount (1/fractional_multiplier)
+    attr_reader :minimum_amount
+
+    # @return [String, nil] Currency name
+    attr_reader :name
+
+    # @return [Integer] Parser precedence for symbol detection
+    attr_reader :priority
+
+    # @return [Integer] Number of decimal places (0 for JPY, 2 for USD, 3 for IQD)
+    attr_reader :subunit
+
+    # @return [String, nil] Display symbol (e.g., "$", "€", "R$")
+    attr_reader :symbol
+
     # @param code [String] ISO 4217 currency code
     # @param symbol [String] Display symbol
     # @param subunit [Integer] Number of decimal places (default 0)
@@ -27,33 +48,54 @@ module Mint
     # @param name [String, nil] Currency name (default nil)
     def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil,
                    disambiguate_symbol: nil)
-      subunit = subunit.to_i
-      priority = priority.to_i
-      fractional_multiplier = 10**subunit
-      symbol = nil if symbol && symbol.empty?
-      disambiguate_symbol = nil if [code, symbol].include? disambiguate_symbol
-      super(code:, subunit:, symbol:, priority:, country:, name:,
-            fractional_multiplier:, disambiguate_symbol:)
+      @code = code
+      @country = country
+      @name = name
+      @priority = priority.to_i
+      @subunit = subunit.to_i
+      @symbol = symbol.nil? || symbol.empty? ? nil : symbol
+
+      @fractional_multiplier = 10**@subunit
+      @minimum_amount = Rational(1, @fractional_multiplier)
+      @disambiguate_symbol = [code, @symbol].include?(disambiguate_symbol) ? nil : disambiguate_symbol
+      freeze
     end
 
+    # Two Currency objects are equal if they share the same ISO code.
+    def ==(other) = other.is_a?(self.class) && code == other.code
+
+    # @return [String, nil] disambiguate_symbol or code/symbol fallback
+    def dsymbol = disambiguate_symbol || (Registry.symbol_shared?(symbol) ? code : symbol)
+
+    # Currency identity is by code — two objects with the same code are +eql?+
+    # regardless of other attributes. This makes Currency usable as a Hash key
+    # where lookup is by currency identity (ISO code).
+    def eql?(other) = other.is_a?(Currency) && code == other.code
+
+    # @return [Integer] stable hash based on currency code
+    def hash = code.hash
+
     # @return [String] debug representation
     def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
 
-    # @return [Rational] smallest representable amount (1/fractional_multiplier)
-    def minimum_amount = Rational(1, fractional_multiplier)
-
     # Normalizes a numeric amount for this currency.
     #
     # @param amount [Numeric] the monetary amount to normalize
     # @return [Rational] the amount converted to +Rational+ and rounded to
-    #   the currency's subunit precision (half-up by default)
+    #   the currency's subunit precision (up by default)
     # @example
     #   usd = Money::Currency.for_code('USD')
     #   usd.normalize_amount(10.567)  #=> (10567/1000)
     #   usd.normalize_amount("5.25")  #=> (21/4)
     #
-    # @see Mint::Rounding.apply Custom rounding modes via {Money.with_rounding}
-    def normalize_amount(amount) = amount.to_r.round(subunit)
+    # @see Money.with_rounding Custom rounding modes via {Money.with_rounding}
+    def normalize_amount(amount)
+      if Currency.custom_rounding_active?
+        amount.to_r.round(subunit, half: Thread.current[Currency::ROUNDING_THREAD_KEY])
+      else
+        amount.to_r.round(subunit)
+      end
+    end
 
     # Returns the cached frozen zero-Money for this currency.
     #
@@ -61,136 +103,5 @@ module Mint
     # @example
     #   Money::Currency.for_code('USD').zero  #=> [USD 0.00]
     def zero = Registry.zero_for(self)
-
-    def dsymbol
-      disambiguate_symbol || (Registry.symbol_shared?(symbol) ? code : symbol)
-    end
-  end
-
-  # Registers a new currency, raising a KeyError if already registered.
-  #
-  # @param code [String] the unique currency code
-  # @param subunit [Integer] the decimal subunit precision, defaults to 0
-  # @param symbol [String] the display symbol
-  # @param priority [Integer] parser precedence priority
-  # @return [Currency] the newly registered Currency instance
-  # @raise [ArgumentError] if the code contains invalid characters
-  # @raise [KeyError] if the currency code is already registered
-  def Currency.register(code:, subunit: 0, symbol: '', priority: 0)
-    Registry.register(code:, subunit:, symbol:, priority:)
-  end
-
-  # Resolves an object into a {Currency}, returning +nil+ when it can't.
-  #
-  # Accepts +nil+, +String+, {Currency}, {Money}, or any object implementing
-  # +#to_currency+ (must return {Currency}) or +#currency_code+ (must return +String+).
-  #
-  # @param object [String, Currency, Money, nil, #to_currency, #currency_code]
-  #   a currency code, object, or +nil+
-  # @return [Currency, nil] the resolved Currency, or +nil+ if +object+ is +nil+
-  #   or the code is not registered
-  # @raise [ArgumentError] if +object+ is an unsupported type, or if the method
-  #   used to resolve it returns a value of the wrong type
-  def Currency.resolve(object)
-    case object
-    when NilClass then nil
-    when Currency then object
-    when Money    then object.currency
-    when String   then Currency.for_code object
-    else
-      if object.respond_to?(:to_currency)
-        result = object.to_currency
-        unless result.is_a?(Currency)
-          raise ArgumentError, "#to_currency must return a [Money::Currency], got #{result.class}"
-        end
-
-        result
-      elsif object.respond_to?(:currency_code)
-        result = object.currency_code
-        raise ArgumentError, "#currency_code must return a [String], got #{result.class}" unless result.is_a?(String)
-
-        Currency.for_code result
-      else
-        raise ArgumentError, "currency must be [Money::Currency], [Money], [String] or nil (#{object})"
-      end
-    end
-  end
-
-  # Resolves an object into a {Currency}, raising on failure.
-  #
-  # Like {.resolve} but raises when the result would be +nil+.
-  #
-  # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
-  # @return [Currency] the resolved Currency
-  # @raise [Mint::UnknownCurrency] if +object+ cannot be resolved into a
-  #   registered currency. +Mint::UnknownCurrency+ inherits from +ArgumentError+,
-  #   so existing +rescue ArgumentError+ handlers continue to work.
-  def Currency.resolve!(object)
-    resolve(object) or raise Mint::UnknownCurrency, "Could not resolve (#{object}) into a currency"
-  end
-
-  # Returns all registered currencies as a frozen hash keyed by ISO code.
-  #
-  # @return [Hash{String => Currency}] frozen hash of all registered currencies
-  # @example Iterate over registered currencies
-  #   Currency.registered_currencies.each { |code, currency| puts "#{code}: #{currency.name}" }
-  # @example Count of registered currencies
-  #   Currency.registered_currencies.size  #=> 154
-  def Currency.registered_currencies = Registry.currencies
-
-  # Looks up a registered currency by its alpha code.
-  #
-  # @param code [String] the currency code
-  # @return [Currency, nil] the registered Currency, or +nil+ if not found
-  def Currency.for_code(code)
-    Registry.currencies[code]
-  end
-
-  # Looks up a currency by its display symbol.
-  #
-  # @param symbol [String] the display symbol (e.g. "$", "R$")
-  # @return [Currency, nil] the highest-priority currency for the symbol
-  def Currency.for_symbol(symbol)
-    Registry.currency_for_symbol(symbol)
   end
-
-  # Returns a zero {Money} in the given currency, useful as a default value
-  # for discounts, totals, or placeholders.
-  #
-  # @param currency [String, Currency] a currency code or object
-  # @return [Money] a frozen zero-Money
-  # @raise [Mint::UnknownCurrency] if the currency can't be resolved
-  def Currency.zero(currency) = Registry.zero_for(Currency.resolve!(currency))
-
-  # Returns the frozen hash of all built-in ISO 4217 world currencies.
-  #
-  # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
-  # @api private
-  def Currency.world_currencies = Registry.world_currencies
-
-  # Returns the list of built-in crypto currency definitions.
-  #
-  # These are not registered by default — call {.register_crypto} to opt in.
-  #
-  # @return [Array<Currency>] frozen array of crypto currency definitions
-  def Currency.crypto_currencies = Registry.crypto_currencies
-
-  # Registers one or more crypto currencies into the shared currency registry.
-  #
-  # Raises on duplicate registration or unknown code — use +rescue+ if
-  # idempotent bulk registration is needed.
-  #
-  # @param codes [Array<String>] one or more crypto currency codes
-  # @raise [ArgumentError] if a code is not a known crypto currency
-  # @raise [KeyError] if the currency code is already registered
-  # @return [Array<Currency>] the newly registered Currency objects
-  def Currency.register_crypto(...) = Registry.register_crypto(...)
-
-  # Registers all built-in crypto currencies at once.
-  #
-  # Raises on the first duplicate — call +rescue+ if idempotency is needed.
-  #
-  # @raise [KeyError] if any currency code is already registered
-  # @return [Array<Currency>] the newly registered Currency objects
-  def Currency.register_all_crypto = Registry.register_all_crypto
 end

data/lib/minting/currency/registry.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Mint
+  # Class-level methods on {Currency} that delegate to the {Registry}.
+  # Separated from the core class definition for readability.
+  #
+  # @api private
+
+  # Returns the list of built-in crypto currency definitions.
+  #
+  # These are not registered by default — call {.register_crypto} to opt in.
+  #
+  # @return [Array<Currency>] frozen array of crypto currency definitions
+  def Currency.crypto_currencies = Registry.crypto_currencies
+
+  # Looks up a registered currency by its alpha code.
+  #
+  # @param code [String] the currency code
+  # @return [Currency, nil] the registered Currency, or +nil+ if not found
+  def Currency.for_code(code) = Registry.currencies[code]
+
+  # Looks up a currency by its display symbol.
+  #
+  # @param symbol [String] the display symbol (e.g. "$", "R$")
+  # @return [Currency, nil] the highest-priority currency for the symbol
+  def Currency.for_symbol(symbol) = Registry.currency_for_symbol(symbol)
+
+  # Registers a new currency, raising a KeyError if already registered.
+  #
+  # @param code [String] the unique currency code
+  # @param subunit [Integer] the decimal subunit precision, defaults to 0
+  # @param symbol [String] the display symbol
+  # @param priority [Integer] parser precedence priority
+  # @return [Currency] the newly registered Currency instance
+  # @raise [ArgumentError] if the code contains invalid characters
+  # @raise [KeyError] if the currency code is already registered
+  def Currency.register(code:, subunit: 0, symbol: '', priority: 0)
+    Registry.register(code:, subunit:, symbol:, priority:)
+  end
+
+  # Registers all built-in crypto currencies at once.
+  #
+  # Raises on the first duplicate — call +rescue+ if idempotency is needed.
+  #
+  # @raise [KeyError] if any currency code is already registered
+  # @return [Array<Currency>] the newly registered Currency objects
+  def Currency.register_all_crypto = Registry.register_all_crypto
+
+  # Registers one or more crypto currencies into the shared currency registry.
+  #
+  # Raises on duplicate registration or unknown code — use +rescue+ if
+  # idempotent bulk registration is needed.
+  #
+  # @param codes [Array<String>] one or more crypto currency codes
+  # @raise [ArgumentError] if a code is not a known crypto currency
+  # @raise [KeyError] if the currency code is already registered
+  # @return [Array<Currency>] the newly registered Currency objects
+  def Currency.register_crypto(...) = Registry.register_crypto(...)
+
+  # Returns all registered currencies as a frozen hash keyed by ISO code.
+  #
+  # @return [Hash{String => Currency}] frozen hash of all registered currencies
+  # @example Iterate over registered currencies
+  #   Currency.registered_currencies.each { |code, currency| puts "#{code}: #{currency.name}" }
+  # @example Count of registered currencies
+  #   Currency.registered_currencies.size  #=> 154
+  def Currency.registered_currencies = Registry.currencies
+
+  # Resolves an object into a {Currency}, returning +nil+ when it can't.
+  #
+  # Accepts +nil+, +String+, {Currency}, {Money}, or any object implementing
+  # +#to_currency+ (must return {Currency}) or +#currency_code+ (must return +String+).
+  #
+  # @param object [String, Currency, Money, nil, #to_currency, #currency_code]
+  #   a currency code, object, or +nil+
+  # @return [Currency, nil] the resolved Currency, or +nil+ if +object+ is +nil+
+  #   or the code is not registered
+  # @raise [ArgumentError] if +object+ is an unsupported type, or if the method
+  #   used to resolve it returns a value of the wrong type
+  def Currency.resolve(object)
+    case object
+    when NilClass then nil
+    when Currency then object
+    when Money    then object.currency
+    when String   then Currency.for_code object
+    else
+      if object.respond_to?(:to_currency)
+        result = object.to_currency
+        unless result.is_a?(Currency)
+          raise ArgumentError, "#to_currency must return a [Money::Currency], got #{result.class}"
+        end
+
+        result
+      elsif object.respond_to?(:currency_code)
+        result = object.currency_code
+        raise ArgumentError, "#currency_code must return a [String], got #{result.class}" unless result.is_a?(String)
+
+        Currency.for_code result
+      else
+        raise ArgumentError, "currency must be [Money::Currency], [Money], [String] or nil (#{object})"
+      end
+    end
+  end
+
+  # Resolves an object into a {Currency}, raising on failure.
+  #
+  # Like {.resolve} but raises when the result would be +nil+.
+  #
+  # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
+  # @return [Currency] the resolved Currency
+  # @raise [Mint::UnknownCurrency] if +object+ cannot be resolved into a
+  #   registered currency. +Mint::UnknownCurrency+ inherits from +ArgumentError+,
+  #   so existing +rescue ArgumentError+ handlers continue to work.
+  def Currency.resolve!(object)
+    resolve(object) or raise Mint::UnknownCurrency, "Could not resolve (#{object}) into a currency"
+  end
+
+  # Returns a zero {Money} in the given currency, useful as a default value
+  # for discounts, totals, or placeholders.
+  #
+  # @param currency [String, Currency] a currency code or object
+  # @return [Money] a frozen zero-Money
+  # @raise [Mint::UnknownCurrency] if the currency can't be resolved
+  def Currency.zero(currency) = Registry.zero_for(Currency.resolve!(currency))
+
+  # --- @api private ---
+
+  # Returns the frozen hash of all built-in ISO 4217 world currencies.
+  #
+  # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
+  # @api private
+  def Currency.world_currencies = Registry.world_currencies
+end

data/lib/minting/currency/rounding.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Mint
+  # :nodoc:
+  class Currency
+    # @api private
+    VALID_ROUNDING_MODES = %i[up down even].freeze
+
+    # @api private
+    ROUNDING_THREAD_KEY = :minting_rounding_mode
+
+    # @return [Boolean] whether a custom rounding mode has been activated
+    # @api private
+    def self.custom_rounding_active? = @custom_rounding_active
+
+    # Activates the custom rounding dispatch path in {#normalize_amount}.
+    # Once called, this cannot be reversed for the lifetime of the process.
+    # @api private
+    def self.activate_custom_rounding! = @custom_rounding_active = true
+
+    # Returns the currently active rounding mode, falling back to +:up+.
+    # @api private
+    # @return [Symbol] one of +:up+, +:down+, +:even+
+    def self.current_rounding_mode
+      Thread.current[ROUNDING_THREAD_KEY] || :up
+    end
+
+    # Sets a rounding mode for the duration of a block, restoring the
+    # previous mode on exit (even on exception).
+    # @api private
+    # @param mode [Symbol] one of +:up+, +:down+, +:even+
+    # @yield block to execute with the mode active
+    # @raise [ArgumentError] on unknown mode
+    def self.rounding_mode(mode)
+      unless VALID_ROUNDING_MODES.include?(mode)
+        raise ArgumentError, "Unknown rounding mode: #{mode} (expected :up, :down, or :even)"
+      end
+
+      prev = Thread.current[ROUNDING_THREAD_KEY]
+      Thread.current[ROUNDING_THREAD_KEY] = mode
+      yield
+    ensure
+      Thread.current[ROUNDING_THREAD_KEY] = prev
+    end
+  end
+end

data/lib/minting/mint/registry/registry.rb

@@ -14,25 +14,23 @@ module Mint
 
     private_constant :MUTEX
 
+    # Preload world currencies from YAML file during module load.
+    path = File.join(File.expand_path('../../data', __dir__), 'world-currencies.yaml')
+    @world_currencies = YAML.load_file(path).to_h do |entry|
+      [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))]
+    end
+    @currencies = @world_currencies.freeze.dup.freeze
+
     # Loads ISO world currencies from YAML file.
     #
     # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
     # @api private
-    def self.world_currencies
-      @world_currencies || MUTEX.synchronize do
-        @world_currencies = begin
-          path = File.join(File.expand_path('../../data', __dir__), 'world-currencies.yaml')
-          YAML.load_file(path).to_h { |entry| [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))] }
-        end.freeze
-      end
-    end
+    def self.world_currencies = @world_currencies
 
     # Returns the frozen hash of all registered currencies (world + custom).
     #
     # @return [Hash{String => Currency}] registered currencies mapped by code
     # @api private
-    def self.currencies
-      @currencies || MUTEX.synchronize { @currencies = world_currencies.dup.freeze }
-    end
+    def self.currencies = @currencies
   end
 end

data/lib/minting/mint.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'currency/currency'
+require_relative 'currency/registry'
+require_relative 'currency/rounding'
 
 require_relative 'mint/dsl/numeric'
 require_relative 'mint/dsl/range'

data/lib/minting/money/allocation/split.rb

@@ -15,7 +15,7 @@ module Mint
     #   money = Money.from(10.00, 'USD')
     #   money.split(3) #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
     def split(slices)
-      raise ArgumentError, 'Slices quantity must be an poitive integer' unless slices.positive? && slices.integer?
+      raise ArgumentError, 'Slices quantity must be a positive integer' unless slices.positive? && slices.integer?
 
       fraction = currency.normalize_amount(amount / slices)
       allocate_left_over(amounts: Array.new(slices, fraction),

data/lib/minting/money/format/formatter.rb

@@ -46,11 +46,13 @@ module Mint
         amount = money.amount
         currency = money.currency
 
-        template = @templates[amount <=> 0] || @positive_template
-        display_amount = template == @negative_template ? -amount : amount
+        templates = @has_placeholder ? @templates_by_subunit[currency.subunit] : @templates
+
+        template = templates[amount <=> 0] || templates[1]
+
+        display_amount = @has_negative_template && amount < 0 ? -amount : amount
         integral = display_amount.to_i
 
-        template = template.gsub(SUBUNIT_PLACEHOLDER, currency.subunit.to_s) if @has_placeholder
         result = Kernel.format(template,
                                currency: currency.code,
                                dsymbol: @needs_dsymbol && currency.dsymbol,
@@ -86,16 +88,22 @@ module Mint
         # The placeholder is later replaced with the actual subunit count at
         # format time (e.g. "\uE000" → "2" for USD, "0" for JPY).
         @templates.transform_values! { |f| f.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{SUBUNIT_PLACEHOLDER}f") }
-        @negative_template = @templates[-1]
-        @positive_template = @templates[1]
-
-        joined_template = @templates.values.join
-        @has_placeholder = joined_template.include?(SUBUNIT_PLACEHOLDER)
-        @needs_fractional = joined_template.include?('%<fractional>')
-        @needs_dsymbol = joined_template.include?('%<dsymbol>')
-        @needs_thousand_substitution = @thousand && !@thousand.empty? && (joined_template.include?('%<amount>') ||
-                         joined_template.include?('%<integral>'))
+        @has_negative_template = @templates.key?(-1)
+
+        joined = @templates.values.join
+        @needs_fractional = joined.include?('%<fractional>')
+        @needs_dsymbol = joined.include?('%<dsymbol>')
+
+        @needs_thousand_substitution = @thousand && !@thousand.empty? &&
+                                       (joined.include?('%<amount>') || joined.include?('%<integral>'))
         @thousand_replacement = "\\1#{@thousand}" if @needs_thousand_substitution
+
+        @has_placeholder = joined.include?(SUBUNIT_PLACEHOLDER)
+        return unless @has_placeholder
+
+        @templates_by_subunit = Hash.new do |h, subunit|
+          h[subunit] = @templates.transform_values { |f| f.gsub(SUBUNIT_PLACEHOLDER, subunit.to_s) }
+        end
       end
     end
   end

data/lib/minting/money/rounding.rb

@@ -9,19 +9,18 @@ module Mint
     # Restores the previous mode (or default) when the block exits, even on
     # exception.
     #
-    # Rounding-mode support is loaded lazily on first call. Once loaded,
-    # +Currency#normalize_amount+ is patched to dispatch through the
-    # rounding module, adding ~10–35&ns of overhead to every money creation
-    # or mutation. When rounding modes are never used (the common case),
-    # the fast path incurs zero overhead.
+    # Rounding-mode support is activated on first call. Once activated,
+    # +Currency#normalize_amount+ dispatches through +Currency.rounding_mode+,
+    # adding ~10–35&ns of overhead to every money creation or mutation.
+    # When rounding modes are never used (the common case), the fast path
+    # incurs zero overhead.
     #
-    # @param mode [Symbol] one of: +:half_up+, +:half_down+, +:floor+,
-    #   +:ceil+, +:truncate+, +:down+
+    # @param mode [Symbol] one of: +:up+, +:down+, +:even+
     # @yield block to execute with the rounding mode active
     # @raise [ArgumentError] if +mode+ is not a recognised rounding mode
     def self.with_rounding(mode, &)
-      require_relative '../mint/rounding' unless defined?(Mint::Rounding)
-      Mint::Rounding.with_mode(mode, &)
+      Currency.activate_custom_rounding!
+      Currency.rounding_mode(mode, &)
     end
   end
 end

data/lib/minting/version.rb

@@ -3,5 +3,5 @@
 # Root namespace for the Minting library.
 module Minting
   # Current version of the Minting gem.
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -46,6 +46,8 @@ files:
 - lib/minting.rb
 - lib/minting/aliases.rb
 - lib/minting/currency/currency.rb
+- lib/minting/currency/registry.rb
+- lib/minting/currency/rounding.rb
 - lib/minting/data/crypto-currencies.yaml
 - lib/minting/data/world-currencies.yaml
 - lib/minting/mint.rb
@@ -59,7 +61,6 @@ files:
 - lib/minting/mint/registry/registry.rb
 - lib/minting/mint/registry/symbols.rb
 - lib/minting/mint/registry/zeros.rb
-- lib/minting/mint/rounding.rb
 - lib/minting/money/allocation/allocation.rb
 - lib/minting/money/allocation/split.rb
 - lib/minting/money/arithmetics/methods.rb
@@ -103,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Library to manipulate currency values
 test_files: []

data/lib/minting/mint/rounding.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module Mint
-  # Rounding-mode dispatch table and block-scoped context.
-  # @api private
-  module Rounding
-    # Maps mode symbols to their corresponding +Rational+ rounding lambdas.
-    # @return [Hash{Symbol => Proc}]
-    # @api private
-    MODES = {
-      half_up: ->(amount, ndigits) { amount.round(ndigits, half: :up) },
-      half_down: ->(amount, ndigits) { amount.round(ndigits, half: :down) },
-      half_even: ->(amount, ndigits) { amount.round(ndigits, half: :even) },
-      floor: ->(amount, ndigits) { amount.floor(ndigits) },
-      ceil: ->(amount, ndigits) { amount.ceil(ndigits) },
-      truncate: ->(amount, ndigits) { amount.truncate(ndigits) },
-      down: ->(amount, ndigits) { amount.truncate(ndigits) }
-    }.freeze
-
-    THREAD_KEY = :minting_rounding_mode
-
-    # Returns the currently active rounding mode, falling back to +:half_up+.
-    # @api private
-    # @return [Symbol]
-    def self.current_mode
-      Thread.current[THREAD_KEY] || :half_up
-    end
-
-    # Rounds +amount+ to +ndigits+ using the currently scoped rounding mode.
-    # Uses the fast path (+to_r.round+) when no custom mode is active.
-    # @api private
-    # @param amount [Numeric]
-    # @param ndigits [Integer]
-    # @return [Rational]
-    def self.apply(amount, ndigits)
-      mode = Thread.current[THREAD_KEY]
-      if mode
-        MODES.fetch(mode).call(amount.to_r, ndigits)
-      else
-        amount.to_r.round(ndigits)
-      end
-    end
-
-    # Sets a rounding mode for the duration of a block, restoring the
-    # previous mode on exit (even on exception).
-    # @api private
-    # @param mode [Symbol]
-    # @yield block to execute with the mode active
-    # @raise [ArgumentError] on unknown mode
-    def self.with_mode(mode)
-      raise ArgumentError, "Unknown rounding mode: #{mode}" unless MODES.key?(mode)
-
-      prev = Thread.current[THREAD_KEY]
-      Thread.current[THREAD_KEY] = mode
-      yield
-    ensure
-      Thread.current[THREAD_KEY] = prev
-    end
-  end
-end
-
-# When loaded, patch Currency to delegate rounding through this module.
-# Remove the default fast-path method first to avoid redefinition warnings.
-Money::Currency.remove_method(:normalize_amount)
-Money::Currency.define_method(:normalize_amount) do |amount|
-  Mint::Rounding.apply(amount, subunit)
-end