amounts 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8169dc3622ec4944cf900418dac855398a8f1ab1dcf59c07a7d839ace60e205
-  data.tar.gz: 6e2d1b8adcaae026bbe777be07f615ec7f7f2c8902e90c6b59e25a0210417b4b
+  metadata.gz: c850c2cdba4add1e09b4d6b5bfe0d1d45ffd9002924a24f5ad59e63a9f4ca513
+  data.tar.gz: bd146211750f51dc54e3967a3f2937eea48334cc88f1c0480b48f199c038e7fa
 SHA512:
-  metadata.gz: 8afe516fe8c082748e669faa6db55f780a59b8b51948780fb5c23615ac417c830227a447393f5c33393249bbe4b10b40012ee8e090109cfeaf6ca366b197c87e
-  data.tar.gz: 984d7e60a58d97dd6b3fed6ba40845bcaa66f2e6bc72e3a2bf36e80880886743ae38217f26efd84a048c7b31d2682b11d993620bd97b6c9dd8901f92e5c29c0c
+  metadata.gz: ff1b3637f8a8df2b98a8c64975f1f0eef01f876bf8239b36a097624a3cc7218477da32d7dc95d26d22f11a83068dabf2306195480efc1d9f65007e01e3308ef1
+  data.tar.gz: 947b9a81380612ca2b0f4ccd234936fca76f479bed1be42096a45715a1cd59fb80ead76089b4cb0c8120f8bf1d8fbe3b26c88c9a9860c39265d0f2bcbc1719da

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.0.8 - 2026-05-05
+
+### Changed
+
+- **Breaking:** Generated constructors now have an `of_` prefix:
+  `Amount.usdc("1.50")` becomes `Amount.of_usdc("1.50")`, `Amount.gold("1.0")`
+  becomes `Amount.of_gold("1.0")`, and so on. Every generated constructor on
+  `Amount` is renamed; only the registered symbol stays the same, so
+  `Amount.new("1.50", :USDC)` still works.
+- The original naming was a latent footgun: any short ISO/symbol code that
+  happened to match a method already defined on `Object` (`try`, `then`,
+  `tap`, `send`, `display`, `format`, ...) would raise
+  `Amount::Registry::AlreadyRegistered` at boot. The first reported
+  manifestation was `:TRY` (Turkish Lira) under Rails, where ActiveSupport's
+  `Object#try` made the gem unusable for any application that needed to
+  denominate amounts in Turkish Lira.
+- The collision check in `GeneratedConstructors#raise_collision!` is kept as
+  a defensive backstop, but with the `of_` prefix it should never fire in
+  practice.
+
+### Migration
+
+Search-and-replace `Amount.<symbol>(` with `Amount.of_<symbol>(` across your
+codebase. Any place that builds an `Amount` from a registered symbol uses one
+of the generated constructors; everywhere else (`Amount.new`,
+`Amount.parse`, `Amount.register`, `Amount.registry`, `Amount.with_registry`)
+is unchanged.
+
 ## 0.0.7 - 2026-05-03
 
 ### Fixed
@@ -38,7 +66,7 @@
   numeric string without the `display_symbol` prefix or suffix. Useful when
   the caller renders the currency label separately (e.g. in a column header
   or chip). Composes with `unit:` and `direction:` — for example,
-  `Amount.gold("1").ui(unit: :gram, decorated: false)` returns `"31.10"`.
+  `Amount.of_gold("1").ui(unit: :gram, decorated: false)` returns `"31.10"`.
   Default remains `decorated: true`, so existing callers see no change.
 
 ## 0.0.4 - 2026-04-26

data/README.md

@@ -60,7 +60,7 @@ Amount.register :USD,
 
 Amount.register_default_rate :USD, :USDC, 1
 
-usdc = Amount.usdc("10.00")
+usdc = Amount.of_usdc("10.00")
 usd = Amount.new("5.00", :USD)
 
 (usdc + usd).ui
@@ -90,7 +90,7 @@ Construction rules:
 - `String` defaults to UI decimal values
 - `Float`, `BigDecimal`, and `Rational` are treated as decimal UI values
 - `from: :atomic`, `:ui`, or `:float` overrides inference
-- registering `:USDC` also defines `Amount.usdc(...)` when the symbol is a valid Ruby method name
+- registering `:USDC` also defines `Amount.of_usdc(...)` when the symbol is a valid Ruby method name
 
 ### Registry
 
@@ -173,7 +173,7 @@ remainder.atomic     # => -1
 ```ruby
 Amount.new(1_500_000, :USDC)
 Amount.new("1.50", :USDC)
-Amount.usdc("1.50")
+Amount.of_usdc("1.50")
 Amount.parse("USDC|1.50")
 Amount.load(atomic: 1_500_000, symbol: :USDC)
 ```

