amounts 0.0.1

data/test/test_amount.rb

@@ -0,0 +1,472 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class AmountTest < Minitest::Test
+  def setup
+    AmountTestSupport.register_default_types!
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_construct_from_integer_treats_as_atomic
+    amount = Amount.new(1_000_000, :USDC)
+
+    assert_equal 1_000_000, amount.atomic
+    assert_equal BigDecimal("1"), amount.decimal
+  end
+
+  def test_construct_from_string_treats_as_ui
+    assert_equal 1_500_000, Amount.new("1.50", :USDC).atomic
+  end
+
+  def test_construct_from_float_treats_as_decimal
+    assert_equal 1_500_000, Amount.new(1.5, :USDC).atomic
+  end
+
+  def test_explicit_from_overrides_inference
+    amount = Amount.new("1500000", :USDC, from: :atomic)
+
+    assert_equal 1_500_000, amount.atomic
+    assert_equal BigDecimal("1.5"), amount.decimal
+  end
+
+  def test_parse_roundtrips_to_s
+    amount = Amount.parse("USDC|1.5")
+
+    assert_equal 1_500_000, amount.atomic
+    assert_equal "USDC|1.5", amount.to_s
+  end
+
+  def test_parse_accepts_explicit_v1_prefix
+    amount = Amount.parse("v1:USDC|1.5")
+
+    assert_equal Amount.new("1.5", :USDC), amount
+  end
+
+  def test_parse_rejects_unknown_version_prefix
+    assert_raises(Amount::InvalidInput) { Amount.parse("v2:USDC|1.5") }
+  end
+
+  def test_generated_constructor_matches_new
+    assert_equal Amount.new("1.50", :USDC), Amount.usdc("1.50")
+  end
+
+  def test_generated_constructor_accepts_from_keyword
+    assert_equal 1_500_000, Amount.usdc(1_500_000, from: :atomic).atomic
+  end
+
+  def test_multi_word_symbol_generates_constructor
+    Amount.register :OIL_WTI_BBL, decimals: 4
+
+    assert_equal Amount.new("1.5", :OIL_WTI_BBL), Amount.oil_wti_bbl("1.5")
+  end
+
+  def test_non_method_safe_symbol_skips_constructor_generation
+    Amount.register :'USDC.e', decimals: 6
+
+    refute Amount.respond_to?(:usdc_e)
+  end
+
+  def test_clear_removes_generated_constructor_methods
+    assert Amount.respond_to?(:usdc)
+
+    Amount.registry.clear!
+
+    refute Amount.respond_to?(:usdc)
+  end
+
+  def test_registry_lock_prevents_mutation
+    Amount.registry.lock!
+
+    assert Amount.registry.locked?
+    assert_raises(Amount::Registry::RegistryLocked) { Amount.register(:DOGE, decimals: 8) }
+    assert_raises(Amount::Registry::RegistryLocked) { Amount.register_default_rate(:USD, :USDC, 1) }
+    assert_raises(Amount::Registry::RegistryLocked) { Amount.registry.clear! }
+  ensure
+    Amount.send(:replace_registry, Amount::Registry.new)
+  end
+
+  def test_constructor_collision_raises_at_registration_time
+    assert_raises(Amount::Registry::AlreadyRegistered) do
+      Amount.register :NEW, decimals: 2
+    end
+  end
+
+  def test_inspect_uses_default_ui_representation
+    assert_equal "#<Amount USDC $1.50>", Amount.new("1.5", :USDC).inspect
+    assert_equal "#<Amount GOLD 1.0000 oz t>", Amount.new("1", :GOLD).inspect
+  end
+
+  def test_parse_rejects_missing_value
+    assert_raises(Amount::InvalidInput) { Amount.parse("USDC|") }
+  end
+
+  def test_parse_rejects_missing_symbol
+    assert_raises(Amount::InvalidInput) { Amount.parse("|1.5") }
+  end
+
+  def test_unregistered_type_raises
+    assert_raises(Amount::Registry::UnknownType) { Amount.new(1, :DOGE) }
+  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
+    assert_equal "1", Amount.new(1, :LOGS).formatted
+  end
+
+  def test_ui_respects_ui_decimals_and_position
+    assert_equal "$1.50", Amount.new("1.5", :USDC).ui
+    assert_equal "$1.56", Amount.new("1.567", :USDC).ui
+    assert_equal "1.5000 SOL", Amount.new("1.5", :SOL).ui
+    assert_equal "1 logs", Amount.new(1, :LOGS).ui
+  end
+
+  def test_ui_ceil_direction
+    assert_equal "$1.57", Amount.new("1.561", :USDC).ui(direction: :ceil)
+  end
+
+  def test_display_units_scale_output
+    gold = Amount.new("1.5", :GOLD)
+
+    assert_equal "1.5000 oz t", gold.ui
+    assert_equal "46.65 g", gold.ui(unit: :gram)
+    assert_equal "0.04665 kg", gold.ui(unit: :kg)
+  end
+
+  def test_in_unit_returns_raw_bigdecimal
+    gold = Amount.new("1.0", :GOLD)
+
+    assert_in_delta 31.1035, gold.in_unit(:gram).to_f, 0.0001
+  end
+
+  def test_unknown_display_unit_raises
+    assert_raises(Amount::Registry::InvalidDisplayUnit) do
+      Amount.new("1", :GOLD).ui(unit: :pound)
+    end
+  end
+
+  def test_predicates
+    assert Amount.new(0, :USDC).zero?
+    assert Amount.new(1, :USDC).positive?
+    assert Amount.new(-1, :USDC).negative?
+  end
+
+  def test_same_type
+    assert Amount.new(1, :USDC).same_type?(Amount.new(2, :USDC))
+    refute Amount.new(1, :USDC).same_type?(Amount.new(1, :SOL))
+    refute Amount.new(1, :USDC).same_type?(1)
+  end
+
+  def test_addition_same_type
+    assert_equal Amount.new("2.0", :USDC), Amount.new("1.5", :USDC) + Amount.new("0.5", :USDC)
+  end
+
+  def test_addition_cross_type_uses_registered_rate
+    Amount.register_default_rate :USD, :USDC, 1
+
+    result = Amount.new("10.00", :USDC) + Amount.new("5.00", :USD)
+
+    assert_equal Amount.new("15.00", :USDC), result
+  end
+
+  def test_addition_different_type_raises_without_rate
+    assert_raises(Amount::TypeMismatch) do
+      Amount.new(1, :USDC) + Amount.new(1, :SOL)
+    end
+  end
+
+  def test_subtraction_cross_type_uses_registered_rate
+    Amount.register_default_rate :USD, :USDC, 1
+
+    result = Amount.new("10.00", :USDC) - Amount.new("5.00", :USD)
+
+    assert_equal Amount.new("5.00", :USDC), result
+  end
+
+  def test_subtraction_different_type_raises_without_rate
+    assert_raises(Amount::TypeMismatch) do
+      Amount.new(1, :USDC) - Amount.new(1, :USD)
+    end
+  end
+
+  def test_asymmetric_rate_registration_only_allows_configured_direction
+    Amount.register_default_rate :USD, :USDC, 1
+
+    assert_equal Amount.new("15.00", :USDC), Amount.new("10.00", :USDC) + Amount.new("5.00", :USD)
+
+    assert_raises(Amount::TypeMismatch) do
+      Amount.new("5.00", :USD) + Amount.new("10.00", :USDC)
+    end
+  end
+
+  def test_unary_minus
+    assert_equal Amount.new("-1", :USDC), -Amount.new("1", :USDC)
+  end
+
+  def test_abs
+    assert_equal Amount.new("1", :USDC), Amount.new("-1", :USDC).abs
+  end
+
+  def test_scalar_multiplication
+    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
+  end
+
+  def test_amount_times_amount_raises
+    assert_raises(Amount::TypeMismatch) do
+      Amount.new("1", :USDC) * Amount.new("1", :USDC)
+    end
+  end
+
+  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
+  end
+
+  def test_amount_division_returns_ratio
+    ratio = Amount.new("10", :USDC) / Amount.new("2", :USDC)
+
+    assert_equal BigDecimal(5), ratio
+  end
+
+  def test_division_by_zero
+    assert_raises(ZeroDivisionError) { Amount.new(1, :USDC) / 0 }
+  end
+
+  def test_split_preserves_total_exactly_with_remainder
+    amount = Amount.new(10, :LOGS)
+    parts, remainder = amount.split(3)
+
+    assert_equal [3, 3, 3], parts.map(&:atomic)
+    assert_equal 1, remainder.atomic
+    assert_equal amount.atomic, parts.sum(&:atomic) + remainder.atomic
+  end
+
+  def test_split_even_division_returns_zero_remainder
+    parts, remainder = Amount.new(9, :LOGS).split(3)
+
+    assert_equal [3, 3, 3], parts.map(&:atomic)
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_split_one_returns_same_amount_and_zero_remainder
+    parts, remainder = Amount.new(9, :LOGS).split(1)
+
+    assert_equal [9], parts.map(&:atomic)
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_split_negative_amount_rounds_toward_zero_with_negative_remainder
+    parts, remainder = Amount.new(-10, :LOGS).split(3)
+
+    assert_equal [-3, -3, -3], parts.map(&:atomic)
+    assert_equal(-1, remainder.atomic)
+    assert_equal(-10, parts.sum(&:atomic) + remainder.atomic)
+  end
+
+  def test_allocate_by_weights
+    amount = Amount.new(100, :LOGS)
+    parts, remainder = amount.allocate([1, 1, 2])
+
+    assert_equal [25, 25, 50], parts.map(&:atomic)
+    assert_equal 0, remainder.atomic
+    assert_equal amount.atomic, parts.sum(&:atomic) + remainder.atomic
+  end
+
+  def test_allocate_remainder_is_explicit
+    parts, remainder = Amount.new(10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal [3, 3, 3], parts.map(&:atomic)
+    assert_equal 1, remainder.atomic
+  end
+
+  def test_allocate_allows_zero_weights
+    parts, remainder = Amount.new(10, :LOGS).allocate([0, 1])
+
+    assert_equal [0, 10], parts.map(&:atomic)
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_allocate_negative_amount_rounds_toward_zero_with_negative_remainder
+    parts, remainder = Amount.new(-10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal [-3, -3, -3], parts.map(&:atomic)
+    assert_equal(-1, remainder.atomic)
+    assert_equal(-10, parts.sum(&:atomic) + remainder.atomic)
+  end
+
+  def test_comparison_same_type
+    left = Amount.new("1", :USDC)
+    right = Amount.new("2", :USDC)
+
+    assert left < right
+    assert right > left
+    assert_equal Amount.new("1", :USDC), left
+  end
+
+  def test_comparison_cross_type_uses_registered_rate
+    Amount.register_default_rate :USD, :USDC, 1
+
+    assert_operator Amount.new("10.00", :USDC), :>, Amount.new("5.00", :USD)
+    assert_equal 0, Amount.new("5.00", :USDC) <=> Amount.new("5.00", :USD)
+  end
+
+  def test_comparison_different_type_nil_without_rate
+    assert_nil(Amount.new(1, :USDC) <=> Amount.new(1, :SOL))
+  end
+
+  def test_sorting
+    amounts = [Amount.new("3", :USDC), Amount.new("1", :USDC), Amount.new("2", :USDC)]
+
+    assert_equal ["1.0", "2.0", "3.0"], amounts.sort.map { |amount| amount.decimal.to_s("F") }
+  end
+
+  def test_to_same_symbol_is_identity
+    amount = Amount.new("1", :USDC)
+
+    assert_equal amount, amount.to(:USDC)
+  end
+
+  def test_to_with_explicit_rate
+    gold = Amount.new("1000", :USDC).to(:GOLD, rate: "0.00042")
+
+    assert_equal BigDecimal("0.42"), gold.decimal
+    assert_equal :GOLD, gold.symbol
+  end
+
+  def test_to_without_rate_requires_default
+    assert_raises(Amount::Registry::NoDefaultRate) do
+      Amount.new("1", :USDC).to(:GOLD)
+    end
+  end
+
+  def test_to_uses_registered_default_rate
+    Amount.register_default_rate :USDC, :USD, 1
+
+    usd = Amount.new("1.5", :USDC).to(:USD)
+
+    assert_equal BigDecimal("1.5"), usd.decimal
+    assert_equal :USD, usd.symbol
+  end
+
+  def test_cross_type_addition_via_explicit_conversion
+    gold = Amount.new("0.0001", :GOLD)
+    usdc = Amount.new("100", :USDC)
+    result = gold + usdc.to(:GOLD, rate: "0.00000042")
+
+    assert_equal BigDecimal("0.000142"), result.decimal
+  end
+
+  def test_hash_equality_semantics
+    one = Amount.new("1.5", :USDC)
+    two = Amount.new("1.5", :USDC)
+    three = Amount.new("1.5", :USD)
+
+    data = { one => :first }
+
+    assert_equal :first, data[two]
+    assert_nil data[three]
+  end
+
+  def test_to_h_and_load_round_trip_for_large_negative_amount
+    amount = Amount.new(-(10**30), :USDC, from: :atomic)
+
+    assert_equal amount, Amount.load(amount.to_h)
+  end
+
+  def test_to_h_returns_versioned_string_safe_payload
+    assert_equal(
+      { v: 1, atomic: "1500000", symbol: "USDC" },
+      Amount.new("1.5", :USDC).to_h
+    )
+  end
+
+  def test_load_accepts_legacy_unversioned_payload
+    amount = Amount.load(atomic: 1_500_000, symbol: :USDC)
+
+    assert_equal Amount.new("1.5", :USDC), amount
+  end
+
+  def test_load_rejects_unknown_serialization_version
+    assert_raises(Amount::InvalidInput) do
+      Amount.load(v: 2, atomic: "1500000", symbol: "USDC")
+    end
+  end
+
+  def test_very_large_atomic_value_preserves_precision
+    amount = Amount.new(10**30, :SOL, from: :atomic)
+
+    assert_equal 10**30, amount.atomic
+    assert_equal "1000000000000000000000.0", amount.decimal.to_s("F")
+  end
+
+  def test_registry_can_be_read_from_multiple_threads
+    errors = Queue.new
+
+    threads = 10.times.map do
+      Thread.new do
+        100.times do
+          Amount.registry.lookup(:USDC)
+          Amount.registry.default_rate?(:USDC, :USD)
+        rescue StandardError => error
+          errors << error
+        end
+      end
+    end
+
+    threads.each(&:join)
+
+    assert errors.empty?, "expected no thread errors, got #{errors.size}"
+  end
+end
+
+class AmountCustomClassTest < Minitest::Test
+  class GoldAmount < Amount
+    def purity_estimate
+      "24k"
+    end
+  end
+
+  def setup
+    Amount.registry.clear!
+    Amount.register :GOLD, decimals: 8, display_symbol: "oz t",
+                     display_position: :suffix, ui_decimals: 4,
+                     class: GoldAmount
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_subclass_instance_from_own_new
+    gold = GoldAmount.new("1", :GOLD)
+
+    assert_instance_of GoldAmount, gold
+    assert_equal "24k", gold.purity_estimate
+  end
+
+  def test_arithmetic_returns_subclass
+    gold = GoldAmount.new("1", :GOLD)
+
+    assert_instance_of GoldAmount, gold + gold
+  end
+
+  def test_generated_constructor_returns_subclass
+    gold = Amount.gold("1", from: :ui)
+
+    assert_instance_of GoldAmount, gold
+    assert_equal "24k", gold.purity_estimate
+  end
+
+  def test_split_returns_subclass_parts_and_remainder
+    parts, remainder = GoldAmount.new("3", :GOLD).split(2)
+
+    assert parts.all? { |part| part.instance_of?(GoldAmount) }
+    assert_instance_of GoldAmount, remainder
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "support/amount_test_support"

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: amounts
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Seb Scholl
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Amounts provides a precise Amount value object with atomic integer storage,
+  safe registered-type arithmetic, explicit conversion rates, display helpers,
+  and an optional ActiveRecord integration layer.
+email:
+- opensource@example.com
+executables:
+- console
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/amount.rb
+- lib/amount/active_record.rb
+- lib/amount/active_record/amount_validator.rb
+- lib/amount/active_record/attribute_definition.rb
+- lib/amount/active_record/migration_methods.rb
+- lib/amount/active_record/model.rb
+- lib/amount/active_record/rspec.rb
+- lib/amount/active_record/type.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/version.rb
+- test/dummy/app/models/holding.rb
+- test/dummy/bin/rails
+- test/dummy/config/application.rb
+- test/dummy/config/database.yml
+- test/dummy/config/environment.rb
+- test/dummy/db/schema.rb
+- test/dummy/log/development.log
+- test/dummy/log/test.log
+- test/postgresql_integration_test.rb
+- test/support/amount_test_support.rb
+- test/test_active_record.rb
+- test/test_amount.rb
+- test/test_helper.rb
+homepage: https://github.com/zarpay/amounts
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/zarpay/amounts/issues
+  changelog_uri: https://github.com/zarpay/amounts/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/zarpay/amounts#readme
+  source_code_uri: https://github.com/zarpay/amounts
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Precise registered quantities for money, tokens, commodities, and other fungible
+  things.
+test_files: []