amounts 0.0.8 → 0.1.0

data/lib/amount.rb

@@ -3,15 +3,31 @@
 require "bigdecimal"
 require "forwardable"
 
+# Every core file loads from here, in dependency order; core files don't
+# require each other. The optional adapters (amount/active_record,
+# amount/rspec) are separate entry points that load their own files.
 require_relative "amount/version"
 require_relative "amount/registry"
+require_relative "amount/registry/generated_constructors"
+require_relative "amount/locale"
+require_relative "amount/compact"
 require_relative "amount/display"
 require_relative "amount/parser"
-require_relative "amount/arithmetic"
-require_relative "amount/allocation"
-require_relative "amount/comparison"
-require_relative "amount/conversion"
-require_relative "amount/serialization"
+require_relative "amount/ui_parser"
+
+# Concerns: modules mixed into Amount. Files live in amount/concerns/, but the
+# constants are Amount::<Name> (the folder is not a namespace).
+require_relative "amount/concerns/registrable"
+require_relative "amount/concerns/localizable"
+require_relative "amount/concerns/parsable"
+require_relative "amount/concerns/constructible"
+require_relative "amount/concerns/coercible"
+require_relative "amount/concerns/calculable"
+require_relative "amount/concerns/allocatable"
+require_relative "amount/concerns/orderable"
+require_relative "amount/concerns/convertible"
+require_relative "amount/concerns/serializable"
+require_relative "amount/concerns/formattable"
 
 # Represents a precise quantity of a registered fungible type.
 #
@@ -20,12 +36,26 @@ require_relative "amount/serialization"
 # 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`
+# This class holds only an amount's identity: its atomic value, its symbol and
+# registry entry, and the decimal view of the value. Everything else comes
+# from concerns:
+# - {Registrable}  — `Amount.registry`, `register`, `register_default_rate`,
+#   `with_registry`
+# - {Localizable}  — `Amount.localize`
+# - {Parsable}       — `Amount.parse`, `Amount.parse_ui`
+# - {Constructible}  — input inference, `Amount.new` dispatch to a registered
+#   subclass, `build`
+# - {Coercible}      — `Amount.coerce_decimal`, cross-type operand coercion
+# - {Calculable}    — `+`, `-`, `*`, `/`, `abs`, `-@`
+# - {Orderable}    — `<=>`, `==`, `eql?`, `hash`, `same_type?`, sign predicates
+# - {Convertible}    — `to(:SYMBOL, rate:)`
+# - {Allocatable}    — `split(n)`, `allocate(weights)`
+# - {Serializable} — `to_h`, `as_json`, `Amount.load`
+# - {Formattable}   — `display_format(unit:, locale:)`, where the number and
+#   unit go
+#
+# New behavior belongs in a concern, not in this class. See
+# `.claude/rules/concerns.md` for the shape a concern takes.
 #
 # @example Constructing from a UI value
 #   Amount.register :USDC, decimals: 6
@@ -37,11 +67,17 @@ require_relative "amount/serialization"
 #   Amount.of_usdc(1_500_000, from: :atomic).decimal.to_s("F")
 #   # => "1.5"
 class Amount
-  include Arithmetic
-  include Allocation
-  include Comparison
-  include Conversion
-  include Serialization
+  include Registrable
+  include Localizable
+  include Parsable
+  include Constructible
+  include Coercible
+  include Calculable
+  include Allocatable
+  include Orderable
+  include Convertible
+  include Serializable
+  include Formattable
 
   extend Forwardable
 
@@ -50,128 +86,11 @@ class Amount
   class InvalidInput < Error; end
   class UnregisteredType < Error; end
 
-  class << self
-    # @return [Amount::Registry]
-    # @example Accessing the shared registry
-    #   Amount.registry.locked?
-    #   # => false
-    def registry
-      Amount.instance_variable_get(:@registry) ||
-        replace_registry(Registry.new)
-    end
-
-    # @param symbol [Symbol, String]
-    # @param opts [Hash]
-    # @return [void]
-    # @example Registering a type
-    #   Amount.register :USDC,
-    #     decimals: 6,
-    #     display_symbol: "$",
-    #     display_position: :prefix,
-    #     ui_decimals: 2
-    def register(symbol, **opts)
-      registry.register(symbol, **opts)
-    end
-
-    # @param from [Symbol, String]
-    # @param to [Symbol, String]
-    # @param rate [String, Numeric, BigDecimal]
-    # @return [void]
-    # @example Registering a directional default rate
-    #   Amount.register_default_rate :USD, :USDC, "1"
-    def register_default_rate(from, to, rate)
-      registry.register_default_rate(from, to, rate)
-    end
-
-    # Parses the compact client-facing string representation.
-    #
-    # Accepts either the default form `SYMBOL|amount` or the explicit versioned
-    # form `v1:SYMBOL|amount`.
-    #
-    # @param str [String]
-    # @return [Amount]
-    # @raise [InvalidInput]
-    # @example Parsing the default compact format
-    #   Amount.parse("USDC|1.50")
-    #
-    # @example Parsing the explicit versioned compact format
-    #   Amount.parse("v1:USDC|1.50")
-    def parse(str)
-      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]
-    # @yield
-    # @return [Object]
-    # @example Using a temporary registry
-    #   test_registry = Amount::Registry.new
-    #   Amount.with_registry(test_registry) do
-    #     Amount.register :TEST, decimals: 2
-    #   end
-    def with_registry(registry)
-      original = Amount.instance_variable_get(:@registry)
-      replace_registry(registry)
-      yield
-    ensure
-      replace_registry(original)
-    end
-
-    private
-
-    def replace_registry(registry)
-      current = Amount.instance_variable_get(:@registry)
-      current&.remove_generated_methods!
-      Amount.instance_variable_set(:@registry, registry)
-      registry&.activate_generated_methods!
-      registry
-    end
-  end
-
   attr_reader :atomic, :symbol, :display
 
   # Creates an amount for a registered symbol.
   #