data/lib/amount/active_record/railtie.rb

@@ -8,7 +8,7 @@ class Amount
       end
 
       generators do
-        require_relative "../../../generators/amount/active_record/registry_generator"
+        require_relative "../../generators/amount/active_record/registry_generator"
       end
     end
   end

data/lib/amount/arithmetic.rb

@@ -9,7 +9,7 @@ class Amount
   module Arithmetic
     # @return [Amount]
     # @example
-    #   Amount.usdc("-1").abs
+    #   Amount.of_usdc("-1").abs
     #   # => #<Amount USDC $1.00>
     def abs
       build(@atomic.abs)
@@ -17,7 +17,7 @@ class Amount
 
     # @return [Amount]
     # @example
-    #   -Amount.usdc("1")
+    #   -Amount.of_usdc("1")
     #   # => #<Amount USDC -$1.00>
     def -@
       build(-@atomic)
@@ -27,11 +27,11 @@ class Amount
     # @return [Amount]
     # @raise [TypeMismatch]
     # @example Same-type addition
-    #   Amount.usdc("1.50") + Amount.usdc("0.50")
+    #   Amount.of_usdc("1.50") + Amount.of_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)
+    #   Amount.of_usdc("10.00") + Amount.new("5.00", :USD)
     def +(other)
       rhs = coerce_other_to_self_type!(other)
       build(@atomic + rhs.atomic)
@@ -41,7 +41,7 @@ class Amount
     # @return [Amount]
     # @raise [TypeMismatch]
     # @example
-    #   Amount.usdc("2.00") - Amount.usdc("0.50")
+    #   Amount.of_usdc("2.00") - Amount.of_usdc("0.50")
     def -(other)
       rhs = coerce_other_to_self_type!(other)
       build(@atomic - rhs.atomic)
@@ -51,7 +51,7 @@ class Amount
     # @return [Amount]
     # @raise [TypeMismatch]
     # @example
-    #   Amount.usdc("1.25") * 2
+    #   Amount.of_usdc("1.25") * 2
     def *(scalar)
       ensure_scalar!(scalar)
       build((BigDecimal(@atomic) * Amount.coerce_decimal(scalar)).to_i)
@@ -61,10 +61,10 @@ class Amount
     # @return [Amount, BigDecimal]
     # @raise [TypeMismatch, ZeroDivisionError]
     # @example Dividing by a scalar returns an amount
-    #   Amount.usdc("1.00") / 2
+    #   Amount.of_usdc("1.00") / 2
     #
     # @example Dividing by an amount returns a ratio
-    #   Amount.usdc("10.00") / Amount.usdc("2.00")
+    #   Amount.of_usdc("10.00") / Amount.of_usdc("2.00")
     def /(other)
       if other.is_a?(Amount)
         ensure_same_type!(other)

data/lib/amount/comparison.rb

@@ -11,7 +11,7 @@ class Amount
     # @param other [Object]
     # @return [Boolean]
     # @example
-    #   Amount.usdc("1").same_type?(Amount.usdc("2"))
+    #   Amount.of_usdc("1").same_type?(Amount.of_usdc("2"))
     #   # => true
     def same_type?(other)
       other.is_a?(Amount) && other.symbol == symbol
@@ -19,26 +19,26 @@ class Amount
 
     # @return [Boolean]
     # @example
-    #   Amount.usdc(0, from: :atomic).zero?
+    #   Amount.of_usdc(0, from: :atomic).zero?
     #   # => true
     def zero? = @atomic.zero?
 
     # @return [Boolean]
     # @example
-    #   Amount.usdc("1").positive?
+    #   Amount.of_usdc("1").positive?
     #   # => true
     def positive? = @atomic.positive?
 
     # @return [Boolean]
     # @example
-    #   Amount.usdc("-1").negative?
+    #   Amount.of_usdc("-1").negative?
     #   # => true
     def negative? = @atomic.negative?
 
     # @param other [Object]
     # @return [-1, 0, 1, nil]
     # @example
-    #   Amount.usdc("1") <=> Amount.usdc("2")
+    #   Amount.of_usdc("1") <=> Amount.of_usdc("2")
     #   # => -1
     def <=>(other)
       return nil unless other.is_a?(Amount)
@@ -52,7 +52,7 @@ class Amount
     # @param other [Object]
     # @return [Boolean]
     # @example
-    #   Amount.usdc("1.50") == Amount.usdc("1.50")
+    #   Amount.of_usdc("1.50") == Amount.of_usdc("1.50")
     #   # => true
     def ==(other)
       same_type?(other) && @atomic == other.atomic
@@ -61,7 +61,7 @@ class Amount
     # @param other [Object]
     # @return [Boolean]
     # @example Hash-key equality keeps class and symbol identity
