minting-rails 0.3.3 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bd3a7589733a495cc181ffa6ab521e5c8090c03cbc3ab5e94b5cd2f75053a44
-  data.tar.gz: 3dcaaa12c7f389d07e29f4ffe7c6636c3370e78a11f366b4ffef9f92539ab026
+  metadata.gz: 5808a2bc3360d2922f6daafe1b3fb76fd22b7e42e55f953c9a710b6403b4d85d
+  data.tar.gz: 3a8f0681a8ec28df623c663a2dcfac34460efab3fa022183b6b69fb3beccf2de
 SHA512:
-  metadata.gz: 4d14f5bf882de78babfc661320fa08a9a182addcd429bebcc1df1c604a09778d637dd34000cb386816e6c3e089018563696dbcedbfcd1bffc38cd8d9832d1914
-  data.tar.gz: cbef220622baba1a8fc0eedce69b6854c2786d347e0b7d487913654ab6221849dff57ce6e7ca8f25fb3ba3e1a433536fcc829afc68fd56227c9dadb6ed2e4ac7
+  metadata.gz: 99b0a1f2b1a2f66687c925cf747af3ec24af0b30847f5ac498a443e28bdc4b8e4a4b66b96211340b73d89a188a2a3bbb60363abb2e3af3a74b911077824e929f
+  data.tar.gz: 591a1dc0d5d7db7cb016294dd0aeb1e235468e95153653348bc8a2e937830369baa9875599cbfa4864beed2cad20a41bd2ba4427e9a196cba595c2034eb4e258

data/README.md

@@ -1,65 +1,266 @@
 # Minting::Rails
 
