amounts 0.0.8 → 0.1.0

data/test/amount/concerns/coercible_test.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+
+class AmountCoercibleTest < Minitest::Test
+  def setup
+    AmountTestSupport.register_default_types!
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_coerce_decimal_returns_big_decimal_unchanged
+    value = BigDecimal("1.25")
+
+    assert_same value, Amount.coerce_decimal(value)
+  end
+
+  def test_coerce_decimal_converts_integer
+    assert_equal BigDecimal("3"), Amount.coerce_decimal(3)
+  end
+
+  def test_coerce_decimal_converts_string
+    assert_equal BigDecimal("1.25"), Amount.coerce_decimal("1.25")
+  end
+
+  def test_coerce_decimal_converts_rational
+    assert_equal BigDecimal("1.5"), Amount.coerce_decimal(Rational(3, 2))
+  end
+
+  def test_coerce_decimal_converts_float_through_its_string_form
+    assert_equal BigDecimal("0.1"), Amount.coerce_decimal(0.1)
+  end
+
+  def test_cross_type_addition_without_rate_names_both_types
+    error = error_from(Amount::TypeMismatch) { Amount.of_usdc("1") + Amount.of_sol("1") }
+
+    assert_equal "type mismatch: USDC vs SOL", error.message
+  end
+
+  def test_adding_a_non_amount_raises_type_mismatch
+    assert_raises(Amount::TypeMismatch) { Amount.of_usdc("1") + 1 }
+  end
+
+  def test_adding_a_non_amount_names_its_class
+    assert_match(/vs Integer\z/, error_from(Amount::TypeMismatch) { Amount.of_usdc("1") + 1 }.message)
+  end
+end

data/test/amount/concerns/constructible_test.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+
+class AmountConstructibleTest < 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_construct_from_integer_treats_as_atomic
+    assert_equal 1_000_000, Amount.new(1_000_000, :USDC).atomic
+  end
+
+  def test_construct_from_integer_gives_matching_decimal
+    assert_equal BigDecimal("1"), Amount.new(1_000_000, :USDC).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_construct_from_rational_treats_as_ui
+    assert_equal 1_500_000, Amount.new(Rational(3, 2), :USDC).atomic
+  end
+
+  def test_construct_from_rational_is_exact_for_repeating_fractions
+    # 1/3 has no finite decimal expansion. With six decimals of storage
+    # the atomic representation is 333333 (truncated toward zero).
+    assert_equal 333_333, Amount.new(Rational(1, 3), :USDC).atomic
+  end
+
+  def test_construct_from_rational_with_explicit_ui_from
+    assert_equal 1_500_000, Amount.new(Rational(3, 2), :USDC, from: :ui).atomic
+  end
+
+  def test_explicit_from_overrides_inference_for_atomic
+    assert_equal 1_500_000, Amount.new("1500000", :USDC, from: :atomic).atomic
+  end
+
+  def test_explicit_from_overrides_inference_for_decimal
+    assert_equal BigDecimal("1.5"), Amount.new("1500000", :USDC, from: :atomic).decimal
+  end
+
+  def test_subclass_instance_from_own_new
+    use_gold_amount_registry!
+
+    assert_instance_of GoldAmount, GoldAmount.new("1", :GOLD)
+  end
+
+  def test_subclass_instance_from_own_new_has_subclass_behavior
+    use_gold_amount_registry!
+
+    assert_equal "24k", GoldAmount.new("1", :GOLD).purity_estimate
+  end
+
+  def test_amount_new_dispatches_to_registered_subclass_from_ui
+    use_gold_amount_registry!
+
+    assert_instance_of GoldAmount, Amount.new("1", :GOLD)
+  end
+
+  def test_amount_new_dispatches_to_registered_subclass_from_atomic
+    use_gold_amount_registry!
+
+    assert_instance_of GoldAmount, Amount.new(100_000_000, :GOLD, from: :atomic)
+  end
+
+  def test_explicit_wrong_subclass_still_raises
+    use_gold_amount_registry!
+    other = Class.new(Amount)
+
+    assert_raises(Amount::InvalidInput) { other.new("1", :GOLD) }
+  end
+
+  def test_explicit_wrong_subclass_message_names_registered_class
+    use_gold_amount_registry!
+    other = Class.new(Amount)
+
+    assert_match(/use AmountConstructibleTest::GoldAmount\.new for GOLD/,
+                 error_from(Amount::InvalidInput) { other.new("1", :GOLD) }.message)
+  end
+
+  def test_amount_new_with_default_class_is_unchanged
+    use_gold_amount_registry!
+    Amount.register :USDC, decimals: 6
+
+    assert_instance_of Amount, Amount.new("1", :USDC)
+  end
+
+  private
+
+  # Replaces the default types with GOLD registered to {GoldAmount}.
+  def use_gold_amount_registry!
+    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/convertible_test.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require_relative "../../test_helper"
+
+class AmountConvertibleTest < Minitest::Test
+  def setup
+    AmountTestSupport.register_default_types!
+  end
+
+  def teardown
+    Amount.registry.clear!
+  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_converts_value
+    assert_equal BigDecimal("0.42"), Amount.new("1000", :USDC).to(:GOLD, rate: "0.00042").decimal
+  end
+
+  def test_to_with_explicit_rate_sets_target_symbol
+    assert_equal :GOLD, Amount.new("1000", :USDC).to(:GOLD, rate: "0.00042").symbol
+  end
+
+  def test_to_with_rational_rate_converts_value
+    assert_equal BigDecimal("2"), Amount.new("4", :USDC).to(:USD, rate: Rational(1, 2)).decimal
+  end
+
+  def test_to_with_rational_rate_sets_target_symbol
+    assert_equal :USD, Amount.new("4", :USDC).to(:USD, rate: Rational(1, 2)).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_value
+    Amount.register_default_rate :USDC, :USD, 1
+
+    assert_equal BigDecimal("1.5"), Amount.new("1.5", :USDC).to(:USD).decimal
+  end
+
+  def test_to_uses_registered_default_rate_symbol
+    Amount.register_default_rate :USDC, :USD, 1
+
+    assert_equal :USD, Amount.new("1.5", :USDC).to(:USD).symbol
+  end
+end