-  # Input inference rules:
-  # - `Integer` => atomic units
-  # - `String` => UI decimal value
-  # - `Float`, `BigDecimal`, `Rational` => UI decimal value
-  # - `from:` overrides inference explicitly
+  # See {Constructible} for how `value` is read.
   #
   # @param value [Integer, String, Float, BigDecimal, Rational]
   # @param symbol [Symbol, String] registered type identifier
@@ -188,12 +107,7 @@ class Amount
   def initialize(value, symbol, from: nil)
     @symbol = symbol.to_sym
     @entry = self.class.registry.lookup(@symbol)
-
-    expected = @entry.amount_class
-    if expected && expected != Amount && self.class != Amount && !instance_of?(expected)
-      raise InvalidInput, "use #{expected}.new for #{@symbol}"
-    end
-
+    ensure_registered_class!
     @atomic = infer_value(from, value)
     @display = Display.new(self)
   end
@@ -222,7 +136,7 @@ class Amount
     BigDecimal(@atomic) / (BigDecimal(10)**decimals)
   end
 
-  def_delegators :display, :formatted, :ui, :to_s, :in_unit
+  def_delegators :display, :formatted, :ui, :unit_label, :to_s, :in_unit
 
   # @return [String]
   # @example Console-friendly inspection
@@ -231,62 +145,4 @@ class Amount
   def inspect
     "#<#{self.class} #{symbol} #{ui}>"
   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 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 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
-
-  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)
-    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.is_a?(Rational) ? value : value.to_s)
-    else
-      raise InvalidInput, "unknown amount format: #{value.inspect}"
-    end
-  end
-
-  def infer_type(value)
-    case value
-    when Integer then :atomic
-    when String then :ui
-    when Float, BigDecimal, Rational then :float
-    else
-      raise InvalidInput, "cannot infer type for #{value.class}"
-    end
-  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}"
-  end
 end

