minting 1.6.0 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 293a64ebe3fd00ed8f6d062b596234550f85ead517b7f8094648dd9502be2f86
-  data.tar.gz: 3a98bb94ce601340b9cced8b275ee0be3e578d7e3cf781245cdd0fe5ee8038f1
+  metadata.gz: 0af1a3786bbef7fd2c9d3614ccd5076e0ad6f77fb35bd0d34e636355bafd4714
+  data.tar.gz: 520dfe15e4a3ddcd180a898769266d27502af54e3ad70503ed734ad351564639
 SHA512:
-  metadata.gz: fe587b6b5180c831b1e32092dfe9857ae37516f7fd274215be27e21af1263e99a93725f019e3be96962c5f20c13519326fc2b18b81b88e22aab43dc0d93a9b49
-  data.tar.gz: b0b8ca0b0dd832668e7b37dfbcca6e3606c673496c8149de90e9d2ffd21a166205e37ae9b455e36b1a71b07729a1d8c5bac074022991d45906ec7c410ec73740
+  metadata.gz: bd835b1ff970861a98dff3f056feb8903e2cb5145f0b60e52372d754daa65d60461e5200cc07de954963c0f31d954f8a8f54faf0a4f16746119e1195dc3c206e
+  data.tar.gz: 5f4e58dea85c7129e00aeef897810053136ba8d30cd49a4f199376b0e4f45885680bf1225b518dd479174e473da6e538efe30831e834e2ce41b3fdaf0a81235c

data/README.md

@@ -8,7 +8,7 @@ Fast, precise, and developer-friendly money handling for Ruby.
 
 **Tired of floating-point errors in financial calculations?** Minting uses Rational numbers for perfect precision.
 
