amounts 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95dbf17ecb45d86b36277c6ecdaf611bdcb99d12eb97a3fc42b5f3bf2cd1ec50
-  data.tar.gz: 67fcceae2bae4582f4c4e2866f453727a23f444703e47717ab9e7420e8ff20de
+  metadata.gz: 8b7620b025be07f1166e655108c2b9cea0232acb60d814cf91b71ecb47ddf1fb
+  data.tar.gz: 8f8ab43608f4ced54ab5020c7cbcf69b0741c9203e549558b27356766187efb5
 SHA512:
-  metadata.gz: 15833dd17e8b167cfc61812af65dc0addad29912459a3886df4bd54b01cd8c43d055654cd971838a1c9b5fc76bca8cf83e8eaa72e25eaa4901eef93177275e4a
-  data.tar.gz: 002e0c5539b2ed22551a87d0d696a8cbfd2b87565b3c991a91fbbacb3c81e722d3b8b1af62bf1aa0604e08691805bfb2375cf2015f06bd57c62228525b9454ca
+  metadata.gz: 466350a8fbfff01e84bd044f23ced9d63288eb4147f13d70df2a3db9b37745cafee46e03cb3d1d9b0b805fff8ece3ca13df029c19786204f21e2fe1336b1e564
+  data.tar.gz: 807ba283121158491de02a78084dae5ce12c6360ac106a7d72a1bde6a7f536ac3009fdf329b9e75972fe3631ade8bdae3dd0f2d1f2d2e74f9a023f28d46f5cb1

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.0.4 - 2026-04-26
+
+### Changed (breaking)
+
+- The opt-in RSpec integration moved into a dedicated `Amount::RSpec` namespace
+  with one file per concern. Constants and require paths changed:
+
+  | Old | New |
+  | --- | --- |
+  | `Amount::RSpecMatchers` | `Amount::RSpec::Matchers` |
+  | `Amount::RSpecSupport`  | `Amount::RSpec::Support`  |
+  | `lib/amount/rspec_matchers.rb` | `lib/amount/rspec/matchers.rb` |
+  | `lib/amount/rspec_support.rb`  | `lib/amount/rspec/support.rb`  |
+
+  The ActiveRecord-specific matchers also live in their own file under the same
+  pattern (`Amount::ActiveRecord::RSpec::Matchers` in
+  `lib/amount/active_record/rspec/matchers.rb`). Top-level `require` paths
+  (`require "amount/rspec"` and `require "amount/active_record/rspec"`) are
+  unchanged.
+
+  Update any direct constant references; no backwards-compatibility aliases are
+  shipped.
+
+### Changed
+
+- The `Amount` instance behavior is now composed from focused mixins instead
+  of all living in a single 500+ line file. New modules under `lib/amount/`:
+  `Arithmetic` (`+`, `-`, `*`, `/`, `abs`, `-@`),
+  `Comparison` (`<=>`, `==`, `eql?`, `hash`, `same_type?`, sign predicates),
+  `Conversion` (`to(target_symbol, rate:)`),
+  `Allocation` (`split`, `allocate`),
+  and `Serialization` (instance `to_h` plus `Serialization::ClassMethods.load`
+  auto-extended via the `included` hook).
+  Public API unchanged. Shared private helpers (`build`,
+  `coerce_other_to_self_type[!]`, `ensure_same_type!`, `infer_value`,
+  `infer_type`, `ui_to_atomic`) remain on the main `Amount` class so every
+  mixin can call them.
+
+### Removed
+
+- `Amount::Serializer` is gone. Its `dump`/`load` class methods moved into
+  `Amount::Serialization` (instance `to_h` plus `ClassMethods.load`).
+  `Amount.load(hash)` and `Amount#to_h` are unchanged.
+
 ## 0.0.3 - 2026-04-26
 
 ### Fixed

data/lib/amount/active_record/rspec/matchers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    module RSpec
+      # ActiveRecord-specific matcher definitions. Companion to
+      # `Amount::RSpec::Matchers` which holds the gem-core matchers.
+      module Matchers
+        module_function
+
+        def define_amount_column_matcher
+          ::RSpec::Matchers.define :have_amount_column do |name, *expected_arguments|
+            match do |record|
+              @name = name
+              @expected = Amount::RSpec::Support.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::RSpec::Support.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
+  end
+end

data/lib/amount/active_record/rspec.rb

@@ -3,6 +3,7 @@
 require_relative "../active_record"
 require "rspec/expectations"
 require_relative "../rspec"
+require_relative "rspec/matchers"
 
