minting 1.9.6 → 2.0.0

data/doc/agents/copilot-instructions.md

@@ -2,9 +2,9 @@ Repository overview
 
 - Language: Ruby gem (minting)
 - Location of main code: lib/minting and its subfolders (mint/, money/)
-- Public API surface: Mint (factory/helpers), Mint::Money, Mint::Currency
+- Public API surface: Mint (factory/helpers), Mint::Money, Money::Currency
 - Data: built-in currencies in lib/minting/data/currencies.yaml
-- Tests: Minitest (unit) + performance benchmarks under test/performance
+- Tests: Minitest (unit) + performance benchmarks under bench/
 
 Build, test and lint commands
 
@@ -43,7 +43,7 @@ High-level architecture (big picture)
 - Currency: lightweight value object (code, subunit, symbol, priority, minimum_amount).
 - Money: immutable value object stored as Rational and rounded to currency.subunit. Core concerns split across lib/minting/money/* (arithmetics, formatting, conversion, coercion, allocation, parsing, comparable).
 - Refinements: Numeric/String/Refinements in lib/minting/mint/refinements.rb expose helpers like 10.dollars, 4.to_money('USD'), and require `using Mint` in scope.
-- Performance tests: separate bench tasks under Rake; test/performance holds benchmark suites.
+- Performance tests: separate bench tasks under Rake; bench/ holds benchmark suites.
 
 Key conventions and repo-specific rules
 
@@ -59,7 +59,7 @@ Files and places to check first during edits
 - lib/minting/money - core behavior and arithmetic
 - lib/minting/mint - currency registry, refinements, and factory API
 - lib/minting/data/currencies.yaml - canonical currency definitions
-- test/ - unit tests; test/performance - benchmark suites
+- test/ - unit tests; bench/ - benchmark suites
 
 Notes for Copilot sessions
 
@@ -67,4 +67,4 @@ Notes for Copilot sessions
 - When changing numeric/rounding behavior, run both unit tests and relevant performance benchmarks.
 - Respect zero-equality semantics and currency code validation when modifying equality/hash logic.
 
-If you want, update this file with project-specific conventions to capture workflow choices (e.g., backport policy, DI patterns).
+If you want, update this file with project-specific conventions to capture workflow choices (e.g., backport policy, DI patterns).

data/doc/agents/expired/copilot-instructions.md

@@ -2,7 +2,7 @@ Repository overview
 
 - Language: Ruby gem (minting)
 - Location of main code: lib/minting and its subfolders (mint/, money/)
-- Public API surface: Mint (factory/helpers), Mint::Money, Mint::Currency
+- Public API surface: Mint (factory/helpers), Mint::Money, Money::Currency
 - Data: built-in currencies in lib/minting/data/currencies.yaml
 - Tests: Minitest (unit) + performance benchmarks under test/performance
 
@@ -72,4 +72,4 @@ Notes for Copilot sessions
 - When changing numeric/rounding behavior, run both unit tests and relevant performance benchmarks.
 - Respect zero-equality semantics and currency code validation when modifying equality/hash logic.
 
-If you want, update this file with project-specific conventions to capture workflow choices (e.g., backport policy, DI patterns).
+If you want, update this file with project-specific conventions to capture workflow choices (e.g., backport policy, DI patterns).

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

@@ -15,20 +15,25 @@ module Mint
   # @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) do
+                         :fractional_multiplier, :disambiguate_symbol) do
     # @param code [String] ISO 4217 currency code
     # @param symbol [String] Display symbol
     # @param subunit [Integer] Number of decimal places (default 0)
     # @param priority [Integer] Parser precedence for symbol detection (default 0)
     # @param country [String, nil] Associated country code (default nil)
     # @param name [String, nil] Currency name (default nil)
-    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: 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:)
+            fractional_multiplier:, disambiguate_symbol:)
     end
 
     # @return [String] debug representation
@@ -37,17 +42,29 @@ module Mint
     # @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
+    # 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)
+    # @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)
 
     # 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)
+
+    def dsymbol
+      disambiguate_symbol || (Registry.symbol_shared?(symbol) ? code : symbol)
+    end
   end
 
   # Registers a new currency, raising a KeyError if already registered.
@@ -65,20 +82,37 @@ module Mint
 
   # Resolves an object into a {Currency}, returning +nil+ when it can't.
   #
-  # Accepts +nil+, +String+, {Currency}, or {Money}.
-  # Passing a {Money} extracts its currency
+  # 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] a currency code, object, or +nil+
+  # @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 (e.g. +Integer+)
+  # @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          raise ArgumentError, "currency must be [Currency], [Money], [String] or nil (#{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
 
@@ -95,6 +129,15 @@ module Mint
     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
@@ -118,4 +161,36 @@ module Mint
   # @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/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