shopify-money 2.0.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 591c60e355144246085ac254fe82b099c85ab4bf7f1e37672b8082331bd9d0aa
-  data.tar.gz: 493384ced59c9a37ebc798b4cb499bd0532ea30243c8248704bf0df6f776ca0f
+  metadata.gz: 75140fb176288187177a79f673b9741b69a4ae96e02b314139318d7ff817b8b9
+  data.tar.gz: d98030d40029dbb686b83b090ab11e43628a194bd2902ba130f5161e860dc839
 SHA512:
-  metadata.gz: 1867df0795206ccd5996b1d8471f23f60340ace3e5e685ddbb98f601402a7748aade38263dbc7f12971c1e4368919cb0122c53eacf0b96b96df44189be3ca32e
-  data.tar.gz: 9ed8869fce8e66c4e9aee275ac3a28c24db47fd2ae8537f2ff3ee100541f122cd9b8b87e7ca102567b976548eb04b53b06f6c560f2e6e12dc3ca506e0bb87f01
+  metadata.gz: 3e140de24fea5b7c90b5044f4b9732e013187a6cad34c7ea6bd9d8119cd118907c7faeb934ed533085389e3e55f7ba0649697e7563ec87380c6fc62ff9a1c935
+  data.tar.gz: 5a1d77f26c7886fc1a96edee8a920df4262385fce001209d640c9427e986e9d95d2d9a8232fca17a670758f45a7bc219d728386c080606d1f8bc348cb71ba0a3

data/.gitignore

@@ -46,6 +46,5 @@ pkg
 
 # For rubinius:
 #*.rbc
-Gemfile.lock
 
-.rspec_status
+.rspec_status

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/Gemfile.lock

@@ -0,0 +1,234 @@
+PATH
+  remote: .
+  specs:
+    shopify-money (2.2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.1.7.7)
+      actionpack (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.1.7.7)
+      actionpack (= 6.1.7.7)
+      activejob (= 6.1.7.7)
+      activerecord (= 6.1.7.7)
+      activestorage (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      mail (>= 2.7.1)
+    actionmailer (6.1.7.7)
+      actionpack (= 6.1.7.7)
+      actionview (= 6.1.7.7)
+      activejob (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.1.7.7)
+      actionview (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      rack (~> 2.0, >= 2.0.9)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.1.7.7)
+      actionpack (= 6.1.7.7)
+      activerecord (= 6.1.7.7)
+      activestorage (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      nokogiri (>= 1.8.5)
+    actionview (6.1.7.7)
+      activesupport (= 6.1.7.7)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.1.7.7)
+      activesupport (= 6.1.7.7)
+      globalid (>= 0.3.6)
+    activemodel (6.1.7.7)
+      activesupport (= 6.1.7.7)
+    activerecord (6.1.7.7)
+      activemodel (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+    activestorage (6.1.7.7)
+      actionpack (= 6.1.7.7)
+      activejob (= 6.1.7.7)
+      activerecord (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      marcel (~> 1.0)
+      mini_mime (>= 1.1.0)
+    activesupport (6.1.7.7)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.2.3)
+    crass (1.0.6)
+    database_cleaner (1.99.0)
+    date (3.3.4)
+    diff-lcs (1.5.1)
+    docile (1.4.0)
+    erubi (1.12.0)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.4)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.6)
+    loofah (2.22.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    method_source (1.0.0)
+    mini_mime (1.1.5)
+    minitest (5.22.3)
+    net-imap (0.4.10)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.0)
+      net-protocol
+    nio4r (2.7.1)
+    nokogiri (1.16.3-aarch64-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.3-arm-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.3-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.3-x86-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.3-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.3-x86_64-linux)
+      racc (~> 1.4)
+    parallel (1.24.0)
+    parser (3.3.0.5)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    racc (1.7.3)
+    rack (2.2.9)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rails (6.1.7.7)
+      actioncable (= 6.1.7.7)
+      actionmailbox (= 6.1.7.7)
+      actionmailer (= 6.1.7.7)
+      actionpack (= 6.1.7.7)
+      actiontext (= 6.1.7.7)
+      actionview (= 6.1.7.7)
+      activejob (= 6.1.7.7)
+      activemodel (= 6.1.7.7)
+      activerecord (= 6.1.7.7)
+      activestorage (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      bundler (>= 1.15.0)
+      railties (= 6.1.7.7)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.0)
+      loofah (~> 2.21)
+      nokogiri (~> 1.14)
+    railties (6.1.7.7)
+      actionpack (= 6.1.7.7)
+      activesupport (= 6.1.7.7)
+      method_source
+      rake (>= 12.2)
+      thor (~> 1.0)
+    rainbow (3.1.1)
+    rake (13.2.0)
+    rexml (3.2.6)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (0.81.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rexml
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sprockets (4.2.1)
+      concurrent-ruby (~> 1.0)
+      rack (>= 2.2.4, < 4)
+    sprockets-rails (3.4.2)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.7.3-aarch64-linux)
+    sqlite3 (1.7.3-arm-linux)
+    sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86-linux)
+    sqlite3 (1.7.3-x86_64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
+    thor (1.3.1)
+    timeout (0.4.1)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (1.8.0)
+    websocket-driver (0.7.6)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.6.13)
+
+PLATFORMS
+  aarch64-linux
+  arm-linux
+  arm64-darwin
+  x86-linux
+  x86_64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  bundler
+  database_cleaner (~> 1.6)
+  pry-byebug
+  rails (~> 6.0)
+  rspec (~> 3.2)
+  rubocop (~> 0.81.0)
+  shopify-money!
+  simplecov
+  sqlite3
+
+BUNDLED WITH
+   2.5.3

