amounts 0.0.1

data/lib/amount/active_record/attribute_definition.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    # Describes one `has_amount` attribute and its backing columns.
+    class AttributeDefinition
+      attr_reader :name, :type, :symbol
+
+      def initialize(name, symbol: nil)
+        @name = name.to_sym
+        @symbol = symbol&.to_sym
+        @type = Type.new(symbol: @symbol)
+      end
+
+      def fixed_symbol?
+        !@symbol.nil?
+      end
+
+      def atomic_column
+        "#{name}_atomic"
+      end
+
+      def symbol_column
+        "#{name}_symbol"
+      end
+
+      def component_columns
+        columns = [atomic_column]
+        columns << symbol_column unless fixed_symbol?
+        columns
+      end
+
+      def read(record)
+        type.deserialize(record.read_attribute(atomic_column), resolved_symbol(record))
+      end
+
+      def write(record, value)
+        if value.nil?
+          record.write_attribute(atomic_column, nil)
+          record.write_attribute(symbol_column, nil) unless fixed_symbol?
+          return nil
+        end
+
+        record.write_attribute(atomic_column, value.atomic.to_s)
+        record.write_attribute(symbol_column, value.symbol.to_s) unless fixed_symbol?
+        value
+      end
+
+      def build_from_values(values)
+        type.deserialize(values[atomic_column], fixed_symbol? ? symbol : values[symbol_column])
+      end
+
+      def query_relation(model, value)
+        amount = type.cast(value)
+        relation_for_symbol(model, amount).where(atomic_column => amount.atomic)
+      end
+
+      def greater_than_relation(model, value)
+        query_relation_with_operator(model, value, :>)
+      end
+
+      def greater_than_or_equal_relation(model, value)
+        query_relation_with_operator(model, value, :>=)
+      end
+
+      def less_than_relation(model, value)
+        query_relation_with_operator(model, value, :<)
+      end
+
+      def less_than_or_equal_relation(model, value)
+        query_relation_with_operator(model, value, :<=)
+      end
+
+      def between_relation(model, lower, upper)
+        lower_amount = type.cast(lower)
+        upper_amount = type.cast(upper)
+        ensure_same_query_symbol!(lower_amount, upper_amount)
+
+        relation_for_symbol(model, lower_amount)
+          .where("#{atomic_column} >= ? AND #{atomic_column} <= ?", lower_amount.atomic, upper_amount.atomic)
+      end
+
+      def currency_relation(model, symbol)
+        model.where(symbol_column => symbol.to_s)
+      end
+
+      def changed?(record)
+        component_columns.any? { |column| record.will_save_change_to_attribute?(column) }
+      end
+
+      def change(record)
+        return unless changed?(record)
+
+        [value_in_database(record), read(record)]
+      end
+
+      def value_in_database(record)
+        values = component_columns.to_h do |column|
+          [column, record.attribute_in_database(column)]
+        end
+
+        build_from_values(values)
+      end
+
+      def saved_change?(record)
+        component_columns.any? { |column| record.saved_change_to_attribute?(column) }
+      end
+
+      def saved_change(record)
+        return unless saved_change?(record)
+
+        [
+          build_from_values(previous_values(record, before: true)),
+          build_from_values(previous_values(record, before: false))
+        ]
+      end
+
+      def before_last_save(record)
+        saved_change(record)&.first
+      end
+
+      def validate(record)
+        add_assignment_error(record)
+
+        atomic = record.read_attribute(atomic_column)
+        return if atomic.nil? && fixed_symbol?
+
+        if fixed_symbol?
+          validate_deserialization(record, atomic, symbol)
+          return
+        end
+
+        symbol_value = record.read_attribute(symbol_column)
+        if atomic.nil? != symbol_value.nil?
+          record.errors.add(name, "must set both atomic and symbol or neither")
+          return
+        end
+
+        return if atomic.nil? && symbol_value.nil?
+
+        validate_deserialization(record, atomic, symbol_value)
+      end
+
+      private
+
+      def resolved_symbol(record)
+        fixed_symbol? ? symbol : record.read_attribute(symbol_column)
+      end
+
+      def query_relation_with_operator(model, value, operator)
+        amount = type.cast(value)
+        relation_for_symbol(model, amount)
+          .where("#{atomic_column} #{operator} ?", amount.atomic)
+      end
+
+      def relation_for_symbol(model, amount)
+        return model if fixed_symbol?
+
+        model.where(symbol_column => amount.symbol.to_s)
+      end
+
+      def ensure_same_query_symbol!(left, right)
+        return if left.symbol == right.symbol
+
+        raise ::Amount::TypeMismatch, "query bounds must use the same symbol: #{left.symbol} vs #{right.symbol}"
+      end
+
+      def previous_values(record, before:)
+        component_columns.to_h do |column|
+          change = record.saved_change_to_attribute(column)
+          value = if change
+                    change.public_send(before ? :first : :last)
+                  else
+                    record.read_attribute(column)
+                  end
+          [column, value]
+        end
+      end
+
+      def add_assignment_error(record)
+        message = record.send(:pending_amount_assignment_errors)[name]
+        record.errors.add(name, message) if message
+      end
+
+      def validate_deserialization(record, atomic, currency_value)
+        type.deserialize(atomic, currency_value)
+      rescue ::Amount::Error => error
+        record.errors.add(name, error.message)
+      end
+    end
+  end
+end

