amounts 0.0.1

data/lib/amount/registry/generated_constructors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Amount
+  class Registry
+    # Manages registry-driven constructor methods such as `Amount.usdc(...)`.
+    class GeneratedConstructors
+      METHOD_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/
+
+      def initialize(target: Amount)
+        @target = target
+        @method_names = []
+      end
+
+      def define_for(entry)
+        method_name = method_name_for(entry.symbol)
+        return unless method_name
+
+        raise_collision!(method_name)
+
+        @target.define_singleton_method(method_name) do |value, **opts|
+          resolved_entry = registry.lookup(entry.symbol)
+          resolved_entry.amount_class.new(value, entry.symbol, **opts)
+        end
+
+        @method_names << method_name.to_sym
+      end
+
+      def activate(entries)
+        entries.each_value { |entry| define_for(entry) }
+      end
+
+      def remove_all
+        @method_names.each do |method_name|
+          remove_method(method_name)
+        end
+
+        @method_names.clear
+      end
+
+      private
+
+      def method_name_for(symbol)
+        method_name = symbol.to_s.downcase
+        return unless method_name.match?(METHOD_NAME_PATTERN)
+
+        method_name
+      end
+
+      def raise_collision!(method_name)
+        return unless @target.respond_to?(method_name)
+
+        raise AlreadyRegistered, "cannot generate #{@target}.#{method_name} - method already exists"
+      end
+
+      def remove_method(method_name)
+        return unless @target.singleton_class.method_defined?(method_name)
+
+        @target.singleton_class.send(:remove_method, method_name)
+      end
+    end
+  end
+end

