amounts 0.0.2 → 0.0.4

data/lib/amount/serialization.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Amount
+  # Versioned hash serialization. `include Serialization` does both halves:
+  # the instance side (`#to_h`) is mixed in directly, and the class-level
+  # entry point (`Amount.load`) is auto-extended onto the including class
+  # via the `included` hook below. The compact-string format is the
+  # responsibility of {Amount::Parser}.
+  module Serialization
+    VERSION = 1
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods automatically extended onto any class that does
+    # `include Serialization`.
+    module ClassMethods
+      # @param payload [Hash]
+      # @return [Amount]
+      # @raise [Amount::InvalidInput] for unsupported versions or missing keys
+      # @example
+      #   Amount.load(v: 1, atomic: "1500000", symbol: "USDC")
+      def load(payload)
+        payload = payload.transform_keys(&:to_sym)
+        validate_serialization_version!(payload[:v])
+
+        Amount.new(payload.fetch(:atomic), payload.fetch(:symbol), from: :atomic)
+      rescue KeyError => e
+        raise Amount::InvalidInput, "amount payload missing key: #{e.key}"
+      end
+
+      private
+
+      def validate_serialization_version!(version)
+        return if version.nil? || version == VERSION
+
+        raise Amount::InvalidInput, "unsupported amount serialization version: #{version}"
+      end
+    end
+
+    # @return [Hash]
+    # @example
+    #   Amount.usdc("1.50").to_h
+    #   # => { v: 1, atomic: "1500000", symbol: "USDC" }
+    def to_h
+      {
+        v: VERSION,
+        atomic: @atomic.to_s,
+        symbol: @symbol.to_s
+      }
+    end
+  end
+end

data/lib/amount/version.rb

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

data/lib/amount.rb

@@ -7,7 +7,11 @@ require_relative "amount/version"
 require_relative "amount/registry"
 require_relative "amount/display"
 require_relative "amount/parser"
-require_relative "amount/serializer"
+require_relative "amount/arithmetic"
+require_relative "amount/allocation"
+require_relative "amount/comparison"
+require_relative "amount/conversion"
+require_relative "amount/serialization"
 
 # Represents a precise quantity of a registered fungible type.
 #
@@ -16,6 +20,13 @@ require_relative "amount/serializer"
 # strings or decimals, while integer inputs are treated as atomic counts unless
 # `from:` overrides inference.
 #
+# Behavior is composed from a set of focused mixins:
+# - {Arithmetic}    — `+`, `-`, `*`, `/`, `abs`, `-@`
+# - {Comparison}    — `<=>`, `==`, `eql?`, `hash`, `same_type?`, sign predicates
+# - {Conversion}    — `to(:SYMBOL, rate:)`
+# - {Allocation}    — `split(n)`, `allocate(weights)`
+# - {Serialization} — `to_h`
+#
 # @example Constructing from a UI value
 #   Amount.register :USDC, decimals: 6
 #
@@ -26,7 +37,12 @@ require_relative "amount/serializer"
 #   Amount.usdc(1_500_000, from: :atomic).decimal.to_s("F")
 #   # => "1.5"
 class Amount
-  include Comparable
+  include Arithmetic
+  include Allocation
+  include Comparison
+  include Conversion
+  include Serialization
+
   extend Forwardable
 
   class Error < StandardError; end
@@ -102,6 +118,22 @@ class Amount
       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]
@@ -131,7 +163,7 @@ class Amount
     end
   end
 
-  attr_reader :atomic, :symbol
+  attr_reader :atomic, :symbol, :display
 
   # Creates an amount for a registered symbol.
   #
@@ -163,6 +195,7 @@ class Amount
     end
 
     @atomic = infer_value(from, value)
+    @display = Display.new(self)
   end
 
   # @return [Amount::Registry::Entry]
@@ -189,14 +222,6 @@ class Amount
     BigDecimal(@atomic) / (BigDecimal(10)**decimals)
   end
 
-  # @return [Amount::Display]
-  # @example Delegating formatting concerns
-  #   Amount.usdc("1.50").display.ui
-  #   # => "$1.50"
-  def display
-    @display ||= Display.new(self)
-  end
-
   def_delegators :display, :formatted, :ui, :to_s, :in_unit
 
   # @return [String]