data/lib/amount/active_record/migration_methods.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    # Adds `t.amount` to migrations.
+    #
+    # Multi-symbol amounts create `*_atomic` and `*_symbol` columns. Fixed
+    # symbol amounts create only the atomic column.
+    #
+    # @example
+    #   create_table :holdings do |t|
+    #     t.amount :amount
+    #     t.amount :fee, symbol: :SOL
+    #     t.amount :reserve, precision: 40
+    #   end
+    module MigrationMethods
+      # Adds one amount attribute to the table definition.
+      #
+      # @param name [Symbol, String] logical attribute name
+      # @param precision [Integer] numeric precision for the atomic column
+      # @param symbol [Symbol, nil] fixed symbol for a single-column amount
+      # @param options [Hash] standard column options applied to the generated columns
+      # @return [void]
+      def amount(name, precision: 78, symbol: nil, **options)
+        default = options.delete(:default)
+        null = options.key?(:null) ? options[:null] : nil
+        comment = options[:comment]
+
+        defaults = normalize_defaults(default, symbol)
+
+        decimal_options = {
+          precision:,
+          scale: 0,
+          default: defaults[:atomic],
+          comment:
+        }
+        decimal_options[:null] = null unless null.nil?
+        decimal(name_to_atomic(name), **decimal_options.compact)
+
+        return if symbol
+
+        string_options = {
+          limit: 10,
+          default: defaults[:symbol],
+          comment:
+        }
+        string_options[:null] = null unless null.nil?
+        string(name_to_symbol(name), **string_options.compact)
+      end
+
+      private
+
+      def normalize_defaults(default, symbol)
+        return {} if default.nil?
+
+        type = Type.new(symbol:)
+        amount = type.cast(default)
+
+        {
+          atomic: amount.atomic.to_s,
+          symbol: symbol ? nil : amount.symbol.to_s
+        }
+      end
+
+      def name_to_atomic(name)
+        :"#{name}_atomic"
+      end
+
+      def name_to_symbol(name)
+        :"#{name}_symbol"
+      end
+    end
+  end
+end

