amounts 0.0.1

data/lib/amount.rb

@@ -0,0 +1,494 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "forwardable"
+
+require_relative "amount/version"
+require_relative "amount/registry"
+require_relative "amount/display"
+require_relative "amount/parser"
+require_relative "amount/serializer"
+
+# Represents a precise quantity of a registered fungible type.
+#
+# `Amount` stores its value as an arbitrary-precision atomic `Integer` in the
+# smallest unit configured for the registered symbol. UI values are parsed from
+# strings or decimals, while integer inputs are treated as atomic counts unless
+# `from:` overrides inference.
+#
+# @example Constructing from a UI value
+#   Amount.register :USDC, decimals: 6
+#
+#   Amount.usdc("1.50").atomic
+#   # => 1500000
+#
+# @example Constructing from an atomic value
+#   Amount.usdc(1_500_000, from: :atomic).decimal.to_s("F")
+#   # => "1.5"
+class Amount
+  include Comparable
+  extend Forwardable
+
+  class Error < StandardError; end
+  class TypeMismatch < Error; end
+  class InvalidInput < Error; end
+  class UnregisteredType < Error; end
+
+  class << self
+    # @return [Amount::Registry]
+    # @example Accessing the shared registry
+    #   Amount.registry.locked?
+    #   # => false
+    def registry
+      Amount.instance_variable_get(:@registry) ||
+        replace_registry(Registry.new)
+    end
+
+    # @param symbol [Symbol, String]
+    # @param opts [Hash]
+    # @return [void]
+    # @example Registering a type
+    #   Amount.register :USDC,
+    #     decimals: 6,
+    #     display_symbol: "$",
+    #     display_position: :prefix,
+    #     ui_decimals: 2
+    def register(symbol, **opts)
+      registry.register(symbol, **opts)
+    end
+
+    # @param from [Symbol, String]
+    # @param to [Symbol, String]
+    # @param rate [String, Numeric, BigDecimal]
+    # @return [void]
+    # @example Registering a directional default rate
+    #   Amount.register_default_rate :USD, :USDC, "1"
+    def register_default_rate(from, to, rate)
+      registry.register_default_rate(from, to, rate)
+    end
+
+    # Parses the compact client-facing string representation.
+    #
+    # Accepts either the default form `SYMBOL|amount` or the explicit versioned
+    # form `v1:SYMBOL|amount`.
+    #
+    # @param str [String]
+    # @return [Amount]
+    # @raise [InvalidInput]
+    # @example Parsing the default compact format
+    #   Amount.parse("USDC|1.50")
+    #
+    # @example Parsing the explicit versioned compact format
+    #   Amount.parse("v1:USDC|1.50")
+    def parse(str)
+      Parser.new(str).parse
+    end
+
+    # Temporarily swaps the global registry. Intended for tests.
+    #
+    # @param registry [Amount::Registry]
+    # @yield
+    # @return [Object]
+    # @example Using a temporary registry
+    #   test_registry = Amount::Registry.new
+    #   Amount.with_registry(test_registry) do
+    #     Amount.register :TEST, decimals: 2
+    #   end
+    def with_registry(registry)
+      original = Amount.instance_variable_get(:@registry)
+      replace_registry(registry)
+      yield
+    ensure
+      replace_registry(original)
+    end
+
+    private
+
+    def replace_registry(registry)
+      current = Amount.instance_variable_get(:@registry)
+      current&.remove_generated_methods!
+      Amount.instance_variable_set(:@registry, registry)
+      registry&.activate_generated_methods!
+      registry
+    end
+  end
+
+  attr_reader :atomic, :symbol
+
+  # Creates an amount for a registered symbol.
+  #
+  # Input inference rules:
+  # - `Integer` => atomic units
+  # - `String` => UI decimal value
+  # - `Float`, `BigDecimal`, `Rational` => UI decimal value
+  # - `from:` overrides inference explicitly
+  #
+  # @param value [Integer, String, Float, BigDecimal, Rational]
+  # @param symbol [Symbol, String] registered type identifier
+  # @param from [Symbol, nil] one of `:atomic`, `:ui`, or `:float`
+  # @raise [Amount::Registry::UnknownType] if the symbol is not registered
+  # @raise [InvalidInput] if the value cannot be interpreted for the symbol
+  # @example Integer inputs are atomic by default
+  #   Amount.new(1_500_000, :USDC).decimal.to_s("F")
+  #   # => "1.5"
+  #
+  # @example String inputs are UI values by default
+  #   Amount.new("1.50", :USDC).atomic
+  #   # => 1500000
+  def initialize(value, symbol, from: nil)
+    @symbol = symbol.to_sym
+    @entry = self.class.registry.lookup(@symbol)
+
+    if @entry.amount_class != self.class && @entry.amount_class != Amount
+      raise InvalidInput, "use #{@entry.amount_class}.new for #{@symbol}" unless instance_of?(@entry.amount_class)
+    end
+
+    @atomic = infer_value(from, value)
+  end
+
+  # @return [Amount::Registry::Entry]
+  # @example Accessing display configuration for this amount
+  #   Amount.usdc("1").registry_entry.ui_decimals
+  #   # => 2
+  def registry_entry
+    @entry
+  end
+
+  # @return [Integer]
+  # @example Reading the registered storage precision
+  #   Amount.usdc("1").decimals
+  #   # => 6
+  def decimals
+    @entry.decimals
+  end
+
+  # @return [BigDecimal]
+  # @example Converting the atomic value back to a decimal quantity
+  #   Amount.usdc(1_500_000, from: :atomic).decimal.to_s("F")
+  #   # => "1.5"
+  def decimal
+    BigDecimal(@atomic) / (BigDecimal(10)**decimals)
+  end
+
+  # @return [Amount::Display]
+  # @example Delegating formatting concerns
+  #   Amount.usdc("1.50").display.ui
+  #   # => "$1.50"
+  def display
+    @display ||= Display.new(self)
+  end
+
+  def_delegators :display, :formatted, :ui, :to_s, :in_unit
+
+  # @return [String]
+  # @example Console-friendly inspection
+  #   Amount.usdc("1.50").inspect
+  #   # => "#<Amount USDC $1.50>"
+  def inspect
+    "#<#{self.class} #{symbol} #{ui}>"
+  end
+
+  # @return [Boolean]
+  # @example
+  #   Amount.usdc(0, from: :atomic).zero?
+  #   # => true
+  def zero? = @atomic.zero?
+
+  # @return [Boolean]
+  # @example
+  #   Amount.usdc("1").positive?
+  #   # => true
+  def positive? = @atomic.positive?
+
+  # @return [Boolean]
+  # @example
+  #   Amount.usdc("-1").negative?
+  #   # => true
+  def negative? = @atomic.negative?
+
+  # @param other [Object]
+  # @return [Boolean]
+  # @example
+  #   Amount.usdc("1").same_type?(Amount.usdc("2"))
+  #   # => true
+  def same_type?(other)
+    other.is_a?(Amount) && other.symbol == symbol
+  end
+
+  # @return [Amount]
+  # @example
+  #   Amount.usdc("-1").abs
+  #   # => #<Amount USDC $1.00>
+  def abs
+    build(@atomic.abs)
+  end
+
+  # @return [Amount]
+  # @example
+  #   -Amount.usdc("1")
+  #   # => #<Amount USDC -$1.00>
+  def -@
+    build(-@atomic)
+  end
+
+  # @param other [Amount]
+  # @return [Amount]
+  # @raise [TypeMismatch]
+  # @example Same-type addition
+  #   Amount.usdc("1.50") + Amount.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)
+  def +(other)
+    rhs = coerce_other_to_self_type!(other)
+    build(@atomic + rhs.atomic)
+  end
+
+  # @param other [Amount]
+  # @return [Amount]
+  # @raise [TypeMismatch]
+  # @example
+  #   Amount.usdc("2.00") - Amount.usdc("0.50")
+  def -(other)
+    rhs = coerce_other_to_self_type!(other)
+    build(@atomic - rhs.atomic)
+  end
+
+  # @param scalar [Numeric]
+  # @return [Amount]
+  # @raise [TypeMismatch]
+  # @example
+  #   Amount.usdc("1.25") * 2
+  def *(scalar)
+    ensure_scalar!(scalar)
+    build((BigDecimal(@atomic) * BigDecimal(scalar.to_s)).to_i)
+  end
+
+  # @param other [Amount, Numeric]
+  # @return [Amount, BigDecimal]
+  # @raise [TypeMismatch, ZeroDivisionError]
+  # @example Dividing by a scalar returns an amount
+  #   Amount.usdc("1.00") / 2
+  #
+  # @example Dividing by an amount returns a ratio
+  #   Amount.usdc("10.00") / Amount.usdc("2.00")
+  def /(other)
+    if other.is_a?(Amount)
+      ensure_same_type!(other)
+      raise ZeroDivisionError if other.zero?
+
+      BigDecimal(@atomic) / BigDecimal(other.atomic)
+    else
+      ensure_scalar!(other)
+      raise ZeroDivisionError if other.zero?
+
+      build((BigDecimal(@atomic) / BigDecimal(other.to_s)).to_i)
+    end
+  end
+
+  # Splits into equal parts and returns the leftover explicitly.
+  #
+  # @param n [Integer]
+  # @return [Array<(Array<Amount>, Amount)>]
+  # @raise [ArgumentError] if `n` is not a positive integer
+  # @example
+  #   parts, remainder = Amount.new(10, :LOGS).split(3)
+  #   parts.map(&:atomic)
+  #   # => [3, 3, 3]
+  #   remainder.atomic
+  #   # => 1
+  def split(n)
+    raise ArgumentError, "n must be positive" unless n.is_a?(Integer) && n.positive?
+
+    sign = atomic_sign
+    base, remainder = @atomic.abs.divmod(n)
+    parts = Array.new(n) { build(sign * base) }
+
+    [parts, build(sign * remainder)]
+  end
+
+  # Allocates proportionally by integer weights and returns the leftover explicitly.
+  #
+  # @param weights [Array<Integer>]
+  # @return [Array<(Array<Amount>, Amount)>]
+  # @raise [ArgumentError] if weights are empty, negative, or sum to zero
+  # @example
+  #   parts, remainder = Amount.new(10, :LOGS).allocate([1, 1, 2])
+  #   parts.map(&:atomic)
+  #   # => [2, 2, 5]
+  #   remainder.atomic
+  #   # => 1
+  def allocate(weights)
+    raise ArgumentError, "weights must be non-empty" if weights.empty?
+    raise ArgumentError, "weights must be non-negative integers" unless weights.all? { |weight| weight.is_a?(Integer) && weight >= 0 }
+
+    total = weights.sum
+    raise ArgumentError, "weights must sum to positive value" unless total.positive?
+
+    sign = atomic_sign
+    absolute_atomic = @atomic.abs
+    allocations = weights.map { |weight| absolute_atomic * weight / total }
+    remainder = absolute_atomic - allocations.sum
+
+    parts = allocations.map { |allocation| build(sign * allocation) }
+    [parts, build(sign * remainder)]
+  end
+
+  # @param other [Object]
+  # @return [-1, 0, 1, nil]
+  # @example
+  #   Amount.usdc("1") <=> Amount.usdc("2")
+  #   # => -1
+  def <=>(other)
+    return nil unless other.is_a?(Amount)
+
+    comparable = coerce_other_to_self_type(other)
+    return nil unless comparable
+
+    @atomic <=> comparable.atomic
+  end
+
+  # @param other [Object]
+  # @return [Boolean]
+  # @example
+  #   Amount.usdc("1.50") == Amount.usdc("1.50")
+  #   # => true
+  def ==(other)
+    same_type?(other) && @atomic == other.atomic
+  end
+
+  # @param other [Object]
+  # @return [Boolean]
+  # @example Hash-key equality keeps class and symbol identity
+  #   Amount.usdc("1").eql?(Amount.usdc("1"))
+  #   # => true
+  def eql?(other)
+    other.class == self.class && symbol == other.symbol && @atomic == other.atomic
+  end
+
+  # @return [Integer]
+  # @example
+  #   { Amount.usdc("1") => :ok }[Amount.usdc("1")]
+  #   # => :ok
+  def hash
+    [self.class, symbol, @atomic].hash
+  end
+
+  # @param target_symbol [Symbol, String]
+  # @param rate [String, Numeric, BigDecimal, nil]
+  # @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")
+  #
+  # @example Using a registered default rate
+  #   Amount.register_default_rate :USDC, :USD, "1"
+  #   Amount.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
+
+    rate = resolve_rate(target_symbol, rate)
+    target_entry = self.class.registry.lookup(target_symbol)
+
+    decimal_result = decimal * BigDecimal(rate.to_s)
+    atomic_result = (decimal_result * (BigDecimal(10)**target_entry.decimals)).to_i
+
+    target_entry.amount_class.new(atomic_result, target_symbol, from: :atomic)
+  end
+
+  # @return [Hash]
+  # @example
+  #   Amount.usdc("1.50").to_h
+  #   # => { v: 1, atomic: "1500000", symbol: "USDC" }
+  def to_h
+    Serializer.dump(self)
+  end
+
+  # @param hash [Hash]
+  # @return [Amount]
+  # @raise [InvalidInput] for unsupported serialized versions
+  # @example Loading the current versioned payload
+  #   Amount.load(v: 1, atomic: "1500000", symbol: "USDC")
+  #
+  # @example Loading the legacy unversioned payload
+  #   Amount.load(atomic: 1500000, symbol: :USDC)
+  def self.load(hash)
+    Serializer.load(hash)
+  end
+
+  private
+
+  def build(atomic_value)
+    self.class.new(atomic_value, symbol, from: :atomic)
+  end
+
+  def atomic_sign
+    return 1 if @atomic.positive?
+    return(-1) if @atomic.negative?
+
+    0
+  end
+
+  def ensure_same_type!(other)
+    return if same_type?(other)
+
+    raise TypeMismatch, "type mismatch: #{symbol} vs #{other.is_a?(Amount) ? other.symbol : other.class}"
+  end
+
+  def ensure_scalar!(value)
+    return if value.is_a?(Integer) || value.is_a?(Float) ||
+              value.is_a?(BigDecimal) || value.is_a?(Rational)
+
+    raise TypeMismatch, "expected scalar, got #{value.class}"
+  end
+
+  def resolve_rate(target, provided)
+    return provided if provided
+
+    self.class.registry.default_rate(symbol, target)
+  end
+
+  def infer_value(from, value)
+    case from || infer_type(value)
+    when :atomic then value.to_i
+    when :ui then ui_to_atomic(value)
+    when :float then ui_to_atomic(value.to_s)
+    else
+      raise InvalidInput, "unknown amount format: #{value.inspect}"
+    end
+  end
+
+  def infer_type(value)
+    case value
+    when Integer then :atomic
+    when String then :ui
+    when Float, BigDecimal, Rational then :float
+    else
+      raise InvalidInput, "cannot infer type for #{value.class}"
+    end
+  end
+
+  def ui_to_atomic(value)
+    (BigDecimal(value.to_s) * (BigDecimal(10)**decimals)).to_i
+  rescue ArgumentError
+    raise InvalidInput, "cannot parse #{value.inspect} as #{symbol}"
+  end
+
+  def coerce_other_to_self_type!(other)
+    coerce_other_to_self_type(other) || raise(
+      TypeMismatch,
+      "type mismatch: #{symbol} vs #{other.is_a?(Amount) ? other.symbol : other.class}"
+    )
+  end
+
+  def coerce_other_to_self_type(other)
+    return other if same_type?(other)
+    return unless other.is_a?(Amount)
+
+    other.to(symbol)
+  rescue Registry::NoDefaultRate
+    nil
+  end
+end

data/test/dummy/app/models/holding.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Holding < ActiveRecord::Base
+  has_amount :amount
+  has_amount :fee, symbol: :SOL
+  has_amount :reserve
+end

data/test/dummy/bin/rails

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../../../Gemfile", __dir__)
+ENV["RAILS_ENV"] ||= "test"
+
+require "bundler/setup"
+require "rails/commands"

data/test/dummy/config/application.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_model/railtie"
+require "active_record/railtie"
+
+module Dummy
+  class Application < Rails::Application
+    config.root = File.expand_path("..", __dir__)
+    config.eager_load = false
+    config.secret_key_base = "amounts-test-secret-key-base"
+    config.hosts.clear
+    config.active_support.deprecation = :stderr
+  end
+end

data/test/dummy/config/database.yml

@@ -0,0 +1,11 @@
+default: &default
+  adapter: postgresql
+  encoding: unicode
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5) %>
+  url: <%= ENV.fetch("AMOUNTS_POSTGRES_URL", "postgresql://localhost/amounts_test") %>
+
+development:
+  <<: *default
+
+test:
+  <<: *default

data/test/dummy/config/environment.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../../Gemfile", __dir__)
+
+require_relative "application"
+Dummy::Application.initialize!

data/test/dummy/db/schema.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+ActiveRecord::Schema.define(version: 1) do
+  create_table :holdings, force: true do |t|
+    t.amount :amount, null: true
+    t.amount :fee, symbol: :SOL, null: true
+    t.amount :reserve, precision: 40, default: "USDC|1.25", null: false
+  end
+end