-    #   Amount.usdc("1").eql?(Amount.usdc("1"))
+    #   Amount.of_usdc("1").eql?(Amount.of_usdc("1"))
     #   # => true
     def eql?(other)
       other.class == self.class && symbol == other.symbol && @atomic == other.atomic
@@ -69,7 +69,7 @@ class Amount
 
     # @return [Integer]
     # @example
-    #   { Amount.usdc("1") => :ok }[Amount.usdc("1")]
+    #   { Amount.of_usdc("1") => :ok }[Amount.of_usdc("1")]
     #   # => :ok
     def hash
       [self.class, symbol, @atomic].hash

data/lib/amount/conversion.rb

@@ -12,11 +12,11 @@ class Amount
     # @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")
+    #   Amount.of_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)
+    #   Amount.of_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

data/lib/amount/display.rb

@@ -27,11 +27,11 @@ class Amount
     #   `false` overrides both.
     # @return [String]
     # @example
-    #   Amount.usdc("1.50").ui                       # => "$1.50"
-    #   Amount.usdc("1.50").ui(decorated: false)     # => "1.50"
-    #   Amount.gold("1").ui(unit: :gram)             # => "31.10 g"
-    #   Amount.gold("1").ui(unit: :gram, decorated: false)  # => "31.10"
-    #   Amount.sol("2.5").ui(trim_zeros: true)       # => "2.5 SOL"
+    #   Amount.of_usdc("1.50").ui                       # => "$1.50"
+    #   Amount.of_usdc("1.50").ui(decorated: false)     # => "1.50"
+    #   Amount.of_gold("1").ui(unit: :gram)             # => "31.10 g"
+    #   Amount.of_gold("1").ui(unit: :gram, decorated: false)  # => "31.10"
+    #   Amount.of_sol("2.5").ui(trim_zeros: true)       # => "2.5 SOL"
     def ui(unit: nil, direction: :floor, decorated: true, trim_zeros: nil)
       if unit
         render_display_unit(unit, direction, decorated:, trim_zeros:)

data/lib/amount/registry/generated_constructors.rb

@@ -2,9 +2,14 @@
 
 class Amount
   class Registry
-    # Manages registry-driven constructor methods such as `Amount.usdc(...)`.
+    # Manages registry-driven constructor methods such as `Amount.of_usdc(...)`.
+    #
+    # Generated names are prefixed with `of_` so that short ISO codes like
+    # `:TRY` (which collides with `Object#try` once ActiveSupport is loaded)
+    # do not clash with existing methods on `Amount`.
     class GeneratedConstructors
-      METHOD_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/
+      SYMBOL_PATTERN = /\A[a-z_][a-z0-9_]*\z/
+      METHOD_NAME_PREFIX = "of_"
 
       def initialize(target: Amount)
         @target = target
@@ -40,10 +45,10 @@ class Amount
       private
 
       def method_name_for(symbol)
-        method_name = symbol.to_s.downcase
-        return unless method_name.match?(METHOD_NAME_PATTERN)
+        downcased = symbol.to_s.downcase
+        return unless downcased.match?(SYMBOL_PATTERN)
 
-        method_name
+        "#{METHOD_NAME_PREFIX}#{downcased}"
       end
 
       def raise_collision!(method_name)

data/lib/amount/registry.rb

@@ -51,8 +51,9 @@ class Amount
     # Registers a new fungible type.
     #
     # When the symbol is a valid Ruby method name after downcasing, an
-    # ergonomic constructor is also generated on `Amount`, such as
-    # `Amount.usdc("1.50")`.
+    # ergonomic constructor is also generated on `Amount` with an `of_`
+    # prefix, such as `Amount.of_usdc("1.50")`. The prefix avoids collisions
+    # with existing methods like `Object#try` (added by ActiveSupport).
     #
     # @param symbol [Symbol, String] registered type identifier
     # @param decimals [Integer] number of storage decimals

data/lib/amount/rspec.rb

@@ -12,10 +12,10 @@ require_relative "rspec/matchers"
 # @example
 #   require "amount/rspec"
 #
-#   expect(Amount.usdc("1.50")).to eq_amount("USDC|1.50")
-#   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")
+#   expect(Amount.of_usdc("1.50")).to eq_amount("USDC|1.50")
+#   expect(Amount.of_usdc("1.50")).to be_amount_of(:USDC)
+#   expect(Amount.of_usdc("1.50")).to be_positive_amount
+#   expect(Amount.of_usdc("1.55")).to be_approximately_amount(:USDC, "1.50", within: "0.10")
 Amount::RSpec::Matchers.define_amount_equality_matcher(:eq_amount) do |*expected_arguments|
   Amount::RSpec::Support.coerce_amount_arguments(expected_arguments)
 end

data/lib/amount/serialization.rb

@@ -41,7 +41,7 @@ class Amount
 
     # @return [Hash]
     # @example