data/lib/amount/registry.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "thread"
+require_relative "registry/generated_constructors"
+
+class Amount
+  # Stores registered amount types and default directional conversion rates.
+  #
+  # The registry is the configuration surface of the gem. Application code
+  # normally uses the shared global instance exposed by {Amount.registry},
+  # configures it during boot, and optionally calls {#lock!} when setup is
+  # complete.
+  #
+  # @example Registering types at boot
+  #   Amount.register :USDC, decimals: 6
+  #
+  #   Amount.register :USD, decimals: 2
+  #
+  #   Amount.register_default_rate :USD, :USDC, "1"
+  #   Amount.registry.lock!
+  class Registry
+    class UnknownType < StandardError; end
+    class AlreadyRegistered < StandardError; end
+    class InvalidDisplayUnit < StandardError; end
+    class NoDefaultRate < StandardError; end
+    class RegistryLocked < StandardError; end
+
+    Entry = Struct.new(
+      :symbol, :decimals, :display_symbol, :display_position,
+      :ui_decimals, :display_units, :default_display, :amount_class,
+      keyword_init: true
+    )
+
+    def initialize
+      @entries = {}
+      @default_rates = {}
+      @generated_constructors = GeneratedConstructors.new
+      @locked = false
+      @lock = Mutex.new
+    end
+
+    # 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")`.
+    #
+    # @param symbol [Symbol, String] registered type identifier
+    # @param decimals [Integer] number of storage decimals
+    # @param display_symbol [String] symbol used by UI helpers
+    # @param display_position [Symbol] either `:prefix` or `:suffix`
+    # @param ui_decimals [Integer] decimals displayed by default UI formatting
+    # @param display_units [Hash, nil] optional display-only scaling definitions
+    # @param default_display [Symbol, nil] optional default display unit key
+    # @param class [Class, nil] optional custom `Amount` subclass
+    # @return [void]
+    # @raise [AlreadyRegistered] if the symbol is already registered or the
+    #   generated constructor would collide with an existing method
+    # @raise [RegistryLocked] if the registry has been locked
+    # @example
+    #   Amount.register :USDC,
+    #     decimals: 6,
+    #     display_symbol: "$",
+    #     display_position: :prefix,
+    #     ui_decimals: 2
+    def register(symbol, decimals:, display_symbol: symbol.to_s, display_position: :suffix,
+                 ui_decimals: decimals, display_units: nil, default_display: nil,
+                 class: nil)
+      symbol = symbol.to_sym
+
+      @lock.synchronize do
+        ensure_unlocked!
+        raise AlreadyRegistered, "#{symbol} already registered" if @entries.key?(symbol)
+
+        validate_display_units!(display_units, default_display) if display_units
+
+        entry = Entry.new(
+          symbol:,
+          decimals:,
+          display_symbol:,
+          display_position:,
+          ui_decimals:,
+          display_units:,
+          default_display:,
+          amount_class: binding.local_variable_get(:class) || Amount
+        )
+
+        @entries[symbol] = entry
+        @generated_constructors.define_for(entry)
+      end
+    end
+
+    # @param symbol [Symbol, String]
+    # @return [Boolean]
+    # @example
+    #   Amount.registry.registered?(:USDC)
+    #   # => true
+    def registered?(symbol)
+      @lock.synchronize { @entries.key?(symbol.to_sym) }
+    end
+
+    # @param symbol [Symbol, String]
+    # @return [Entry]
+    # @raise [UnknownType]
+    # @example
+    #   Amount.registry.lookup(:USDC).decimals
+    #   # => 6
+    def lookup(symbol)
+      @lock.synchronize do
+        @entries.fetch(symbol.to_sym) do
+          raise UnknownType, "#{symbol} is not registered"
+        end
+      end
+    end
+
+    # @return [Array<Symbol>]
+    # @example
+    #   Amount.registry.symbols
+    #   # => [:USDC, :USD]
+    def symbols
+      @lock.synchronize { @entries.keys }
+    end
+
+    # @return [void]
+    # @raise [RegistryLocked] if the registry has been locked
+    # @example
+    #   Amount.registry.clear!
+    def clear!
+      @lock.synchronize do
+        ensure_unlocked!
+        @generated_constructors.remove_all
+        @entries.clear
+        @default_rates.clear
+      end
+    end
+
+    # @param from [Symbol, String]
+    # @param to [Symbol, String]
+    # @param rate [String, Numeric, BigDecimal]
+    # @return [void]
+    # @raise [RegistryLocked] if the registry has been locked
+    # @example
+    #   Amount.register_default_rate :USD, :USDC, "1"
+    def register_default_rate(from, to, rate)
+      from = from.to_sym
+      to = to.to_sym
+
+      lookup(from)
+      lookup(to)
+
+      @lock.synchronize do
+        ensure_unlocked!
+        @default_rates[[from, to]] = BigDecimal(rate.to_s)
+      end
+    end
+
+    # @param from [Symbol, String]
+    # @param to [Symbol, String]
+    # @return [BigDecimal]
+    # @raise [NoDefaultRate]
+    # @example
+    #   Amount.registry.default_rate(:USD, :USDC)
+    #   # => 0.1e1
+    def default_rate(from, to)
+      @lock.synchronize do
+        @default_rates.fetch([from.to_sym, to.to_sym]) do
+          raise NoDefaultRate, "no default rate for #{from} -> #{to}; pass rate: explicitly"
+        end
+      end
+    end
+
+    # @param from [Symbol, String]
+    # @param to [Symbol, String]
+    # @return [Boolean]
+    # @example
+    #   Amount.registry.default_rate?(:USD, :USDC)
+    #   # => true
+    def default_rate?(from, to)
+      @lock.synchronize { @default_rates.key?([from.to_sym, to.to_sym]) }
+    end
+
+    # @return [void]
+    # @example Locking the global registry after initialization
+    #   Amount.registry.lock!
+    def lock!
+      @lock.synchronize do
+        @locked = true
+      end
+    end
+
+    # @return [Boolean]
+    # @example
+    #   Amount.registry.locked?
+    #   # => true
+    def locked?
+      @lock.synchronize { @locked }
+    end
+
+    # @return [void]
+    def activate_generated_methods!
+      @lock.synchronize do
+        @generated_constructors.activate(@entries)
+      end
+    end
+
+    # @return [void]
+    def remove_generated_methods!
+      @lock.synchronize do
+        @generated_constructors.remove_all
+      end
+    end
+
+    private
+
+    def ensure_unlocked!
+      raise RegistryLocked, "registry is locked" if @locked
+    end
+
+    def validate_display_units!(units, default)
+      unless units.is_a?(Hash) && !units.empty?
+        raise InvalidDisplayUnit, "display_units must be a non-empty hash"
+      end
+
+      if default && !units.key?(default)
+        raise InvalidDisplayUnit, "default_display #{default} not in display_units"
+      end
+
+      units.each do |key, spec|
+        unless spec.is_a?(Hash) && spec.key?(:scale)
+          raise InvalidDisplayUnit, "display_unit #{key} must have :scale"
+        end
+      end
+    end
+  end
+end