data/test/amount/concerns/formattable_test.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require "i18n"
+require_relative "../../test_helper"
+require_relative "../../support/locale_test_setup"
+
+class AmountFormattableTest < Minitest::Test
+  include LocaleTestSetup
+
+  NBSP = " "
+
+  # Template primitives
+
+  def test_fill_places_number_before_label
+    assert_equal "12.50 €", Amount::Formattable.fill("%n %u", number: "12.50", label: "€")
+  end
+
+  def test_fill_places_label_before_number
+    assert_equal "€12.50", Amount::Formattable.fill("%u%n", number: "12.50", label: "€")
+  end
+
+  def test_fill_does_not_expand_placeholders_inside_the_values
+    assert_equal "5 %n", Amount::Formattable.fill("%n %u", number: "5", label: "%n")
+  end
+
+  {
+    prefix: "%u%n",
+    suffix: "%n %u",
+    nil => "%n %u"
+  }.each do |position, template|
+    define_method("test_template_for_#{position.inspect.delete(':')}_matches_the_legacy_layout") do
+      assert_equal template, Amount::Formattable.template_for(position)
+    end
+  end
+
+  def test_valid_template_accepts_a_string_with_the_number
+    assert Amount::Formattable.valid_template?("%n")
+  end
+
+  {
+    "string_without_the_number" => "%u",
+    "symbol" => :'%n',
+    "nil" => nil
+  }.each do |name, template|
+    define_method("test_valid_template_rejects_a_#{name}") do
+      refute Amount::Formattable.valid_template?(template)
+    end
+  end
+
+  # Amount#display_format
+
+  def test_display_format_is_part_of_the_amount_api
+    assert_includes Amount.ancestors, Amount::Formattable
+  end
+
+  def test_display_format_is_part_of_an_amount_subclass_api
+    assert_includes Class.new(Amount).ancestors, Amount::Formattable
+  end
+
+  def test_display_format_returns_the_registered_prefix_template
+    assert_equal "%u%n", Amount.of_usd("1").display_format
+  end
+
+  def test_display_format_returns_the_registered_suffix_template
+    assert_equal "%n %u", Amount.of_sol("1").display_format
+  end
+
+  def test_display_format_for_a_display_unit_with_a_format
+    register_mass
+
+    assert_equal "%n#{NBSP}%u", Amount.new("1", :MASS).display_format(unit: :kilo)
+  end
+
+  def test_display_format_for_a_display_unit_with_a_position
+    register_mass
+
+    assert_equal "%u%n", Amount.new("1", :MASS).display_format(unit: :pre)
+  end
+
+  def test_display_format_for_a_display_unit_named_by_a_string_without_a_template
+    register_mass
+
+    assert_equal "[%u] %n", Amount.new("1", :MASS).display_format(unit: "plain")
+  end
+
+  def test_display_format_for_a_locale_without_a_template
+    register_eur_with_german_template
+
+    assert_equal "%u%n", Amount.of_eur("1").display_format(locale: :en)
+  end
+
+  def test_display_format_for_a_locale_with_a_template
+    register_eur_with_german_template
+
+    assert_equal "%n#{NBSP}%u", Amount.of_eur("1").display_format(locale: :de)
+  end
+
+  def test_display_format_without_a_locale_ignores_locale_templates
+    register_eur_with_german_template
+
+    assert_equal "%u%n", Amount.of_eur("1").display_format
+  end
+
+  def test_display_format_for_an_unknown_display_unit_raises
+    register_mass
+
+    assert_raises(Amount::Registry::InvalidDisplayUnit) { Amount.new("1", :MASS).display_format(unit: :ton) }
+  end
+
+  def test_display_format_for_a_display_unit_of_a_type_without_units_raises
+    assert_raises(Amount::Registry::InvalidDisplayUnit) { Amount.of_usd("1").display_format(unit: :cents) }
+  end
+
+  def test_display_format_with_a_locale_requires_i18n
+    without_i18n do
+      assert_raises(ArgumentError) { Amount.of_usd("1").display_format(locale: :de) }
+    end
+  end
+
+  # Rendering without templates
+
+  def test_output_without_templates_prefix
+    assert_equal "$1.50", Amount.of_usdc("1.5").ui
+  end
+
+  def test_output_without_templates_negative_prefix
+    assert_equal "$-5.00", Amount.of_usd("-5").ui
+  end
+
+  def test_output_without_templates_suffix
+    assert_equal "1.5000 oz t", Amount.of_gold("1.5").ui
+  end
+
+  def test_output_without_templates_display_unit
+    assert_equal "46.65 g", Amount.of_gold("1.5").ui(unit: :gram)
+  end
+
+  def test_output_without_templates_in_en
+    assert_equal "$1,500.00", Amount.of_usd("1500").ui(locale: :en)
+  end
+
+  def test_output_without_templates_in_de
+    assert_equal "$1.500,00", Amount.of_usd("1500").ui(locale: :de)
+  end
+
+  # Rendering a type's template
+
+  def test_display_format_places_number_and_label
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%u %n"
+
+    assert_equal "€ 12.50", Amount.of_eur("12.5").ui
+  end
+
+  def test_display_format_keeps_the_sign_in_the_number
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%u%n"
+
+    assert_equal "€-12.50", Amount.of_eur("-12.5").ui
+  end
+
+  def test_display_format_keeps_non_breaking_spaces
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%n#{NBSP}%u"
+
+    assert_equal "12.50#{NBSP}€", Amount.of_eur("12.5").ui
+  end
+
+  def test_display_format_places_a_singular_label
+    register_plural_searches_with_template
+
+    assert_equal "search: 1", Amount.of_searches(1).ui
+  end
+
+  def test_display_format_places_a_plural_label
+    register_plural_searches_with_template
+
+    assert_equal "searches: 3", Amount.of_searches(3).ui
+  end
+
+  def test_display_format_works_without_i18n
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%n#{NBSP}%u"
+
+    without_i18n { assert_equal "12.50#{NBSP}€", Amount.of_eur("12.5").ui }
+  end
+
+  def test_undecorated_output_is_the_number_alone
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "[%u] %n"
+
+    assert_equal "12.50", Amount.of_eur("12.5").ui(decorated: false)
+  end
+
+  def test_empty_label_renders_the_number_alone
+    Amount.register :BARE, decimals: 0, display_symbol: "", display_format: "%n %u"
+
+    assert_equal "7", Amount.of_bare(7).ui
+  end
+
+  def test_wire_format_ignores_display_format
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%u%n"
+
+    assert_equal "EUR|12.50", Amount.of_eur("12.5").to_s
+  end
+
+  # Locale templates for a type
+
+  def test_locale_without_a_template_uses_the_types_template
+    register_eur_with_german_template
+
+    assert_equal "€1,234.50", Amount.of_eur("1234.5").ui(locale: :en)
+  end
+
+  def test_locale_template_replaces_the_types_template
+    register_eur_with_german_template
+
+    assert_equal "1.234,50#{NBSP}€", Amount.of_eur("1234.5").ui(locale: :de)
+  end
+
+  def test_locale_template_keeps_the_sign_in_the_number
+    register_eur_with_german_template
+
+    assert_equal "-1.234,50#{NBSP}€", Amount.of_eur("-1234.5").ui(locale: :de)
+  end
+
+  def test_locale_template_is_ignored_when_not_localizing
+    register_eur_with_german_template
+
+    assert_equal "€1234.50", Amount.of_eur("1234.5").ui
+  end
+
+  def test_locale_template_follows_i18n_locale_when_localize_is_on
+    register_eur_with_german_template
+    Amount.localize = true
+    I18n.locale = :de
+
+    assert_equal "1.234,50#{NBSP}€", Amount.of_eur("1234.5").ui
+  end
+
+  def test_locale_template_overrides_display_position
+    I18n.backend.store_translations(:de, amounts: { formats: { usd: "%n %u" } })
+
+    assert_equal "1.500,00 $", Amount.of_usd("1500").ui(locale: :de)
+  end
+
+  def test_locale_template_uses_the_translated_label
+    Amount.register :SEARCHES, decimals: 0
+    I18n.backend.store_translations(:de, amounts: { units: { searches: "Suchen" }, formats: { searches: "%u: %n" } })
+
+    assert_equal "Suchen: 1.500", Amount.new(1500, :SEARCHES).ui(locale: :de)
+  end
+
+  def test_locale_template_without_number_is_ignored
+    register_eur_with_german_template
+    I18n.backend.store_translations(:de, amounts: { formats: { eur: "%u" } })
+
+    assert_equal "€1.234,50", Amount.of_eur("1234.5").ui(locale: :de)
+  end
+
+  # Display units
+
+  def test_display_unit_format_places_number_and_label
+    register_mass
+
+    assert_equal "1.00#{NBSP}kg", Amount.new("1", :MASS).ui(unit: :kilo)
+  end
+
+  def test_display_unit_position_still_works
+    register_mass
+
+    assert_equal "p1.00", Amount.new("1", :MASS).ui(unit: :pre)
+  end
+
+  def test_display_unit_without_template_uses_the_types
+    register_mass
+
+    assert_equal "[x] 1.00", Amount.new("1", :MASS).ui(unit: :plain)
+  end
+
+  def test_display_unit_locale_template_overrides_its_format
+    register_mass_with_german_kilo_template
+
+    assert_equal "kg 1,00", Amount.new("1", :MASS).ui(unit: :kilo, locale: :de)
+  end
+
+  def test_display_unit_locale_template_is_only_used_for_its_locale
+    register_mass_with_german_kilo_template
+
+    assert_equal "1.00#{NBSP}kg", Amount.new("1", :MASS).ui(unit: :kilo, locale: :en)
+  end
+
+  def test_display_unit_without_template_uses_the_types_locale_template
+    register_mass_with_german_type_template
+
+    assert_equal "x: 1,00", Amount.new("1", :MASS).ui(unit: :plain, locale: :de)
+  end
+
+  def test_display_unit_position_wins_over_the_types_locale_template
+    register_mass_with_german_type_template
+
+    assert_equal "p1,00", Amount.new("1", :MASS).ui(unit: :pre, locale: :de)
+  end
+
+  def test_display_unit_undecorated_output_is_the_number_alone
+    register_mass
+
+    assert_equal "1.00", Amount.new("1", :MASS).ui(unit: :kilo, decorated: false)
+  end
+
+  private
+
+  def register_eur_with_german_template
+    Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%u%n"
+    I18n.backend.store_translations(:de, amounts: { formats: { eur: "%n#{NBSP}%u" } })
+  end
+
+  def register_mass
+    Amount.register :MASS, decimals: 2, display_symbol: "mass", display_format: "[%u] %n", display_units: {
+      kilo: { scale: 1, symbol: "kg", format: "%n#{NBSP}%u" },
+      pre: { scale: 1, symbol: "p", position: :prefix },
+      plain: { scale: 1, symbol: "x" }
+    }
+  end
+
+  def register_mass_with_german_kilo_template
+    register_mass
+    I18n.backend.store_translations(:de, amounts: { display_unit_formats: { mass: { kilo: "%u %n" } } })
+  end
+
+  def register_mass_with_german_type_template
+    register_mass
+    I18n.backend.store_translations(:de, amounts: { formats: { mass: "%u: %n" } })
+  end
+
+  def register_plural_searches_with_template
+    Amount.register :SEARCHES, decimals: 0,
+                               display_symbol: { one: "search", other: "searches" },
+                               display_format: "%u: %n"
+  end
+end