data/lib/amount/active_record/model.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    # Provides `has_amount` for ActiveRecord models.
+    module Model
+      def has_amount(name, symbol: nil)
+        definition = AttributeDefinition.new(name, symbol:)
+        amount_attribute_definitions[definition.name] = definition
+
+        define_amount_reader(definition)
+        define_amount_writer(definition)
+        define_amount_dirty_tracking(definition)
+        define_amount_scopes(definition)
+        define_amount_validation(definition)
+      end
+
+      def amount_attribute_definitions
+        @amount_attribute_definitions ||= {}
+      end
+
+      def amount_component_columns(name)
+        amount_attribute_definition(name).component_columns
+      end
+
+      def amount_atomic_column(name)
+        amount_attribute_definition(name).atomic_column
+      end
+
+      def amount_symbol_column(name)
+        amount_attribute_definition(name).symbol_column
+      end
+
+      private
+
+      def amount_attribute_definition(name)
+        amount_attribute_definitions.fetch(name.to_sym)
+      end
+
+      def define_amount_reader(definition)
+        define_method(definition.name) do
+          definition.read(self)
+        end
+      end
+
+      def define_amount_writer(definition)
+        define_method("#{definition.name}=") do |value|
+          clear_amount_assignment_error(definition.name)
+          definition.write(self, definition.type.cast(value))
+        rescue ::Amount::Error, ArgumentError => error
+          remember_amount_assignment_error(definition.name, error.message)
+        end
+      end
+
+      def define_amount_dirty_tracking(definition)
+        define_method("#{definition.name}_changed?") do
+          definition.changed?(self)
+        end
+
+        define_method("#{definition.name}_was") do
+          definition.value_in_database(self)
+        end
+
+        define_method("#{definition.name}_change") do
+          definition.change(self)
+        end
+
+        define_method("saved_change_to_#{definition.name}?") do
+          definition.saved_change?(self)
+        end
+
+        define_method("saved_change_to_#{definition.name}") do
+          definition.saved_change(self)
+        end
+
+        define_method("#{definition.name}_before_last_save") do
+          definition.before_last_save(self)
+        end
+      end
+
+      def define_amount_scopes(definition)
+        define_method("where_#{definition.name}") do |value|
+          self.class.public_send("where_#{definition.name}", value)
+        end
+
+        scope :"where_#{definition.name}", lambda { |value|
+          definition.query_relation(self, value)
+        }
+
+        scope :"where_#{definition.name}_gt", lambda { |value|
+          definition.greater_than_relation(self, value)
+        }
+
+        scope :"where_#{definition.name}_gte", lambda { |value|
+          definition.greater_than_or_equal_relation(self, value)
+        }
+
+        scope :"where_#{definition.name}_lt", lambda { |value|
+          definition.less_than_relation(self, value)
+        }
+
+        scope :"where_#{definition.name}_lte", lambda { |value|
+          definition.less_than_or_equal_relation(self, value)
+        }
+
+        scope :"where_#{definition.name}_between", lambda { |lower, upper|
+          definition.between_relation(self, lower, upper)
+        }
+
+        return if definition.fixed_symbol?
+
+        scope :"#{definition.name}_in", lambda { |symbol|
+          definition.currency_relation(self, symbol)
+        }
+      end
+
+      def define_amount_validation(definition)
+        validate do
+          definition.validate(self)
+        end
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      def pending_amount_assignment_errors
+        @pending_amount_assignment_errors ||= {}
+      end
+
+      def remember_amount_assignment_error(name, message)
+        pending_amount_assignment_errors[name.to_sym] = message
+      end
+
+      def clear_amount_assignment_error(name)
+        pending_amount_assignment_errors.delete(name.to_sym)
+      end
+    end
+  end
+end

data/lib/amount/active_record/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "../active_record"
+require "rspec/expectations"
+require_relative "../rspec"
+
+Amount::RSpecMatchers.define_amount_column_matcher
+Amount::RSpecMatchers.define_amount_sum_matcher

