money_attribute 1.2.0 → 1.2.1

data/lib/money_attribute/query/helpers.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Internal helpers shared by the query sub-modules.
+  #
+  # @api private
   module QueryHelpers
     # Returns the registered money attribute spec or raises when missing.
     #
     # @param attr [Symbol, String] the money attribute name
     # @return [AttributeSpec]
     # @raise [ArgumentError] if the attribute is not registered
+    # @api private
     def money_attribute_spec!(attr)
       spec = klass.money_attribute_spec(attr)
       raise ArgumentError, "#{attr} is not a money attribute on #{klass.name}" unless spec
@@ -15,16 +18,36 @@ module MoneyAttribute
       spec
     end
 
+    # Extracts money values for all specs from a single result row.
+    #
+    # @param row [Array] the flat row from +pluck+ or +pick+
+    # @param specs [Array<AttributeSpec>] the money attribute specs
+    # @return [Array] the extracted money values
+    # @api private
+    def extract_money_row(row, specs)
+      cursor = 0
+
+      specs.map do |spec|
+        value, cursor = extract_attribute_value(row, spec, cursor)
+        value
+      end
+    end
+
+    private
+
     # Extracts a single value from a flat row at the given cursor position.
     #
     # @param row [Array] the flat row from +pluck+ or +pick+
     # @param spec [AttributeSpec] the money attribute spec
     # @param cursor [Integer] current position in the row array
     # @return [Array(Object, Integer)] the extracted value and updated cursor
-    def extract_pick_value(row, spec, cursor)
-      return [row[cursor], cursor + 1] if spec.single?
-
-      [spec.build_money(row[cursor], row[cursor + 1]), cursor + 2]
+    # @api private
+    def extract_attribute_value(row, spec, cursor)
+      if spec.single?
+        [row[cursor], cursor + 1]
+      else
+        [spec.build_money(row[cursor], row[cursor + 1]), cursor + 2]
+      end
     end
   end
 end

data/lib/money_attribute/query/pick.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Internal pick resolution for the +pick_amount+ query helper.
+  #
+  # @api private
   module PickAmount
     # Picks money-aware amounts for one or more attributes.
     #
     # @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
+    # @api private
     def pick_amount(*attrs)
       raise ArgumentError, 'No attribute specified' if attrs.empty?
 
@@ -17,22 +20,22 @@ module MoneyAttribute
       raw = pick(*specs.flat_map(&:columns))
       return unless raw
 
-      cursor = 0
-      specs.map do |spec|
-        value, cursor = extract_pick_value(raw, spec, cursor)
-        value
-      end
+      extract_money_row(raw, specs)
     end
 
     private
 
     # Picks a single money-aware attribute and returns a single value.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Mint::Money, Object, nil] the composed Money, the raw value for
+    #   single-column attributes, or nil when the relation is empty
+    # @api private
     def pick_single_amount(spec)
       raw = pick(*spec.columns)
       return unless raw
-      return raw if spec.single?
 
-      spec.build_money(raw[0], raw[1])
+      spec.single? ? raw : spec.build_money(raw[0], raw[1])
     end
   end
 end

data/lib/money_attribute/query/pluck.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Internal pluck resolution for the +pluck_amount+ query helper.
+  #
+  # @api private
   module PluckAmount
     # Plucks money-aware amounts for one or more attributes.
     #
@@ -9,6 +11,7 @@ module MoneyAttribute
     # @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
+    # @api private
     def pluck_amount(*attrs)
       raise ArgumentError, 'No attribute specified' if attrs.empty?
 
@@ -22,22 +25,15 @@ module MoneyAttribute
     private
 
     # Plucks a single money-aware attribute and returns money values.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Array] raw values for single-column attributes, composed
+    #   +Mint::Money+ values for composite attributes
+    # @api private
     def pluck_single_amount(spec)
-      return pluck(spec.amount_col) if spec.single?
-
-      pluck(spec.amount_col, spec.currency_col).map do |amount, currency|
-        spec.build_money(amount, currency)
-      end
-    end
-
-    # Rebuilds a result row for multi-attribute plucks.
-    def extract_money_row(row, specs)
-      cursor = 0
+      return pluck(spec.amount_column) if spec.single?
 
