minting 1.9.7 → 2.1.0

data/doc/agents/expired/gemini_gem_evaluation.md

@@ -29,7 +29,7 @@ lib/
 │   ├── data/
 │   │   └── currencies.yaml      # built-in ISO 4217 database
 │   ├── mint/
-│   │   ├── currency.rb          # Mint::Currency model
+│   │   ├── currency.rb          # Money::Currency model
 │   │   ├── refinements.rb       # Scoped Numeric/String refinements
 │   │   └── registry.rb          # Global lookup & registration
 │   ├── money/
@@ -70,7 +70,7 @@ lib/
 
 The gem exhibits top-tier Ruby development practices:
 
-- **Immutability & Safety**: Both `Mint::Currency` and `Mint::Money` objects are frozen upon initialization:
+- **Immutability & Safety**: Both `Money::Currency` and `Mint::Money` objects are frozen upon initialization:
   ```ruby
   def initialize(amount, currency)
     # ...

data/lib/minting/aliases.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# @!parse
+#   # Top-level alias for {Money::Currency}, opt-in via +require 'minting/aliases'+.
+#   Currency = Money::Currency
+
+# Top-level alias for {Money::Currency}, opt-in via +require 'minting/aliases'+.
+#
+# {::Currency} is **not** auto-bound by `require 'minting'` because
+# application domain models are commonly named +Currency+ (e.g. a Rails
+# model). Load this file explicitly to opt in.
+#
+# If {::Currency} is already defined, a warning is emitted and the existing
+# constant is preserved — use {Money::Currency} explicitly in that case.
+#
+# @see Money::Currency
+
+Currency = Money::Currency unless defined?(Currency)
+
+if Currency != Money::Currency
+  warn "minting: top-level Currency was already defined (#{Currency}); skipping alias. Use Money::Currency"
+end

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,98 +48,60 @@ 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
-      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 numeric amounts for this currency
-    # 1. Converts to Rational
-    # 2. Rounds to respect currency subunit
-    def normalize_amount(amount) = amount.to_r.round(subunit)
+    # 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 (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 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.
     #
     # @return [Money] a frozen zero-Money instance
     # @example
-    #   Mint::Currency.for_code('USD').zero  #=> [USD 0.00]
+    #   Money::Currency.for_code('USD').zero  #=> [USD 0.00]
     def zero = Registry.zero_for(self)
   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}, or {Money}.
-  # Passing a {Money} extracts its currency
-  #
-  # @param object [String, Currency, Money, nil] 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 (e.g. +Integer+)
-  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          raise ArgumentError, "currency must be [Currency], [Money], [String] or nil (#{object})"
-    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
-
-  # 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))
 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/data/crypto-currencies.yaml

@@ -0,0 +1,126 @@
+---
+- code: BTC
+  subunit: 8
+  symbol: "₿"
+  priority: 1000
+  name: Bitcoin
+- code: ETH
+  subunit: 18
+  symbol: "Ξ"
+  priority: 950
+  name: Ethereum
+- code: USDT
+  subunit: 6
+  symbol: "$"
+  priority: 900
+  name: Tether
+- code: SOL
+  subunit: 9
+  symbol: "◎"
+  priority: 850
+  name: Solana
+- code: XRP
+  subunit: 6
+  symbol: "✕"
+  priority: 800
+  name: XRP
+- code: BNB
+  subunit: 8
+  symbol: ""
+  priority: 750
+  name: BNB
+- code: USDC
+  subunit: 6
+  symbol: "$"
+  priority: 740
+  name: USD Coin
+- code: DOGE
+  subunit: 8
+  symbol: "Ð"
+  priority: 730
+  name: Dogecoin
+- code: ADA
+  subunit: 6
+  symbol: "₳"
+  priority: 720
+  name: Cardano
+- code: TRX
+  subunit: 6
+  symbol: ""
+  priority: 710
+  name: TRON
+- code: AVAX
+  subunit: 9
+  symbol: ""
+  priority: 700
+  name: Avalanche
+- code: DOT
+  subunit: 10
+  symbol: ""
+  priority: 680
+  name: Polkadot
+- code: LINK
+  subunit: 8
+  symbol: ""
+  priority: 660
+  name: Chainlink
+- code: MATIC
+  subunit: 6
+  symbol: "⧫"
+  priority: 640
+  name: Polygon
+- code: SHIB
+  subunit: 8
+  symbol: ""
+  priority: 620
+  name: Shiba Inu
+- code: UNI
+  subunit: 8
+  symbol: ""
+  priority: 600
+  name: Uniswap
+- code: ATOM
+  subunit: 6
+  symbol: ""
+  priority: 580
+  name: Cosmos
+- code: LTC
+  subunit: 8
+  symbol: "Ł"
+  priority: 560
+  name: Litecoin
+- code: BCH
+  subunit: 8
+  symbol: ""
+  priority: 540
+  name: Bitcoin Cash
+- code: FIL
+  subunit: 9
+  symbol: ""
+  priority: 520
+  name: Filecoin
+- code: APT
+  subunit: 8
+  symbol: ""
+  priority: 500
+  name: Aptos
+- code: SUI
+  subunit: 9
+  symbol: ""
+  priority: 480
+  name: Sui
+- code: TON
+  subunit: 9
+  symbol: ""
+  priority: 460
+  name: Toncoin
+- code: PEPE
+  subunit: 8
+  symbol: ""
+  priority: 440
+  name: Pepe
+- code: STX
+  subunit: 6
+  symbol: ""
+  priority: 420
+  name: Stacks

data/lib/minting/mint/i18n.rb

@@ -5,52 +5,102 @@ module Mint
   class << self
     # Optional callable that returns a Hash with locale-aware formatting defaults.
     #
-    # The callable receives no arguments and returns a Hash with these keys:
-    #   [+:decimal+]   Decimal separator (e.g. +","+)
-    #   [+:thousand+]  Thousands delimiter (e.g. +"."+)
-    #   [+:format+]    Format template string (e.g. +"%<amount>f %<symbol>s"+)
+    # The callable receives the locale (as passed to +#format+'s +locale:+ kwarg,
+    # or +nil+ when omitted) and returns a Hash with these keys (strings and
+    # symbols are treated interchangeably):
+    #   [+decimal+]   Decimal separator (e.g. +","+) — also accepts +:separator+
+    #   [+thousand+]  Thousands delimiter (e.g. +"."+) — also accepts +:delimiter+
+    #   [+format+]    Format template string (e.g. +"%<amount>f %<symbol>s"+)
     #
     # When set, +#to_formatted_s+ and +#format+ use these values as fallbacks when the
     # corresponding parameter is not explicitly provided.
     #
-    # @example Rails I18n integration (in attribute-money railtie)
-    #   Mint.locale_backend = -> {
-    #     fmt = I18n.t('number.currency.format')
-    #     {
-    #       decimal: fmt[:separator],
-    #       thousand: fmt[:delimiter],
-    #       format: fmt[:format] == '%n %u' ? '%<amount>f %<symbol>s' : '%<symbol>s%<amount>f'
-    #     }
+    # @example Per-locale formatting with string keys
+    #   LOCALE_DATA = {
+    #     'en'    => { decimal: '.', thousand: ',', format: '%<symbol>s%<amount>f' },
+    #     'de'    => { decimal: ',', thousand: '.', format: '%<amount>f %<currency>s' },
+    #   }.freeze
+    #   Mint.locale_backend = ->(locale) { LOCALE_DATA[locale.to_s] || {} }
+    #
+    # @example Rails I18n integration (direct pass-through, no mapping needed)
+    #   Mint.locale_backend = ->(locale = nil) {
+    #     I18n.with_locale(locale || I18n.default_locale) do
+    #       I18n.t('number.currency.format', default: {})
+    #     end
     #   }
     #
     # @return [Proc, #call, nil]
     attr_accessor :locale_backend
   end
 
+  # Resolves locale-aware formatting defaults from +Mint.locale_backend+.
+  #
+  # Returns a Hash with +:decimal+, +:thousand+, and +:format+ keys (any of
+  # which may be +nil+ if the backend doesn't provide them).
+  #
+  # @param locale [Symbol, String, nil] locale passed to the backend callable
+  # @return [Hash{Symbol => String, nil}]
   # @api private
-  class Money
-    private
+  def self.resolve_locale_for(locale: nil)
+    return EMPTY_LOCALE if Mint.locale_backend.nil?
+
+    lc = resolve_locale_backend(locale)
+    return EMPTY_LOCALE if lc.empty?
+
+    { decimal: fetch_locale_key(lc, :decimal),
+      thousand: fetch_locale_key(lc, :thousand),
+      format: fetch_locale_key(lc, :format) }.freeze
+  end
 
-    # Resolves format/decimal/thousand from locale_backend when not explicitly given.
-    # @private
-    def resolve_locale_for(format, decimal, thousand)
-      locale = locale_backend
+  EMPTY_LOCALE = { decimal: nil, thousand: nil, format: nil }.freeze
 
-      [format || locale[:format] || DEFAULT_FORMAT,
-       decimal || locale[:decimal] || '.',
-       thousand.nil? ? (locale[:thousand] || ',') : thousand]
+  # Looks up a locale key from a hash, trying both symbol and string forms.
+  #
+  # Supports aliases: +:decimal+ checks +:decimal+ and +:separator+,
+  # +:thousand+ checks +:thousand+ and +:delimiter+, +:format+ checks +:format+.
+  #
+  # @param hash [Hash] locale config hash
+  # @param key [Symbol] the primary key (+:decimal+, +:thousand+, or +:format+)
+  # @return [String, nil] the value found, or nil
+  # @api private
+  def self.fetch_locale_key(hash, key)
+    aliases = { decimal: %i[decimal separator], thousand: %i[thousand delimiter], format: [:format] }
+    aliases.fetch(key).each do |name|
+      val = hash[name] || hash[name.to_s]
+      return val unless val.nil?
     end
+    nil
+  end
 
-    def locale_backend
-      case bk = Mint.locale_backend
-      when Hash     then bk
-      when NilClass then {}
-      else
-        return bk.call if bk.respond_to?(:call)
+  # Resolves the locale backend configuration into a Hash.
+  #
+  # Handles three backend types:
+  # - +Hash+: returned as-is
+  # - +Proc+/callable: called with the locale (or no args for 0-arity),
+  #   result must be a Hash or nil
+  # - +nil+: returns empty Hash
+  #
+  # Invalid return values or backends emit a warning and return +{}+.
+  #
+  # @param locale [Symbol, String, nil] locale passed to the backend callable
+  # @return [Hash] locale configuration (possibly empty)
+  # @api private
+  def self.resolve_locale_backend(locale = nil)
+    case bk = Mint.locale_backend
+    when Hash     then bk
+    when NilClass then {}
+    else
+      if bk.respond_to?(:call)
+        args = bk.respond_to?(:arity) && bk.arity == 0 ? [] : [locale]
+        result = bk.call(*args)
+        return result if result.is_a?(Hash) || result.nil?
 
-        warn "ignoring invalid locale_backend: #{bk.inspect}"
-        {}
+        warn "ignoring invalid locale_backend result: #{result.inspect}"
+        return {}
       end
+
+      warn "ignoring invalid locale_backend: #{bk.inspect}"
+      {}
     end
   end
 end