data/lib/amount/rspec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../amount"
+require "rspec/expectations"
+require_relative "rspec_support"
+require_relative "rspec_matchers"
+
+# Opt-in RSpec matchers for `Amount`.
+#
+# Applications enable these matchers explicitly in their spec helper:
+#
+# @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")
+Amount::RSpecMatchers.define_amount_equality_matcher(:eq_amount) do |*expected_arguments|
+  Amount::RSpecSupport.coerce_amount_arguments(expected_arguments)
+end
+
+Amount::RSpecMatchers.define_amount_type_matcher
+Amount::RSpecMatchers.define_amount_predicate_matcher(:be_zero_amount, "a zero Amount", &:zero?)
+Amount::RSpecMatchers.define_amount_predicate_matcher(:be_positive_amount, "a positive Amount", &:positive?)
+Amount::RSpecMatchers.define_amount_predicate_matcher(:be_negative_amount, "a negative Amount", &:negative?)
+Amount::RSpecMatchers.define_approximate_amount_matcher

data/lib/amount/rspec_matchers.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+class Amount
+  # Internal matcher helpers for the opt-in RSpec integration.
+  module RSpecMatchers
+    module_function
+
+    def define_amount_equality_matcher(name, &expected_builder)
+      RSpec::Matchers.define name do |*arguments|
+        match do |actual|
+          @expected = instance_exec(*arguments, &expected_builder)
+          actual.is_a?(Amount) && actual == @expected
+        end
+
+        failure_message do |actual|
+          return "expected #{actual.inspect} to be an Amount equal to #{@expected.inspect}" unless actual.is_a?(Amount)
+
+          "expected #{actual.inspect} to equal amount #{@expected.inspect}"
+        end
+      end
+    end
+
+    def define_amount_predicate_matcher(name, description, &predicate)
+      RSpec::Matchers.define name do
+        match do |actual|
+          actual.is_a?(Amount) && instance_exec(actual, &predicate)
+        end
+
+        failure_message do |actual|
+          "expected #{actual.inspect} to be #{description}"
+        end
+      end
+    end
+
+    def define_amount_type_matcher
+      RSpec::Matchers.define :be_amount_of do |expected_symbol|
+        match do |actual|
+          @expected_symbol = expected_symbol.to_sym
+          actual.is_a?(Amount) && actual.symbol == @expected_symbol
+        end
+
+        failure_message do |actual|
+          "expected #{actual.inspect} to be an Amount of #{@expected_symbol}"
+        end
+      end
+    end
+
+    def define_approximate_amount_matcher
+      RSpec::Matchers.define :be_approximately_amount do |*expected_arguments, within:|
+        match do |actual|
+          @expected = Amount::RSpecSupport.coerce_amount_arguments(expected_arguments)
+          @within = Amount::RSpecSupport.coerce_delta(@expected, within)
+
+          actual.is_a?(Amount) &&
+            actual.same_type?(@expected) &&
+            @within.same_type?(@expected) &&
+            (actual - @expected).abs.atomic <= @within.atomic
+        end
+
+        failure_message do |actual|
+          return "expected #{actual.inspect} to be an Amount within #{@within.inspect} of #{@expected.inspect}" unless actual.is_a?(Amount)
+
+          "expected #{actual.inspect} to be within #{@within.inspect} of #{@expected.inspect}"
+        end
+      end
+    end
+
+    def define_amount_column_matcher
+      RSpec::Matchers.define :have_amount_column do |name, *expected_arguments|
+        match do |record|
+          @name = name
+          @expected = Amount::RSpecSupport.coerce_amount_arguments(expected_arguments)
+          @definition = record.class.amount_attribute_definitions.fetch(name.to_sym)
+
+          @definition.read(record) == @expected &&
+            record.public_send(@definition.atomic_column).to_i == @expected.atomic &&
+            (@definition.fixed_symbol? ||
+              record.public_send(@definition.symbol_column) == @expected.symbol.to_s)
+        end
+
+        failure_message do |record|
+          "expected #{record.inspect} to have #{@name} column matching #{@expected.inspect}"
+        end
+      end
+    end
+
+    def define_amount_sum_matcher
+      RSpec::Matchers.define :match_amounts do |expected_hash|
+        match do |actual_hash|
+          @expected = expected_hash.to_h do |symbol, value|
+            amount = Amount.new(value, symbol)
+            [amount.symbol, amount]
+          end
+          @actual = Amount::RSpecSupport.normalize_amount_sums(actual_hash)
+
+          @actual == @expected
+        end
+
+        failure_message do |_actual_hash|
+          "expected grouped amounts #{@actual.inspect} to match #{@expected.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/amount/rspec_support.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class Amount
+  # Shared coercion helpers for opt-in RSpec integrations.
+  module RSpecSupport
+    module_function
+
+    def coerce_amount_arguments(arguments)
+      case arguments.length
+      when 1
+        coerce_amount(arguments.first)
+      when 2
+        Amount.new(arguments.last, arguments.first)
+      else
+        raise ArgumentError, "expected an Amount, a parse string, or a symbol/value pair"
+      end
+    end
+
+    def coerce_amount(value)
+      case value
+      when Amount then value
+      when String then Amount.parse(value)
+      when Hash then Amount.load(value)
+      else
+        raise ArgumentError, "cannot coerce #{value.inspect} into an Amount"
+      end
+    end
+
+    def coerce_delta(expected_amount, within)
+      case within
+      when Amount
+        within
+      when Integer, Float, BigDecimal, Rational, String
+        Amount.new(within, expected_amount.symbol)
+      else
+        raise ArgumentError, "cannot coerce #{within.inspect} into an amount delta"
+      end
+    end
+
+    def normalize_amount_sums(sum_hash)
+      sum_hash.to_h do |symbol, atomic|
+        amount = Amount.new(atomic, symbol, from: :atomic)
+        [amount.symbol, amount]
+      end
+    end
+  end
+end

data/lib/amount/serializer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Amount
+  # Converts amounts to and from the versioned hash payload.
+  class Serializer
+    VERSION = 1
+
+    def self.dump(amount)
+      {
+        v: VERSION,
+        atomic: amount.atomic.to_s,
+        symbol: amount.symbol.to_s
+      }
+    end
+
+    def self.load(payload)
+      version = payload[:v] || payload["v"]
+      validate_version!(version)
+
+      Amount.new(
+        payload.fetch(:atomic) { payload.fetch("atomic") },
+        payload.fetch(:symbol) { payload.fetch("symbol") },
+        from: :atomic
+      )
+    end
+
+    def self.validate_version!(version)
+      return if version.nil? || version == VERSION
+
+      raise InvalidInput, "unsupported amount serialization version: #{version}"
+    end
+
+    private_class_method :validate_version!
+  end
+end

data/lib/amount/version.rb

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