-    #   Amount.usdc("1.50").to_h
+    #   Amount.of_usdc("1.50").to_h
     #   # => { v: 1, atomic: "1500000", symbol: "USDC" }
     def to_h
       {

data/lib/amount/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Amount
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/lib/amount.rb

@@ -30,11 +30,11 @@ require_relative "amount/serialization"
 # @example Constructing from a UI value
 #   Amount.register :USDC, decimals: 6
 #
-#   Amount.usdc("1.50").atomic
+#   Amount.of_usdc("1.50").atomic
 #   # => 1500000
 #
 # @example Constructing from an atomic value
-#   Amount.usdc(1_500_000, from: :atomic).decimal.to_s("F")
+#   Amount.of_usdc(1_500_000, from: :atomic).decimal.to_s("F")
 #   # => "1.5"
 class Amount
   include Arithmetic
@@ -200,7 +200,7 @@ class Amount
 
   # @return [Amount::Registry::Entry]
   # @example Accessing display configuration for this amount
-  #   Amount.usdc("1").registry_entry.ui_decimals
+  #   Amount.of_usdc("1").registry_entry.ui_decimals
   #   # => 2
   def registry_entry
     @entry
@@ -208,7 +208,7 @@ class Amount
 
   # @return [Integer]
   # @example Reading the registered storage precision
-  #   Amount.usdc("1").decimals
+  #   Amount.of_usdc("1").decimals
   #   # => 6
   def decimals
     @entry.decimals
@@ -216,7 +216,7 @@ class Amount
 
   # @return [BigDecimal]
   # @example Converting the atomic value back to a decimal quantity
-  #   Amount.usdc(1_500_000, from: :atomic).decimal.to_s("F")
+  #   Amount.of_usdc(1_500_000, from: :atomic).decimal.to_s("F")
   #   # => "1.5"
   def decimal
     BigDecimal(@atomic) / (BigDecimal(10)**decimals)
@@ -226,7 +226,7 @@ class Amount
 
   # @return [String]
   # @example Console-friendly inspection
-  #   Amount.usdc("1.50").inspect
+  #   Amount.of_usdc("1.50").inspect
   #   # => "#<Amount USDC $1.50>"
   def inspect
     "#<#{self.class} #{symbol} #{ui}>"

data/test/test_amount.rb

@@ -66,31 +66,39 @@ class AmountTest < Minitest::Test
   end
 
   def test_generated_constructor_matches_new
-    assert_equal Amount.new("1.50", :USDC), Amount.usdc("1.50")
+    assert_equal Amount.new("1.50", :USDC), Amount.of_usdc("1.50")
   end
 
   def test_generated_constructor_accepts_from_keyword
-    assert_equal 1_500_000, Amount.usdc(1_500_000, from: :atomic).atomic
+    assert_equal 1_500_000, Amount.of_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")
+    assert_equal Amount.new("1.5", :OIL_WTI_BBL), Amount.of_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)
+    refute Amount.respond_to?(:of_usdc_e)
+  end
+
+  def test_generated_constructor_uses_of_prefix
+    # Without the `of_` prefix the generated method would shadow
+    # `Object#try` once ActiveSupport is loaded — see the :TRY regression.
+    Amount.register :TRY, decimals: 2
+    assert Amount.respond_to?(:of_try)
+    assert_equal Amount.new("100", :TRY), Amount.of_try("100")
   end
 
   def test_clear_removes_generated_constructor_methods
-    assert Amount.respond_to?(:usdc)
+    assert Amount.respond_to?(:of_usdc)
 
     Amount.registry.clear!
 
-    refute Amount.respond_to?(:usdc)
+    refute Amount.respond_to?(:of_usdc)
   end
 
   def test_registry_lock_prevents_mutation
@@ -105,9 +113,13 @@ class AmountTest < Minitest::Test
   end
 
   def test_constructor_collision_raises_at_registration_time
+    Amount.singleton_class.send(:define_method, :of_collide) { :existing }
+
     assert_raises(Amount::Registry::AlreadyRegistered) do
-      Amount.register :NEW, decimals: 2
+      Amount.register :COLLIDE, decimals: 2
     end
+  ensure
+    Amount.singleton_class.send(:remove_method, :of_collide) if Amount.singleton_class.method_defined?(:of_collide)
   end
 
   def test_inspect_uses_default_ui_representation
@@ -617,7 +629,7 @@ class AmountCustomClassTest < Minitest::Test
   end
 
   def test_generated_constructor_returns_subclass
-    gold = Amount.gold("1", from: :ui)
+    gold = Amount.of_gold("1", from: :ui)
 
     assert_instance_of GoldAmount, gold
     assert_equal "24k", gold.purity_estimate

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amounts
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Seb Scholl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-02 00:00:00.000000000 Z
+date: 2026-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal