money_attribute 0.14.5 → 1.2.0

data/lib/money_attribute/attribute_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # @private Constructor for integer (subunit) columns used by +composed_of+.
+  INTEGER_CONSTRUCTOR = lambda do |amount, currency|
+    next nil if amount.nil?
+
+    resolved = Money::Currency.resolve(currency.presence || MoneyAttribute.default_currency) || 'XXX'
+    Mint::Money.from_subunits(amount, resolved)
+  end.freeze
+
+  # @private Constructor for decimal (unit value) columns used by +composed_of+.
+  DECIMAL_CONSTRUCTOR = lambda do |amount, currency|
+    next nil if amount.nil?
+
+    resolved = Money::Currency.resolve(currency.presence || MoneyAttribute.default_currency) || 'XXX'
+    Mint::Money.from(amount, resolved)
+  end.freeze
+
+  # Value object holding metadata for a registered money attribute.
+  #
+  # Created by +money_attribute+ or +money_amount+ and stored in the class-level registry.
+  # Used by query helpers to resolve column names, build Money values, and generate SQL.
+  AttributeSpec = Struct.new(:name, :kind, :amount_col, :currency_col, :amount_type, keyword_init: true) do
+    # @return [Boolean] +true+ when the spec describes a two-column (amount + currency) attribute.
+    def composite? = kind == :composite
+
+    # @return [Boolean] +true+ when the spec describes a single-column (fixed currency) attribute.
+    def single? = kind == :single
+
+    # Returns the backing database columns for the attribute.
+    #
+    # @return [Array<String>] two-element array for composite, one-element for single.
+    def columns
+      @columns ||= (composite? ? [amount_col, currency_col] : [amount_col]).freeze
+    end
+
+    # @return [Boolean] +true+ when the amount column stores subunits (bigint).
+    def integer_amount? = amount_type == :integer
+
+    # @return [Symbol] +:subunits+ for integer columns, +:to_d+ for decimal columns.
+    def amount_extractor = integer_amount? ? :subunits : :to_d
+
+    # @return [Hash{String => Symbol}] mapping suitable for +composed_of+.
+    def composed_of_mapping = { amount_col => amount_extractor, currency_col => :currency_code }
+
+    # @return [Proc] the constructor lambda used by +composed_of+ to instantiate Money values.
+    def constructor
+      integer_amount? ? INTEGER_CONSTRUCTOR : DECIMAL_CONSTRUCTOR
+    end
+
+    # Converts a raw amount and currency into a +Mint::Money+ value.
+    #
+    # @param amount [Integer, BigDecimal, nil] the raw column value
+    # @param currency [String, Mint::Currency, nil] the currency code or object
+    # @return [Mint::Money, nil] the resolved money value, or nil when amount is nil
+    def build_money(amount, currency)
+      return unless amount
+      return amount if amount.is_a?(Mint::Money)
+
+      constructor.call(amount, currency)
+    end
+
+    # Normalizes a query value to the column's storage format.
+    #
+    # Composite attributes: decomposes +Mint::Money+ to subunits via +.subunits+.
+    # Single-column attributes: passes through (the registered Type handles serialization).
+    #
+    # @param value [Mint::Money, Numeric] the query value
+    # @return [Integer, BigDecimal, Mint::Money] the normalized value
+    def normalize_query_value(value)
+      return value unless integer_amount?
+      return value.subunits if value.is_a?(Mint::Money)
+
+      value
+    end
+  end
+end

data/lib/money_attribute/attribute_spec_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+
+module MoneyAttribute
+  # Stores money attribute metadata on the model class.
+  module AttributeSpecRegistry
+    extend ActiveSupport::Concern
+
+    REGISTRY = Concurrent::Map.new
+
+    class_methods do
+      # Registers a money attribute spec for the current model class.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @param kind [Symbol] +:composite+ or +:single+
+      # @param amount_col [Symbol, String] the amount column name
+      # @param currency_col [Symbol, String, nil] the currency column name (composite only)
+      # @param amount_type [Symbol, nil] +:integer+ or +:decimal+
+      # @return [AttributeSpec]
+      def register_money_attribute_spec(name, kind:, amount_col:, currency_col: nil, amount_type: nil)
+        spec = MoneyAttribute::AttributeSpec.new(
+          name: name.to_s,
+          kind: kind,
+          amount_col: amount_col.to_s,
+          currency_col: currency_col&.to_s,
+          amount_type: amount_type
+        )
+
+        money_attribute_specs[spec.name] = spec
+        spec
+      end
+
+      # Returns the registered money attribute spec for the given name.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [AttributeSpec, nil]
+      def money_attribute_spec(name)
+        REGISTRY[self]&.fetch(name.to_s, nil)
+      end
+
+      # Returns the registry hash for the current model class.
+      #
+      # @return [Hash{String => AttributeSpec}]
+      def money_attribute_specs
+        REGISTRY.fetch_or_store(self) { {} }
+      end
+    end
+  end
+end

