money_attribute 1.1.0 → 1.2.1

data/lib/money_attribute/query.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative 'query/helpers'
+require_relative 'query/currency_condition'
+require_relative 'query/amount_condition'
+require_relative 'query/amount_order'
+require_relative 'query/pluck'
+require_relative 'query/pick'
+require_relative 'query/sum'
+
+module MoneyAttribute
+  # Money-aware query helpers for ActiveRecord.
+  #
+  #   Offer.where_currency(price: 'EUR')
+  #   Offer.where_amount(price: 10..100)
+  #   Offer.order_by_amount(price: :desc)
+  #   Offer.pluck_amount(:price)
+  #   Offer.pick_amount(:price)
+  #   Offer.sum_amount(:price)
+  #
+  module Query
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Filters by currency for one or more money attributes.
+      #
+      # @param conditions [Hash{Symbol => String}] attribute name to currency code
+      # @return [ActiveRecord::Relation]
+      # @raise [ArgumentError] if the attribute is not a composite money attribute
+      def where_currency(conditions)
+        scope = all
+        conditions.each { |attr, value| scope = scope.resolve_currency_condition(attr, value) }
+        scope
+      end
+
+      # Filters by amount for one or more money attributes.
+      #
+      # Accepts a hash of conditions or a SQL string with +?+ placeholders.
+      # Hash: +{ attr: value }+, supports +Mint::Money+, +Range+, +Array+.
+      # SQL: only money attribute names, +and+, +or+, +not+, +is+, +null+.
+      #
+      # @param args [Array] a condition hash, or a SQL string with bind values
+      # @return [ActiveRecord::Relation]
+      # @raise [ArgumentError] if an identifier is not a registered money attribute
+      def where_amount(*args)
+        if args.first.is_a?(Hash)
+          scope = all
+          args.first.each { |attr, value| scope = scope.resolve_amount_condition(attr, value) }
+          scope
+        else
+          all.resolve_amount_condition_from_sql(*args)
+        end
+      end
+
+      # Orders by amount for one or more money attributes.
+      #
+      # Composite attributes sort by currency ASC first, then amount.
+      #
+      # @param conditions [Hash{Symbol => Symbol}] attribute name to +:asc+ or +:desc+
+      # @return [ActiveRecord::Relation]
+      # @raise [ArgumentError] if the attribute is not a registered money attribute
+      def order_by_amount(conditions)
+        scope = all
+        conditions.each { |attr, dir| scope = scope.resolve_amount_order(attr, dir || :asc) }
+        scope
+      end
+
+      # Plucks money-aware amounts from the current relation.
+      #
+      #   Offer.pluck_amount(:price)
+      #   # => [Mint::Money(10.0, 'EUR'), Mint::Money(20.0, 'USD')]
+      #
+      # @param attrs [Array<Symbol>] one or more registered money attribute names
+      # @return [Array<Mint::Money>] for a single attribute
+      # @return [Array<Array>] for multiple attributes, one row array per attribute
+      # @raise [ArgumentError] if any attribute is not a registered money attribute
+      def pluck_amount(*attrs)
+        all.pluck_amount(*attrs)
+      end
+
+      # Picks a single money-aware value from the current relation.
+      #
+      #   Offer.pick_amount(:price)
+      #   # => Mint::Money(10.0, 'EUR')
+      #
+      # @param attrs [Array<Symbol>] one or more registered money attribute names
+      # @return [Mint::Money, Array, nil] Money for a single attribute, row array for multiple, nil if empty
+      # @raise [ArgumentError] if any attribute is not a registered money attribute
+      def pick_amount(*attrs)
+        all.pick_amount(*attrs)
+      end
+
+      # Sums money-aware amounts, grouping by currency for composite attributes.
+      #
+      #   Offer.sum_amount(:price)
+      #   # => [Mint::Money(30.0, 'EUR'), Mint::Money(50.0, 'USD')]
+      #
+      # @param attr [Symbol] a registered money attribute name
+      # @return [Array<Mint::Money>] one Money per currency (or one for single-column attributes)
+      # @raise [ArgumentError] if the attribute is not a registered money attribute
+      def sum_amount(attr)
+        all.sum_amount(attr)
+      end
+    end
+  end
+
+  # Internal mixin combining all query sub-modules onto relations.
+  #
+  # @api private
+  module QueryMethods
+    include QueryHelpers
+    include CurrencyCondition
+    include AmountCondition
+    include AmountOrder
+    include PluckAmount
+    include PickAmount
+    include SumAmount
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include MoneyAttribute::AttributeSpecRegistry
+  include MoneyAttribute::Query
+  ActiveRecord::Relation.include(MoneyAttribute::QueryMethods)
+end

data/lib/money_attribute/railtie.rb