data/test/postgresql_integration_test.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+begin
+  require "pg"
+rescue LoadError
+  # Handled in setup.
+end
+
+ENV["RAILS_ENV"] = "test"
+
+require_relative "dummy/config/environment"
+require "active_record/tasks/database_tasks"
+
+class PostgreSQLIntegrationTest < Minitest::Test
+  def setup
+    skip "pg gem is not installed" unless defined?(PG)
+    skip "set AMOUNTS_POSTGRES_URL to run PostgreSQL integration tests" unless ENV["AMOUNTS_POSTGRES_URL"]
+
+    AmountTestSupport.register_active_record_types!
+    configure_database_tasks
+    recreate_schema!
+    Holding.delete_all
+  rescue PG::Error, ActiveRecord::ConnectionNotEstablished => error
+    skip "PostgreSQL is unavailable: #{error.message}"
+  end
+
+  def teardown
+    Amount.registry.clear!
+  end
+
+  def test_postgresql_round_trips_large_atomic_values_exactly
+    huge_atomic = 10**30
+    holding = Holding.create!(amount: Amount.new(huge_atomic, :SOL, from: :atomic))
+
+    assert_equal huge_atomic, holding.reload.amount.atomic
+  end
+
+  def test_postgresql_uses_numeric_precision_for_amount_columns
+    columns = Holding.columns_hash
+
+    assert_equal 78, columns.fetch("amount_atomic").precision
+    assert_equal 0, columns.fetch("amount_atomic").scale
+    assert_equal 40, columns.fetch("reserve_atomic").precision
+    assert_equal 0, columns.fetch("reserve_atomic").scale
+  end
+
+  def test_postgresql_where_and_group_queries_work_with_amount_columns
+    usdc = Holding.create!(amount: "USDC|1.50")
+    Holding.create!(amount: "USD|3.00")
+
+    assert_equal [usdc.id], Holding.where_amount("USDC|1.50").pluck(:id)
+    assert_equal({ "USDC" => 1_500_000, "USD" => 300 }, Holding.group(:amount_symbol).sum(:amount_atomic))
+  end
+
+  private
+
+  def configure_database_tasks
+    ActiveRecord::Tasks::DatabaseTasks.database_configuration = Rails.application.config.database_configuration
+    ActiveRecord::Tasks::DatabaseTasks.db_dir = File.expand_path("dummy/db", __dir__)
+    ActiveRecord::Tasks::DatabaseTasks.env = "test"
+    ActiveRecord::Tasks::DatabaseTasks.root = File.expand_path("dummy", __dir__)
+  end
+
+  def recreate_schema!
+    ActiveRecord::Base.establish_connection(:test)
+    load File.expand_path("dummy/db/schema.rb", __dir__)
+    Holding.reset_column_information
+  end
+end

