Add custom currency support via custom_currency_path config

Allow apps to define custom currencies (e.g., loyalty points) by
pointing Money::Config to a YAML file. Lookup order: ISO → crypto →
custom, so custom currencies cannot shadow built-in ones.

Uses YAML.safe_load_file for user-provided paths and a path-keyed
cache to support per-Fiber config isolation.

Author: csgavino

lib/money/config.rb

@@ -41,7 +41,7 @@ def thread_local_config
       end
     end
 
-    attr_accessor :legacy_json_format, :experimental_crypto_currencies, :default_subunit_format
+    attr_accessor :legacy_json_format, :experimental_crypto_currencies, :default_subunit_format, :custom_currency_path
 
     attr_reader :default_currency
     alias_method :currency, :default_currency
@@ -72,6 +72,7 @@ def initialize
       @legacy_json_format = false
       @experimental_crypto_currencies = false
       @default_subunit_format = :iso4217
+      @custom_currency_path = nil
     end
   end
 end

lib/money/currency.rb

@@ -31,6 +31,15 @@ def crypto_currencies
         @@crypto_currencies ||= Loader.load_crypto_currencies
       end
 
+      def custom_currencies(path)
+        @@custom_currencies_cache ||= {}
+        @@custom_currencies_cache[path] ||= Loader.load_custom_currencies(path)
+      end
+
+      def reset_custom_currencies
+        @@custom_currencies_cache = nil
+      end
+
       def reset_loaded_currencies
         @@loaded_currencies = {}
       end
@@ -52,6 +61,10 @@ def initialize(currency_iso)
       if data.nil? && Money::Config.current.experimental_crypto_currencies
         data = self.class.crypto_currencies[currency_iso]
       end
+      if data.nil?
+        custom_path = Money::Config.current.custom_currency_path
+        data = self.class.custom_currencies(custom_path)[currency_iso] if custom_path
+      end
 
       raise UnknownCurrency, "Invalid iso4217 currency '#{currency_iso}'" unless data
       @symbol                = data['symbol']

lib/money/currency/loader.rb

@@ -22,6 +22,12 @@ def load_crypto_currencies
           deep_deduplicate!(currencies)
         end
 
+        def load_custom_currencies(path)
+          data = YAML.safe_load_file(path, permitted_classes: [])
+          raise ArgumentError, "Custom currency file must contain a YAML hash" unless data.is_a?(Hash)
+          deep_deduplicate!(data)
+        end
+
         private
 
         def deep_deduplicate!(data)

sig/money/config.rbs

@@ -7,6 +7,7 @@ class Money
     attr_accessor legacy_json_format: bool
     attr_accessor experimental_crypto_currencies: bool
     attr_accessor default_subunit_format: Symbol
+    attr_accessor custom_currency_path: String?
 
     attr_reader default_currency: (Currency | NullCurrency | nil)
     def default_currency=: (String | Currency | NullCurrency | nil value) -> (Currency | NullCurrency | nil)
@@ -16,7 +17,7 @@ class Money
     def self.global: () -> Config
     def self.current: () -> Config
     def self.current=: (Config config) -> Config
-    def self.configure_current: [T] (?currency: (String | Currency | NullCurrency | nil), ?legacy_json_format: bool, ?experimental_crypto_currencies: bool, ?default_subunit_format: Symbol) { () -> T } -> T
+    def self.configure_current: [T] (?currency: (String | Currency | NullCurrency | nil), ?legacy_json_format: bool, ?experimental_crypto_currencies: bool, ?default_subunit_format: Symbol, ?custom_currency_path: String?) { () -> T } -> T
     def self.reset_current: () -> nil
 
     private

sig/money/currency.rbs

@@ -7,6 +7,7 @@ class Money
 
       def self.load_currencies: () -> Hash[String, untyped]
       def self.load_crypto_currencies: () -> Hash[String, untyped]
+      def self.load_custom_currencies: (String path) -> Hash[String, untyped]
 
       private
 
@@ -31,6 +32,8 @@ class Money
     def self.find: (String | Symbol currency_iso) -> Currency?
     def self.currencies: () -> Hash[String, Hash[String, untyped]]
     def self.crypto_currencies: () -> Hash[String, Hash[String, untyped]]
+    def self.custom_currencies: (String path) -> Hash[String, Hash[String, untyped]]
+    def self.reset_custom_currencies: () -> nil
     def self.reset_loaded_currencies: () -> Hash[String, Currency]
 
     def initialize: (String currency_iso) -> void