@@ -207,266 +232,34 @@ class Amount
     "#<#{self.class} #{symbol} #{ui}>"
   end
 
-  # @return [Boolean]
-  # @example
-  #   Amount.usdc(0, from: :atomic).zero?
-  #   # => true
-  def zero? = @atomic.zero?
-
-  # @return [Boolean]
-  # @example
-  #   Amount.usdc("1").positive?
-  #   # => true
-  def positive? = @atomic.positive?
-
-  # @return [Boolean]
-  # @example
-  #   Amount.usdc("-1").negative?
-  #   # => true
-  def negative? = @atomic.negative?
-
-  # @param other [Object]
-  # @return [Boolean]
-  # @example
-  #   Amount.usdc("1").same_type?(Amount.usdc("2"))
-  #   # => true
-  def same_type?(other)
-    other.is_a?(Amount) && other.symbol == symbol
-  end
-
-  # @return [Amount]
-  # @example
-  #   Amount.usdc("-1").abs
-  #   # => #<Amount USDC $1.00>
-  def abs
-    build(@atomic.abs)
-  end
-
-  # @return [Amount]
-  # @example
-  #   -Amount.usdc("1")
-  #   # => #<Amount USDC -$1.00>
-  def -@
-    build(-@atomic)
-  end
-
-  # @param other [Amount]
-  # @return [Amount]
-  # @raise [TypeMismatch]
-  # @example Same-type addition
-  #   Amount.usdc("1.50") + Amount.usdc("0.50")
-  #
-  # @example Cross-type addition using a registered directional rate
-  #   Amount.register_default_rate :USD, :USDC, "1"
-  #   Amount.usdc("10.00") + Amount.new("5.00", :USD)
-  def +(other)
-    rhs = coerce_other_to_self_type!(other)
-    build(@atomic + rhs.atomic)
-  end
-
-  # @param other [Amount]
-  # @return [Amount]
-  # @raise [TypeMismatch]
-  # @example
-  #   Amount.usdc("2.00") - Amount.usdc("0.50")
-  def -(other)
-    rhs = coerce_other_to_self_type!(other)
-    build(@atomic - rhs.atomic)
-  end
-
-  # @param scalar [Numeric]
-  # @return [Amount]
-  # @raise [TypeMismatch]
-  # @example
-  #   Amount.usdc("1.25") * 2
-  def *(scalar)
-    ensure_scalar!(scalar)
-    build((BigDecimal(@atomic) * BigDecimal(scalar.to_s)).to_i)
-  end
-
-  # @param other [Amount, Numeric]
-  # @return [Amount, BigDecimal]
-  # @raise [TypeMismatch, ZeroDivisionError]
-  # @example Dividing by a scalar returns an amount
-  #   Amount.usdc("1.00") / 2
-  #
-  # @example Dividing by an amount returns a ratio
-  #   Amount.usdc("10.00") / Amount.usdc("2.00")
-  def /(other)
-    if other.is_a?(Amount)
-      ensure_same_type!(other)
-      raise ZeroDivisionError if other.zero?
-
-      BigDecimal(@atomic) / BigDecimal(other.atomic)
-    else
-      ensure_scalar!(other)
-      raise ZeroDivisionError if other.zero?
-
-      build((BigDecimal(@atomic) / BigDecimal(other.to_s)).to_i)
-    end
-  end
-
-  # Splits into equal parts and returns the leftover explicitly.
-  #
-  # @param n [Integer]
-  # @return [Array<(Array<Amount>, Amount)>]
-  # @raise [ArgumentError] if `n` is not a positive integer
-  # @example
-  #   parts, remainder = Amount.new(10, :LOGS).split(3)
-  #   parts.map(&:atomic)
-  #   # => [3, 3, 3]
-  #   remainder.atomic
-  #   # => 1
-  def split(n)
-    raise ArgumentError, "n must be positive" unless n.is_a?(Integer) && n.positive?
-
-    sign = atomic_sign
-    base, remainder = @atomic.abs.divmod(n)
-    parts = Array.new(n) { build(sign * base) }
-
-    [parts, build(sign * remainder)]
-  end
-
-  # Allocates proportionally by integer weights and returns the leftover explicitly.
-  #
-  # @param weights [Array<Integer>]
-  # @return [Array<(Array<Amount>, Amount)>]
-  # @raise [ArgumentError] if weights are empty, negative, or sum to zero
-  # @example
-  #   parts, remainder = Amount.new(10, :LOGS).allocate([1, 1, 2])
-  #   parts.map(&:atomic)
-  #   # => [2, 2, 5]
-  #   remainder.atomic
-  #   # => 1
-  def allocate(weights)
-    raise ArgumentError, "weights must be non-empty" if weights.empty?
-    raise ArgumentError, "weights must be non-negative integers" unless weights.all? { |weight| weight.is_a?(Integer) && weight >= 0 }
-
-    total = weights.sum
-    raise ArgumentError, "weights must sum to positive value" unless total.positive?
-
-    sign = atomic_sign
-    absolute_atomic = @atomic.abs
-    allocations = weights.map { |weight| absolute_atomic * weight / total }
-    remainder = absolute_atomic - allocations.sum
-
-    parts = allocations.map { |allocation| build(sign * allocation) }
-    [parts, build(sign * remainder)]
-  end
-
-  # @param other [Object]
-  # @return [-1, 0, 1, nil]
-  # @example
-  #   Amount.usdc("1") <=> Amount.usdc("2")
-  #   # => -1
-  def <=>(other)
-    return nil unless other.is_a?(Amount)
-
-    comparable = coerce_other_to_self_type(other)
-    return nil unless comparable
-
-    @atomic <=> comparable.atomic
-  end
-
-  # @param other [Object]
-  # @return [Boolean]
-  # @example
-  #   Amount.usdc("1.50") == Amount.usdc("1.50")
-  #   # => true
-  def ==(other)
-    same_type?(other) && @atomic == other.atomic
-  end
-
-  # @param other [Object]
-  # @return [Boolean]
-  # @example Hash-key equality keeps class and symbol identity
-  #   Amount.usdc("1").eql?(Amount.usdc("1"))
-  #   # => true
-  def eql?(other)
-    other.class == self.class && symbol == other.symbol && @atomic == other.atomic
-  end
-
-  # @return [Integer]
-  # @example
-  #   { Amount.usdc("1") => :ok }[Amount.usdc("1")]
-  #   # => :ok
-  def hash
-    [self.class, symbol, @atomic].hash
-  end
-
-  # @param target_symbol [Symbol, String]
-  # @param rate [String, Numeric, BigDecimal, nil]
-  # @return [Amount]
-  # @raise [Amount::Registry::NoDefaultRate] if no explicit or registered rate is available
-  # @example Using an explicit one-off rate
-  #   Amount.usdc("100").to(:GOLD, rate: "0.00042")
-  #
-  # @example Using a registered default rate
-  #   Amount.register_default_rate :USDC, :USD, "1"
-  #   Amount.usdc("1.50").to(:USD)
-  def to(target_symbol, rate: nil)
-    target_symbol = target_symbol.to_sym
-    return self.class.new(@atomic, symbol, from: :atomic) if target_symbol == symbol
-
-    rate = resolve_rate(target_symbol, rate)
-    target_entry = self.class.registry.lookup(target_symbol)
-
-    decimal_result = decimal * BigDecimal(rate.to_s)
-    atomic_result = (decimal_result * (BigDecimal(10)**target_entry.decimals)).to_i
-
-    target_entry.amount_class.new(atomic_result, target_symbol, from: :atomic)
-  end
-
-  # @return [Hash]
-  # @example
-  #   Amount.usdc("1.50").to_h
-  #   # => { v: 1, atomic: "1500000", symbol: "USDC" }
-  def to_h
-    Serializer.dump(self)
-  end
-
-  # @param hash [Hash]
-  # @return [Amount]
-  # @raise [InvalidInput] for unsupported serialized versions
-  # @example Loading the current versioned payload
-  #   Amount.load(v: 1, atomic: "1500000", symbol: "USDC")
-  #
-  # @example Loading the legacy unversioned payload
-  #   Amount.load(atomic: 1500000, symbol: :USDC)
-  def self.load(hash)
-    Serializer.load(hash)
-  end
-
   private
 