-Amount::RSpecMatchers.define_amount_column_matcher
-Amount::RSpecMatchers.define_amount_sum_matcher
+Amount::ActiveRecord::RSpec::Matchers.define_amount_column_matcher
+Amount::ActiveRecord::RSpec::Matchers.define_amount_sum_matcher

data/lib/amount/active_record/type.rb

@@ -77,12 +77,11 @@ class Amount
       private
 
       def cast_hash(value)
-        if value.key?(:atomic) || value.key?("atomic")
+        value = value.transform_keys(&:to_sym)
+        if value.key?(:atomic)
           ::Amount.load(value)
         else
-          symbol = value.fetch(:symbol) { value.fetch("symbol", fixed_symbol) }
-          amount_value = value.fetch(:value) { value.fetch("value") }
-          ::Amount.new(amount_value, symbol)
+          ::Amount.new(value.fetch(:value), value.fetch(:symbol, fixed_symbol))
         end
       rescue KeyError
         raise ::Amount::InvalidInput, "hash input must contain atomic/symbol or value/symbol"

data/lib/amount/allocation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class Amount
+  # Splitting and proportional allocation. Both operations return
+  # `[parts, remainder]`, preserving the invariant that the parts plus
+  # remainder always sum back to the receiver's atomic value (including
+  # the sign).
+  module Allocation
+    # 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
+
+    private
+
+    def atomic_sign
+      return 1 if @atomic.positive?
+      return(-1) if @atomic.negative?
+
+      0
+    end
+  end
+end

data/lib/amount/arithmetic.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class Amount
+  # Arithmetic operators for `Amount`. Mixed into `Amount` and inherited by
+  # any registered subclass.
+  #
+  # All operators preserve the receiver's class via `build`, so subclass
+  # identity (`GoldAmount`) survives through `+`, `-`, `*`, `/`, `abs`, `-@`.
+  module Arithmetic
+    # @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
+
+    private
+
+    def ensure_scalar!(value)
+      return if value.is_a?(Integer) || value.is_a?(Float) ||
+                value.is_a?(BigDecimal) || value.is_a?(Rational)
+
+      raise TypeMismatch, "expected scalar, got #{value.class}"
+    end
+  end
+end

data/lib/amount/comparison.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Amount
+  # Comparison, equality, hashing, and sign predicates for `Amount`.
+  #
+  # Pulls in `Comparable` itself so consumers only need `include Comparison`
+  # to get `<`, `<=`, `>`, `>=`, `between?`, `clamp`, and `Enumerable#min`/
+  # `#max` alongside the explicit `<=>` / `==` / `eql?` / `hash` defined here.
+  module Comparison
+    include Comparable
+    # @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 [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 [-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
+  end
+end

data/lib/amount/conversion.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Amount
+  # Cross-type conversion via `to(target_symbol, rate:)`. Uses an explicitly
+  # passed rate when provided, otherwise looks up the registered directional
+  # default rate. The result class is taken from the target symbol's registry
+  # entry, so a `class:`-registered subclass becomes the natural identity for
+  # conversion outputs.
+  module Conversion
+    # @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
+
+    private
+
+    def resolve_rate(target, provided)
+      return provided if provided
+
+      self.class.registry.default_rate(symbol, target)
+    end
+  end
+end

data/lib/amount/parser.rb

@@ -3,8 +3,8 @@
 class Amount
   # Parses compact amount strings such as `USDC|1.50`.
   class Parser
-    VERSION_PREFIX = /\A(v\d+):(.*)\z/
     SUPPORTED_VERSION = "v1"
+    VERSION_PREFIX = /\A(v\d+):(.*)\z/
 
     def initialize(input)
       @input = input

data/lib/amount/registry.rb

@@ -21,23 +21,30 @@ class Amount
   #   Amount.registry.lock!
   class Registry
     class UnknownType < StandardError; end
-    class AlreadyRegistered < StandardError; end
-    class InvalidDisplayUnit < StandardError; end
     class NoDefaultRate < StandardError; end
     class RegistryLocked < StandardError; end
+    class AlreadyRegistered < StandardError; end
+    class InvalidDisplayUnit < StandardError; end
 
     Entry = Struct.new(
-      :symbol, :decimals, :display_symbol, :display_position,
-      :ui_decimals, :display_units, :default_display, :amount_class,
+      :symbol,
+      :decimals,
+      :display_symbol,
+      :display_position,
+      :ui_decimals,
+      :display_units,
+      :default_display,
+      :amount_class,
       keyword_init: true
     )
 
     def initialize
-      @entries = {}
+      @entries       = {}
       @default_rates = {}