-**Need performance?** Minting is 2× faster than alternatives for high-volume operations (often 10×+ for formatting). See the [Performance](#performance) section for full benchmarks.
+**Need performance?** Minting is 2× faster than alternatives for high-volume operations (often 10×+ for formatting). See the [Performance](https://github.com/gferraz/minting/blob/master/test/performance/README.md) section for full benchmarks.
 
 **Want a clean API?** Minting provides an intuitive interface with helpful error messages.
 
@@ -212,75 +212,10 @@ Bug reports and pull requests are welcome on GitHub at <https://github.com/gferr
 
 1. Fork and create a feature branch
 2. Run the test suite: `rake`
-3. Run performance suites as needed: `BENCH=true rake bench:performance`
+3. Run performance suites as needed: `rake bench:performance`
 4. Open a PR with a clear description and benchmarks if relevant
 
 
-## Performance
-
-This gem includes a performance suite under `test/performance`:
-
-- Core operations (creation, arithmetic, comparisons)
-- Algorithm benchmarks (split, allocate)
-- Memory and GC pressure tests
-- Competitive benchmarks vs `money` gem
-
-Run locally:
-
-```bash
-# All performance suites
-BENCH=true rake bench:performance
-
-# Competitive vs money gem
-BENCH=true rake bench:competitive
-
-# Regression checks
-rake bench:regression
-```
-
-## Benchmark Summary: Minting vs Money Gem
-
-Generated by Qwen from the latest benchmark run on Ruby 4.0.1. - 2026-05-30
-
-### Key Takeaways
-
-- **Mint is consistently faster** than the Money gem across all measured operations.
-- **Mint is 2.28x faster** in the 50,000-transaction simulation.
-- **Mint object creation is 2.76x faster** than `Money.from_amount`.
-- In formatting and conversion, Mint is often **10+x **.
-- Mint’s performance advantage is especially strong for numeric conversion, string formatting, comparisons, and high-volume transaction loops.
-
-### Performance Highlights
-
-| Category | Mint | Money | Approx. Ratio |
-| --- | --- | --- | --- |
-| High-volume transactions | 195,412 ops/sec | 85,882 ops/sec | 2.28x faster |
-| `Mint.money` creation | 1.14M ops/sec | — | 2.76x faster than `Money.from_amount` |
-| `some.dollars` creation | 990k ops/sec | — | 1.15x faster than `Mint.money` |
-| `Money.new` creation | — | 715k ops/sec | Mint 1.59x faster |
-| `to_f` formatting | 8.8M–9.3M ops/sec | 0.7M ops/sec | ~12x faster |
-| `to_d` conversion | 2.1M–2.3M ops/sec | 0.73M–0.79M ops/sec | ~3x faster |
-| `to_s` formatting | 300k–420k ops/sec | 109k–132k ops/sec | ~3x faster |
-| `inspect` formatting | ~2.6–2.9M ops/sec | ~1.1–1.16M ops/sec | ~2.5x faster |
-| `to_json` formatting | ~2.0–2.2M ops/sec | ~110k–126k ops/sec | ~17x faster |
-| Currency lookup `Mint.currency('USD')` | 3.82M ops/sec | — | 1.60x faster than `Money::Currency.new` |
-| Currency lookup `Money::Currency.find('USD')` | 3.63M ops/sec | 1.67M ops/sec | 2.29x faster |
-| Addition | 1.11M ops/sec | 0.37M ops/sec | 3.0x faster |
-| Subtraction | 1.11M ops/sec | 0.36M ops/sec | 3.0x faster |
-| Multiplication | 1.28M ops/sec | 0.51M ops/sec | 2.5x faster |
-| Division | 1.04M ops/sec | 0.37M ops/sec | 2.8x faster |
-| Ratio division | 2.94M ops/sec | 0.39M ops/sec | 7.6x faster |
-| Comparison (`==`, `<`, `>`) | 2.5M–4.1M ops/sec | 0.35M–0.38M ops/sec | 7x–10x faster |
-| Allocation (`Mint.allocate`) | 279k ops/sec | 146k ops/sec | 1.9x faster |
-| Split (`Mint.split`) | 215k ops/sec | 85k ops/sec | 3.3x faster |
-
-### Commands Used
-
-```sh
-BENCH=true bundle exec ruby -Ilib:test -r ./test/test_helper.rb test/performance/competitive_performance_benchmark.rb
-BENCH=true bundle exec ruby -Ilib:test -r ./test/test_helper.rb test/performance/competitive_memory_benchmark.rb
-```
-
 ## License
 
 MIT

data/Rakefile

@@ -12,33 +12,29 @@ Rake::TestTask.new(:test) do |t|
   t.ruby_opts << '-rtest_helper.rb'
 end
 
-Rake::TestTask.new('bench') do |t|
+Rake::TestTask.new('bench:all') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/*_benchmark.rb'
+  t.pattern = 'test/performance/**/*_benchmark.rb'
 end
 
-Rake::TestTask.new('bench:parse') do |t|
+Rake::TestTask.new('bench:core') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/parse_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/core/parse_benchmark.rb'
 end
 
-Rake::TestTask.new('bench:edge') do |t|
+Rake::TestTask.new('bench:memory') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/algorithm_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/memory/*_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:regression') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/regression_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/regression/*_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:competitive') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/competitive_performance_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/competitive/**/*_benchmark.rb'
 end
 
 RuboCop::RakeTask.new(:cop)

data/bin/check-currencies

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+
+require "yaml"
+require "set"
+
+yaml = YAML.load_file(
+  File.expand_path("~/code/minting/lib/minting/data/world-currencies.yaml")
+)
+
+minting_codes = yaml.map { |c| c["code"] }.to_set
+
+iso_codes = %w[
+  AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB
+  BRL BSD BTN BWP BYN BZD CAD CDF CHF CLP CNY COP CRC CUP CVE CZK DJF DKK DOP
+  DZD EGP ERN ETB EUR FJD FKP FOK GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL
+  HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KID KMF
+  KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR
+  MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG
+  QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLE SLL SOS SRD SSP STN SVC
+  SYP SZL THB TJS TMT TND TOP TRY TTD TVD TWD TZS UAH UGX USD UYU UZS VES VND
+  VUV WST XAF XCD XDR XOF XPF YER ZAR ZMW ZWL
+]
+
+missing = iso_codes.reject { |c| minting_codes.include?(c) }
+if missing.empty?
+  puts "Currencies: #{minting_codes.size}. No currency missing!"
+else
+  puts "Missing: #{missing.sort.join(", ")}"
+end

data/doc/agents/AGENTS.md

@@ -20,6 +20,6 @@ Project highlights & conventions:
 - Amounts stored as Rational; prefer rationals or decimal strings for precision
 - Zero-equality: zeros equal across currencies; non-zero comparisons require same currency
 - Currency codes must match /^[A-Z_]+$/
-- Tests: Minitest; performance benches under test/performance (use BENCH=true)
+- Tests: Minitest; performance benches under test/performance 
 
 Edit guidance: keep this file minimal and link to existing docs; add repo-specific agent tips here.

data/doc/agents/copilot-instructions.md

@@ -21,9 +21,9 @@ Build, test and lint commands
 - Run a single test method by name (Minitest -n regexp):
   - ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb -n /test_creation/
 
-- Performance suites (set BENCH=true as in README):
-  - BENCH=true rake bench:performance
-  - BENCH=true rake bench:competitive
+- Performance suites:
+  - rake bench:performance
+  - rake bench:competitive
   - rake bench:regression
 
 - Linting:
@@ -56,7 +56,7 @@ Key conventions and repo-specific rules
 - Currency registration: use Mint.register_currency for idempotent registration; Mint.register_currency! raises on duplicates. Codes must match /^[A-Z_]+$/.
 - Symbol parsing: parser resolves symbols by longest match then currency priority (see Mint.currency_symbols sorting).
 - Tests: test_helper.rb configures coverage (SimpleCov) and loads minitest; when running tests outside rake, require test_helper (-r ./test/test_helper.rb).
-- Benchmarks: set BENCH=true to enable benchmark-heavy tasks; benchmarks use Minitest::Benchmark patterns.
+- Benchmarks: set to enable benchmark-heavy tasks; benchmarks use Minitest::Benchmark patterns.
 - Formatting: Money.to_s uses Kernel.format patterns; take care with %<amount>f vs %<amount>d depending on desired rounding/formatting.
 
 Files and places to check first during edits

data/doc/agents/recommendations.md

@@ -87,7 +87,7 @@ Qwen run on 2026-05-30 and aren't reproducible from CI.
 **Concrete action:** in CI, run
 
 ```sh
-BENCH=true rake bench:regression
+ake bench:regression
 ```
 
 and fail the build if any benchmark regresses by more than (e.g.)

data/lib/minting/data/{currencies.yaml → world-currencies.yaml}

@@ -133,6 +133,12 @@
   symbol: د.إ
   name: United Arab Emirates Dirham
   priority: 600
+- code: YER
+  country: YEM
+  subunit: 2
+  symbol: "﷼"
+  name: Yemeni Rial
+  priority: 114
 - code: IDR
   country: IDN
   subunit: 2
@@ -151,6 +157,12 @@
   symbol: "₦"
   name: Nigerian Naira
   priority: 111
+- code: SOS
+  country: SOM
+  subunit: 2
+  symbol: Sh
+  name: Somali Shilling
+  priority: 110
 - code: BDT
   country: BGD
   subunit: 2
@@ -169,12 +181,24 @@
   symbol: "₽"
   name: Russian Ruble
   priority: 107
+- code: SYP
+  country: SYR
+  subunit: 2
+  symbol: "£"
+  name: Syrian Pound
+  priority: 106
 - code: ETB
   country: ETH
   subunit: 2
   symbol: Br
   name: Ethiopian Birr
   priority: 105
+- code: ZWL
+  country: ZWE
+  subunit: 2
+  symbol: Z$
+  name: Zimbabwean Dollar
+  priority: 104
 - code: PHP
   country: PHL
   subunit: 2
@@ -211,6 +235,12 @@
   symbol: "฿"
   name: Thai Baht
   priority: 98
+- code: TMT
+  country: TKM
+  subunit: 2
+  symbol: m
+  name: Turkmenistani Manat
+  priority: 97
 - code: TZS
   country: TZA
   subunit: 2
@@ -223,6 +253,12 @@
   symbol: FCFA
   name: Central African CFA franc
   priority: 95
+- code: DJF
+  country: DJI
+  subunit: 0
+  symbol: Fdj
+  name: Djiboutian Franc
+  priority: 94
 - code: KES
   country: KEN
   subunit: 2
@@ -241,6 +277,12 @@
   symbol: "$"
   name: Colombian Peso
   priority: 91
+- code: ERN
+  country: ERI
+  subunit: 2
+  symbol: Nfk
+  name: Eritrean Nakfa
+  priority: 90
 - code: UGX
   country: UGA
   subunit: 0
@@ -271,6 +313,12 @@
   symbol: "؋"
   name: Afghan Afghani
   priority: 85
+- code: LBP
+  country: LBN
+  subunit: 2
+  symbol: "£"
+  name: Lebanese Pound
+  priority: 84
 - code: MAD
   country: MAR
   subunit: 2
@@ -283,6 +331,12 @@
   symbol: zł
   name: Polish Zloty
   priority: 82
+- code: SVC
+  country: SLV
+  subunit: 2
+  symbol: "$"
+  name: El Salvadoran Colón
+  priority: 81
 - code: UAH
   country: UKR
   subunit: 2
@@ -337,6 +391,12 @@
   symbol: Bs.
   name: Venezuelan Bolívar
   priority: 72
+- code: SSP
+  country: SSD
+  subunit: 2
+  symbol: "£"
+  name: South Sudanese Pound
+  priority: 71
 - code: TWD
   country: TWN
   subunit: 2
@@ -445,6 +505,18 @@
   symbol: د.ا
   name: Jordanian Dinar
   priority: 53
+- code: ALL
+  country: ALB
+  subunit: 2
+  symbol: L
+  name: Albanian Lek
+  priority: 52
+- code: MKD
+  country: MKD
+  subunit: 2
+  symbol: ден
+  name: North Macedonian Denar
+  priority: 51
 - code: AZN
   country: AZE
   subunit: 2
@@ -481,6 +553,18 @@
   symbol: Br
   name: Belarusian Ruble
   priority: 45
+- code: BAM
+  country: BIH
+  subunit: 2
+  symbol: KM
+  name: Bosnia and Herzegovina Convertible Mark
+  priority: 44
+- code: MOP
+  country: MAC
+  subunit: 2
+  symbol: P
+  name: Macanese Pataca
+  priority: 43
 - code: LAK
   country: LAO
   subunit: 2
@@ -493,6 +577,12 @@
   symbol: лв
   name: Kyrgyzstani Som
   priority: 41
+- code: MVR
+  country: MDV
+  subunit: 2
+  symbol: Rf
+  name: Maldivian Rufiyaa
+  priority: 40
 - code: LYD
   country: LBY
   subunit: 3
@@ -523,6 +613,30 @@
   symbol: лв
   name: Bulgarian Lev
   priority: 36
+- code: GNF
+  country: GIN
+  subunit: 0
+  symbol: Fr
+  name: Guinean Franc
+  priority: 35
+- code: GMD
+  country: GMB
+  subunit: 2
+  symbol: D
+  name: Gambian Dalasi
+  priority: 34
+- code: SLL
+  country: SLE
+  subunit: 2
+  symbol: Le
+  name: Sierra Leonean Leone
+  priority: 33
+- code: STN
+  country: STP
+  subunit: 2
+  symbol: Db
+  name: São Tomé and Príncipe Dobra
+  priority: 31
 - code: CRC
   country: CRI
   subunit: 2
@@ -535,6 +649,12 @@
   symbol: د.ك
   name: Kuwaiti Dinar
   priority: 30
+- code: BTN
+  country: BTN
+  subunit: 2
+  symbol: Nu.
+  name: Bhutanese Ngultrum
+  priority: 30
 - code: OMR
   country: OMN
   subunit: 3
@@ -553,6 +673,12 @@
   symbol: kn
   name: Croatian Kuna
   priority: 27
+- code: KMF
+  country: COM
+  subunit: 0
+  symbol: CF
+  name: Comorian Franc
+  priority: 26
 - code: GEL
   country: GEO
   subunit: 2
@@ -565,6 +691,12 @@
   symbol: "$U"
   name: Uruguayan Peso
   priority: 25
+- code: SCR
+  country: SYC
+  subunit: 2
+  symbol: "₨"
+  name: Seychellois Rupee
+  priority: 24
 - code: AMD
   country: ARM
   subunit: 2
@@ -583,6 +715,12 @@
   symbol: "﷼"
   name: Qatari Riyal
   priority: 22
+- code: MUR
+  country: MUS
+  subunit: 2
+  symbol: "₨"
+  name: Mauritian Rupee
+  priority: 22
 - code: BWP
   country: BWA
   subunit: 2
@@ -595,24 +733,48 @@
   symbol: L
   name: Moldovan Leu
   priority: 20
+- code: ANG
+  country: null
+  subunit: 2
+  symbol: ƒ
+  name: Netherlands Antillean Guilder
+  priority: 19
 - code: NAD
   country: NAM
   subunit: 2
   symbol: N$
   name: Namibian Dollar
   priority: 19
+- code: CVE
+  country: CPV
+  subunit: 2
+  symbol: $
+  name: Cape Verdean Escudo
+  priority: 18
 - code: LSL
   country: LSO
   subunit: 2
   symbol: L
   name: Lesotho Loti
   priority: 18
+- code: GIP
+  country: GIB
+  subunit: 2
+  symbol: £
+  name: Gibraltar Pound
+  priority: 17
 - code: BHD
   country: BHR
   subunit: 3
   symbol: ".د.ب"
   name: Bahraini Dinar
   priority: 17
+- code: FKP
+  country: FLK
+  subunit: 2
+  symbol: £
+  name: Falkland Islands Pound
+  priority: 16
 - code: TTD
   country: TTO
   subunit: 2
@@ -710,8 +872,123 @@
   name: Tongan Paʻanga
   priority: 1
 - code: XXX
-  country:
+  country: null
   subunit: 0
   symbol: ¤
   name: No Currency
   priority: 0
+- code: AWG
+  country: ABW
+  subunit: 2
+  symbol: ƒ
+  name: Aruban Florin
+  priority: 0
+- code: BMD
+  country: BMU
+  subunit: 2
+  symbol: "$"
+  name: Bermudian Dollar
+  priority: 0
+- code: CDF
+  country: COD
+  subunit: 2
+  symbol: Fr
+  name: Congolese Franc
+  priority: 0
+- code: CUP
+  country: CUB
+  subunit: 2
+  symbol: "$"
+  name: Cuban Peso
+  priority: 0
+- code: FOK
+  country: FRO
+  subunit: 2
+  symbol: kr
+  name: Faroese Króna
+  priority: 0
+- code: GGP
+  country: GGY
+  subunit: 2
+  symbol: £
+  name: Guernsey Pound
+  priority: 0
+- code: IMP
+  country: IMN
+  subunit: 2
+  symbol: £
+  name: Manx Pound
+  priority: 0
+- code: JEP
+  country: JEY
+  subunit: 2
+  symbol: £
+  name: Jersey Pound
+  priority: 0
+- code: KID
+  country: KIR
+  subunit: 2
+  symbol: "$"
+  name: Kiribati Dollar
+  priority: 0
+- code: KYD
+  country: CYM
+  subunit: 2
+  symbol: "$"
+  name: Cayman Islands Dollar
+  priority: 0
+- code: LRD
+  country: LBR
+  subunit: 2
+  symbol: "$"
+  name: Liberian Dollar
+  priority: 0
+- code: MGA
+  country: MDG
+  subunit: 2
+  symbol: Ar
+  name: Malagasy Ariary
+  priority: 0
+- code: MNT
+  country: MNG
+  subunit: 2
+  symbol: "₮"
+  name: Mongolian Tögrög
+  priority: 0
+- code: MRU
+  country: MRT
+  subunit: 2
+  symbol: UM
+  name: Mauritanian Ouguiya
+  priority: 0
+- code: SDG
+  country: SDN
+  subunit: 2
+  symbol: "£"
+  name: Sudanese Pound
+  priority: 0
+- code: SHP
+  country: SHN
+  subunit: 2
+  symbol: "£"
+  name: Saint Helena Pound
+  priority: 0
+- code: SLE
+  country: SLE
+  subunit: 2
+  symbol: Le
+  name: Sierra Leonean Leone (re-denominated)
+  priority: 0
+- code: TVD
+  country: TUV
+  subunit: 2
+  symbol: "$"
+  name: Tuvaluan Dollar
+  priority: 0
+- code: XDR
+  country: null
+  subunit: 0
+  symbol: SDR
+  name: Special Drawing Rights
+  priority: 0
+

data/lib/minting/mint/currency/currency.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mint
+  # Represents a specific currency unit, identified by ISO 4217 alphabetic code.
+  # Currency objects are immutable and define the properties of a monetary unit
+  # including its subunit precision, display symbol, and formatting rules.
+  #
+  # @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)
+  Currency = Data.define(:code, :subunit, :symbol, :priority, :country, :name,
+                         :fractional_multiplier) do
+    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
+      subunit = subunit.to_i
+      priority = priority.to_i
+      fractional_multiplier = 10**subunit
+      super(code:, subunit:, symbol:, priority:, country:, name:,
+            fractional_multiplier:)
+    end
+
+    def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
+
+    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)
+  end
+end

data/lib/minting/mint/{currency_store.rb → currency/currency_registry.rb}

@@ -6,8 +6,8 @@ require 'yaml'
 module Mint
   # Internal currency registry
   # Manages the registry cache and currency symbol lookups.
-  module Registry
-    module_function
+  module CurrencyRegistry
+    extend self
 
     # Returns the hash of all registered currencies.
     #
@@ -30,6 +30,32 @@ module Mint
       end.freeze
     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 register(code:, subunit: 0, symbol: '', priority: 0)
+      raise ArgumentError, 'Currency code must be String' unless code.is_a? String
+      unless code.match?(/^[A-Z_]+$/)
+        raise ArgumentError,
+              "Currency code must have only letters or '_' ('USD',, 'MY_COIN')"
+      end
+
+      currencies = CurrencyRegistry.currencies
+      raise KeyError, "Currency: #{code} already registered" if currencies[code]
+
+      currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
+      invalidate_symbols_cache
+      currency
+    end
+
+    private
+
     # Clears and refreshes the currency symbol cache.
     # Called when currencies are registered.
     #

data/lib/minting/mint/{world_currencies.rb → currency/world_currencies.rb}

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
+# Mint list of world currencies
 module Mint
-  module_function
-
   # Loads ISO world currencies from YAML file into the registry.
   #
   # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
   # @api private
-  def world_currencies
+  def self.world_currencies
     @world_currencies ||= begin
-      path = File.join(File.expand_path('../data', __dir__), 'currencies.yaml')
+      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

data/lib/minting/mint/mint.rb

@@ -3,7 +3,7 @@
 # Mint currency registration and factory (public API)
 module Mint
   # Unknown currency excpetion
-  class UnknownCurreny < StandardError
+  class UnknownCurrency < StandardError
   end
 
   # Creates a new {Money} instance with the given amount and currency code.
@@ -23,8 +23,21 @@ module Mint
     case currency
     when nil      then nil
     when Currency then currency
-    when String   then Registry.currencies[currency]
+    when String   then CurrencyRegistry.currencies[currency]
     else raise ArgumentError, "currency must be [Currency] ot [String] (#{currency})"
     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 self.register_currency(code:, subunit: 0, symbol: '', priority: 0)
+    CurrencyRegistry.register(code:, subunit:, symbol:, priority:)
+  end
 end

data/lib/minting/mint/parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Mint Money parsing
 module Mint
   extend self
 
@@ -68,7 +69,7 @@ module Mint
       return currency if currency
 
       # Fall back to registered symbols, longest first (HK$ before $).
-      Mint.currency_symbols.each do |symbol, currency|
+      CurrencyRegistry.currency_symbols.each do |symbol, currency|
         return currency if input.include?(symbol)
       end
     end

data/lib/minting/mint.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require 'minting/mint/currency'
-require 'minting/mint/currency_store'
+require 'minting/mint/currency/currency'
+require 'minting/mint/currency/currency_registry'
+require 'minting/mint/currency/world_currencies'
 require 'minting/mint/mint'
 require 'minting/mint/parser'
-require 'minting/mint/registry'
 require 'minting/mint/refinements'
-require 'minting/mint/world_currencies'
 require 'minting/money/allocation'
 require 'minting/money/arithmetics'
 require 'minting/money/coercion'

data/lib/minting/money/coercion.rb

@@ -4,9 +4,13 @@ module Mint
   # Implements the standard Ruby coercion protocol.
   class Money
     # Allows {Money} to interact seamlessly as the right-hand operand in Numeric arithmetic.
+    # This enables expressions like `5 + money` where `5` is a Numeric and `money` is a Money object.
     #
     # @param other [Numeric] the left-hand operand to coerce
     # @return [Array(CoercedNumber, Money)] coerced operand array
+    # @example
+    #   price = Mint.money(10, 'USD')
+    #   5 + price  #=> [USD 15.00] (via coercion)
     def coerce(other)
       [CoercedNumber.new(other), self]
     end

data/lib/minting/money/constructors.rb

@@ -44,9 +44,16 @@ module Mint
       new(amount, checked_currency)
     end
 
-    # Returns a new Money object with the specified amount, or self if unchanged
-    # @param new_amount [Numeric] The new amount
-    # @return [Money] A new Money object or self
+    # Returns a new Money object with the specified amount, or self if unchanged.
+    # This is the primary method for creating a modified copy of a Money instance
+    # while preserving immutability.
+    #
+    # @param new_amount [Numeric] The new monetary amount
+    # @return [Money] A new Money object with the new amount, or self if the amount is unchanged
+    # @example
+    #   price = Mint.money(10.00, 'USD')
+    #   price.mint(15.00)  #=> [USD 15.00]
+    #   price.mint(10.00)  #=> [USD 10.00] (returns self)
     def mint(new_amount)
       new_amount = currency.normalize_amount(new_amount)
       new_amount == amount ? self : Money.new(new_amount, currency)

data/lib/minting/money/conversion.rb

@@ -9,6 +9,8 @@ module Mint
     # Converts the monetary amount to a BigDecimal object.
     #
     # @return [BigDecimal] the decimal representation of the money amount
+    # @example
+    #   Mint.money(9.99, 'USD').to_d  #=> 0.999e1
     def to_d = amount.to_d 0
 
     # Converts the monetary amount to a standard float.
@@ -31,8 +33,17 @@ module Mint
     # Truncates and converts the monetary amount to an Integer.
     #
     # @return [Integer] the integer representation of the money amount
+    # @example
+    #   Mint.money(9.99, 'USD').to_i  #=> 9
+    #   Mint.money(-9.99, 'USD').to_i #=> -9
     def to_i = amount.to_i
 
+    # Returns a Hash representation of the money instance.
+    #
+    # @return [Hash] hash with :currency (String) and :amount (String) keys
+    # @example
+    #   Mint.money(134120, 'BRL').to_hash
+    #   #=> { currency: "BRL", amount: "134120.00" }
     def to_hash
       { currency: currency_code, amount: Kernel.format("%0.#{currency.subunit}f", amount) }
     end

data/lib/minting/money/formatting.rb

@@ -91,9 +91,9 @@ module Mint
       end
       format ||= '%<symbol>s%<amount>f'
 
-      # Automatically adjust decimal places based on currency subunit
-      adjusted_format = format.gsub(/%<amount>(\+?\d*)f/,
-                                    "%<amount>\\1.#{currency.subunit}f")
+      # Automatically adjust decimal places based on currency subunit if missing
+      adjusted_format = format
+                        .gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{currency.subunit}f")
 
       Kernel.format(adjusted_format,
                     amount: value,

data/lib/minting/money/money.rb

@@ -11,9 +11,19 @@ module Mint
 
     # Returns the ISO 3-letter currency code string.
     #
-    # @return [String] the ISO currency code
+    # @return [String] the ISO currency code (e.g., "USD", "EUR", "BRL")
+    # @example
+    #   Mint.money(100, 'USD').currency_code  #=> "USD"
     def currency_code = currency.code
 
+    # Returns the monetary amount expressed in the currency's smallest unit (fractional units).
+    # For example, cents for USD (subunit 2), yen for JPY (subunit 0), fils for IQD (subunit 3).
+    #
+    # @return [Integer] the amount in fractional units
+    # @example
+    #   Mint.money(1234.56, 'USD').fractional  #=> 123456
+    #   Mint.money(1000, 'JPY').fractional     #=> 1000
+    #   Mint.money(123.456, 'IQD').fractional  #=> 123456
     def fractional = (amount * currency.fractional_multiplier).to_i
 
     # Generates a stable hash key for Money instances.

data/lib/minting/version.rb

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

data/lib/minting.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
 require 'minting/mint'
-require 'minting/money'
 require 'minting/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.6.2
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -32,6 +32,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bin/check-currencies
 - bin/console
 - bin/setup
 - doc/agents/AGENTS.md
@@ -40,15 +41,14 @@ files:
 - doc/agents/recommendations.md
 - doc/agents/rubocop-issues.md
 - lib/minting.rb
-- lib/minting/data/currencies.yaml
+- lib/minting/data/world-currencies.yaml
 - lib/minting/mint.rb
-- lib/minting/mint/currency.rb
-- lib/minting/mint/currency_store.rb
+- lib/minting/mint/currency/currency.rb
+- lib/minting/mint/currency/currency_registry.rb
+- lib/minting/mint/currency/world_currencies.rb
 - lib/minting/mint/mint.rb
 - lib/minting/mint/parser.rb
 - lib/minting/mint/refinements.rb
-- lib/minting/mint/registry.rb
-- lib/minting/mint/world_currencies.rb
 - lib/minting/money/allocation.rb
 - lib/minting/money/arithmetics.rb
 - lib/minting/money/coercion.rb

data/lib/minting/mint/currency.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Mint
-  # Represents a specific currency unit, identified by ISO 4217 alphabetic code
-  #
-  # @see https://www.iso.org/iso-4217-currency-codes.html
-  Currency = Data.define(:code, :subunit, :symbol, :priority, :country, :name,
-                         :fractional_multiplier, :minimum_amount) do
-    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
-      subunit = subunit.to_i
-      priority = priority.to_i
-      fractional_multiplier = 10**subunit
-      minimum_amount = Rational(1, fractional_multiplier)
-      super(code:, subunit:, symbol:, priority:, country:, name:,
-            fractional_multiplier:, minimum_amount:)
-    end
-
-    def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
-
-    # 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)
-  end
-end

data/lib/minting/mint/registry.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-# Mint currency registration and factory (public API)
-module Mint
-  # 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 self.register_currency(code:, subunit: 0, symbol: '', priority: 0)
-    raise ArgumentError, 'Currency code must be String' unless code.is_a? String
-    unless code.match?(/^[A-Z_]+$/)
-      raise ArgumentError,
-            "Currency code must have only letters or '_' ('USD',, 'MY_COIN')"
-    end
-
-    currencies = Registry.currencies
-    raise KeyError, "Currency: #{code} already registered" if currencies[code]
-
-    currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
-    Registry.invalidate_symbols_cache
-    currency
-  end
-
-  # Registered symbols sorted for detection: longest match wins, then parser priority.
-  # Internal API - used by Money parser.
-  #
-  # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
-  # @api private
-  def self.currency_symbols
-    Registry.currency_symbols
-  end
-end