spec/config_spec.rb

@@ -72,6 +72,18 @@
     end
   end
 
+  describe 'custom_currency_path' do
+    it 'defaults to nil' do
+      expect(Money::Config.new.custom_currency_path).to eq(nil)
+    end
+
+    it 'can be set to a path' do
+      config = Money::Config.new
+      config.custom_currency_path = '/tmp/custom.yml'
+      expect(config.custom_currency_path).to eq('/tmp/custom.yml')
+    end
+  end
+
   describe 'legacy_json_format' do
     it 'defaults to false' do
       expect(Money::Config.new.legacy_json_format).to eq(false)

spec/currency/loader_spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require 'spec_helper'
+require 'tempfile'
 
 RSpec.describe Money::Currency::Loader do
 
@@ -37,4 +38,53 @@
       expect(currencies['usdc']['iso_code']).to be_frozen
     end
   end
+
+  describe 'load_custom_currencies' do
+    it 'loads custom currencies from the given path' do
+      file = Tempfile.new(['custom_currencies', '.yml'])
+      file.write({
+        "credits" => {
+          "iso_code" => "CREDITS",
+          "name" => "Loyalty Points",
+          "symbol" => "CR",
+          "disambiguate_symbol" => "CR",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      }.to_yaml)
+      file.close
+
+      currencies = subject.load_custom_currencies(file.path)
+      expect(currencies['credits']['iso_code']).to eq('CREDITS')
+      expect(currencies['credits']['name']).to eq('Loyalty Points')
+      expect(currencies['credits']['symbol']).to eq('CR')
+      expect(currencies['credits']['subunit_to_unit']).to eq(1)
+    ensure
+      file.unlink
+    end
+
+    it 'returns frozen and deduplicated data' do
+      file = Tempfile.new(['custom_currencies', '.yml'])
+      file.write({
+        "credits" => {
+          "iso_code" => "CREDITS",
+          "name" => "Loyalty Points",
+          "symbol" => "CR",
+          "disambiguate_symbol" => "CR",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      }.to_yaml)
+      file.close
+
+      currencies = subject.load_custom_currencies(file.path)
+      expect(currencies).to be_frozen
+      expect(currencies['credits']).to be_frozen
+      expect(currencies['credits']['iso_code']).to be_frozen
+    ensure
+      file.unlink
+    end
+  end
 end

spec/currency_spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require 'spec_helper'
+require 'tempfile'
 
 RSpec.describe "Currency" do
   CURRENCY_DATA = {
@@ -17,6 +18,20 @@
 
   let(:currency) { Money::Currency.new('usd') }
 
+  let(:mock_custom_currency) do
+    {
+      "credits" => {
+        "iso_code" => "CREDITS",
+        "name" => "Loyalty Points",
+        "symbol" => "CR",
+        "disambiguate_symbol" => "CR",
+        "subunit_to_unit" => 1,
+        "smallest_denomination" => 1,
+        "decimal_mark" => "."
+      }
+    }
+  end
+
   let(:mock_crypto_currency) do
     { 
       "usdc" => { 
@@ -69,6 +84,89 @@
         expect(Money::Currency.find("USDC")).to be_nil
       end
     end
+
+    it "looks up custom currencies when path is set" do
+      allow(Money::Currency).to receive(:currencies).and_return({})
+      allow(Money::Currency).to receive(:custom_currencies).with('/tmp/custom.yml').and_return(mock_custom_currency)
+
+      configure(custom_currency_path: '/tmp/custom.yml') do
+        currency = Money::Currency.new('CREDITS')
+        expect(currency.iso_code).to eq('CREDITS')
+        expect(currency.symbol).to eq('CR')
+      end
+    end
+
+    it "doesn't look up custom currencies when path is nil" do
+      expect(Money::Currency.find("CREDITS")).to eq(nil)
+    end
+
+    it "can't override ISO currencies with custom currencies" do
+      allow(Money::Currency).to receive(:custom_currencies).with('/tmp/custom.yml').and_return(
+        "usd" => {
+          "iso_code" => "USD",
+          "name" => "Fake Dollar",
+          "symbol" => "FAKE",
+          "disambiguate_symbol" => "FAKE",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      )
+
+      configure(custom_currency_path: '/tmp/custom.yml') do
+        currency = Money::Currency.new('USD')
+        expect(currency.name).to eq('United States Dollar')
+        expect(currency.symbol).to eq('$')
+      end
+    end
+
+    it "can't override crypto currencies with custom currencies" do
+      allow(Money::Currency).to receive(:currencies).and_return({})
+      allow(Money::Currency).to receive(:crypto_currencies).and_return(mock_crypto_currency)
+      allow(Money::Currency).to receive(:custom_currencies).with('/tmp/custom.yml').and_return(
+        "usdc" => {
+          "iso_code" => "USDC",
+          "name" => "Fake USDC",
+          "symbol" => "FAKE",
+          "disambiguate_symbol" => "FAKE",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      )
+
+      configure(experimental_crypto_currencies: true, custom_currency_path: '/tmp/custom.yml') do
+        currency = Money::Currency.new('USDC')
+        expect(currency.name).to eq('USD Coin')
+        expect(currency.symbol).to eq('USDC')
+      end
+    end
+
+    it "loads custom currencies end-to-end from a YAML file" do
+      file = Tempfile.new(['custom_currencies', '.yml'])
+      file.write({
+        "credits" => {
+          "iso_code" => "CREDITS",
+          "name" => "Loyalty Points",
+          "symbol" => "CR",
+          "disambiguate_symbol" => "CR",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      }.to_yaml)
+      file.close
+
+      configure(custom_currency_path: file.path) do
+        money = Money.new(500, "CREDITS")
+        expect(money.currency.iso_code).to eq("CREDITS")
+        expect(money.currency.symbol).to eq("CR")
+        expect(money.currency.name).to eq("Loyalty Points")
+        expect(money.value).to eq(500)
+      end
+    ensure
+      file.unlink
+    end
   end
 
   describe ".find" do
@@ -96,6 +194,20 @@
         expect(Money::Currency.find('USDC')).to eq(nil)
       end
     end
+
+    it "returns custom currency when path is set" do
+      allow(Money::Currency).to receive(:currencies).and_return({})
+      allow(Money::Currency).to receive(:custom_currencies).with('/tmp/custom.yml').and_return(mock_custom_currency)
+
+      configure(custom_currency_path: '/tmp/custom.yml') do
+        expect(Money::Currency.find('CREDITS')).not_to eq(nil)
+        expect(Money::Currency.find('CREDITS').iso_code).to eq('CREDITS')
+      end
+    end
+
+    it "returns nil for custom currency when path is not set" do
+      expect(Money::Currency.find('CREDITS')).to eq(nil)
+    end
   end
 
   describe ".find!" do
@@ -123,6 +235,23 @@
     end
   end
 
+  describe ".custom_currencies" do
+    it "loads custom currencies from the loader" do
+      old_cache = Money::Currency.class_variable_get(:@@custom_currencies_cache) rescue nil
+      Money::Currency.class_variable_set(:@@custom_currencies_cache, nil)
+
+      allow(Money::Currency::Loader).to receive(:load_custom_currencies)
+        .with('/tmp/custom.yml')
+        .and_return(mock_custom_currency)
+
+      expect(Money::Currency.custom_currencies('/tmp/custom.yml')).to eq(mock_custom_currency)
+      expect(Money::Currency.custom_currencies('/tmp/custom.yml')).to eq(mock_custom_currency) # Second call to verify caching
+      expect(Money::Currency::Loader).to have_received(:load_custom_currencies).with('/tmp/custom.yml').once
+
+      Money::Currency.class_variable_set(:@@custom_currencies_cache, old_cache) if old_cache
+    end
+  end
+
   CURRENCY_DATA.each do |attribute, value|
     describe "##{attribute}" do
       it 'returns the correct value' do

spec/spec_helper.rb

@@ -75,17 +75,19 @@ def missing_methods
 end
 
 
-def configure(default_currency: nil, legacy_json_format: nil, experimental_crypto_currencies: nil)
+def configure(default_currency: nil, legacy_json_format: nil, experimental_crypto_currencies: nil, custom_currency_path: nil)
   Money::Config.current = Money::Config.new.tap do |config|
     config.default_currency = default_currency if default_currency
     config.legacy_json_format! if legacy_json_format
-    config.experimental_crypto_currencies! if experimental_crypto_currencies
+    config.experimental_crypto_currencies = experimental_crypto_currencies unless experimental_crypto_currencies.nil?
+    config.custom_currency_path = custom_currency_path if custom_currency_path
   end
-  Money::Currency.reset_loaded_currencies if experimental_crypto_currencies == false
 
   yield
 ensure
   Money::Config.reset_current
+  Money::Currency.reset_loaded_currencies
+  Money::Currency.reset_custom_currencies if custom_currency_path
 end
 
 def yaml_load(yaml)