-      @generated_constructors = GeneratedConstructors.new
-      @locked = false
+      @locked        = false
+
       @lock = Mutex.new
+      @generated_constructors = GeneratedConstructors.new
     end
 
     # Registers a new fungible type.
@@ -67,6 +74,8 @@ class Amount
     def register(symbol, decimals:, display_symbol: symbol.to_s, display_position: :suffix,
                  ui_decimals: decimals, display_units: nil, default_display: nil,
                  class: nil)
+      raise ArgumentError, "symbol must not be blank" if symbol.nil? || symbol.to_s.empty?
+
       symbol = symbol.to_sym
 
       @lock.synchronize do

data/lib/amount/rspec/matchers.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class Amount
+  module RSpec
+    # Internal matcher helpers for the opt-in RSpec integration.
+    #
+    # All bare `RSpec` references inside this module are fully qualified to
+    # `::RSpec` to dodge the constant-lookup ambiguity introduced by living
+    # under `Amount::RSpec`.
+    module Matchers
+      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::RSpec::Support.coerce_amount_arguments(expected_arguments)
+            @within = Amount::RSpec::Support.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
+    end
+  end
+end

data/lib/amount/rspec/support.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Amount
+  module RSpec
+    # Shared coercion helpers for opt-in RSpec integrations.
+    module Support
+      module_function
+
+      def coerce_amount_arguments(arguments)
+        case arguments.length
+        when 1
+          coerce_amount(arguments.first)
+        when 2
+          Amount.new(arguments.last, arguments.first)
+        else
+          raise ArgumentError, "expected an Amount, a parse string, or a symbol/value pair"
+        end
+      end
+
+      def coerce_amount(value)
+        case value
+        when Amount then value
+        when String then Amount.parse(value)
+        when Hash then Amount.load(value)
+        else
+          raise ArgumentError, "cannot coerce #{value.inspect} into an Amount"
+        end
+      end
+
+      def coerce_delta(expected_amount, within)
+        case within
+        when Amount
+          within
+        when Integer, Float, BigDecimal, Rational, String
+          Amount.new(within, expected_amount.symbol)
+        else
+          raise ArgumentError, "cannot coerce #{within.inspect} into an amount delta"
+        end
+      end
+
+      def normalize_amount_sums(sum_hash)
+        sum_hash.to_h do |symbol, atomic|
+          amount = Amount.new(atomic, symbol, from: :atomic)
+          [amount.symbol, amount]
+        end
+      end
+    end
+  end
+end

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.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
@@ -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

metadata

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

data/lib/amount/rspec_support.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-class Amount
-  # Shared coercion helpers for opt-in RSpec integrations.
-  module RSpecSupport
-    module_function
-
-    def coerce_amount_arguments(arguments)
-      case arguments.length
-      when 1
-        coerce_amount(arguments.first)
-      when 2
-        Amount.new(arguments.last, arguments.first)
-      else
-        raise ArgumentError, "expected an Amount, a parse string, or a symbol/value pair"
-      end
-    end
-
-    def coerce_amount(value)
-      case value
-      when Amount then value
-      when String then Amount.parse(value)
-      when Hash then Amount.load(value)
-      else
-        raise ArgumentError, "cannot coerce #{value.inspect} into an Amount"
-      end
-    end
-
-    def coerce_delta(expected_amount, within)
-      case within
-      when Amount
-        within
-      when Integer, Float, BigDecimal, Rational, String
-        Amount.new(within, expected_amount.symbol)
-      else
-        raise ArgumentError, "cannot coerce #{within.inspect} into an amount delta"
-      end
-    end
-
-    def normalize_amount_sums(sum_hash)
-      sum_hash.to_h do |symbol, atomic|
-        amount = Amount.new(atomic, symbol, from: :atomic)
-        [amount.symbol, amount]
-      end
-    end
-  end
-end

data/lib/amount/serializer.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-class Amount
-  # Converts amounts to and from the versioned hash payload.
-  class Serializer
-    VERSION = 1
-
-    def self.dump(amount)
-      {
-        v: VERSION,
-        atomic: amount.atomic.to_s,
-        symbol: amount.symbol.to_s
-      }
-    end
-
-    def self.load(payload)
-      version = payload[:v] || payload["v"]
-      validate_version!(version)
-
-      Amount.new(
-        payload.fetch(:atomic) { payload.fetch("atomic") },
-        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)
-      return if version.nil? || version == VERSION
-
-      raise InvalidInput, "unsupported amount serialization version: #{version}"
-    end
-
-    private_class_method :validate_version!
-  end
-end