amounts 0.0.3 → 0.0.5

data/lib/amount/rspec.rb

@@ -2,8 +2,8 @@
 
 require_relative "../amount"
 require "rspec/expectations"
-require_relative "rspec_support"
-require_relative "rspec_matchers"
+require_relative "rspec/support"
+require_relative "rspec/matchers"
 
 # Opt-in RSpec matchers for `Amount`.
 #
@@ -16,12 +16,12 @@ require_relative "rspec_matchers"
 #   expect(Amount.usdc("1.50")).to be_amount_of(:USDC)
 #   expect(Amount.usdc("1.50")).to be_positive_amount
 #   expect(Amount.usdc("1.55")).to be_approximately_amount(:USDC, "1.50", within: "0.10")
-Amount::RSpecMatchers.define_amount_equality_matcher(:eq_amount) do |*expected_arguments|
-  Amount::RSpecSupport.coerce_amount_arguments(expected_arguments)
+Amount::RSpec::Matchers.define_amount_equality_matcher(:eq_amount) do |*expected_arguments|
+  Amount::RSpec::Support.coerce_amount_arguments(expected_arguments)
 end
 
-Amount::RSpecMatchers.define_amount_type_matcher
-Amount::RSpecMatchers.define_amount_predicate_matcher(:be_zero_amount, "a zero Amount", &:zero?)
-Amount::RSpecMatchers.define_amount_predicate_matcher(:be_positive_amount, "a positive Amount", &:positive?)
-Amount::RSpecMatchers.define_amount_predicate_matcher(:be_negative_amount, "a negative Amount", &:negative?)
-Amount::RSpecMatchers.define_approximate_amount_matcher
+Amount::RSpec::Matchers.define_amount_type_matcher
+Amount::RSpec::Matchers.define_approximate_amount_matcher
+Amount::RSpec::Matchers.define_amount_predicate_matcher(:be_zero_amount, "a zero Amount", &:zero?)
+Amount::RSpec::Matchers.define_amount_predicate_matcher(:be_positive_amount, "a positive Amount", &:positive?)
+Amount::RSpec::Matchers.define_amount_predicate_matcher(:be_negative_amount, "a negative Amount", &:negative?)

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.3"
+  VERSION = "0.0.5"
 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
@@ -147,7 +163,7 @@ class Amount
     end
   end
 
-  attr_reader :atomic, :symbol
+  attr_reader :atomic, :symbol, :display
 
   # Creates an amount for a registered symbol.
   #
@@ -179,6 +195,7 @@ class Amount
     end
 
     @atomic = infer_value(from, value)
+    @display = Display.new(self)
   end
 
   # @return [Amount::Registry::Entry]
@@ -205,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]
@@ -223,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) * Amount.coerce_decimal(scalar)).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) / Amount.coerce_decimal(other)).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 * 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)
-  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)
@@ -512,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
@@ -143,6 +169,16 @@ class AmountTest < Minitest::Test
     assert_equal "$1.57", Amount.new("1.561", :USDC).ui(direction: :ceil)
   end
 
+  def test_ui_decorated_false_omits_the_display_symbol
+    assert_equal "1.50", Amount.new("1.5", :USDC).ui(decorated: false)
+    assert_equal "1.5000", Amount.new("1.5", :SOL).ui(decorated: false)
+    assert_equal "1", Amount.new(1, :LOGS).ui(decorated: false)
+  end
+
+  def test_ui_decorated_false_with_ceil_direction
+    assert_equal "1.57", Amount.new("1.561", :USDC).ui(direction: :ceil, decorated: false)
+  end
+
   def test_display_units_scale_output
     gold = Amount.new("1.5", :GOLD)
 
@@ -151,6 +187,14 @@ class AmountTest < Minitest::Test
     assert_equal "0.04665 kg", gold.ui(unit: :kg)
   end
 
+  def test_display_units_with_decorated_false
+    gold = Amount.new("1.5", :GOLD)
+
+    assert_equal "1.5000", gold.ui(decorated: false)
+    assert_equal "46.65", gold.ui(unit: :gram, decorated: false)
+    assert_equal "0.04665", gold.ui(unit: :kg, decorated: false)
+  end
+
   def test_in_unit_returns_raw_bigdecimal
     gold = Amount.new("1.0", :GOLD)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amounts
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 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