amounts 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92c0c2ebae750b68a79648157559ca2fe6c0c67d5892a83a31beb36e15936648
-  data.tar.gz: c5b8661d2b980a48a655407fdababfe8428bdd978e1fd7a6d52a6d8a554be287
+  metadata.gz: 95dbf17ecb45d86b36277c6ecdaf611bdcb99d12eb97a3fc42b5f3bf2cd1ec50
+  data.tar.gz: 67fcceae2bae4582f4c4e2866f453727a23f444703e47717ab9e7420e8ff20de
 SHA512:
-  metadata.gz: 2bc8b173facf22c287824621e15f02102cff7cb4e096789e35945a77418815b6027cf9637e0e86bcfc3c427946b1b0aa3f544b01cc338550503aa50b2fa34c7e
-  data.tar.gz: e4cf1297e4c987f8121d6a9f35f76bc9e668a5f22b130531022428ec0443d019f9ad7d637f098c34be26edaa78d1f105479d935765d3353ef9f42cf8199e3936
+  metadata.gz: 15833dd17e8b167cfc61812af65dc0addad29912459a3886df4bd54b01cd8c43d055654cd971838a1c9b5fc76bca8cf83e8eaa72e25eaa4901eef93177275e4a
+  data.tar.gz: 002e0c5539b2ed22551a87d0d696a8cbfd2b87565b3c991a91fbbacb3c81e722d3b8b1af62bf1aa0604e08691805bfb2375cf2015f06bd57c62228525b9454ca

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.0.3 - 2026-04-26
+
+### Fixed
+
+- Rational scalars and rates are now accepted everywhere they are documented to
+  work: `Amount#*`, `Amount#/`, `Amount#to(rate:)`, `Amount.register_default_rate`,
+  and `display_units[unit][:scale]`. Previously each of these called
+  `BigDecimal(value.to_s)`, which raises `ArgumentError` for `Rational#to_s`
+  (`"3/2"`). All five sites now go through a single internal helper,
+  `Amount.coerce_decimal`, that handles `BigDecimal`, `Rational`, and string-or-
+  numeric inputs uniformly.
+- `Amount.load` wraps a missing `:atomic` or `:symbol` key as
+  `Amount::InvalidInput` (`"amount payload missing key: atomic"`) instead of
+  leaking a raw `KeyError`. This matches the AR adapter's `Type#cast_hash`
+  behavior so callers can rescue a single error class.
+
+## 0.0.2 - 2026-04-26
+
+### Fixed
+
+- `Amount.new(value, symbol)` now dispatches to the registered subclass when the
+  symbol was registered with `class:`, so `Amount.parse`, `Amount.load`, and the
+  ActiveRecord adapter (`Type#cast`, `Type#deserialize`) construct the correct
+  type instead of raising `InvalidInput`. The previous behavior made it
+  impossible to read a custom-class amount back out of an ActiveRecord column.
+  The strict-mode error is preserved for explicit wrong-subclass usage
+  (`OtherSubclass.new(value, :GOLD)`).
+- `Rational` UI input is now accepted as documented. Previously
+  `Amount.new(Rational(3, 2), :USDC)` raised because the value was stringified
+  into `"3/2"` before reaching `BigDecimal()`. Rational input is now converted
+  via integer math (`(rational * 10**decimals).to_i`), giving exact results for
+  finite fractions and well-defined truncate-toward-zero behavior for
+  repeating fractions.
+- `AmountValidator` thresholds for multi-symbol `has_amount` attributes accept
+  raw numerics. `validates :amount, amount: { greater_than: 0 }` now means
+  "greater than zero in the value's symbol" instead of producing
+  `"has invalid greater_than constraint: raw numeric assignment requires a
+  fixed symbol"`. Fixed-symbol attributes are unchanged.
+
 ## 0.0.1 - 2026-04-25
 
 - Initial release.

