minting-rails 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfed7ac7c21d15b7b983eac0bd391ec8f4eb4f1f89b1cb9ae0308701dd15ba76
-  data.tar.gz: da2eb9d34f56f26a71674a45a792b922adb57d0ff9d6a5098eb96d2e3cf5394a
+  metadata.gz: 7f128e6d9ea67e7b1f082a06c27bc7f9a332094bdfefcdf5c63ed101eafbb59b
+  data.tar.gz: a8d8a159f47e1a9fa906777072bcb9872db56367a5b2479b786968aaa43804fe
 SHA512:
-  metadata.gz: bca70a3dc33e70b65635e1dddf9a435ee718b5d6e06e26262fdc53b8d7a9c7e3b7534b88e4ee064cdc6015c2c2772d7941a9482787e96d84397c8a74ec8cd51e
-  data.tar.gz: 73ef1dcbedaa6cbbf832d37b450c08af1ebf41c12d47a76eb1a884a571ba869c1fbebb89be24a0422a855e53e245c53cd64811466b7a73ef0fa7de5878aa0791
+  metadata.gz: f1076b8630bc62f73a37c3b1f72121e5aee2afce3ebba8b6964dfe84f0cde55961081ea84b48e2514b2230c9ebbacd9a939aca796037401e667e7a4bb8849fde
+  data.tar.gz: a6346b842fb7c1337b13ffecf18967f72d581125ecdc9999e82dd358b4021d5ac2824ad4c1fdc8ae43085065343523b75c81796da6f6a5a03a60e536f5620e6e

data/README.md