data/lib/amount/active_record/type.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    # Casts user input into Amount objects for the optional ActiveRecord adapter.
+    #
+    # The type is intentionally explicit:
+    # - strings are parsed using {Amount.parse}
+    # - hashes are loaded or interpreted as value/symbol pairs
+    # - raw numerics are only accepted for fixed-symbol attributes
+    #
+    # @example Casting a multi-symbol string value
+    #   Amount::ActiveRecord::Type.new.cast("USDC|1.50")
+    #
+    # @example Casting a fixed-symbol numeric value
+    #   Amount::ActiveRecord::Type.new(symbol: :SOL).cast(0.25)
+    class Type
+      attr_reader :fixed_symbol
+
+      # @param symbol [Symbol, String, nil]
+      # @example
+      #   Amount::ActiveRecord::Type.new(symbol: :SOL)
+      def initialize(symbol: nil)
+        @fixed_symbol = symbol&.to_sym
+      end
+
+      # @param value [Amount, String, Hash, Numeric, nil]
+      # @return [Amount, nil]
+      # @raise [Amount::InvalidInput] when the value cannot be cast
+      # @raise [Amount::TypeMismatch] when a fixed-symbol assignment uses a
+      #   different symbol
+      # @example
+      #   type = Amount::ActiveRecord::Type.new
+      #   type.cast("USDC|1.50")
+      def cast(value)
+        return nil if value.nil? || value == ""
+
+        amount = case value
+                 when ::Amount then value
+                 when String then ::Amount.parse(value)
+                 when Hash then cast_hash(value)
+                 when Integer, Float, BigDecimal, Rational then cast_numeric(value)
+                 else
+                   raise ::Amount::InvalidInput, "cannot cast #{value.class} to Amount"
+                 end
+
+        ensure_fixed_symbol!(amount) if fixed_symbol
+        amount
+      end
+
+      # @param atomic [Integer, String, BigDecimal]
+      # @param symbol [Symbol, String, nil]
+      # @return [Amount, nil]
+      # @example
+      #   Amount::ActiveRecord::Type.new.deserialize("1500000", :USDC)
+      def deserialize(atomic, symbol = fixed_symbol)
+        return nil if atomic.nil?
+
+        resolved_symbol = (symbol || fixed_symbol)
+        return nil if resolved_symbol.nil?
+
+        ::Amount.new(atomic.to_i, resolved_symbol, from: :atomic)
+      end
+
+      # @param value [Amount, String, Hash, Numeric, nil]
+      # @return [Hash, nil]
+      # @example
+      #   Amount::ActiveRecord::Type.new.dump("USDC|1.50")
+      #   # => { atomic: 1500000, symbol: :USDC }
+      def dump(value)
+        amount = cast(value)
+        return nil unless amount
+
+        { atomic: amount.atomic, symbol: amount.symbol }
+      end
+
+      private
+
+      def cast_hash(value)
+        if value.key?(:atomic) || value.key?("atomic")
+          ::Amount.load(value)
+        else
+          symbol = value.fetch(:symbol) { value.fetch("symbol", fixed_symbol) }
+          amount_value = value.fetch(:value) { value.fetch("value") }
+          ::Amount.new(amount_value, symbol)
+        end
+      rescue KeyError
+        raise ::Amount::InvalidInput, "hash input must contain atomic/symbol or value/symbol"
+      end
+
+      def cast_numeric(value)
+        unless fixed_symbol
+          raise ::Amount::InvalidInput, "raw numeric assignment requires a fixed symbol"
+        end
+
+        ::Amount.new(value, fixed_symbol, from: :float)
+      end
+
+      def ensure_fixed_symbol!(amount)
+        return if amount.symbol == fixed_symbol
+
+        raise ::Amount::TypeMismatch, "expected #{fixed_symbol}, got #{amount.symbol}"
+      end
+    end
+  end
+end

data/lib/amount/active_record.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "../amount"
+require_relative "active_record/attribute_definition"
+require_relative "active_record/amount_validator"
+require_relative "active_record/type"
+require_relative "active_record/migration_methods"
+require_relative "active_record/model"
+
+class Amount
+  # Optional Rails integration for ActiveRecord models and migrations.
+  #
+  # This file is intentionally opt-in. Requiring `"amount/active_record"`
+  # extends ActiveRecord table definitions with `t.amount` and models with
+  # `has_amount`.
+  #
+  # @example Loading the integration in a Rails app
+  #   require "amount/active_record"
+  #
+  #   class Holding < ApplicationRecord
+  #     has_amount :amount
+  #     has_amount :fee, symbol: :SOL
+  #   end
+  module ActiveRecord
+    # Installs the migration DSL and model macros into ActiveRecord.
+    #
+    # This is called automatically when the file is required.
+    #
+    # @return [void]
+    def self.install!
+      ::ActiveRecord::ConnectionAdapters::TableDefinition.include(MigrationMethods)
+      if defined?(::ActiveRecord::ConnectionAdapters::Table)
+        ::ActiveRecord::ConnectionAdapters::Table.include(MigrationMethods)
+      end
+
+      ::ActiveRecord::Base.extend(Model)
+      ::ActiveRecord::Base.include(InstanceMethods)
+    end
+  end
+end
+
+Amount::ActiveRecord.install!