@@ -1,6 +1,21 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
+  # Rails engine integration.
+  #
+  # On boot, includes the migration and form-builder extensions into the
+  # corresponding Rails classes, wires Mint's locale backend to Rails i18n,
+  # and registers custom currencies declared in the initializer.
+  #
+  # @example Generated initializer
+  #   MoneyAttribute.configure do |config|
+  #     config.default_currency = 'BRL'
+  #     config.added_currencies = [
+  #       { currency: 'BTB', subunit: 8, symbol: '₿' }
+  #     ]
+  #   end
+  #
+  # @api private
   class Railtie < ::Rails::Railtie
     generators do
       require 'generators/money_attribute/initializer_generator'
@@ -20,15 +35,28 @@ module MoneyAttribute
       register_custom_currencies!
     end
 
+    # Configures Mint to use the Rails locale currency format.
+    #
+    # @return [void]
+    # @api private
     def self.setup_locale_backend!
       ::Mint.locale_backend = method(:build_locale_format).to_proc
     end
 
+    # Builds the locale-aware currency formatting hash.
+    #
+    # @return [Hash] the +:decimal+, +:thousand+, and +:format+ keys for Mint
+    # @api private
     def self.build_locale_format
       fmt = I18n.t('number.currency.format', default: {})
       { decimal: fmt[:separator], thousand: fmt[:delimiter], format: build_format(fmt) }
     end
 
+    # Builds the final currency format string or hash for Mint.
+    #
+    # @param fmt [Hash] the Rails currency format settings
+    # @return [String, Hash] a single format string or a per-sign format hash
+    # @api private
     def self.build_format(fmt)
       if %i[positive negative zero].any? { |k| fmt.key?(k) }
         build_hash_format(fmt)
@@ -37,6 +65,11 @@ module MoneyAttribute
       end
     end
 
+    # Builds a per-sign currency format hash.
+    #
+    # @param fmt [Hash] the Rails currency format settings
+    # @return [Hash] the +:positive+, +:negative+, and +:zero+ format strings
+    # @api private
     def self.build_hash_format(fmt)
       {
         positive: translate_format(fmt[:positive] || fmt[:format]),
@@ -45,10 +78,23 @@ module MoneyAttribute
       }
     end
 
+    # Translates Rails currency placeholders into Mint placeholders.
+    #
+    # @param str [String, nil] the Rails format string
+    # @return [String] the translated format string
+    # @api private
     def self.translate_format(str)
       str.to_s.gsub('%n', '%<amount>f').gsub('%u', '%<symbol>s')
     end
 
+    # Registers custom currencies configured by the application.
+    #
+    # Accepts hashes with +:currency+, +:subunit+, +:symbol+ keys or the
+    # matching positional array form. Already-registered currencies are skipped.
+    #
+    # @return [void]
+    # @raise [ArgumentError] if a currency hash is missing a required key
+    # @api private
     def self.register_custom_currencies!
       Array(MoneyAttribute.config.added_currencies).each do |currency_data|
         if currency_data.respond_to?(:values_at)
@@ -58,7 +104,7 @@ module MoneyAttribute
         else
           code, subunit, symbol = *currency_data
         end
-        ::Mint::Currency.register(code:, subunit:, symbol:)
+        Money::Currency.register(code:, subunit:, symbol:)
       rescue KeyError => e
         unless e.message.include?('already registered')
           raise ArgumentError,

data/lib/money_attribute/type.rb

@@ -1,54 +1,62 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # Type
-  class Type < ActiveRecord::Type::Value
-    def initialize(currency:, column_type: ActiveRecord::Type::Decimal.new)
-      @currency = currency
-      @column_type = column_type
-      super()
-    end
-
-    def cast(value)
-      if value.is_a?(String)
-        Mint::Money.parse(value, @currency)
-      else
-        super
-      end
-    end
+  # Base type for money amount attributes. Handles casting and validation.
+  class AmountType < ActiveRecord::Type::Value
+    # Casts string input into a +Mint::Money+ value.
+    #
+    # @param value [String, Numeric, Mint::Money, nil] the input value
+    # @return [Mint::Money, Numeric, nil] a Money value for strings, otherwise delegates to super
+    def cast(value) = value.is_a?(String) ? Money.parse(value, MoneyAttribute.default_currency) : super
 
+    # Validates that the value is compatible with the fixed currency type.
+    #
+    # @param value [Object] the value to validate
+    # @return [void]
+    # @raise [ArgumentError] when the value has a mismatched currency or is an unsupported type
     def assert_valid_value(value)
       case value
       when NilClass, Numeric, String then return
       when Mint::Money
-        return if value.currency == @currency
+        currency = MoneyAttribute.default_currency
+        return if value.currency == currency
 