data/lib/money_attribute/configuration.rb

@@ -1,28 +1,55 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  class Configuration
-    attr_accessor :added_currencies, :default_currency
+  # @private
+  CONFIG_MUTEX = Mutex.new
 
-    def initialize
-      @added_currencies = []
-      @default_currency = 'USD'
+  class << self
+    # Returns the lazily initialized gem configuration.
+    #
+    # @return [Config]
+    def config
+      CONFIG_MUTEX.synchronize { @config ||= Config.new }
     end
-  end
 
-  # Class-level caches — written during Rails boot (single-threaded),
-  # read-only during request handling. Safe without synchronization.
-  def self.config
-    @config ||= Configuration.new
-  end
+    # Yields the current configuration object for mutation.
+    #
+    # @yield [config] the current configuration
+    # @return [void]
+    def configure = yield config
+
+    # Returns the current request or default currency as a resolved currency.
+    # Memoized per-thread — within a request, Current.currency is stable.
+    #
+    # @return [Mint::Currency]
+    def default_currency
+      code = MoneyAttribute::Current.currency.presence || config.default_currency
+
+      last_code, last_currency = Thread.current[:money_attribute_default_currency]
+      return last_currency if last_code == code
 
-  def self.configure
-    yield config if block_given?
-    @default_currency = nil
-    config
+      currency = Money::Currency.resolve!(code)
+      Thread.current[:money_attribute_default_currency] = [code, currency]
+      currency
+    end
   end
 
-  def self.default_currency
-    @default_currency ||= ::Mint::Currency.resolve!(config.default_currency)
+  # Gem configuration holding the default currency and registered custom currencies.
+  #
+  #   MoneyAttribute.configure do |config|
+  #     config.default_currency = 'BRL'
+  #   end
+  class Config
+    # @return [String] ISO 4217 currency code used when no per-request or per-row currency is set.
+    attr_accessor :default_currency
+
+    # @return [Array<Hash>] custom currencies registered via +register_custom_currencies!+.
+    attr_accessor :added_currencies
+
+    # Initializes the default gem configuration values.
+    def initialize
+      @default_currency = 'USD'
+      @added_currencies = []
+    end
   end
 end

data/lib/money_attribute/converter.rb

@@ -1,19 +1,31 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # :nodoc:
   class Converter
-    def initialize(currency = MoneyAttribute.default_currency)
-      @default_currency = currency
+    DEFAULT = new.freeze
+
+    # Initializes a converter with an optional fixed currency.
+    def initialize(currency = nil)
+      @static_currency = currency
+    end
+
+    # Returns the shared default converter instance.
+    def self.default
+      DEFAULT
     end
 
-    def parse(amount, currency = @default_currency)
+    # Converts raw input into a `Money` value.
+    def parse(amount)
+      currency = @static_currency || MoneyAttribute.default_currency
       case amount
-      when Mint::Money, NilClass then amount
-      when Numeric               then Mint::Money.from(amount, currency)
-      when String                then Mint.parse(amount, currency)
+      when Money, NilClass      then amount
+      when Numeric              then Money.from(amount, currency)
+      when String               then Money.parse(amount, currency)
       else raise ArgumentError, "Cannot convert #{amount.inspect} (#{amount.class}) to Money"
       end
     end
+
     alias call parse
   end
 end

data/lib/money_attribute/core_ext/numeric.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# :nodoc:
+class Numeric
+  remove_method :to_money if method_defined?(:to_money)
+
+  def to_money(currency = MoneyAttribute.default_currency) = Money.from(self, currency)
+end

data/lib/money_attribute/core_ext/string.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# :nodoc:
+class String
+  remove_method :to_money if method_defined?(:to_money)
+
+  def to_money(currency = MoneyAttribute.default_currency) = Money.parse(self, currency)
+end