data/test/amount/concerns/localizable_test.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+require_relative "../../support/locale_test_setup"
+
+class AmountLocalizableTest < Minitest::Test
+  include LocaleTestSetup
+
+  def test_localize_defaults_to_false
+    refute_predicate Amount, :localize?
+  end
+
+  def test_setting_localize_true_makes_localize_predicate_true
+    Amount.localize = true
+
+    assert_predicate Amount, :localize?
+  end
+
+  def test_localize_is_an_alias_of_localize_predicate
+    assert_equal :localize?, Amount.method(:localize).original_name
+  end
+
+  { "false" => false, "nil" => nil }.each do |name, value|
+    define_method("test_setting_localize_#{name}_makes_localize_predicate_false") do
+      Amount.localize = true
+      Amount.localize = value
+
+      assert_equal false, Amount.localize?
+    end
+  end
+
+  def test_localize_true_without_i18n_raises_when_set
+    without_i18n do
+      assert_raises(ArgumentError) { Amount.localize = true }
+    end
+  end
+
+  def test_localize_true_without_i18n_message_names_i18n
+    without_i18n do
+      assert_match(/i18n/, error_from(ArgumentError) { Amount.localize = true }.message)
+    end
+  end
+
+  def test_localize_true_without_i18n_leaves_localize_off
+    without_i18n do
+      error_from(ArgumentError) { Amount.localize = true }
+
+      refute_predicate Amount, :localize?
+    end
+  end
+
+  def test_localize_true_without_i18n_leaves_ui_unlocalized
+    without_i18n do
+      error_from(ArgumentError) { Amount.localize = true }
+
+      assert_equal "$1500.00", Amount.of_usd("1500").ui
+    end
+  end
+end

