amounts 0.0.8 → 0.1.0

data/test/amount/compact_test.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "i18n"
+require_relative "../test_helper"
+require_relative "../support/locale_test_setup"
+
+class AmountCompactTest < Minitest::Test
+  include LocaleTestSetup
+
+  def setup
+    super
+    Amount.register :TOKENS, decimals: 0
+  end
+
+  # Off by default
+
+  def test_without_compact_output_is_unchanged
+    assert_equal "50000000 TOKENS", tokens(50_000_000).ui
+  end
+
+  def test_compact_false_output_is_unchanged
+    assert_equal "50000000 TOKENS", tokens(50_000_000).ui(compact: false)
+  end
+
+  def test_without_compact_prefix_type_output_is_unchanged
+    assert_equal "$1500000.00", Amount.of_usd("1500000").ui
+  end
+
+  # Thresholds
+
+  def test_below_one_thousand_is_formatted_normally
+    assert_equal "999 TOKENS", tokens(999).ui(compact: true)
+  end
+
+  def test_below_one_thousand_keeps_decimals
+    assert_equal "$999.99", Amount.of_usd("999.99").ui(compact: true)
+  end
+
+  def test_zero_is_formatted_normally
+    assert_equal "0 TOKENS", tokens(0).ui(compact: true)
+  end
+
+  # Each row: count => expected compact output (default floor rounding).
+  {
+    1_000 => "1K TOKENS",
+    999_999 => "999K TOKENS",
+    1_000_000 => "1M TOKENS",
+    999_999_999 => "999M TOKENS",
+    1_000_000_000 => "1B TOKENS",
+    1_000_000_000_000 => "1T TOKENS"
+  }.each do |count, expected|
+    define_method("test_scale_threshold_#{count}") do
+      assert_equal expected, tokens(count).ui(compact: true)
+    end
+  end
+
+  {
+    1_500_000_000_000_000 => "1.5Qa TOKENS",
+    10**18 => "1Qi TOKENS",
+    10**21 => "1Sx TOKENS",
+    10**24 => "1Sp TOKENS",
+    10**27 => "1Oc TOKENS",
+    10**30 => "1No TOKENS",
+    10**33 => "1Dc TOKENS",
+    (10**21) - 1 => "999Qi TOKENS"
+  }.each do |count, expected|
+    define_method("test_scales_past_trillions_#{count}") do
+      assert_equal expected, tokens(count).ui(compact: true)
+    end
+  end
+
+  def test_scales_past_trillions_ceil_rounds_into_sextillions
+    assert_equal "1Sx TOKENS", tokens((10**21) - 1).ui(compact: true, direction: :ceil)
+  end
+
+  def test_beyond_decillions_stays_in_decillions
+    assert_equal "1500Dc TOKENS", tokens(15 * (10**35)).ui(compact: true)
+  end
+
+  def test_beyond_decillions_stays_in_decillions_with_locale_delimiter
+    assert_equal "1.500Dc TOKENS", tokens(15 * (10**35)).ui(compact: true, locale: :de)
+  end
+
+  # Precision and rounding
+
+  {
+    1_234 => "1.23K TOKENS",
+    12_345_678 => "12.3M TOKENS",
+    123_456_789_012 => "123B TOKENS"
+  }.each do |count, expected|
+    define_method("test_three_significant_digits_by_default_#{count}") do
+      assert_equal expected, tokens(count).ui(compact: true)
+    end
+  end
+
+  {
+    50_000_000 => "50M TOKENS",
+    1_500 => "1.5K TOKENS",
+    1_010 => "1.01K TOKENS"
+  }.each do |count, expected|
+    define_method("test_trailing_zeros_are_trimmed_#{count}") do
+      assert_equal expected, tokens(count).ui(compact: true)
+    end
+  end
+
+  def test_floor_never_rounds_up
+    assert_equal "1.99M TOKENS", tokens(1_999_999).ui(compact: true)
+  end
+
+  def test_ceil_rounds_up_to_whole
+    assert_equal "2M TOKENS", tokens(1_999_999).ui(compact: true, direction: :ceil)
+  end
+
+  def test_ceil_rounds_up_last_significant_digit
+    assert_equal "1.24K TOKENS", tokens(1_234).ui(compact: true, direction: :ceil)
+  end
+
+  def test_rounding_into_the_next_scale_uses_that_scale_millions
+    assert_equal "1M TOKENS", tokens(999_999).ui(compact: true, direction: :ceil)
+  end
+
+  def test_rounding_into_the_next_scale_uses_that_scale_trillions
+    assert_equal "1T TOKENS", tokens(999_999_999_999).ui(compact: true, direction: :ceil)
+  end
+
+  # floor goes toward negative infinity, as `ui` does for any negative amount
+
+  def test_negative_exact_value
+    assert_equal "-1.5M TOKENS", tokens(-1_500_000).ui(compact: true)
+  end
+
+  def test_negative_floor_rounds_away_from_zero
+    assert_equal "-2M TOKENS", tokens(-1_999_999).ui(compact: true)
+  end
+
+  def test_negative_ceil_rounds_toward_zero
+    assert_equal "-1.99M TOKENS", tokens(-1_999_999).ui(compact: true, direction: :ceil)
+  end
+
+  def test_negative_floor_rounds_into_the_next_scale
+    assert_equal "-1M TOKENS", tokens(-999_999).ui(compact: true)
+  end
+
+  def test_negative_below_one_thousand_is_formatted_normally
+    assert_equal "-999 TOKENS", tokens(-999).ui(compact: true)
+  end
+
+  def test_negative_prefix_type
+    assert_equal "$-1.5K", Amount.of_usd("-1500").ui(compact: true)
+  end
+
+  def test_precision_two_floors
+    assert_equal "1.2M TOKENS", tokens(1_299_999).ui(compact: { precision: 2 })
+  end
+
+  def test_precision_one
+    assert_equal "1M TOKENS", tokens(1_299_999).ui(compact: { precision: 1 })
+  end
+
+  def test_precision_two_trims_trailing_zero
+    assert_equal "150K TOKENS", tokens(155_000).ui(compact: { precision: 2 })
+  end
+
+  def test_precision_five
+    assert_equal "1.2345M TOKENS", tokens(1_234_567).ui(compact: { precision: 5 })
+  end
+
+  def test_empty_options_hash_uses_default_precision
+    assert_equal "1.23M TOKENS", tokens(1_234_567).ui(compact: {})
+  end
+
+  {
+    "symbol" => :yes,
+    "zero_precision" => { precision: 0 },
+    "string_precision" => { precision: "2" },
+    "unknown_key" => { digits: 2 }
+  }.each do |name, compact|
+    define_method("test_invalid_compact_option_raises_#{name}") do
+      assert_raises(ArgumentError) { tokens(1).ui(compact:) }
+    end
+  end
+
+  def test_compact_ignores_fractional_atomic_noise
+    assert_equal "$1.23M", Amount.of_usdc("1234567.891234").ui(compact: true)
+  end
+
+  # Labels and templates
+
+  def test_prefix_type_wraps_the_compacted_number
+    assert_equal "$1.5M", Amount.of_usd("1500000").ui(compact: true)
+  end
+
+  def test_suffix_type_wraps_the_compacted_number
+    assert_equal "2.5K SOL", Amount.of_sol("2500").ui(compact: true)
+  end
+
+  def test_display_format_wraps_the_compacted_number
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%n %u"
+
+    assert_equal "1.5M €", Amount.of_eur("1500000").ui(compact: true)
+  end
+
+  def test_undecorated_returns_just_the_compacted_number
+    assert_equal "50M", tokens(50_000_000).ui(compact: true, decorated: false)
+  end
+
+  def test_undecorated_keeps_the_locale_scale_word
+    german_keys
+
+    assert_equal "1,5 Mio.", tokens(1_500_000).ui(compact: true, decorated: false, locale: :de)
+  end
+
+  def test_plural_label_agrees_with_the_full_value
+    register_searches
+
+    assert_equal "1K searches", Amount.of_searches(1_000).ui(compact: true)
+  end
+
+  def test_singular_label_below_one_thousand
+    register_searches
+
+    assert_equal "1 search", Amount.of_searches(1).ui(compact: true)
+  end
+
+  def test_display_unit_compacts_the_scaled_number
+    assert_equal "31.1K g", Amount.of_gold("1000").ui(unit: :gram, compact: true)
+  end
+
+  def test_display_unit_compacts_the_scaled_number_with_ceil
+    assert_equal "31.2K g", Amount.of_gold("1000").ui(unit: :gram, compact: true, direction: :ceil)
+  end
+
+  def test_display_unit_compacts_another_unit
+    assert_equal "1K oz t", Amount.of_gold("1000").ui(unit: :oz_t, compact: true)
+  end
+
+  def test_display_unit_below_one_thousand_uses_its_decimals
+    assert_equal "311.03 g", Amount.of_gold("10").ui(unit: :gram, compact: true)
+  end
+
+  def test_wire_format_ignores_compact
+    assert_equal "TOKENS|50000000", tokens(50_000_000).to_s
+  end
+
+  # Scale words
+
+  def test_short_forms_when_not_localizing_even_with_locale_keys
+    german_keys
+
+    assert_equal "1.5M TOKENS", tokens(1_500_000).ui(compact: true)
+  end
+
+  def test_en_with_rails_keys_million
+    english_keys
+
+    assert_equal "50 Million TOKENS", tokens(50_000_000).ui(compact: true, locale: :en)
+  end
+
+  def test_en_with_rails_keys_thousand
+    english_keys
+
+    assert_equal "1.23 Thousand TOKENS", tokens(1_234).ui(compact: true, locale: :en)
+  end
+
+  def test_en_with_rails_keys_billion_prefix_type
+    english_keys
+
+    assert_equal "$1.5 Billion", Amount.of_usd("1500000000").ui(compact: true, locale: :en)
+  end
+
+  def test_en_with_rails_keys_quadrillion
+    english_keys
+
+    assert_equal "1.5 Quadrillion TOKENS", tokens(1_500_000_000_000_000).ui(compact: true, locale: :en)
+  end
+
+  # no `quintillion` key: falls back to the short form
+  def test_en_with_rails_keys_missing_quintillion_falls_back_to_short_form
+    english_keys
+
+    assert_equal "2Qi TOKENS", tokens(2 * (10**18)).ui(compact: true, locale: :en)
+  end
+
+  {
+    1_500_000 => "1,5 Mio. Token",
+    1_999_999 => "1,99 Mio. Token",
+    12_000 => "12 Tsd. Token",
+    999 => "999 Token"
+  }.each do |count, expected|
+    define_method("test_de_with_its_own_keys_#{count}") do
+      german_keys
+
+      assert_equal expected, tokens(count).ui(compact: true, locale: :de)
+    end
+  end
+
+  def test_localize_true_uses_i18n_locale
+    german_keys
+    Amount.localize = true
+    I18n.locale = :de
+
+    assert_equal "1,5 Mio. Token", tokens(1_500_000).ui(compact: true)
+  end
+
+  def test_pluralized_scale_word_one
+    store_decimal_units(:de, units: { million: { one: "Million", other: "Millionen" } })
+
+    assert_equal "1 Million TOKENS", tokens(1_000_000).ui(compact: true, locale: :de)
+  end
+
+  def test_pluralized_scale_word_other
+    store_decimal_units(:de, units: { million: { one: "Million", other: "Millionen" } })
+
+    assert_equal "2,5 Millionen TOKENS", tokens(2_500_000).ui(compact: true, locale: :de)
+  end
+
+  def test_locale_format_joins_number_and_word
+    store_decimal_units(:de, format: "%n%u", units: { thousand: "k" })
+
+    assert_equal "1,5k TOKENS", tokens(1_500).ui(compact: true, locale: :de)
+  end
+
+  def test_missing_locale_keys_fall_back_to_short_form
+    assert_equal "1,5M TOKENS", tokens(1_500_000).ui(compact: true, locale: :de)
+  end
+
+  def test_missing_locale_word_falls_back_to_short_form
+    german_keys
+
+    assert_equal "1,5B Token", tokens(1_500_000_000).ui(compact: true, locale: :de)
+  end
+
+  def test_locale_format_without_number_is_ignored
+    store_decimal_units(:de, format: "%u", units: { thousand: "Tsd." })
+
+    assert_equal "1,5 Tsd. TOKENS", tokens(1_500).ui(compact: true, locale: :de)
+  end
+
+  def test_compact_works_without_i18n
+    without_i18n { assert_equal "50M TOKENS", tokens(50_000_000).ui(compact: true) }
+  end
+
+  private
+
+  def tokens(count)
+    Amount.of_tokens(count)
+  end
+
+  def register_searches
+    Amount.register :SEARCHES, decimals: 0, display_symbol: { one: "search", other: "searches" }
+  end
+
+  # number.human.decimal_units, the keys Rails' number_to_human reads
+  def store_decimal_units(locale, units:, format: nil)
+    decimal_units = { units: }
+    decimal_units[:format] = format if format
+    I18n.backend.store_translations(locale, number: { human: { decimal_units: } })
+  end
+
+  def english_keys
+    store_decimal_units(:en, format: "%n %u", units: {
+                          unit: "", thousand: "Thousand", million: "Million", billion: "Billion", trillion: "Trillion",
+                          quadrillion: "Quadrillion"
+                        })
+  end
+
+  def german_keys
+    store_decimal_units(:de, format: "%n %u", units: { thousand: "Tsd.", million: "Mio." })
+    I18n.backend.store_translations(:de, amounts: { units: { tokens: "Token" } })
+  end
+end