data/README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/zarpay/amounts/actions/workflows/ci.yml/badge.svg)](https://github.com/zarpay/amounts/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/zarpay/amounts)](https://github.com/zarpay/amounts/releases)
 [![License](https://img.shields.io/github/license/zarpay/amounts)](https://github.com/zarpay/amounts/blob/main/LICENSE.txt)
-[![Ruby](https://img.shields.io/gem/required-ruby-version/amounts)](https://rubygems.org/gems/amounts)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.1-red)](https://rubygems.org/gems/amounts)
 
 `amounts` is a Ruby gem for precise quantities of fungible things: money, crypto tokens, commodities, inventory units, points, and similar value-like amounts. It stores every value as an arbitrary-precision atomic `Integer`, keeps type identity in a registry, rejects accidental cross-type math unless an explicit directional rate exists, and offers an optional ActiveRecord adapter without making Rails part of the core runtime.
 

data/lib/amount/active_record/amount_validator.rb

@@ -56,7 +56,7 @@ class Amount
         COMPARATORS.each do |option_name, operator|
           next unless options.key?(option_name)
 
-          other = coerce_comparison_amount(record, attribute, options.fetch(option_name))
+          other = coerce_comparison_amount(record, attribute, options.fetch(option_name), value)
           next unless other
 
           compare_amounts(record, attribute, value, operator, other, option_name)
@@ -65,10 +65,13 @@ class Amount
         end
       end
 
-      def coerce_comparison_amount(record, attribute, candidate)
-        definition = fetch_definition(record, attribute)
+      def coerce_comparison_amount(record, attribute, candidate, value)
         return candidate if candidate.is_a?(::Amount)
 
+        definition = fetch_definition(record, attribute)
+        return definition.type.cast(candidate) if definition.type.fixed_symbol
+        return ::Amount.new(candidate, value.symbol, from: :float) if candidate.is_a?(Numeric)
+
         definition.type.cast(candidate)
       end
 

data/lib/amount/display.rb

@@ -32,7 +32,7 @@ class Amount
     # @return [BigDecimal]
     def in_unit(unit)
       unit_spec = fetch_display_unit(unit)
-      @amount.decimal * BigDecimal(unit_spec[:scale].to_s)
+      @amount.decimal * Amount.coerce_decimal(unit_spec[:scale])
     end
 
     private
@@ -44,7 +44,7 @@ class Amount
 
     def render_display_unit(unit, direction)
       spec = fetch_display_unit(unit)
-      scaled = @amount.decimal * BigDecimal(spec[:scale].to_s)
+      scaled = @amount.decimal * Amount.coerce_decimal(spec[:scale])
       decimals = spec[:ui_decimals] || @entry.ui_decimals
       rounded = round(scaled, decimals, direction)
 

data/lib/amount/registry.rb

@@ -151,7 +151,7 @@ class Amount
 
       @lock.synchronize do
         ensure_unlocked!
-        @default_rates[[from, to]] = BigDecimal(rate.to_s)
+        @default_rates[[from, to]] = Amount.coerce_decimal(rate)
       end
     end
 

data/lib/amount/serializer.rb

@@ -22,6 +22,8 @@ class Amount
         payload.fetch(:symbol) { payload.fetch("symbol") },
         from: :atomic
       )
+    rescue KeyError => e
+      raise InvalidInput, "amount payload missing key: #{e.key}"
     end
 
     def self.validate_version!(version)

data/lib/amount/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Amount
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/amount.rb

@@ -84,6 +84,40 @@ class Amount
       Parser.new(str).parse
     end
 
+    # When called as `Amount.new` for a symbol whose registry entry binds a
+    # custom class, dispatch the construction to that class instead of raising.
+    # Direct calls to a subclass (`GoldAmount.new(...)`) still go through the
+    # default `Class.new` path. Calls that target the wrong subclass continue
+    # to raise from `#initialize`.
+    #
+    # @param value [Integer, String, Float, BigDecimal, Rational]
+    # @param symbol [Symbol, String]
+    # @param from [Symbol, nil]
+    # @return [Amount]
+    def new(value, symbol, from: nil)
+      if equal?(::Amount)
+        entry_class = registry.lookup(symbol.to_sym).amount_class
+        return entry_class.new(value, symbol, from:) if entry_class && entry_class != ::Amount
+      end
+      super
+    end
+
+    # Coerces a numeric input to BigDecimal in a way that preserves Rational
+    # values. `BigDecimal(value.to_s)` raises `ArgumentError` for Rational
+    # because `Rational#to_s` produces strings like `"3/2"`. This helper is
+    # the single place every call site should use to convert a scalar / rate /
+    # display-unit scale into a BigDecimal.
+    #
+    # @param value [Numeric, BigDecimal, Rational, String]
+    # @return [BigDecimal]
+    def coerce_decimal(value)
+      case value
+      when BigDecimal then value
+      when Rational then BigDecimal(value, Float::DIG + 4)
+      else BigDecimal(value.to_s)
+      end
+    end
+
     # Temporarily swaps the global registry. Intended for tests.
     #
     # @param registry [Amount::Registry]
@@ -139,8 +173,9 @@ class Amount
     @symbol = symbol.to_sym
     @entry = self.class.registry.lookup(@symbol)
 
-    if @entry.amount_class != self.class && @entry.amount_class != Amount
-      raise InvalidInput, "use #{@entry.amount_class}.new for #{@symbol}" unless instance_of?(@entry.amount_class)
+    expected = @entry.amount_class
+    if expected && expected != Amount && self.class != Amount && !instance_of?(expected)
+      raise InvalidInput, "use #{expected}.new for #{@symbol}"
     end
 
     @atomic = infer_value(from, value)
@@ -262,7 +297,7 @@ class Amount
   #   Amount.usdc("1.25") * 2
   def *(scalar)
     ensure_scalar!(scalar)
-    build((BigDecimal(@atomic) * BigDecimal(scalar.to_s)).to_i)
+    build((BigDecimal(@atomic) * Amount.coerce_decimal(scalar)).to_i)
   end
 
   # @param other [Amount, Numeric]
@@ -283,7 +318,7 @@ class Amount
       ensure_scalar!(other)
       raise ZeroDivisionError if other.zero?
 
-      build((BigDecimal(@atomic) / BigDecimal(other.to_s)).to_i)
+      build((BigDecimal(@atomic) / Amount.coerce_decimal(other)).to_i)
     end
   end
 
@@ -392,7 +427,7 @@ class Amount
     rate = resolve_rate(target_symbol, rate)
     target_entry = self.class.registry.lookup(target_symbol)
 
-    decimal_result = decimal * BigDecimal(rate.to_s)
+    decimal_result = decimal * Amount.coerce_decimal(rate)
     atomic_result = (decimal_result * (BigDecimal(10)**target_entry.decimals)).to_i
 
     target_entry.amount_class.new(atomic_result, target_symbol, from: :atomic)
@@ -454,7 +489,7 @@ class Amount
     case from || infer_type(value)
     when :atomic then value.to_i
     when :ui then ui_to_atomic(value)
-    when :float then ui_to_atomic(value.to_s)
+    when :float then ui_to_atomic(value.is_a?(Rational) ? value : value.to_s)
     else
       raise InvalidInput, "unknown amount format: #{value.inspect}"
     end
@@ -471,6 +506,8 @@ class Amount
   end
 
   def ui_to_atomic(value)
+    return (value * (10**decimals)).to_i if value.is_a?(Rational)
+
     (BigDecimal(value.to_s) * (BigDecimal(10)**decimals)).to_i
   rescue ArgumentError
     raise InvalidInput, "cannot parse #{value.inspect} as #{symbol}"

data/test/test_active_record.rb

@@ -309,4 +309,67 @@ class AmountActiveRecordTest < Minitest::Test
 
     assert holding.valid?
   end
+
+  def test_amount_validator_accepts_numeric_threshold_on_multi_symbol_attribute
+    klass = Class.new(::ActiveRecord::Base) do
+      self.table_name = "holdings"
+
+      has_amount :amount
+      validates :amount, amount: { greater_than: 0, less_than_or_equal_to: 100 }
+    end
+
+    above = klass.new(amount: "USDC|50.00")
+    assert above.valid?
+
+    at_zero = klass.new(amount: "USDC|0.00")
+    refute at_zero.valid?
+    assert_includes at_zero.errors[:amount].join, "greater than"
+
+    above_max = klass.new(amount: "USDC|150.00")
+    refute above_max.valid?
+    assert_includes above_max.errors[:amount].join, "less than"
+  end
+
+  def test_amount_validator_numeric_threshold_uses_value_symbol
+    klass = Class.new(::ActiveRecord::Base) do
+      self.table_name = "holdings"
+
+      has_amount :amount
+      validates :amount, amount: { greater_than: 1 }
+    end
+
+    # The same `greater_than: 1` is interpreted as 1 USDC for a USDC value
+    # and as 1 SOL for a SOL value, because the threshold inherits the
+    # value's symbol on multi-symbol attributes.
+    assert klass.new(amount: "USDC|2.00").valid?
+    refute klass.new(amount: "USDC|0.50").valid?
+    assert klass.new(amount: "SOL|2").valid?
+    refute klass.new(amount: "SOL|0.5").valid?
+  end
+
+  def test_custom_class_symbol_round_trips_through_active_record
+    metal_class = Class.new(Amount) do
+      def self.name
+        "MetalAmount"
+      end
+    end
+    Amount.register :METAL, decimals: 4, class: metal_class
+
+    ::ActiveRecord::Schema.define do
+      create_table :metal_holdings, force: true do |t|
+        t.amount :weight, symbol: :METAL, null: false
+      end
+    end
+
+    klass = Class.new(::ActiveRecord::Base) do
+      self.table_name = "metal_holdings"
+      has_amount :weight, symbol: :METAL
+    end
+
+    record = klass.create!(weight: metal_class.new("2.5", :METAL))
+    record.reload
+
+    assert_instance_of metal_class, record.weight
+    assert_equal 25_000, record.weight.atomic
+  end
 end

data/test/test_amount.rb

@@ -26,6 +26,20 @@ class AmountTest < Minitest::Test
     assert_equal 1_500_000, Amount.new(1.5, :USDC).atomic
   end
 
+  def test_construct_from_rational_treats_as_ui
+    assert_equal 1_500_000, Amount.new(Rational(3, 2), :USDC).atomic
+  end
+
+  def test_construct_from_rational_is_exact_for_repeating_fractions
+    # 1/3 has no finite decimal expansion. With six decimals of storage
+    # the atomic representation is 333333 (truncated toward zero).
+    assert_equal 333_333, Amount.new(Rational(1, 3), :USDC).atomic
+  end
+
+  def test_construct_from_rational_with_explicit_ui_from
+    assert_equal 1_500_000, Amount.new(Rational(3, 2), :USDC, from: :ui).atomic
+  end
+
   def test_explicit_from_overrides_inference
     amount = Amount.new("1500000", :USDC, from: :atomic)
 
@@ -215,6 +229,8 @@ class AmountTest < Minitest::Test
     assert_equal Amount.new("3", :USDC), Amount.new("1", :USDC) * 3
     assert_equal Amount.new("1.5", :USDC), Amount.new("1", :USDC) * 1.5
     assert_equal Amount.new("2", :USDC), Amount.new("-1", :USDC) * -2
+    assert_equal Amount.new("3", :USDC), Amount.new("2", :USDC) * BigDecimal("1.5")
+    assert_equal Amount.new("3", :USDC), Amount.new("2", :USDC) * Rational(3, 2)
   end
 
   def test_amount_times_amount_raises
@@ -226,6 +242,8 @@ class AmountTest < Minitest::Test
   def test_scalar_division_returns_amount
     assert_equal Amount.new("0.5", :USDC), Amount.new("1", :USDC) / 2
     assert_equal Amount.new("2", :USDC), Amount.new("-1", :USDC) / -0.5
+    assert_equal Amount.new("2", :USDC), Amount.new("3", :USDC) / Rational(3, 2)
+    assert_equal Amount.new("2", :USDC), Amount.new("3", :USDC) / BigDecimal("1.5")
   end
 
   def test_amount_division_returns_ratio
@@ -339,6 +357,33 @@ class AmountTest < Minitest::Test
     assert_equal :GOLD, gold.symbol
   end
 
+  def test_to_with_rational_rate
+    converted = Amount.new("4", :USDC).to(:USD, rate: Rational(1, 2))
+
+    assert_equal BigDecimal("2"), converted.decimal
+    assert_equal :USD, converted.symbol
+  end
+
+  def test_register_default_rate_accepts_rational
+    Amount.register_default_rate :USDC, :USD, Rational(1, 2)
+
+    assert_equal BigDecimal("0.5"), Amount.registry.default_rate(:USDC, :USD)
+    assert_equal BigDecimal("0.5"), Amount.new("1", :USDC).to(:USD).decimal
+  end
+
+  def test_display_units_with_rational_scale
+    Amount.registry.clear!
+    Amount.register :METAL, decimals: 4, display_symbol: "x", display_position: :suffix,
+      ui_decimals: 2,
+      display_units: { half: { scale: Rational(1, 2), symbol: "h", ui_decimals: 2 } },
+      default_display: :half
+
+    metal = Amount.new("1", :METAL)
+
+    assert_equal BigDecimal("0.5"), metal.in_unit(:half)
+    assert_match(/\A0\.50/, metal.ui(unit: :half))
+  end
+
   def test_to_without_rate_requires_default
     assert_raises(Amount::Registry::NoDefaultRate) do
       Amount.new("1", :USDC).to(:GOLD)
@@ -392,6 +437,14 @@ class AmountTest < Minitest::Test
     assert_equal Amount.new("1.5", :USDC), amount
   end
 
+  def test_load_wraps_missing_keys_as_invalid_input
+    error = assert_raises(Amount::InvalidInput) { Amount.load(v: 1, symbol: "USDC") }
+    assert_match(/missing key: atomic/, error.message)
+
+    error = assert_raises(Amount::InvalidInput) { Amount.load({}) }
+    assert_match(/missing key/, error.message)
+  end
+
   def test_load_rejects_unknown_serialization_version
     assert_raises(Amount::InvalidInput) do
       Amount.load(v: 2, atomic: "1500000", symbol: "USDC")
@@ -469,4 +522,35 @@ class AmountCustomClassTest < Minitest::Test
     assert parts.all? { |part| part.instance_of?(GoldAmount) }
     assert_instance_of GoldAmount, remainder
   end
+
+  def test_amount_new_dispatches_to_registered_subclass
+    assert_instance_of GoldAmount, Amount.new("1", :GOLD)
+    assert_instance_of GoldAmount, Amount.new(100_000_000, :GOLD, from: :atomic)
+  end
+
+  def test_parse_dispatches_to_registered_subclass
+    assert_instance_of GoldAmount, Amount.parse("GOLD|1.0")
+  end
+
+  def test_load_dispatches_to_registered_subclass
+    payload = GoldAmount.new("1", :GOLD).to_h
+    restored = Amount.load(payload)
+
+    assert_instance_of GoldAmount, restored
+    assert_equal "24k", restored.purity_estimate
+  end
+
+  def test_explicit_wrong_subclass_still_raises
+    other = Class.new(Amount)
+
+    error = assert_raises(Amount::InvalidInput) { other.new("1", :GOLD) }
+    assert_match(/use AmountCustomClassTest::GoldAmount\.new for GOLD/, error.message)
+  end
+
+  def test_amount_new_with_default_class_is_unchanged
+    Amount.register :USDC, decimals: 6
+    instance = Amount.new("1", :USDC)
+
+    assert_instance_of Amount, instance
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amounts
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Seb Scholl