-        message = "'#{value.inspect}' has different currency. Only #{@currency.code} allowed."
+        message = "'#{value.inspect}' has different currency. Only #{currency.code} allowed."
       else
         message = "'#{value.inspect}' is not a valid type for the attribute."
       end
       raise ArgumentError, message
     end
+  end
 
-    def deserialize(value)
-      return nil unless value
+  # Type for integer columns storing subunits (e.g. cents).
+  class IntegerAmountType < AmountType
+    # Deserializes a subunit integer into a +Mint::Money+ value.
+    #
+    # @param value [Integer, nil] the raw database value
+    # @return [Mint::Money, nil]
+    def deserialize(value) = value && Money.from_subunits(value.to_i, MoneyAttribute.default_currency)
 
-      if @column_type.is_a?(ActiveRecord::Type::Integer)
-        Mint::Money.from_subunits(value, @currency)
-      else
-        Mint::Money.from(value, @currency)
-      end
-    end
+    # Serializes a +Mint::Money+ value into subunits.
+    #
+    # @param value [Mint::Money, nil]
+    # @return [Integer, nil]
+    def serialize(value) = value&.subunits
+  end
 
-    def serialize(value)
-      return nil unless value
+  # Type for decimal columns storing unit values (e.g. 12.34).
+  class DecimalAmountType < AmountType
+    # Deserializes a decimal value into a +Mint::Money+ value.
+    #
+    # @param value [BigDecimal, nil] the raw database value
+    # @return [Mint::Money, nil]
+    def deserialize(value) = value&.to_money(MoneyAttribute.default_currency)
 
-      if @column_type.is_a?(ActiveRecord::Type::Integer)
-        value.subunits
-      else
-        value.to_d
-      end
-    end
+    # Serializes a +Mint::Money+ value into a decimal.
+    #
+    # @param value [Mint::Money, nil]
+    # @return [BigDecimal, nil]
+    def serialize(value) = value&.to_d
   end
 end
 

data/lib/money_attribute/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  VERSION = '1.1.0'
+  # The current gem version, following semantic versioning.
+  VERSION = '1.2.1'
 end

data/lib/money_attribute.rb

@@ -1,13 +1,28 @@
 # frozen_string_literal: true
 
+# MoneyAttribute provides ActiveRecord integrations for the Minting money gem.
+#
+# Two storage modes:
+#
+# - +money_attribute :price+ — composite (amount + currency columns)
+# - +money_amount :price+    — single column (fixed currency)
+#
+# @see MoneyAttribute::Macro
+# @see MoneyAttribute::MoneyAmount
+
 require 'minting'
-require 'money_attribute/core_ext'
+require 'money_attribute/core_ext/numeric'
 require 'money_attribute/core_ext/string'
 require 'money_attribute/configuration'
+require 'money_attribute/current'
+require 'money_attribute/column_type_validations'
+require 'money_attribute/attribute_spec'
+require 'money_attribute/attribute_spec_registry'
 require 'money_attribute/macro'
 require 'money_attribute/money_amount'
 require 'money_attribute/converter'
 require 'money_attribute/type'
 require 'money_attribute/form_builder_extension'
+require 'money_attribute/query'
 require 'money_attribute/railtie'
 require 'money_attribute/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: money_attribute
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -50,16 +50,28 @@ files:
 - lib/generators/money_attribute/initializer_generator.rb
 - lib/generators/templates/money_attribute.rb
 - lib/money_attribute.rb
+- lib/money_attribute/attribute_spec.rb
+- lib/money_attribute/attribute_spec_registry.rb
+- lib/money_attribute/column_type_validations.rb
 - lib/money_attribute/configuration.rb
 - lib/money_attribute/converter.rb
-- lib/money_attribute/core_ext.rb
+- lib/money_attribute/core_ext/numeric.rb
 - lib/money_attribute/core_ext/string.rb
+- lib/money_attribute/current.rb
 - lib/money_attribute/form_builder_extension.rb
 - lib/money_attribute/macro.rb
 - lib/money_attribute/migration_extensions/helper.rb
 - lib/money_attribute/migration_extensions/schema_statements.rb
 - lib/money_attribute/migration_extensions/table_definition.rb
 - lib/money_attribute/money_amount.rb
+- lib/money_attribute/query.rb
+- lib/money_attribute/query/amount_condition.rb
+- lib/money_attribute/query/amount_order.rb
+- lib/money_attribute/query/currency_condition.rb
+- lib/money_attribute/query/helpers.rb
+- lib/money_attribute/query/pick.rb
+- lib/money_attribute/query/pluck.rb
+- lib/money_attribute/query/sum.rb
 - lib/money_attribute/railtie.rb
 - lib/money_attribute/type.rb
 - lib/money_attribute/version.rb
@@ -88,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Money attributes for ActiveRecord
 test_files: []

data/lib/money_attribute/core_ext.rb

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