data/lib/money_attribute/current.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module MoneyAttribute
+  # Per-request currency container. Set MoneyAttribute::Current.currency in your
+  # controller (or a before_action) to override the configured default for that request.
+  # Automatically reset after each request by MoneyAttribute::Middleware.
+  class Current < ::ActiveSupport::CurrentAttributes
+    # @return [String, nil] per-request ISO 4217 currency code override.
+    attribute :currency
+  end
+end

data/lib/money_attribute/form_builder_extension.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # :nodoc:
   module FormBuilderExtension
+    # Renders a text input for a composed money attribute.
     def money_field(method, options = {})
       money = object.public_send(method)
-      value = money&.to_fs(:currency)
+      value = money&.to_fs
 
       @template.text_field_tag(field_name(method), value,
                                { id: field_id(method) }.merge(options))
     end
 
+    # Renders a number input for a single-column money attribute.
     def money_amount_field(method, options = {})
       money_from_column = object.public_send(method)
       value = money_from_column&.to_d

data/lib/money_attribute/macro.rb

@@ -1,103 +1,80 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # :nodoc:
   module Macro
     extend ActiveSupport::Concern
 
-    class_methods do
-      def money_attribute(name, currency: MoneyAttribute.default_currency, mapping: nil)
-        columns = attribute_names
-        currency = ::Mint::Currency.resolve!(currency)
-        name = name.to_s
-        resolved_mapping = mapping || resolve_mapping(name, columns)
+    # :nodoc:
+    module CompositeClassMethods
+      # Normalizes the requested mapping by applying conventions and overrides.
+      def resolve_mapping(name, mapping_override)
+        override = mapping_override.compact
+        override.slice!(:amount, :currency)
+        override.transform_values!(&:to_s)
 
-        if columns.include?(name) && resolved_mapping.nil?
-          define_single_column_money_attribute(name, currency)
-        else
-          define_composite_money_attribute(name, resolved_mapping, currency)
-        end
-      end
-
-      private
+        mapping = default_mapping(name).merge(override)
 
-      # --- Preparation (no side effects) ---
+        assert_columns_exist!(name, mapping)
+        mapping
+      end
 
-      def resolve_mapping(name, columns)
-        return nil unless columns.include?(name)
+      # Returns the default amount/currency mapping for the attribute name.
+      def default_mapping(name)
+        name = name.to_s
+        names = column_names
 
-        if columns.include?("#{name}_currency")
-          { amount: name, currency: :"#{name}_currency" }
-        elsif columns.include?('currency') && name == 'amount'
-          { amount: name, currency: :currency }
+        if names.include?("#{name}_currency") && names.include?(name)
+          { amount: name, currency: "#{name}_currency" }
+        elsif name == 'amount' && names.include?('currency')
+          { amount: name, currency: 'currency' }
+        else
+          { amount: "#{name}_amount", currency: "#{name}_currency" }
         end
       end
 
-      def resolve_composite_for(name, mapping:)
-        composite = { amount: "#{name}_amount", currency: "#{name}_currency" }
-
-        composite[:amount]    = mapping[:amount].to_s   if mapping&.key?(:amount)
-        composite[:currency]  = mapping[:currency].to_s if mapping&.key?(:currency)
-
-        assert_columns_exist!(name, composite)
-        composite
+      # Registers the composite money attribute spec for the model.
+      def register_composite_spec(name, mapping)
+        column = column_for_attribute(mapping[:amount])
+        register_money_attribute_spec(
+          name,
+          kind: :composite,
+          amount_col: mapping[:amount],
+          currency_col: mapping[:currency],
+          amount_type: %i[integer bigint].include?(column.type) ? :integer : :decimal
+        )
       end
 
-      def assert_columns_exist!(name, composite)
-        missing = composite.values - attribute_names
+      # Raises when the resolved columns are not present on the model.
+      def assert_columns_exist!(name, mapping)
+        missing = mapping.values - column_names
         return if missing.empty?
 
         raise ArgumentError,
               "Could not find columns for :#{name} money attribute. " \
-              "Expected: #{composite.values.join(', ')}, " \
+              "Expected: #{mapping.values.join(', ')}, " \
               "Found: #{attribute_names.join(', ')}"
       end
+    end
 