-Minting::Rails is a gem that provides money attributes to ActiveRecord models. It integrates the [Minting](https://github.com/gferraz/minting) library into your Rails application.
+Minting::Rails brings [Minting](https://github.com/gferraz/minting) money objects to Active Record models.
+
+It adds a `money_attribute` model helper, registers a `:mint_money` Active Record type, and includes small convenience methods such as `12.to_money(:USD)`, `12.dollars`, and `'12.00'.mint(:BRL)`.
+
+## What it does
+
+- Stores and reads model attributes as `Mint::Money` objects.
+- Supports composed money attributes backed by amount and currency columns.
+- Normalizes numeric, string, and `Mint::Money` assignments.
+- Validates currencies against the currencies enabled in Minting.
+
+## Requirements
+
+- Ruby 3.3 or newer.
+- Rails 7.1.3.2 or newer.
+- Minting 1.0.0 or newer.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your Rails application's `Gemfile`:
 
 ```ruby
 gem 'minting-rails'
 ```
 
-And then execute:
+Install it:
 
-```bash
-  bundle
+```sh
+bundle install
+```
+
+Generate the initializer:
+
+```sh
+bin/rails g mint:initializer
 ```
 
 ## Configuration
 
-After intalling generate Minting configuration initializer:
+Configure Minting in `config/initializers/minting.rb`:
 
-```sh
-rails g mint:initializer
+```ruby
+Mint.configure do |config|
+  config.enabled_currencies = :all
+  config.default_currency = 'USD'
+end
 ```
 
-You can configure the default currency for your application by adding the following line to your config/initializers/minting.rb:
+You can limit the currencies that may be used:
 
 ```ruby
-Minting.configure do |config|
-  config.default_currency = :usd
+Mint.configure do |config|
+  config.enabled_currencies = %w[USD EUR BRL]
+  config.default_currency = 'USD'
 end
 ```
 
+You can also register custom currencies before enabling or using them:
+
+```ruby
+Mint.configure do |config|
+  config.added_currencies = [
+    { currency: 'CRC', subunit: 2, symbol: 'CRC' },
+    { currency: 'NGN', subunit: 2, symbol: 'NGN' }
+  ]
+
+  config.enabled_currencies = :all
+  config.default_currency = 'CRC'
+end
+```
+
+The default currency must be registered and included in `enabled_currencies`.
+
 ## Usage
 
-To use Minting::Rails, you add the money_attribute method to your ActiveRecord models. For example:
+Declare money attributes in your Active Record models with `money_attribute`.
+
+### Single-column fixed currency
+
+Use this when a column always stores one currency, such as a `price` column that is always USD.
+
+Migration:
+
+```ruby
+class CreateProducts < ActiveRecord::Migration[7.1]
+  def change
+    create_table :products do |t|
+      t.decimal :price
+      t.decimal :discount
+
+      t.timestamps
+    end
+  end
+end
+```
+
+Model:
 
 ```ruby
-class SimpleOffer < ApplicationRecord
+class Product < ApplicationRecord
   money_attribute :price, currency: 'USD'
   money_attribute :discount, currency: 'USD'
 end
 ```
 
-Now you can use the price attribute as a Money object:
+Assignments are normalized to `Mint::Money`:
+
+```ruby
+product = Product.new(price: 12, discount: '3.50')
+
+product.price
+# => #<Mint::Money ... USD 12.00>
+
+product.discount
+# => #<Mint::Money ... USD 3.50>
+```
+
+Assigning a `Mint::Money` with a different currency raises `ArgumentError`:
+
+```ruby
+Product.new(price: 12.to_money(:EUR))
+# raises ArgumentError because the attribute only accepts USD
+```
+
+### Amount and currency columns
+
+Use this when each row can store a different currency per record.
+
+Migration:
+
+```ruby
+class CreateOffers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :offers do |t|
+      t.decimal :price_amount
+      t.string :price_currency
+
+      t.timestamps
+    end
+  end
+end
+```
+
+Model:
+
+```ruby
+class Offer < ApplicationRecord
+  money_attribute :price
+end
+```
+
+The attribute is composed from `price_amount` and `price_currency`:
 
 ```ruby
-product = Product.ne(price: 100)
-puts product.price # => "$100.00"
+offer = Offer.new(price: 15.to_money(:EUR))
+
+offer.price
+# => #<Mint::Money ... EUR 15.00>
+
+offer.price_amount
+# => 15.0
+
+offer.price_currency
+# => "EUR"
+```
+
+When you assign a plain number or string, Minting::Rails uses `Mint.default_currency`:
+
+```ruby
+offer = Offer.new(price: '12')
+
+offer.price.currency_code
+# => "USD"
+```
+
+### Custom column names
+
+If your amount and currency columns do not follow the `<name>_amount` and `<name>_currency` convention, pass a mapping:
+
+```ruby
+class Invoice < ApplicationRecord
+  money_attribute :total, mapping: {
+    total_amount: :amount,
+    currency_code: :currency
+  }
+end
+```
+
+The mapping keys are your database columns. The values must identify which column stores the `:amount` and which stores the `:currency`.
+
+## Querying
+
+Fixed-currency attributes can be queried with `Mint::Money` values:
+
+```ruby
+Product.where(price: 15.to_money(:USD))
+```
+
+Composed attributes can also be queried with a money object:
+
+```ruby
+Offer.where(price: 15.to_money(:EUR))
+```
+
+You can still query the backing columns directly when that is clearer:
+
+```ruby
+Offer.where(price_amount: 15, price_currency: 'EUR')
+```
+
+## Convenience methods
+
+Minting::Rails adds a few small helpers:
+
+```ruby
+12.to_money(:USD)
+12.mint(:BRL)
+12.dollars
+12.euros
+'12.50'.to_money(:USD)
+'12.50'.mint(:BRL)
+```
+
+These return `Mint::Money` instances.
+
+## Development
+
+Clone the repository and install dependencies:
+
+```sh
+bundle install
 ```
 
-## To do
+Run the test suite:
 
-- API Documentation
-- Internationalization
-- Publish 1.0 Beta
+```sh
+bundle exec rake test
+```
+
+The repository includes a dummy Rails application under `test/dummy` for exercising the engine in a Rails environment.
+
+## Releasing
+
+Update the version in `lib/minting/money_attribute/version.rb`, update release notes, and build the gem:
+
+```sh
+gem build minting-rails.gemspec
+```
+
+Publishing is configured for RubyGems.org.
 
 ## Contributing
 
-Contribution directions go here.
+Bug reports and pull requests are welcome on GitHub at [gferraz/minting-rails](https://github.com/gferraz/minting-rails).
+
+Before opening a pull request, please run:
+
+```sh
+bundle exec rake test
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).

data/lib/minting/money_attribute/configuration.rb

@@ -1,26 +1,44 @@
 # frozen_string_literal: true
 
 module Mint
-  include ActiveSupport::Configurable
+  module MoneyAttribute
+    class Configuration
+      attr_accessor :added_currencies, :enabled_currencies, :default_currency,
+                    :rounding_mode, :default_format
 
-  def self.assert_valid_currency!(currency)
-    if currency.is_a? Mint::Currency
-      code = currency.code
-    else
-      code = currency.to_s
-      currency = Mint.currency(code)
+      def initialize
+        @added_currencies = []
+        @enabled_currencies = :all
+        @default_currency = 'USD'
+        @rounding_mode = nil
+        @default_format = nil
+      end
     end
-    return currency if valid_currency_codes.include?(code)
+  end
+
+  def self.config
+    @config ||= MoneyAttribute::Configuration.new
+  end
+
+  def self.configure
+    yield config if block_given?
+    @default_currency = nil
+    config
+  end
+
+  def self.assert_valid_currency!(currency)
+    currency = Mint.currency(currency)
+    return currency if config.valid_currency?(currency)
 
-    raise ArgumentError,
-          "Invalid currency '#{code}'. Please select a registered currency: #{valid_currency_codes}"
+    raise ArgumentError, "Invalid currency '#{currency.code}'. Please select a registered currency"
   end
 
   def self.default_currency
     @default_currency ||= Mint.assert_valid_currency!(config.default_currency)
   end
 
-  def self.valid_currency_codes
-    config.enabled_currencies == :all ? Mint.currencies.keys : config.enabled_currencies
+  def self.valid_currency?(currency)
+    currencies = config.enabled_currencies == :all ? Mint.currencies : config.enabled_currencies
+    currencies.include?(currency)
   end
 end

data/lib/minting/money_attribute/version.rb

@@ -2,6 +2,6 @@
 
 module Mint
   module MoneyAttribute
-    VERSION = '0.3.3'
+    VERSION = '0.4.2'
   end
 end

data/lib/minting/railties.rb

@@ -7,8 +7,15 @@ module Mint
     end
 
     config.to_prepare do
-      Mint.config.added_currencies do |currency_data|
-        Mint.register_currency(*currency_data)
+      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']
+        else
+          code, subunit, symbol = *currency_data
+        end
+        Mint.register_currency(code, subunit:, symbol:)
       end
     end
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: minting-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.2
 platform: ruby
 authors:
 - Gilson Ferraz
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minting
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -68,7 +67,6 @@ metadata:
   changelog_uri: https://github.com/gferraz/minting-rails/releases
   bug_tracker_uri: https://github.com/gferraz/minting-rails/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -83,8 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.14
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Money attributes to ActiveRecord
 test_files: []