data/test/support/amount_test_support.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require_relative "../../lib/amount"
+
+module AmountTestSupport
+  module_function
+
+  def register_default_types!
+    Amount.registry.clear!
+    Amount.register :USDC, decimals: 6, display_symbol: "$",
+                    display_position: :prefix, ui_decimals: 2
+    Amount.register :USD, decimals: 2, display_symbol: "$",
+                    display_position: :prefix, ui_decimals: 2
+    Amount.register :SOL, decimals: 9, display_symbol: "SOL",
+                    display_position: :suffix, ui_decimals: 4
+    Amount.register :GOLD, decimals: 8, display_symbol: "oz t",
+                     display_position: :suffix, ui_decimals: 4,
+                     display_units: {
+                       oz_t: { scale: 1, symbol: "oz t", ui_decimals: 4 },
+                       gram: { scale: "31.1035", symbol: "g", ui_decimals: 2 },
+                       kg: { scale: "0.0311035", symbol: "kg", ui_decimals: 5 }
+                     },
+                     default_display: :oz_t
+    Amount.register :LOGS, decimals: 0, display_symbol: "logs",
+                    display_position: :suffix, ui_decimals: 0
+  end
+
+  def register_active_record_types!
+    Amount.registry.clear!
+    Amount.register :USDC, decimals: 6, display_symbol: "$",
+                    display_position: :prefix, ui_decimals: 2
+    Amount.register :USD, decimals: 2, display_symbol: "$",
+                    display_position: :prefix, ui_decimals: 2
+    Amount.register :SOL, decimals: 9, display_symbol: "SOL",
+                    display_position: :suffix, ui_decimals: 4
+  end
+end