shopify-money 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3376d45362e482215d25c4c1e256842d5a5011708ab3775125255e48637f5962
-  data.tar.gz: 2909f3605931b62b9efcb1799d928aea723fcde9a5f3182f3705a14887c1c2d1
+  metadata.gz: cadc7891cca0acc6f6128c570b259a5c1bead3a6a87175ebe3def93d9a618afb
+  data.tar.gz: 3fcc02abc7af2a86aba449ed135361a1024a18975430c8075f4b36d36d70c72a
 SHA512:
-  metadata.gz: 7bf580f71b0341993e260c1ee10036f46d585ffcb286fa567d0bc72b18e38a531600622f828a7d3895d0df48c0edc7aa3b9b539477f2ac5aacf7cd902ca8ac76
-  data.tar.gz: e5b249cb19e32a2ceb897cb047382a8fcb27b7408e4675f59a9b951dc8e916777e54038e43b7157d22484a6b443a9ad19273fb2030305f714ab184291742fc56
+  metadata.gz: 982ccb02e8ad20c3ad3ba9d217e0a53531d370cf32e7664947d859997ee2bc493614908f722fd1dc1ee0f234e114cb4c7e3552c85401d978afac4d462e35344c
+  data.tar.gz: 4a5e188fb292ad0ca2afdc2ba3dbcde89507a352d34ac7b7964870fc1584c0f9fd10d1036bd5b78a1971649d107b89f549f3b38a4f9bad823e829ac0c60d29ea

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shopify-money (4.0.0)
+    shopify-money (4.1.0)
       bigdecimal (>= 3.0)
 
 GEM

data/README.md

@@ -157,6 +157,23 @@ Money.new(money.value * exchange_rate, "JPY")
 money.convert_currency(exchange_rate, "JPY")
 ```
 
+### Allocation Strategy
+
+By default `allocate` distributes leftover subunits using the `:roundrobin` strategy.
+You can change the default:
+
+``` ruby
+Money.configure do |config|
+  config.default_allocation_strategy = :nearest
+end
+```
+
+Or pass a strategy per call:
+
+``` ruby
+Money.new(10.55, "USD").allocate([0.25, 0.5, 0.25], :nearest)
+```
+
 ### Crypto Currencies
 To enable support for currencies listed in `crypto.yml` use
 ``` ruby