+  # Builds a same-symbol amount in the receiver's class. Used by every
+  # operator that returns an Amount so subclass identity propagates.
   def build(atomic_value)
     self.class.new(atomic_value, symbol, from: :atomic)
   end
 
-  def atomic_sign
-    return 1 if @atomic.positive?
-    return(-1) if @atomic.negative?
-
-    0
-  end
-
   def ensure_same_type!(other)
     return if same_type?(other)
 
     raise TypeMismatch, "type mismatch: #{symbol} vs #{other.is_a?(Amount) ? other.symbol : other.class}"
   end
 
-  def ensure_scalar!(value)
-    return if value.is_a?(Integer) || value.is_a?(Float) ||
-              value.is_a?(BigDecimal) || value.is_a?(Rational)
+  def coerce_other_to_self_type(other)
+    return other if same_type?(other)
+    return unless other.is_a?(Amount)
 
-    raise TypeMismatch, "expected scalar, got #{value.class}"
+    other.to(symbol)
+  rescue Registry::NoDefaultRate
+    nil
   end
 
-  def resolve_rate(target, provided)
-    return provided if provided
-
-    self.class.registry.default_rate(symbol, target)
+  def coerce_other_to_self_type!(other)
+    coerce_other_to_self_type(other) || raise(
+      TypeMismatch,
+      "type mismatch: #{symbol} vs #{other.is_a?(Amount) ? other.symbol : other.class}"
+    )
   end
 
   def infer_value(from, value)