data/test/amount/concerns/allocatable_test.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+
+class AmountAllocatableTest < Minitest::Test
+  class GoldAmount < Amount
+    def purity_estimate
+      "24k"
+    end
+  end
+
+  def setup
+    AmountTestSupport.register_default_types!
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_split_with_remainder_parts
+    parts, = Amount.new(10, :LOGS).split(3)
+
+    assert_equal [3, 3, 3], parts.map(&:atomic)
+  end
+
+  def test_split_with_remainder_remainder
+    _, remainder = Amount.new(10, :LOGS).split(3)
+
+    assert_equal 1, remainder.atomic
+  end
+
+  def test_split_with_remainder_preserves_total
+    parts, remainder = Amount.new(10, :LOGS).split(3)
+
+    assert_equal 10, parts.sum(&:atomic) + remainder.atomic
+  end
+
+  def test_split_even_division_parts
+    parts, = Amount.new(9, :LOGS).split(3)
+
+    assert_equal [3, 3, 3], parts.map(&:atomic)
+  end
+
+  def test_split_even_division_returns_zero_remainder
+    _, remainder = Amount.new(9, :LOGS).split(3)
+
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_split_one_returns_same_amount
+    parts, = Amount.new(9, :LOGS).split(1)
+
+    assert_equal [9], parts.map(&:atomic)
+  end
+
+  def test_split_one_returns_zero_remainder
+    _, remainder = Amount.new(9, :LOGS).split(1)
+
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_split_negative_amount_parts_round_toward_zero
+    parts, = Amount.new(-10, :LOGS).split(3)
+
+    assert_equal [-3, -3, -3], parts.map(&:atomic)
+  end
+
+  def test_split_negative_amount_has_negative_remainder
+    _, remainder = Amount.new(-10, :LOGS).split(3)
+
+    assert_equal(-1, remainder.atomic)
+  end
+
+  def test_split_negative_amount_preserves_total
+    parts, remainder = Amount.new(-10, :LOGS).split(3)
+
+    assert_equal(-10, parts.sum(&:atomic) + remainder.atomic)
+  end
+
+  def test_allocate_by_weights_parts
+    parts, = Amount.new(100, :LOGS).allocate([1, 1, 2])
+
+    assert_equal [25, 25, 50], parts.map(&:atomic)
+  end
+
+  def test_allocate_by_weights_zero_remainder
+    _, remainder = Amount.new(100, :LOGS).allocate([1, 1, 2])
+
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_allocate_by_weights_preserves_total
+    parts, remainder = Amount.new(100, :LOGS).allocate([1, 1, 2])
+
+    assert_equal 100, parts.sum(&:atomic) + remainder.atomic
+  end
+
+  def test_allocate_uneven_parts
+    parts, = Amount.new(10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal [3, 3, 3], parts.map(&:atomic)
+  end
+
+  def test_allocate_remainder_is_explicit
+    _, remainder = Amount.new(10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal 1, remainder.atomic
+  end
+
+  def test_allocate_allows_zero_weights
+    parts, = Amount.new(10, :LOGS).allocate([0, 1])
+
+    assert_equal [0, 10], parts.map(&:atomic)
+  end
+
+  def test_allocate_with_zero_weight_has_zero_remainder
+    _, remainder = Amount.new(10, :LOGS).allocate([0, 1])
+
+    assert_equal 0, remainder.atomic
+  end
+
+  def test_allocate_negative_amount_parts_round_toward_zero
+    parts, = Amount.new(-10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal [-3, -3, -3], parts.map(&:atomic)
+  end
+
+  def test_allocate_negative_amount_has_negative_remainder
+    _, remainder = Amount.new(-10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal(-1, remainder.atomic)
+  end
+
+  def test_allocate_negative_amount_preserves_total
+    parts, remainder = Amount.new(-10, :LOGS).allocate([1, 1, 1])
+
+    assert_equal(-10, parts.sum(&:atomic) + remainder.atomic)
+  end
+
+  def test_split_returns_subclass_parts
+    parts, = gold_split
+
+    assert parts.all? { |part| part.instance_of?(GoldAmount) }
+  end
+
+  def test_split_returns_subclass_remainder
+    _, remainder = gold_split
+
+    assert_instance_of GoldAmount, remainder
+  end
+
+  private
+
+  def gold_split
+    register_gold_subclass!
+    GoldAmount.new("3", :GOLD).split(2)
+  end
+
+  # Replaces the default registry with GOLD bound to GoldAmount.
+  def register_gold_subclass!
+    Amount.registry.clear!
+    Amount.register :GOLD, decimals: 8, display_symbol: "oz t",
+                           display_position: :suffix, ui_decimals: 4,
+                           class: GoldAmount
+  end
+end

data/test/amount/concerns/calculable_test.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require_relative "../../test_helper"
+
+class AmountCalculableTest < Minitest::Test
+  class GoldAmount < Amount
+    def purity_estimate
+      "24k"
+    end
+  end
+
+  def setup
+    AmountTestSupport.register_default_types!
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_frozen_amount_addition_returns_correct_sum
+    assert_equal Amount.new("3", :USDC), frozen_sum
+  end
+
+  def test_frozen_amount_addition_returns_unfrozen_result
+    refute_predicate frozen_sum, :frozen?
+  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_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)
+  end
+
+  def test_asymmetric_rate_rejects_reverse_direction
+    Amount.register_default_rate :USD, :USDC, 1
+
+    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
+
+  # name => [expected, amount, factor]
+  {
+    "integer" => ["3", "1", 3],
+    "float" => ["1.5", "1", 1.5],
+    "negative_by_negative" => ["2", "-1", -2],
+    "bigdecimal" => ["3", "2", BigDecimal("1.5")],
+    "rational" => ["3", "2", Rational(3, 2)]
+  }.each do |name, (expected, amount, factor)|
+    define_method("test_scalar_multiplication_by_#{name}") do
+      assert_equal Amount.new(expected, :USDC), Amount.new(amount, :USDC) * factor
+    end
+  end
+
+  def test_amount_times_amount_raises
+    assert_raises(Amount::TypeMismatch) do
+      Amount.new("1", :USDC) * Amount.new("1", :USDC)
+    end
+  end
+
+  # name => [expected, amount, divisor]
+  {
+    "integer" => ["0.5", "1", 2],
+    "negative_float" => ["2", "-1", -0.5],
+    "rational" => ["2", "3", Rational(3, 2)],
+    "bigdecimal" => ["2", "3", BigDecimal("1.5")]
+  }.each do |name, (expected, amount, divisor)|
+    define_method("test_scalar_division_by_#{name}_returns_amount") do
+      assert_equal Amount.new(expected, :USDC), Amount.new(amount, :USDC) / divisor
+    end
+  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_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_arithmetic_returns_subclass
+    register_gold_subclass!
+    gold = GoldAmount.new("1", :GOLD)
+
+    assert_instance_of GoldAmount, gold + gold
+  end
+
+  private
+
+  def frozen_sum
+    Amount.new("1", :USDC).freeze + Amount.new("2", :USDC).freeze
+  end
+
+  # Replaces the default registry with GOLD bound to GoldAmount.
+  def register_gold_subclass!
+    Amount.registry.clear!
+    Amount.register :GOLD, decimals: 8, display_symbol: "oz t",
+                           display_position: :suffix, ui_decimals: 4,
+                           class: GoldAmount
+  end
+end