data/README.md

@@ -3,7 +3,7 @@
 [![tests](https://github.com/Shopify/money/workflows/tests/badge.svg)](https://github.com/Shopify/money/actions?query=workflow%3Atests+branch%3Amain)
 
 
-money_column expects a DECIMAL(21,3) database field.
+`money_column` expects a `DECIMAL(21,3)` database field.
 
 ### Features
 
@@ -11,7 +11,8 @@ money_column expects a DECIMAL(21,3) database field.
 - Provides a `Money::Currency` class which encapsulates all information about a monetary unit.
 - Represents monetary values as decimals. No need to convert your amounts every time you use them. Easily understand the data in your DB.
 - Does NOT provide APIs for exchanging money from one currency to another.
-- Will not lose pennies during divisions
+- Will not lose pennies during divisions. For instance, given $1 / 3 the resulting chunks will be .34, .33, and .33. Notice that one chunk is larger than the others, so the result still adds to $1.
+- Allows callers to select a rounding strategy when dividing, to determine the order in which leftover pennies are given out.
 
 ## Installation
 
@@ -57,6 +58,30 @@ m.allocate([Rational(2, 3), Rational(1, 3)]).map(&:value) == [666.67, 333.33]
 m.allocate_max_amounts([500, 300, 200]).map(&:value) == [500, 300, 200]
 m.allocate_max_amounts([500, 300, 300]).map(&:value) == [454.55, 272.73, 272.72]
 
+## Selectable rounding strategies during division
+
+# Assigns leftover subunits left to right
+m = Money::Allocator.new(Money.new(10.55, "USD"))
+monies = m.allocate([0.25, 0.5, 0.25], :roundrobin)
+#monies[0] == 2.64  <-- gets 1 penny
+#monies[1] == 5.28  <-- gets 1 penny
+#monies[2] == 2.63  <-- gets no penny
+
+# Assigns leftover subunits right to left
+m = Money::Allocator.new(Money.new(10.55, "USD"))
+monies = m.allocate([0.25, 0.5, 0.25], :roundrobin_reverse)
+#monies[0] == 2.63  <-- gets no penny
+#monies[1] == 5.28  <-- gets 1 penny
+#monies[2] == 2.64  <-- gets 1 penny
+
+# Assigns leftover subunits to the nearest whole subunit
+m = Money::Allocator.new(Money.new(10.55, "USD"))
+monies = m.allocate([0.25, 0.5, 0.25], :nearest)
+#monies[0] == 2.64  <-- gets 1 penny
+#monies[1] == 5.27  <-- gets no penny
+#monies[2] == 2.64  <-- gets 1 penny
+# $2.6375 is closer to the next whole penny than $5.275
+
 # Clamp
 Money.new(50, "USD").clamp(1, 100) == Money.new(50, "USD")
 
@@ -170,17 +195,11 @@ require:
 
 Money/MissingCurrency:
   Enabled: true
-  # If your application is currently handling only one currency,
-  # it can autocorrect this by specifying a default currency.
-  ReplacementCurrency: CAD
+  # ReplacementCurrency: CAD
 
 Money/ZeroMoney:
   Enabled: true
-  # Same here:
   # ReplacementCurrency: CAD
-
-Money/UnsafeToMoney:
-  Enabled: true
 ```
 
 ## Contributing to money
@@ -193,6 +212,21 @@ Money/UnsafeToMoney:
 - Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 - Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
+### Releasing
+
+To release a new version of the gem, follow these steps:
+
+- Audit what has changed since the last version of the gem was released.
+- Determine what the next version number should be, according to [Semantic Versioning](https://semver.org/).
+- Open a PR to update the version accordingly in `lib/money/version`.
+- After getting approval, merge the PR.
+- [**Publish** a release in Github](https://github.com/Shopify/money/releases/new):
+  - Target the `main` branch with a tag matching the new version, prefixed with `v` (e.g. `v1.2.3`).
+  - Use the "Generate Release Notes" button to help generate the copy for the release. Include **consumer facing changes** in the release notes.
+- Deploy the new version to Rubygems using [ShipIt](https://shipit.shopify.io/shopify/money/production).
+- For more information see [the publish a gem vault page](https://vault.shopify.io/page/Publish-a-new-version-of-an-internal-gem~dhbc57d.md)
+- You are now responsible to [merge the bump PR in core](https://github.com/Shopify/shopify/pulls?q=is%3Aopen+is%3Apr+author%3Aapp%2Fdependabot+shopify-money+)
+
 ## Copyright
 
 Copyright (c) 2011 Shopify. See LICENSE.txt for

data/dev.yml

@@ -3,7 +3,7 @@
 ---
 name: money
 up:
-- ruby: 3.3.0
+- ruby
 - bundler
 commands:
   test: bundle exec rspec

data/lib/money/allocator.rb

@@ -9,18 +9,27 @@ class Money
 
     ONE = BigDecimal("1")
 
-    # Allocates money between different parties without losing pennies.
-    # After the mathematically split has been performed, left over pennies will
-    # be distributed round-robin amongst the parties. This means that parties
-    # listed first will likely receive more pennies than ones that are listed later
+    # Allocates money between different parties without losing subunits. A "subunit"
+    # in this context is the smallest unit of a currency that can be divided no
+    # further. In USD the unit is dollars and the subunit is cents. In JPY the unit
+    # is yen and the subunit is also yen. So given $1 divided by 3, the resulting subunits
+    # should be [34¢, 33¢, 33¢]. Notice that one of these chunks is larger than the other
+    # two, because we cannot transact in amounts less than 1 subunit.
+    #
+    # After the mathematically split has been performed, left over subunits will
+    # be distributed round-robin or nearest-subunit strategy amongst the parties.
+    # Round-robin strategy has the virtue of being easier to understand, while
+    # nearest-subunit is a more complex alogirthm that results in the most fair
+    # distribution.
     #
     # @param splits [Array<Numeric>]
     # @param strategy Symbol
     # @return [Array<Money>]
     #
     # Strategies:
-    # - `:roundrobin` (default): leftover pennies will be accumulated starting from the first allocation left to right
-    # - `:roundrobin_reverse`: leftover pennies will be accumulated starting from the last allocation right to left
+    # - `:roundrobin` (default): leftover subunits will be accumulated starting from the first allocation left to right
+    # - `: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
     #
     # @example
     #   Money.new(5, "USD").allocate([0.50, 0.25, 0.25])
@@ -38,29 +47,49 @@ class Money
     #   Money.new(30, "USD").allocate([Rational(2, 3), Rational(1, 3)])
     #     #=> [#<Money value:20.00 currency:USD>, #<Money value:10.00 currency:USD>]
 
-    # @example left over pennies distributed reverse order when using roundrobin_reverse strategy
+    # @example left over subunits distributed reverse order when using roundrobin_reverse strategy
     #   Money.new(10.01, "USD").allocate([0.5, 0.5], :roundrobin_reverse)
     #     #=> [#<Money value:5.00 currency:USD>, #<Money value:5.01 currency:USD>]
+
+    # @examples left over subunits distributed by nearest strategy
+    #   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)
+      if splits.empty?
+        raise ArgumentError, 'at least one split must be provided'
+      end
+
       splits.map!(&:to_r)
       allocations = splits.inject(0, :+)
 
       if (allocations - ONE) > Float::EPSILON
-        raise ArgumentError, "splits add to more than 100%"
+        raise ArgumentError, "allocations add to more than 100%"
       end
 
       amounts, left_over = amounts_from_splits(allocations, splits)
 
+      order = case strategy
+      when :roundrobin
+        (0...left_over).to_a
+      when :roundrobin_reverse
+        (0...amounts.length).to_a.reverse
+      when :nearest
+        rank_by_nearest(amounts)
+      else
+        raise ArgumentError, "Invalid strategy. Valid options: :roundrobin, :roundrobin_reverse, :nearest"
+      end
+
       left_over.to_i.times do |i|
-        amounts[allocation_index_for(strategy, amounts.length, i)] += 1
+        amounts[order[i]][:whole_subunits] += 1
       end
 
-      amounts.collect { |subunits| Money.from_subunits(subunits, currency) }
+      amounts.map { |amount| Money.from_subunits(amount[:whole_subunits], currency) }
     end
 
     # Allocates money between different parties up to the maximum amounts specified.
-    # Left over pennies will be assigned round-robin up to the maximum specified.
-    # Pennies are dropped when the maximums are attained.
+    # Left over subunits will be assigned round-robin up to the maximum specified.
+    # Subunits are dropped when the maximums are attained.
     #
     # @example
     #   Money.new(30.75).allocate_max_amounts([Money.new(26), Money.new(4.75)])
@@ -90,6 +119,7 @@ class Money
       total_allocatable = [maximums_total.subunits, self.subunits].min
 
       subunits_amounts, left_over = amounts_from_splits(1, splits, total_allocatable)
+      subunits_amounts.map! { |amount| amount[:whole_subunits] }
 
       subunits_amounts.each_with_index do |amount, index|
         break unless left_over > 0
@@ -119,10 +149,14 @@ class Money
 
       left_over = subunits_to_split
 
-      amounts = splits.collect do |ratio|
-        frac = (subunits_to_split * ratio / allocations.to_r).floor
-        left_over -= frac
-        frac
+      amounts = splits.map do |ratio|
+        whole_subunits = (subunits_to_split * ratio / allocations.to_r).floor
+        fractional_subunits = (subunits_to_split * ratio / allocations.to_r).to_f - whole_subunits
+        left_over -= whole_subunits
+        {
+          :whole_subunits => whole_subunits,
+          :fractional_subunits => fractional_subunits
+        }
       end
 
       [amounts, left_over]
@@ -132,15 +166,13 @@ class Money
       splits.all? { |split| split.is_a?(Rational) }
     end
 
-    def allocation_index_for(strategy, length, idx)
-      case strategy
-      when :roundrobin
-        idx % length
-      when :roundrobin_reverse
-        length - (idx % length) - 1
-      else
-        raise ArgumentError, "Invalid strategy. Valid options: :roundrobin, :roundrobin_reverse"
-      end
+    # Given a list of decimal numbers, return a list ordered by which is nearest to the next whole number.
+    # For instance, given inputs [1.1, 1.5, 1.9] the correct ranking is 2, 1, 0. This is because 1.9 is nearly 2.
+    # Note that we are not ranking by absolute size, we only care about the distance between our input number and
+    # the next whole number. Similarly, given the input [9.1, 5.5, 3.9] the correct ranking is *still* 2, 1, 0. This
+    # is because 3.9 is nearer to 4 than 9.1 is to 10.
+    def rank_by_nearest(amounts)
+      amounts.each_with_index.sort_by{ |amount, i| 1 - amount[:fractional_subunits] }.map(&:last)
     end
   end
 end

data/lib/money/helpers.rb

@@ -16,6 +16,8 @@ class Money
     def value_to_decimal(num)
       value =
         case num
+        when Money
+          num.value
         when BigDecimal
           num
         when nil, 0, ''