data/lib/amount/display.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class Amount
+  # Formats amounts for UI output without changing their type.
+  class Display
+    # @param amount [Amount]
+    def initialize(amount)
+      @amount = amount
+      @entry = amount.registry_entry
+    end
+
+    # @return [String]
+    def formatted
+      format("%.#{@entry.decimals}f", @amount.decimal)
+    end
+
+    # @param unit [Symbol, nil]
+    # @param direction [Symbol]
+    # @return [String]
+    def ui(unit: nil, direction: :floor)
+      unit ? render_display_unit(unit, direction) : render_default(direction)
+    end
+
+    # @return [String]
+    def to_s
+      "#{@entry.symbol}|#{@amount.decimal.to_s("F")}"
+    end
+
+    # @param unit [Symbol]
+    # @return [BigDecimal]
+    def in_unit(unit)
+      unit_spec = fetch_display_unit(unit)
+      @amount.decimal * BigDecimal(unit_spec[:scale].to_s)
+    end
+
+    private
+
+    def render_default(direction)
+      rounded = round(@amount.decimal, @entry.ui_decimals, direction)
+      apply_symbol(format("%.#{@entry.ui_decimals}f", rounded), @entry.display_symbol, @entry.display_position)
+    end
+
+    def render_display_unit(unit, direction)
+      spec = fetch_display_unit(unit)
+      scaled = @amount.decimal * BigDecimal(spec[:scale].to_s)
+      decimals = spec[:ui_decimals] || @entry.ui_decimals
+      rounded = round(scaled, decimals, direction)
+
+      apply_symbol(
+        format("%.#{decimals}f", rounded),
+        spec[:symbol] || @entry.display_symbol,
+        spec[:position] || @entry.display_position
+      )
+    end
+
+    def fetch_display_unit(unit)
+      units = @entry.display_units
+      unless units
+        raise Registry::InvalidDisplayUnit, "#{@entry.symbol} has no display_units configured"
+      end
+
+      units.fetch(unit.to_sym) do
+        raise Registry::InvalidDisplayUnit, "unknown display unit #{unit} for #{@entry.symbol}"
+      end
+    end
+
+    def round(value, decimals, direction)
+      factor = BigDecimal(10)**decimals
+      scaled = value * factor
+      truncated = direction == :ceil ? scaled.ceil : scaled.floor
+      truncated / factor
+    end
+
+    def apply_symbol(str, symbol, position)
+      return str if symbol.nil? || symbol.empty?
+
+      position == :prefix ? "#{symbol}#{str}" : "#{str} #{symbol}"
+    end
+  end
+end

data/lib/amount/parser.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Amount
+  # Parses compact amount strings such as `USDC|1.50`.
+  class Parser
+    VERSION_PREFIX = /\A(v\d+):(.*)\z/
+    SUPPORTED_VERSION = "v1"
+
+    def initialize(input)
+      @input = input
+    end
+
+    def parse
+      symbol, value = parse_components
+      validate!(symbol, value)
+
+      Amount.new(value, symbol)
+    rescue ArgumentError
+      raise InvalidInput, "cannot parse #{@input.inspect}"
+    end
+
+    private
+
+    def parse_components
+      compact = @input.to_s
+      versioned = compact.match(VERSION_PREFIX)
+      return split_components(compact) unless versioned
+
+      version, body = versioned.captures
+      validate_version!(version)
+      split_components(body)
+    end
+
+    def split_components(compact)
+      compact.split("|", 2)
+    end
+
+    def validate_version!(version)
+      return if version == SUPPORTED_VERSION
+
+      raise InvalidInput, "cannot parse #{@input.inspect}"
+    end
+
+    def validate!(symbol, value)
+      return unless symbol.nil? || value.nil? || symbol.empty? || value.empty?
+
+      raise InvalidInput, "cannot parse #{@input.inspect}"
+    end
+  end
+end