@@ -496,20 +289,4 @@ class Amount
   rescue ArgumentError
     raise InvalidInput, "cannot parse #{value.inspect} as #{symbol}"
   end
-
-  def coerce_other_to_self_type!(other)
-    coerce_other_to_self_type(other) || raise(
-      TypeMismatch,
-      "type mismatch: #{symbol} vs #{other.is_a?(Amount) ? other.symbol : other.class}"
-    )
-  end
-
-  def coerce_other_to_self_type(other)
-    return other if same_type?(other)
-    return unless other.is_a?(Amount)
-
-    other.to(symbol)
-  rescue Registry::NoDefaultRate
-    nil
-  end
 end

data/test/test_amount.rb

@@ -126,6 +126,32 @@ class AmountTest < Minitest::Test
     assert_raises(Amount::Registry::UnknownType) { Amount.new(1, :DOGE) }
   end
 
+  def test_register_rejects_empty_symbol
+    error = assert_raises(ArgumentError) { Amount.register :"", decimals: 2 }
+    assert_match(/symbol must not be blank/, error.message)
+  end
+
+  def test_register_rejects_nil_symbol
+    assert_raises(ArgumentError) { Amount.register nil, decimals: 2 }
+  end
+
+  def test_frozen_amount_renders_display
+    amount = Amount.new("1.5", :USDC).freeze
+
+    assert_equal "$1.50", amount.ui
+    assert_equal "1.500000", amount.formatted
+    assert_equal "USDC|1.5", amount.to_s
+  end
+
+  def test_frozen_amount_arithmetic_returns_unfrozen_result
+    a = Amount.new("1", :USDC).freeze
+    b = Amount.new("2", :USDC).freeze
+    sum = a + b
+
+    assert_equal Amount.new("3", :USDC), sum
+    refute sum.frozen?
+  end
+
   def test_formatted_respects_storage_decimals
     assert_equal "1.500000", Amount.new("1.5", :USDC).formatted
     assert_equal "1.500000000", Amount.new("1.5", :SOL).formatted
@@ -229,6 +255,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
@@ -240,6 +268,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
@@ -353,6 +383,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)
@@ -406,6 +463,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")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amounts
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Seb Scholl
@@ -51,15 +51,20 @@ files:
 - lib/amount/active_record/migration_methods.rb
 - lib/amount/active_record/model.rb
 - lib/amount/active_record/rspec.rb
+- lib/amount/active_record/rspec/matchers.rb
 - lib/amount/active_record/type.rb
+- lib/amount/allocation.rb
+- lib/amount/arithmetic.rb
+- lib/amount/comparison.rb
+- lib/amount/conversion.rb
 - lib/amount/display.rb
 - lib/amount/parser.rb
 - lib/amount/registry.rb
 - lib/amount/registry/generated_constructors.rb
 - lib/amount/rspec.rb