@@ -86,6 +86,51 @@ end
 
 See the [Minting gem](https://github.com/gferraz/minting) for full configuration options (custom currencies, formatting, rounding).
 
+### I18n / Locale-aware formatting
+
+Minting-rails integrates with Rails I18n to automatically format money amounts according to the current locale.
+
+With `I18n.locale` set to `:en`:
+```ruby
+Mint.money(1234.56, 'USD').to_s  # => "$1,234.56"
+```
+
+Switch to `:'pt-BR'` and the separators change automatically (requires [`rails-i18n`](https://github.com/svenfuchs/rails-i18n) or your own locale file):
+```ruby
+I18n.locale = :'pt-BR'
+Mint.money(1234.56, 'USD').to_s  # => "$1.234,56"
+```
+
+The locale backend reads `number.currency.format` from your I18n translations and maps Rails format syntax (`%n` for amount, `%u` for unit) to `Mint::Money#to_s`. If the translation key is missing (no locale file for that language), it falls back to hardcoded defaults (`.` decimal, `,` thousand, `%<symbol>s%<amount>f` format).
+
+You can configure per-sign formatting by adding `positive`, `negative`, and `zero` keys to your locale:
+
+```yaml
+# config/locales/minting-rails.en.yml
+en:
+  number:
+    currency:
+      format:
+        format: "%u%n"           # fallback when no per-sign key matches
+        positive: "%u%n"         # "$1,234.56"
+        negative: "(%u%n)"       # "($1,234.56)"
+        zero: "--"               # "--"
+        separator: "."
+        delimiter: ","
+```
+
+When any of `positive`, `negative`, or `zero` is present, a Hash format is built. Missing keys fall back to `format`:
+
+```ruby
+Mint.money(1234.56, 'USD').to_s  # => "$1,234.56"
+Mint.money(-1234.56, 'USD').to_s # => "($1,234.56)"
+Mint.money(0, 'USD').to_s        # => "--"
+```
+
+If none of those keys are set, `format` is used as a plain string (simple formatting).
+
+> Formatting respects the currency's own `subunit` for decimal precision — `I18n` locale settings for `precision` are ignored since that is a currency property, not a locale one.
+
 ## Usage — Two modes
 
 ### Decision table
@@ -224,6 +269,46 @@ end
 
 The mapping keys are `:amount` and `:currency`; values are your database column names.
 
+## Column resolution
+
+When you declare `money_attribute :name`, the gem resolves which database columns to use by checking the table schema in this order:
+
+| Step | Condition | Columns used | Mode |
+|---|---|---|---|
+| 1 | `mapping:` provided | As specified | Explicit composite |
+| 2 | `name_currency` column exists | `name` + `name_currency` | Composite (multi-currency) |
+| 3 | `name == 'amount'` AND `currency` column exists | `amount` + `currency` | Composite (multi-currency) |
+| 4 | `name_amount` + `name_currency` columns exist | `name_amount` + `name_currency` | Composite (multi-currency) |
+| 5 | `name` column exists (no currency partner) | `name` alone | Single-column (fixed-currency) |
+
+**Example**
+
+```ruby
+create_table :financial_transactions do |t|
+  t.integer :amount
+  t.string  :currency, limit: 3
+  t.integer :discount
+  t.string  :discount_currency, limit: 3
+  t.decimal :price_amount
+  t.string  :price_currency, limit: 3
+  t.bigint  :surplus
+  t.bigint  :tax
+  t.decimal :total_amount
+  t.string  :currency_code, limit: 3
+end
+```
+
+```ruby
+class FinancialTransaction < ApplicationRecord
+  money_attribute :amount                   # step 3: amount(int) + currency
+  money_attribute :discount                 # step 2: discount(int) + discount_currency
+  money_attribute :price                    # step 4: price_amount(dec) + price_currency
+  money_attribute :surplus, currency: 'EUR' # step 5: surplus(int) (single-column, will use EUR)
+  money_attribute :tax                      # step 5: tax(int) (single-column, will use default currency)
+  money_attribute :total, mapping: { amount: :total_amount, currency: :currency_code }  # step 1: explicit
+end
+```
+
 ## Querying
 
 Fixed-currency attributes support Rails-native querying through the custom type:
@@ -411,7 +496,7 @@ Minting-rails is intentionally minimal — it focuses on storing and reading mon
 | **Mongoid support** | Yes | ActiveRecord only |
 | **Migration helpers** | `add_monetize :products, :price` | None |
 | **View helpers** | `humanized_money`, `money_without_cents`, etc. | None |
-| **I18n / locale files** | Built-in locale-aware formatting | None |
+| **I18n / locale files** | Locale-aware formatting via I18n `number.currency.format` — reads your existing translations, no extra setup | Built-in locale-aware formatting with bundled translations |
 | **Test matcher** | `monetize(:price_cents)` RSpec matcher | None |
 | **Currency exchange** | `default_bank`, `add_rate`, EuCentralBank | None |
 | **Custom currencies** | `register_currency` for non-ISO codes | Via `minting` gem config |
@@ -429,7 +514,6 @@ If you need any of these features today, money-rails may be a better fit. mintin
 1. **Allow nil** — `money_attribute :price, currency: 'USD', allow_nil: true`
 1. **Method-level currency** — lambda-based currency resolution for multi-tenant and instance-level scenarios
 1. **Migration helper**
-1. **Internationalization**
 
 Contributions and suggestions are welcome — open an issue or PR at [gferraz/minting-rails](https://github.com/gferraz/minting-rails).
 

data/lib/generators/templates/minting.rb

@@ -10,8 +10,8 @@ Mint.configure do |config|
   #    {currency: 'NGN', subunit: 3, symbol: '₦'}
   #   ]
   config.added_currencies = [
-    { currency: 'CRC', subunit: 2, symbol: '₡' },
-    { currency: 'NGN', subunit: 3, symbol: '₦' }
+    { currency: 'XCRC', subunit: 2, symbol: '₡' },
+    { currency: 'XNGN', subunit: 3, symbol: '₦' }
   ]
 
   # To set the default currency

data/lib/minting/money_attribute/money_attribute.rb

@@ -1,65 +1,91 @@
 # frozen_string_literal: true
 
 module Mint
-  # MoneyAttribute
   module MoneyAttribute
     extend ActiveSupport::Concern
 
     class_methods do
-      # Money attribute
       def money_attribute(name, currency: Mint.default_currency, mapping: nil)
+        columns = attribute_names
         currency = Currency.resolve!(currency)
+        name = name.to_s
         parser = Parser.new(currency)
-        if attribute_names.include? name.to_s
-          attribute(name, :mint_money, currency:)
-          normalizes(name, with: parser)
+        resolved_mapping = mapping || resolve_mapping(name, columns)
+
+        if columns.include?(name) && resolved_mapping.nil?
+          define_single_column_money_attribute(name, currency, parser)
         else
-          aggregated = find_money_attributes(name, mapping:)
-          options = {
-            allow_nil: true, class_name: 'Mint::Money',
-            constructor: parser, converter: parser,
-            mapping: {
-              aggregated[:amount] => amount_extractor_for(aggregated[:amount]),
-              aggregated[:currency] => :currency_code
-            }
-          }
-          composed_of(name, options)
+          define_composite_money_attribute(name, resolved_mapping, parser)
         end
       end
 
-      def amount_extractor_for(column_name)
-        col = columns.find { |c| c.name == column_name.to_s }
+      private
 
-        case col&.type
-        when :bigint, :integer
-          :fractional
-        else
-          :to_d # :decimal, :numeric, unknown
+      # --- Preparation (no side effects) ---
+
+      def resolve_mapping(name, columns)
+        return nil unless columns.include?(name)
+
+        if columns.include?("#{name}_currency")
+          { amount: name, currency: :"#{name}_currency" }
+        elsif columns.include?('currency') && name == 'amount'
+          { amount: name, currency: :currency }
         end
       end
 
-      def find_money_attributes(name, mapping:)
-        if mapping.present?
-          missing_keys = (%i[amount currency] - mapping.keys).join(', ')
-          if missing_keys.present?
-            raise ArgumentError,
-                  "Mapping for :#{name} money attribute is missing required keys: #{missing_keys}"
-          end
-          composite = { amount: mapping[:amount].to_s, currency: mapping[:currency].to_s }
-        else
-          composite = { amount: "#{name}_amount", currency: "#{name}_currency" }
-        end
+      def resolve_composite_for(name, mapping:)
+        composite = { amount: "#{name}_amount", currency: "#{name}_currency" }
 
-        missing = composite.values - attribute_names
-        if missing.any?
-          raise ArgumentError,
-                "Could not find columns for :#{name} money attribute. " \
-                "Expected: #{composite.values.join(', ')}, " \
-                "Found: #{attribute_names.join(', ')}"
-        end
+        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
       end
+
+      def assert_columns_exist!(name, composite)
+        missing = composite.values - attribute_names
+        return if missing.empty?
+
+        raise ArgumentError,
+              "Could not find columns for :#{name} money attribute. " \
+              "Expected: #{composite.values.join(', ')}, " \
+              "Found: #{attribute_names.join(', ')}"
+      end
+
+      def amount_extractor_for(column_name)
+        integer_column?(column_name) ? :fractional : :to_d
+      end
+
+      def money_constructor_for(amount_column) = integer_column?(amount_column) ? :from_fractional : :from
+
+      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, parser)
+        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: parser)
+      end
+
+      def define_composite_money_attribute(name, mapping, parser)
+        aggregated = resolve_composite_for(name, mapping:)
+
+        composed_of(name.to_sym, {
+                      allow_nil: true,
+                      class_name: 'Mint::Money',
+                      constructor: money_constructor_for(aggregated[:amount]),
+                      converter: parser,
+                      mapping: {
+                        aggregated[:amount] => amount_extractor_for(aggregated[:amount]),
+                        aggregated[:currency] => :currency_code
+                      }
+                    })
+      end
     end
   end
 end

data/lib/minting/money_attribute/money_type.rb

@@ -26,9 +26,9 @@ module Mint
       return nil unless value
 
       if @column_type.is_a?(ActiveRecord::Type::Integer)
-        Mint.money(value * @currency.fractional_multiplier, @currency)
+        Mint::Money.from_fractional(value, @currency)
       else
-        Mint.money(value, @currency)
+        Mint::Money.from(value, @currency)
       end
     end
 

data/lib/minting/money_attribute/version.rb

@@ -2,6 +2,6 @@
 
 module Mint
   module MoneyAttribute
-    VERSION = '0.8.1'
+    VERSION = '0.8.3'
   end
 end

data/lib/minting/railties.rb

@@ -7,15 +7,41 @@ module Mint
     end
 
     config.after_initialize do
+      setup_locale_backend!
+      register_custom_currencies!
+    end
+
+    def self.setup_locale_backend!
+      Mint.locale_backend = lambda {
+        fmt = I18n.t('number.currency.format', default: {})
+        translator = ->(s) { s&.gsub('%n', '%<amount>f')&.gsub('%u', '%<symbol>s') }
+
+        format = if fmt.key?(:positive) || fmt.key?(:negative) || fmt.key?(:zero)
+                   {
+                     positive: translator.call(fmt[:positive] || fmt[:format]),
+                     negative: translator.call(fmt[:negative] || fmt[:format]),
+                     zero: translator.call(fmt[:zero] || fmt[:format])
+                   }
+                 else
+                   translator.call(fmt[:format])
+                 end
+
+        { decimal: fmt[:separator], thousand: fmt[:delimiter], format: format }
+      }
+    end
+
+    def self.register_custom_currencies!
       Array(Mint.config.added_currencies).each do |currency_data|
         if currency_data.respond_to?(:values_at)
-          code = currency_data[:currency] || currency_data['currency']
-          subunit = currency_data[:subunit] || currency_data['subunit']
-          symbol = currency_data[:symbol] || currency_data['symbol']
+          code = currency_data[:currency]
+          subunit = currency_data[:subunit]
+          symbol = currency_data[:symbol]
         else
           code, subunit, symbol = *currency_data
         end
         Currency.register(code:, subunit:, symbol:)
+      rescue KeyError
+        nil
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting-rails
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.3
 platform: ruby
 authors:
 - Gilson Ferraz