@@ -165,6 +182,28 @@ Money.configure do |config|
 end
 ```
 
+### Custom Currencies
+To load custom currencies from a YAML file:
+``` ruby
+Money.configure do |config|
+  config.experimental_custom_currency_path = Rails.root.join("config/custom_currencies.yml")
+end
+```
+
+``` yaml
+# config/custom_currencies.yml
+credits:
+  iso_code: "CREDITS"
+  name: "Loyalty Points"
+  symbol: "CR"
+  disambiguate_symbol: "CR"
+  subunit_to_unit: 1
+  smallest_denomination: 1
+  decimal_mark: "."
+```
+
+Custom currencies are looked up after ISO and crypto currencies, so they cannot shadow built-in currencies.
+
 ### Converters
 The Money gem provides a flexible converter system for handling different subunit formats. This is particularly useful when working with payment providers or APIs that have their own conventions for handling currency subunits.
 

data/lib/money/allocator.rb

@@ -33,6 +33,8 @@ class Money
     # - `:roundrobin_reverse`: leftover subunits will be accumulated starting from the last allocation right to left
     # - `:nearest`: leftover subunits will by given first to the party closest to the next whole subunit
     #
+    # The default strategy can be changed via `Money::Config.current.default_allocation_strategy`.
+    #
     # @example
     #   Money.new(5, "USD").allocate([0.50, 0.25, 0.25])
     #     #=> [#<Money value:2.50 currency:USD>, #<Money value:1.25 currency:USD>, #<Money value:1.25 currency:USD>]
@@ -57,12 +59,16 @@ class Money
     #   Money.new(10.55, "USD").allocate([0.25, 0.5, 0.25], :nearest)
     #     #=> [#<Money value:2.64 currency:USD>, #<Money value:5.27 currency:USD>, #<Money value:2.64 currency:USD>]
 
-    def allocate(splits, strategy = :roundrobin)
+    def allocate(splits, strategy = nil)
       if splits.empty?
         raise ArgumentError, 'at least one split must be provided'
       end
 
-      splits.map!(&:to_r)
+      strategy ||= Money::Config.current.default_allocation_strategy
+
+      # Float#to_r preserves float imprecision (0.98.to_r != 98/100).
+      # Rationalize gives the clean fraction (0.98.rationalize == 49/50).
+      splits.map!(&:rationalize)
       allocations = splits.inject(0, :+)
 
       if (allocations - ONE) > Float::EPSILON

data/lib/money/config.rb

@@ -41,7 +41,7 @@ class Money
       end
     end
 
-    attr_accessor :legacy_json_format, :experimental_crypto_currencies, :default_subunit_format
+    attr_accessor :legacy_json_format, :experimental_crypto_currencies, :default_subunit_format, :experimental_custom_currency_path, :default_allocation_strategy
 
     attr_reader :default_currency
     alias_method :currency, :default_currency
@@ -72,6 +72,8 @@ class Money
       @legacy_json_format = false
       @experimental_crypto_currencies = false
       @default_subunit_format = :iso4217
+      @experimental_custom_currency_path = nil
+      @default_allocation_strategy = :roundrobin
     end
   end
 end

data/lib/money/currency/loader.rb

@@ -22,6 +22,13 @@ class Money
           deep_deduplicate!(currencies)
         end
 
+        def load_custom_currencies(path)
+          raise ArgumentError, "Custom currency file not found: #{path}" unless File.exist?(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)

data/lib/money/currency.rb

@@ -31,6 +31,15 @@ class Money
         @@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 @@ class Money
       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.experimental_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']

data/lib/money/money.rb

@@ -128,13 +128,16 @@ class Money
     raise ArgumentError if value.nan?
     raise ArgumentError if value.infinite?
 
-    @currency = Helpers.value_to_currency(currency)
+    @currency = currency
     @value = BigDecimal(value.round(@currency.minor_units))
     freeze
   end
 
   def init_with(coder)
-    initialize(Helpers.value_to_decimal(coder['value']), coder['currency'])
+    initialize(
+      Helpers.value_to_decimal(coder['value']),
+      Helpers.value_to_currency(coder['currency']),
+    )
   end
 
   def encode_with(coder)

data/lib/money/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Money
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

data/sig/money/config.rbs

@@ -7,6 +7,8 @@ class Money
     attr_accessor legacy_json_format: bool
     attr_accessor experimental_crypto_currencies: bool
     attr_accessor default_subunit_format: Symbol
+    attr_accessor experimental_custom_currency_path: String?
+    attr_accessor default_allocation_strategy: Symbol
 
     attr_reader default_currency: (Currency | NullCurrency | nil)
     def default_currency=: (String | Currency | NullCurrency | nil value) -> (Currency | NullCurrency | nil)
@@ -16,7 +18,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, ?experimental_custom_currency_path: String?, ?default_allocation_strategy: Symbol) { () -> T } -> T
     def self.reset_current: () -> nil
 
     private

data/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

data/spec/allocator_spec.rb

@@ -42,7 +42,7 @@ RSpec.describe "Allocator" do
 
     specify "#allocate will use rationals if provided" do
       splits = [128400,20439,14589,14589,25936].map{ |num| Rational(num, 203953) } # sums to > 1 if converted to float
-      expect(new_allocator(2.25).allocate(splits)).to eq([Money.new(1.42), Money.new(0.23), Money.new(0.16), Money.new(0.16), Money.new(0.28)])
+      expect(new_allocator(2.25).allocate(splits, :roundrobin)).to eq([Money.new(1.42), Money.new(0.23), Money.new(0.16), Money.new(0.16), Money.new(0.28)])
     end
 
     specify "#allocate will convert rationals with high precision" do
@@ -61,6 +61,29 @@ RSpec.describe "Allocator" do
       expect { new_allocator(0.03).allocate([0.5, 0.5], :bad_strategy_name) }.to raise_error(ArgumentError, "Invalid strategy. Valid options: :roundrobin, :roundrobin_reverse, :nearest")
     end
 
+    specify "#allocate defaults to :nearest strategy" do
+      # With :nearest, the party closest to the next whole subunit gets the leftover.
+      monies = new_allocator(1).allocate([0.02, 0.98])
+      expect(monies[0]).to eq(Money.new(0.02))
+      expect(monies[1]).to eq(Money.new(0.98))
+    end
+
+    specify "#allocate uses the configured default_allocation_strategy" do
+      Money.with_config(default_allocation_strategy: :roundrobin) do
+        # With :roundrobin, leftover subunits accumulate from the first allocation.
+        monies = new_allocator(0.05).allocate([0.33, 0.34, 0.33])
+        expect(monies[0]).to eq(Money.new(0.02))
+        expect(monies[1]).to eq(Money.new(0.02))
+        expect(monies[2]).to eq(Money.new(0.01))
+      end
+    end
+
+    specify "#allocate exact splits produce no leftover regardless of strategy" do
+      monies = new_allocator(1).allocate([0.02, 0.98], :roundrobin)
+      expect(monies[0]).to eq(Money.new(0.02))
+      expect(monies[1]).to eq(Money.new(0.98))
+    end
+
     specify "#allocate raises an error when splits exceed 100%" do
       expect { new_allocator(0.03).allocate([0.5, 0.6]) }.to raise_error(ArgumentError, "allocations add to more than 100%")
     end

data/spec/config_spec.rb

@@ -72,6 +72,30 @@ RSpec.describe "Money::Config" do
     end
   end
 
+  describe 'experimental_custom_currency_path' do
+    it 'defaults to nil' do
+      expect(Money::Config.new.experimental_custom_currency_path).to eq(nil)
+    end
+
+    it 'can be set to a path' do
+      config = Money::Config.new
+      config.experimental_custom_currency_path = '/tmp/custom.yml'
+      expect(config.experimental_custom_currency_path).to eq('/tmp/custom.yml')
+    end
+  end
+
+  describe 'default_allocation_strategy' do
+    it 'defaults to :roundrobin' do
+      expect(Money::Config.new.default_allocation_strategy).to eq(:roundrobin)
+    end
+
+    it 'can be set to a different strategy' do
+      config = Money::Config.new
+      config.default_allocation_strategy = :roundrobin
+      expect(config.default_allocation_strategy).to eq(:roundrobin)
+    end
+  end
+
   describe 'legacy_json_format' do
     it 'defaults to false' do
       expect(Money::Config.new.legacy_json_format).to eq(false)

data/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,55 @@ RSpec.describe Money::Currency::Loader do
       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 = custom_currency_file(
+        "credits" => {
+          "iso_code" => "CREDITS",
+          "name" => "Loyalty Points",
+          "symbol" => "CR",
+          "disambiguate_symbol" => "CR",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      )
+
+      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 'raises ArgumentError when file does not exist' do
+      expect {
+        subject.load_custom_currencies('/nonexistent/path.yml')
+      }.to raise_error(ArgumentError, /not found/)
+    end
+
+    it 'returns frozen and deduplicated data' do
+      file = custom_currency_file(
+        "credits" => {
+          "iso_code" => "CREDITS",
+          "name" => "Loyalty Points",
+          "symbol" => "CR",
+          "disambiguate_symbol" => "CR",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      )
+
+      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

data/spec/currency_spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require 'spec_helper'
+require 'tempfile'
 
 RSpec.describe "Currency" do
   CURRENCY_DATA = {
@@ -16,6 +17,20 @@ RSpec.describe "Currency" do
 
   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" => { 
@@ -68,6 +83,80 @@ RSpec.describe "Currency" do
         expect(Money::Currency.find("USDC")).to be_nil
       end
     end
+
+    it "looks up custom currencies when path is set" do
+      file = custom_currency_file(mock_custom_currency)
+
+      configure(experimental_custom_currency_path: file.path) do
+        currency = Money::Currency.new('CREDITS')
+        expect(currency.iso_code).to eq('CREDITS')
+        expect(currency.symbol).to eq('CR')
+      end
+    ensure
+      file.unlink
+    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
+      file = custom_currency_file(
+        "usd" => {
+          "iso_code" => "USD",
+          "name" => "Fake Dollar",
+          "symbol" => "FAKE",
+          "disambiguate_symbol" => "FAKE",
+          "subunit_to_unit" => 1,
+          "smallest_denomination" => 1,
+          "decimal_mark" => "."
+        }
+      )
+
+      configure(experimental_custom_currency_path: file.path) do
+        currency = Money::Currency.new('USD')
+        expect(currency.name).to eq('United States Dollar')
+        expect(currency.symbol).to eq('$')
+      end
+    ensure
+      file.unlink
+    end
+
+    it "can't override crypto currencies with custom currencies" do
+      file = custom_currency_file(
+        "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, experimental_custom_currency_path: file.path) do
+        currency = Money::Currency.new('USDC')
+        expect(currency.name).to eq('USD Coin')
+        expect(currency.symbol).to eq('USDC')
+      end
+    ensure
+      file.unlink
+    end
+
+    it "loads custom currencies end-to-end from a YAML file" do
+      file = custom_currency_file(mock_custom_currency)
+
+      configure(experimental_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
@@ -95,6 +184,21 @@ RSpec.describe "Currency" do
         expect(Money::Currency.find('USDC')).to eq(nil)
       end
     end
+
+    it "returns custom currency when path is set" do
+      file = custom_currency_file(mock_custom_currency)
+
+      configure(experimental_custom_currency_path: file.path) do
+        expect(Money::Currency.find('CREDITS')).not_to eq(nil)
+        expect(Money::Currency.find('CREDITS').iso_code).to eq('CREDITS')
+      end
+    ensure
+      file.unlink
+    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
@@ -122,6 +226,20 @@ RSpec.describe "Currency" do
     end
   end
 
+  describe ".custom_currencies" do
+    after { Money::Currency.reset_custom_currencies }
+
+    it "loads custom currencies from the loader" do
+      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
+    end
+  end
+
   CURRENCY_DATA.each do |attribute, value|
     describe "##{attribute}" do
       it 'returns the correct value' do

data/spec/spec_helper.rb

@@ -75,17 +75,27 @@ RSpec::Matchers.define :quack_like do
 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, experimental_custom_currency_path: nil, default_allocation_strategy: 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.experimental_custom_currency_path = experimental_custom_currency_path if experimental_custom_currency_path
+    config.default_allocation_strategy = default_allocation_strategy if default_allocation_strategy
   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 experimental_custom_currency_path
+end
+
+def custom_currency_file(currencies_hash)
+  file = Tempfile.new(['custom_currencies', '.yml'])
+  file.write(currencies_hash.to_yaml)
+  file.close
+  file
 end
 
 def yaml_load(yaml)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shopify-money
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Shopify Inc
@@ -252,7 +252,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Shopify's money gem
 test_files: []