-- lib/amount/rspec_matchers.rb
-- lib/amount/rspec_support.rb
-- lib/amount/serializer.rb
+- lib/amount/rspec/matchers.rb
+- lib/amount/rspec/support.rb
+- lib/amount/serialization.rb
 - lib/amount/version.rb
 - test/dummy/app/models/holding.rb
 - test/dummy/bin/rails

data/lib/amount/rspec_matchers.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-class Amount
-  # Internal matcher helpers for the opt-in RSpec integration.
-  module RSpecMatchers
-    module_function
-
-    def define_amount_equality_matcher(name, &expected_builder)
-      RSpec::Matchers.define name do |*arguments|
-        match do |actual|
-          @expected = instance_exec(*arguments, &expected_builder)
-          actual.is_a?(Amount) && actual == @expected
-        end
-
-        failure_message do |actual|
-          return "expected #{actual.inspect} to be an Amount equal to #{@expected.inspect}" unless actual.is_a?(Amount)
-
-          "expected #{actual.inspect} to equal amount #{@expected.inspect}"
-        end
-      end
-    end
-
-    def define_amount_predicate_matcher(name, description, &predicate)
-      RSpec::Matchers.define name do
-        match do |actual|
-          actual.is_a?(Amount) && instance_exec(actual, &predicate)
-        end
-
-        failure_message do |actual|
-          "expected #{actual.inspect} to be #{description}"
-        end
-      end
-    end
-
-    def define_amount_type_matcher
-      RSpec::Matchers.define :be_amount_of do |expected_symbol|
-        match do |actual|
-          @expected_symbol = expected_symbol.to_sym
-          actual.is_a?(Amount) && actual.symbol == @expected_symbol
-        end
-
-        failure_message do |actual|
-          "expected #{actual.inspect} to be an Amount of #{@expected_symbol}"
-        end
-      end
-    end
-
-    def define_approximate_amount_matcher
-      RSpec::Matchers.define :be_approximately_amount do |*expected_arguments, within:|
-        match do |actual|
-          @expected = Amount::RSpecSupport.coerce_amount_arguments(expected_arguments)
-          @within = Amount::RSpecSupport.coerce_delta(@expected, within)
-
-          actual.is_a?(Amount) &&
-            actual.same_type?(@expected) &&
-            @within.same_type?(@expected) &&
-            (actual - @expected).abs.atomic <= @within.atomic
-        end
-
-        failure_message do |actual|
-          return "expected #{actual.inspect} to be an Amount within #{@within.inspect} of #{@expected.inspect}" unless actual.is_a?(Amount)
-
-          "expected #{actual.inspect} to be within #{@within.inspect} of #{@expected.inspect}"
-        end
-      end
-    end
-
-    def define_amount_column_matcher
-      RSpec::Matchers.define :have_amount_column do |name, *expected_arguments|
-        match do |record|
-          @name = name
-          @expected = Amount::RSpecSupport.coerce_amount_arguments(expected_arguments)
-          @definition = record.class.amount_attribute_definitions.fetch(name.to_sym)
-
-          @definition.read(record) == @expected &&
-            record.public_send(@definition.atomic_column).to_i == @expected.atomic &&
-            (@definition.fixed_symbol? ||
-              record.public_send(@definition.symbol_column) == @expected.symbol.to_s)
-        end
-
-        failure_message do |record|
-          "expected #{record.inspect} to have #{@name} column matching #{@expected.inspect}"
-        end
-      end
-    end
-
-    def define_amount_sum_matcher
-      RSpec::Matchers.define :match_amounts do |expected_hash|
-        match do |actual_hash|
-          @expected = expected_hash.to_h do |symbol, value|
-            amount = Amount.new(value, symbol)
-            [amount.symbol, amount]
-          end
-          @actual = Amount::RSpecSupport.normalize_amount_sums(actual_hash)
-
-          @actual == @expected
-        end
-
-        failure_message do |_actual_hash|
-          "expected grouped amounts #{@actual.inspect} to match #{@expected.inspect}"
-        end
-      end
-    end
-  end
-end