-      def amount_extractor_for(column_name) = integer_column?(column_name) ? :subunits : :to_d
-
-      def money_constructor_for(amount_column)
-        default = MoneyAttribute.default_currency
-        if integer_column?(amount_column)
-          lambda { |amount, currency|
-            return nil if amount.nil?
-
-            Mint::Money.from_subunits(amount, currency.presence || default)
-          }
-        else
-          lambda { |amount, currency|
-            return nil if amount.nil?
-
-            Mint::Money.from(amount, currency.presence || default)
-          }
-        end
-      end
-
-      def integer_column?(column_name)
-        col = columns.find { |c| c.name == column_name }
-        %i[integer bigint].include?(col&.type)
-      end
-
-      # --- Configuration (registers types, normalizers, composed_of) ---
-
-      def define_single_column_money_attribute(name, currency)
-        column_type = integer_column?(name) ? ActiveRecord::Type::Integer.new : ActiveRecord::Type::Decimal.new
-        attribute(name.to_sym, :mint_money, currency:, column_type: column_type)
-        normalizes(name.to_sym, with: Converter.new(currency))
-      end
-
-      def define_composite_money_attribute(name, mapping, currency)
-        aggregated = resolve_composite_for(name, mapping:)
+    class_methods do
+      # Declares a composite money attribute on the model.
+      def money_attribute(name, mapping: {})
+        mapping = resolve_mapping(name, mapping)
+        spec = register_composite_spec(name, mapping)
 