data/test/amount/active_record/amount_validator_test.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+require_relative "../../support/active_record_test_support"
+
+class AmountActiveRecordAmountValidatorTest < Minitest::Test
+  include ActiveRecordTestSetup
+
+  def test_accepts_valid_multi_symbol_amount
+    assert validated(amount: "USDC|100.00").valid?
+  end
+
+  def test_rejects_wrong_symbol
+    refute validated(amount: "USD|100.00").valid?
+  end
+
+  def test_reports_wrong_symbol
+    assert_includes errors_on(validated(amount: "USD|100.00"), :amount), "must have symbol USDC"
+  end
+
+  def test_rejects_amount_below_lower_bound
+    refute validated(amount: "USDC|0.00").valid?
+  end
+
+  def test_reports_amount_below_lower_bound
+    assert_includes errors_on(validated(amount: "USDC|0.00"), :amount), "must be greater than USDC|0.00"
+  end
+
+  def test_rejects_amount_above_upper_bound
+    refute validated(amount: "USDC|1000.01").valid?
+  end
+
+  def test_reports_amount_above_upper_bound
+    assert_includes errors_on(validated(amount: "USDC|1000.01"), :amount), "must be less than or equal to USDC|1000.00"
+  end
+
+  def test_allows_nil_when_allow_nil_is_set
+    assert validated(amount: "USDC|100.00", fee: nil).valid?
+  end
+
+  def test_supports_fixed_symbol_numeric_thresholds
+    assert validated(amount: "USDC|100.00", fee: 0.5).valid?
+  end
+
+  def test_rejects_fixed_symbol_amount_below_lower_bound
+    refute validated(amount: "USDC|100.00", fee: 0).valid?
+  end
+
+  def test_reports_fixed_symbol_amount_below_lower_bound
+    assert_includes errors_on(validated(amount: "USDC|100.00", fee: 0), :fee), "must be greater than SOL|0.0000"
+  end
+
+  def test_rejects_fixed_symbol_amount_at_exclusive_upper_bound
+    refute validated(amount: "USDC|100.00", fee: 10).valid?
+  end
+
+  def test_reports_fixed_symbol_amount_at_exclusive_upper_bound
+    assert_includes errors_on(validated(amount: "USDC|100.00", fee: 10), :fee), "must be less than SOL|10.0000"
+  end
+
+  def test_rejects_cross_type_threshold_without_rate
+    refute cross_type_threshold_model.new(amount: "USDC|2.00").valid?
+  end
+
+  def test_reports_cross_type_threshold_without_rate
+    holding = cross_type_threshold_model.new(amount: "USDC|2.00")
+
+    assert_includes errors_on(holding, :amount), "cannot compare USDC to USD for greater_than"
+  end
+
+  def test_adds_symbol_error_by_key_with_interpolations
+    holding = validated(amount: "USD|100.00")
+    holding.valid?
+
+    assert_includes holding.errors.details[:amount], { error: :amount_symbol, expected: :USDC }
+  end
+
+  def test_adds_comparison_error_by_key_with_interpolations
+    holding = validated(amount: "USDC|0.00")
+    holding.valid?
+
+    assert_includes holding.errors.details[:amount], { error: :greater_than, count: "USDC|0.00" }
+  end
+
+  def test_incomparable_error_details
+    holding = cross_type_threshold_model.new(amount: "USDC|2.00")
+    holding.valid?
+
+    assert_includes holding.errors.details[:amount],
+                    { error: :amount_incomparable, symbol: :USDC, other_symbol: :USD, option: :greater_than }
+  end
+
+  def test_symbol_message_can_be_translated_by_the_app
+    messages = with_german_messages { errors_on(validated(amount: "USD|100.00"), :amount) }
+
+    assert_includes messages, "muss das Symbol USDC haben"
+  end
+
+  def test_comparison_message_can_be_translated_by_the_app
+    messages = with_german_messages { errors_on(validated(amount: "USDC|0.00"), :amount) }
+
+    assert_includes messages, "muss groesser als USDC|0.00 sein"
+  end
+
+  def test_uses_registered_rate_for_cross_type_threshold_when_available
+    Amount.register_default_rate :USD, :USDC, "1"
+
+    assert cross_type_threshold_model.new(amount: "USDC|2.00").valid?
+  end
+
+  def test_numeric_thresholds_on_multi_symbol_attribute_accept_value_inside_range
+    assert bounded_numeric_threshold_model.new(amount: "USDC|50.00").valid?
+  end
+
+  def test_numeric_thresholds_on_multi_symbol_attribute_reject_value_at_exclusive_lower_bound
+    refute bounded_numeric_threshold_model.new(amount: "USDC|0.00").valid?
+  end
+
+  def test_numeric_thresholds_on_multi_symbol_attribute_report_lower_bound
+    holding = bounded_numeric_threshold_model.new(amount: "USDC|0.00")
+
+    assert_includes errors_on(holding, :amount).join, "greater than"
+  end
+
+  def test_numeric_thresholds_on_multi_symbol_attribute_reject_value_above_upper_bound
+    refute bounded_numeric_threshold_model.new(amount: "USDC|150.00").valid?
+  end
+
+  def test_numeric_thresholds_on_multi_symbol_attribute_report_upper_bound
+    holding = bounded_numeric_threshold_model.new(amount: "USDC|150.00")
+
+    assert_includes errors_on(holding, :amount).join, "less than"
+  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.
+  def test_numeric_threshold_accepts_usdc_value_above_one_usdc
+    assert greater_than_one_model.new(amount: "USDC|2.00").valid?
+  end
+
+  def test_numeric_threshold_rejects_usdc_value_below_one_usdc
+    refute greater_than_one_model.new(amount: "USDC|0.50").valid?
+  end
+
+  def test_numeric_threshold_accepts_sol_value_above_one_sol
+    assert greater_than_one_model.new(amount: "SOL|2").valid?
+  end
+
+  def test_numeric_threshold_rejects_sol_value_below_one_sol
+    refute greater_than_one_model.new(amount: "SOL|0.5").valid?
+  end
+
+  private
+
+  def validated(**attributes)
+    ValidatedHolding.new(reserve: "USDC|1.25", **attributes)
+  end
+
+  def errors_on(record, attribute)
+    record.valid?
+    record.errors[attribute]
+  end
+
+  def holdings_model_validating_amount(**options)
+    Class.new(::ActiveRecord::Base) do
+      self.table_name = "holdings"
+
+      has_amount :amount
+      validates :amount, amount: options
+    end
+  end
+
+  def cross_type_threshold_model
+    holdings_model_validating_amount(greater_than: "USD|1.00")
+  end
+
+  def bounded_numeric_threshold_model
+    holdings_model_validating_amount(greater_than: 0, less_than_or_equal_to: 100)
+  end
+
+  def greater_than_one_model
+    holdings_model_validating_amount(greater_than: 1)
+  end
+
+  # Runs the block under :de with app-provided translations of the
+  # validator's error keys.
+  def with_german_messages(&)
+    original_locales = I18n.available_locales
+    I18n.available_locales = original_locales | [:de]
+    # rubocop:disable Style/FormatStringToken
+    I18n.backend.store_translations(:de, errors: { messages: {
+                                      amount_symbol: "muss das Symbol %{expected} haben",
+                                      greater_than: "muss groesser als %{count} sein"
+                                    } })
+    # rubocop:enable Style/FormatStringToken
+    I18n.with_locale(:de, &)
+  ensure
+    I18n.available_locales = original_locales
+  end
+end