data/test/amount/concerns/orderable_test.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+
+class AmountOrderableTest < Minitest::Test
+  def setup
+    AmountTestSupport.register_default_types!
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_zero_predicate
+    assert Amount.new(0, :USDC).zero?
+  end
+
+  def test_positive_predicate
+    assert Amount.new(1, :USDC).positive?
+  end
+
+  def test_negative_predicate
+    assert Amount.new(-1, :USDC).negative?
+  end
+
+  def test_same_type_true_for_same_symbol
+    assert Amount.new(1, :USDC).same_type?(Amount.new(2, :USDC))
+  end
+
+  def test_same_type_false_for_different_symbol
+    refute Amount.new(1, :USDC).same_type?(Amount.new(1, :SOL))
+  end
+
+  def test_same_type_false_for_non_amount
+    refute Amount.new(1, :USDC).same_type?(1)
+  end
+
+  def test_less_than_same_type
+    assert Amount.new("1", :USDC) < Amount.new("2", :USDC)
+  end
+
+  def test_greater_than_same_type
+    assert Amount.new("2", :USDC) > Amount.new("1", :USDC)
+  end
+
+  def test_equality_same_type
+    assert_equal Amount.new("1", :USDC), Amount.new("1", :USDC)
+  end
+
+  def test_greater_than_cross_type_uses_registered_rate
+    Amount.register_default_rate :USD, :USDC, 1
+
+    assert_operator Amount.new("10.00", :USDC), :>, Amount.new("5.00", :USD)
+  end
+
+  def test_spaceship_cross_type_uses_registered_rate
+    Amount.register_default_rate :USD, :USDC, 1
+
+    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_equal_amounts_are_the_same_hash_key
+    data = { Amount.new("1.5", :USDC) => :first }
+
+    assert_equal :first, data[Amount.new("1.5", :USDC)]
+  end
+
+  def test_different_symbol_is_a_different_hash_key
+    data = { Amount.new("1.5", :USDC) => :first }
+
+    assert_nil data[Amount.new("1.5", :USD)]
+  end
+end