-        composed_of(name.to_sym, {
+        composed_of(name, {
                       allow_nil: true,
                       class_name: 'Mint::Money',
-                      constructor: money_constructor_for(aggregated[:amount]),
-                      converter: Converter.new(currency),
-                      mapping: {
-                        aggregated[:amount] => amount_extractor_for(aggregated[:amount]),
-                        aggregated[:currency] => :currency_code
-                      }
+                      constructor: spec.constructor,
+                      converter: Converter.default,
+                      mapping: spec.composed_of_mapping
                     })
       end
     end
+
+    included do
+      extend CompositeClassMethods
+    end
   end
 end

data/lib/money_attribute/migration_extensions/helper.rb

@@ -2,61 +2,68 @@
 
 module MoneyAttribute
   module MigrationExtensions
+    # :nodoc:
     module Helper
-      private
+      AMOUNT_CONFIG = {
+        crypto_decimal: { type: :decimal, precision: 36, scale: 18 },
+        fiat_decimal: { type: :decimal, precision: 20, scale: 4 },
+        fiat_integer: { type: :bigint }
+      }.freeze
 
-      def parse_money_args(accessor, options = {})
-        name = accessor.to_s
+      CURRENCY_MIN_LIMIT = 8
+      CURRENCY_DEFAULT_LIMIT = 20
+
+      private
 
-        if options.key?(:amount) && options[:amount].is_a?(Hash)
-          amount_col = options[:amount][:column]&.to_s || name
-          opts = options[:amount]
-          amount_opts = {
-            type: opts[:type],
-            null: opts[:null],
-            default: opts[:default],
-            precision: opts[:precision],
-            scale: opts[:scale]
-          }.compact
-        else
-          amount_col = name
-          amount_opts = {}
+      def parse_money_amount_args(accessor, options)
+        options ||= {}
+        if options.key?(:precision) || options.key?(:scale)
+          raise ArgumentError,
+                'precision:/scale: are not configurable — money_attribute uses fixed, ' \
+                'vetted values per type (:crypto_decimal, :fiat_decimal, :fiat_integer) ' \
+                'to prevent under-precision bugs, particularly for crypto amounts.'
         end
 
-        amount_opts[:type] ||= :decimal
+        column = (options[:column] || accessor).to_s
 
-        if amount_opts[:type] == :decimal && !amount_opts.key?(:precision) && !amount_opts.key?(:scale)
-          amount_opts[:precision] = 16
-          amount_opts[:scale]     = 4
-        elsif amount_opts[:type] != :decimal
-          amount_opts.delete(:precision)
-          amount_opts.delete(:scale)
+        config = AMOUNT_CONFIG[options[:type] || :fiat_decimal]
+        unless config
+          raise ArgumentError, "Invalid type #{options[:type]}. Use :crypto_decimal, :fiat_decimal or :fiat_integer"
         end
 
-        stripped = name.end_with?('_amount') ? name.sub(/_amount$/, '') : name
-        default_currency_col = if name == 'amount' && !(options[:currency].is_a?(Hash) && options[:currency][:column])
-                                 'currency'
-                               else
-                                 "#{stripped}_currency"
-                               end
-
-        if options.key?(:currency) && options[:currency].is_a?(Hash)
-          currency_col = options[:currency][:column]&.to_s || default_currency_col
-          opts = options[:currency]
-          currency_opts = {
-            limit: opts[:limit],
-            null: opts[:null],
-            default: opts[:default]
-          }.compact
-        elsif options[:currency] == false
-          currency_col = nil
-          currency_opts = {}
-        else
-          currency_col = default_currency_col
-          currency_opts = {}
+        options = { null: options[:null], default: options[:default] }.compact
+        [column, config.merge(options)]
+      end
+
+      def parse_currency_args(accessor, options)
+        options ||= {}
+        limit = (options[:limit] || CURRENCY_DEFAULT_LIMIT).to_i
+        if limit < CURRENCY_MIN_LIMIT
+          raise ArgumentError,
+                "currency limit: #{limit} is too small to hold an ISO 4217 code and crypto popular codes" \
+                "(minimum #{CURRENCY_MIN_LIMIT}). Omit limit: to use the default of #{CURRENCY_DEFAULT_LIMIT}, " \
+                "or pass a value >= #{CURRENCY_MIN_LIMIT}."
         end
 
-        [amount_col, currency_col, amount_opts, currency_opts]
+        column = currency_column_name(accessor, options[:column])
+        [column, { limit:, null: options[:null], default: options[:default] }.compact]
+      end
+
+      def currency_column_name(accessor, column_override)
+        return column_override.to_s if column_override
+
+        name = accessor.to_s
+        return 'currency' if name == 'amount'
+
+        radical = name.end_with?('_amount') ? name.sub(/_amount$/, '') : name
+        "#{radical}_currency"
+      end
+
+      def parse_money_args(accessor, options = {})
+        amount_column, amount_options = parse_money_amount_args(accessor, options[:amount])
+        currency_column, currency_options = parse_currency_args(accessor, options[:currency])
+
+        [amount_column, currency_column, amount_options, currency_options]
       end
     end
   end

data/lib/money_attribute/migration_extensions/schema_statements.rb

@@ -4,21 +4,34 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
+    # :nodoc:
     module SchemaStatements
       include Helper
 
       def add_money_attribute(table_name, accessor, options = {})
         amount_col, currency_col, amount_opts, currency_opts = parse_money_args(accessor, options)
 
-        add_column(table_name, amount_col, amount_opts[:type], **amount_opts.except(:type))
-        add_column(table_name, currency_col, :string, **currency_opts) if currency_col
+        type = amount_opts.delete(:type)
+        add_column(table_name, amount_col, type, **amount_opts)
+        add_column(table_name, currency_col, :string, **currency_opts)
       end
 
       def remove_money_attribute(table_name, accessor, options = {})
         amount_col, currency_col, = parse_money_args(accessor, options)
 
         remove_column(table_name, amount_col)
-        remove_column(table_name, currency_col) if currency_col
+        remove_column(table_name, currency_col)
+      end
+
+      def add_money_amount(table_name, accessor, options = {})
+        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+
+        type = amount_opts.delete(:type)
+        add_column(table_name, amount_col, type, **amount_opts)
+      end
+
+      def remove_money_amount(table_name, accessor, options = {})
+        remove_column(table_name, (options[:column] || accessor).to_s)
       end
     end
   end

data/lib/money_attribute/migration_extensions/table_definition.rb

@@ -4,6 +4,7 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
+    # :nodoc:
     module TableDefinition
       include Helper
 
@@ -11,14 +12,26 @@ module MoneyAttribute
         amount_col, currency_col, amount_opts, currency_opts = parse_money_args(accessor, options)
 
         column(amount_col, amount_opts[:type], **amount_opts.except(:type))
-        column(currency_col, :string, **currency_opts) if currency_col
+        column(currency_col, :string, **currency_opts)
       end
 
       def remove_money_attribute(accessor, options = {})
         amount_col, currency_col, = parse_money_args(accessor, options)
 
         remove_column(amount_col)
-        remove_column(currency_col) if currency_col
+        remove_column(currency_col)
+      end
+
+      def money_amount(accessor, options = {})
+        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+
+        column(amount_col, amount_opts[:type], **amount_opts.except(:type))
+      end
+
+      def remove_money_amount(accessor, options = {})
+        amount_col, = parse_money_amount_args(accessor, options)
+
+        remove_column(amount_col)
       end
     end
   end