-      specs.map do |spec|
-        value, cursor = extract_pick_value(row, spec, cursor)
-        value
-      end
+      pluck(spec.amount_column, spec.currency_column).map { |amount, currency| spec.build_money(amount, currency) }
     end
   end
 end

data/lib/money_attribute/query/sum.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Internal sum resolution for the +sum_amount+ query helper.
+  #
+  # @api private
   module SumAmount
     # Sums money-aware amounts for a single attribute.
     #
     # @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
+    # @api private
     def sum_amount(attr)
       raise ArgumentError, 'No attribute specified' if attr.nil?
 
@@ -22,8 +25,13 @@ module MoneyAttribute
     private
 
     # Sums a composite attribute grouped by currency.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Array<Mint::Money>] one +Mint::Money+ per currency, sorted by
+    #   currency code, or a single zero-value Money when no rows match
+    # @api private
     def resolve_composite_sum(spec)
-      totals = group(spec.currency_col).sum(spec.amount_col)
+      totals = group(spec.currency_column).sum(spec.amount_column)
       return [spec.build_money(0, MoneyAttribute.default_currency)] if totals.empty?
 
       totals.map { |code, amount| spec.build_money(amount, code) }
@@ -31,8 +39,12 @@ module MoneyAttribute
     end
 
     # Sums a fixed-currency single-column attribute.
+    #
+    # @param spec [AttributeSpec] the money attribute spec
+    # @return [Array<Mint::Money>] a single +Mint::Money+ in the default currency
+    # @api private
     def resolve_single_sum(spec)
-      total = sum(spec.amount_col)
+      total = sum(spec.amount_column)
 
       [spec.build_money(total, MoneyAttribute.default_currency)]
     end

data/lib/money_attribute/query.rb

@@ -35,18 +35,21 @@ module MoneyAttribute
 
       # Filters by amount for one or more money attributes.
       #
-      # Accepts +Mint::Money+ objects, numeric values (decimal columns), Ranges, or Arrays.
+      # 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+.
       #
-      #   Offer.where_amount(price: 10.dollars..100.dollars)
-      #   Offer.where_amount(total: [10, 20, 30])
-      #
-      # @param conditions [Hash{Symbol => Numeric, Range, Array}] attribute name to filter value
+      # @param args [Array] a condition hash, or a SQL string with bind values
       # @return [ActiveRecord::Relation]
-      # @raise [ArgumentError] if the attribute is not a registered money attribute
-      def where_amount(conditions)
-        scope = all
-        conditions.each { |attr, value| scope = scope.resolve_amount_condition(attr, value) }
-        scope
+      # @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.
@@ -101,7 +104,9 @@ module MoneyAttribute
     end
   end
 
-  # :nodoc:
+  # Internal mixin combining all query sub-modules onto relations.
+  #
+  # @api private
   module QueryMethods
     include QueryHelpers
     include CurrencyCondition

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'
@@ -21,17 +36,27 @@ module MoneyAttribute
     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)
@@ -41,6 +66,10 @@ module MoneyAttribute
     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]),
@@ -50,11 +79,22 @@ 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)

data/lib/money_attribute/type.rb

@@ -50,7 +50,7 @@ module MoneyAttribute
     #
     # @param value [BigDecimal, nil] the raw database value
     # @return [Mint::Money, nil]
-    def deserialize(value) = value && Money.from(value, MoneyAttribute.default_currency)
+    def deserialize(value) = value&.to_money(MoneyAttribute.default_currency)
 
     # Serializes a +Mint::Money+ value into a decimal.
     #

data/lib/money_attribute/version.rb

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

data/lib/money_attribute.rb

@@ -15,6 +15,7 @@ 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: money_attribute
 version: !ruby/object:Gem::Version
-  version: 1.2.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
@@ -52,6 +52,7 @@ files:
 - 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/numeric.rb
@@ -99,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Money attributes for ActiveRecord
 test_files: []