whittaker_tech-midas 0.1.1 → 0.3.0

data/db/migrate/20260219120000_rename_resource_label_to_resource_role_in_wt_midas_coins.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class RenameResourceLabelToResourceRoleInWtMidasCoins < ActiveRecord::Migration[8.0]
+  def change
+    rename_column WhittakerTech::Midas.table_name('coins'), :resource_label, :resource_role
+    rename_index  WhittakerTech::Midas.table_name('coins'),
+                  'index_midas_coins_on_owner_and_label',
+                  'index_midas_coins_on_resource_and_role'
+  end
+end

data/db/migrate/20260219150000_rename_wt_midas_coins_to_midas_coins.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class RenameWtMidasCoinsToMidasCoins < ActiveRecord::Migration[8.0]
+  def change
+    rename_table :wt_midas_coins, :midas_coins
+    rename_index :midas_coins,
+                 'index_wt_midas_coins_on_resource_and_role',
+                 'index_midas_coins_on_resource_and_role'
+    rename_index :midas_coins,
+                 'index_wt_midas_coins_on_resource',
+                 'index_midas_coins_on_resource'
+  end
+end

data/db/migrate/20260707000000_create_midas_exchanges.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasExchanges < ActiveRecord::Migration[8.0]
+  def change
+    create_table WhittakerTech::Midas.table_name('exchanges') do |t|
+      t.decimal :rate, precision: 24, scale: 12, null: false
+      t.string  :source, null: false
+      t.datetime :at, null: false
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/whittaker_tech/midas/install/install_generator.rb

@@ -1,16 +1,10 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    module Generators
-      class InstallGenerator < Rails::Generators::Base
-        desc 'Installs Midas and copies migrations.'
+class WhittakerTech::Midas::Generators::InstallGenerator < Rails::Generators::Base
+  desc 'Installs Midas and copies migrations.'
 
-        def copy_migrations
-          say_status 'migrations', 'Copying migrations for Midas...', :green
-          rake 'midas:install:migrations'
-        end
-      end
-    end
+  def copy_migrations
+    say_status 'migrations', 'Copying migrations for Midas...', :green
+    rake 'midas:install:migrations'
   end
 end

data/lib/whittaker_tech/midas/deprecation.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Emits or raises deprecation notices for Midas API changes.
+#
+# Behavior is controlled by WhittakerTech::Midas.deprecation_behavior:
+#   :warn    - prints a warning to STDERR (default)
+#   :raise   - raises a DeprecationError (useful in test mode)
+#   :silence - suppresses all notices
+module WhittakerTech::Midas::Deprecation
+  # Removal horizon advertised in deprecation messages.
+  HORIZON = '0.3.0'
+
+  # Error raised when deprecation_behavior is :raise.
+  class DeprecationError < StandardError; end
+
+  # Emits a deprecation notice for `message` attributed to `callsite`.
+  #
+  # @param message  [String]           human-readable deprecation description
+  # @param callsite [Thread::Backtrace::Location, nil]
+  def self.warn(message, callsite = caller_locations(1, 1).first)
+    location = callsite ? "#{callsite.path}:#{callsite.lineno}" : 'unknown'
+    full = "[DEPRECATED] #{message} " \
+           "(called from #{location}). " \
+           "Will be removed in whittaker_tech-midas #{HORIZON}."
+
+    case WhittakerTech::Midas.deprecation_behavior
+    when :raise   then raise DeprecationError, full
+    when :silence then nil
+    else               Kernel.warn full
+    end
+  end
+end

data/lib/whittaker_tech/midas/engine.rb

@@ -1,122 +1,120 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    # The Midas Engine provides monetary value management capabilities as a Rails Engine.
-    # It integrates seamlessly with Rails applications to add currency handling, coin management,
-    # and monetary formatting functionality through the Bankable concern and related components.
-    #
-    # This engine follows Rails Engine conventions and can be mounted in any Rails application
-    # to provide comprehensive monetary value handling capabilities. It includes models, helpers,
-    # and utilities for working with currencies and monetary amounts.
-    #
-    # == Features
-    #
-    # - **Bankable Concern**: Allows any Active Record model to have monetary attributes
-    # - **Coin Model**: Stores monetary values with currency information
-    # - **Form Helpers**: View helpers for monetary input and display
-    # - **Currency Management**: Integration with the Money gem for currency operations
-    # - **Namespace Isolation**: Clean separation from host application code
-    #
-    # == Installation and Setup
-    #
-    # Add the engine to your Rails application's Gemfile and run bundle install.
-    # The engine will automatically configure itself when Rails boots.
-    #
-    # @example Adding to a Rails application
-    #   # In your Gemfile
-    #   gem 'whittaker_tech-midas'
-    #
-    #   # The engine auto-configures on Rails boot
-    #   # No additional setup required
-    #
-    # == Usage in Host Applications
-    #
-    # Once installed, the engine's functionality becomes available throughout
-    # your Rails application:
-    #
-    # @example Using Bankable in models
-    #   class Product < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #     has_coin :price
-    #   end
-    #
-    # @example Using form helpers in views
-    #   <%= form_with model: @product do |form| %>
-    #     <%= form.money_field :price %>
-    #   <% end %>
-    #
-    # == Configuration
-    #
-    # The engine provides several configuration points:
-    #
-    # - **Eager Loading**: Automatically configures model loading paths
-    # - **Helper Integration**: Injects form helpers into ActionView
-    # - **Namespace Isolation**: Keeps engine code separate from host application
-    #
-    # == Directory Structure
-    #
-    # The engine follows standard Rails Engine structure:
-    # - `app/models/`: Coin model and concerns
-    # - `app/helpers/`: Form helpers for monetary inputs
-    # - `db/migrate/`: Database migrations for coin storage
-    # - `lib/`: Engine configuration and initialization
-    #
-    # == Database Integration
-    #
-    # The engine provides database migrations that create the necessary tables
-    # for storing monetary values. Run migrations after installation:
-    #
-    # @example Running migrations
-    #   rails db:migrate
-    #
-    # == Namespace Isolation
-    #
-    # The engine uses `isolate_namespace` to prevent conflicts with host
-    # application code. All engine components are properly namespaced under
-    # `WhittakerTech::Midas`.
-    #
-    # == Helper Integration
-    #
-    # Form helpers are automatically made available in all views through
-    # an initializer that extends ActionView::Base when the view layer loads.
-    # This provides seamless integration without requiring manual includes.
-    #
-    # == Eager Loading
-    #
-    # The engine configures additional eager load paths to ensure all models
-    # are properly loaded in production environments. This includes the models
-    # directory which contains the Coin model and Bankable concern.
-    #
-    # == Thread Safety
-    #
-    # The engine follows Rails conventions for thread safety and can be safely
-    # used in multi-threaded environments like Puma or Falcon.
-    #
-    # == Development and Testing
-    #
-    # The engine can be developed and tested independently using its own
-    # test suite, or integrated into a host application for testing.
-    #
-    # @see WhittakerTech::Midas::Bankable
-    # @see WhittakerTech::Midas::Coin
-    # @see WhittakerTech::Midas::FormHelper
-    # @since 0.1.0
-    class Engine < ::Rails::Engine
-      isolate_namespace WhittakerTech::Midas
+# The Midas Engine provides monetary value management capabilities as a Rails Engine.
+# It integrates seamlessly with Rails applications to add currency handling, coin management,
+# and monetary formatting functionality through the Bankable concern and related components.
+#
+# This engine follows Rails Engine conventions and can be mounted in any Rails application
+# to provide comprehensive monetary value handling capabilities. It includes models, helpers,
+# and utilities for working with currencies and monetary amounts.
+#
+# == Features
+#
+# - **Bankable Concern**: Allows any Active Record model to have monetary attributes
+# - **Coin Model**: Stores monetary values with currency information
+# - **Form Helpers**: View helpers for monetary input and display
+# - **Currency Management**: Integration with the Money gem for currency operations
+# - **Namespace Isolation**: Clean separation from host application code
+#
+# == Installation and Setup
+#
+# Add the engine to your Rails application's Gemfile and run bundle install.
+# The engine will automatically configure itself when Rails boots.
+#
+# @example Adding to a Rails application
+#   # In your Gemfile
+#   gem 'whittaker_tech-midas'
+#
+#   # The engine auto-configures on Rails boot
+#   # No additional setup required
+#
+# == Usage in Host Applications
+#
+# Once installed, the engine's functionality becomes available throughout
+# your Rails application:
+#
+# @example Using Bankable in models
+#   class Product < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#     has_coin :price
+#   end
+#
+# @example Using form helpers in views
+#   <%= form_with model: @product do |form| %>
+#     <%= form.money_field :price %>
+#   <% end %>
+#
+# == Configuration
+#
+# The engine provides several configuration points:
+#
+# - **Eager Loading**: Automatically configures model loading paths
+# - **Helper Integration**: Injects form helpers into ActionView
+# - **Namespace Isolation**: Keeps engine code separate from host application
+#
+# == Directory Structure
+#
+# The engine follows standard Rails Engine structure:
+# - `app/models/`: Coin model and concerns
+# - `app/helpers/`: Form helpers for monetary inputs
+# - `db/migrate/`: Database migrations for coin storage
+# - `lib/`: Engine configuration and initialization
+#
+# == Database Integration
+#
+# The engine provides database migrations that create the necessary tables
+# for storing monetary values. Run migrations after installation:
+#
+# @example Running migrations
+#   rails db:migrate
+#
+# == Namespace Isolation
+#
+# The engine uses `isolate_namespace` to prevent conflicts with host
+# application code. All engine components are properly namespaced under
+# `WhittakerTech::Midas`.
+#
+# == Helper Integration
+#
+# Form helpers are automatically made available in all views through
+# an initializer that extends ActionView::Base when the view layer loads.
+# This provides seamless integration without requiring manual includes.
+#
+# == Eager Loading
+#
+# The engine configures additional eager load paths to ensure all models
+# are properly loaded in production environments. This includes the models
+# directory which contains the Coin model and Bankable concern.
+#
+# == Thread Safety
+#
+# The engine follows Rails conventions for thread safety and can be safely
+# used in multi-threaded environments like Puma or Falcon.
+#
+# == Development and Testing
+#
+# The engine can be developed and tested independently using its own
+# test suite, or integrated into a host application for testing.
+#
+# See also:
+#
+# - `WhittakerTech::Midas::Bankable`
+# - `WhittakerTech::Midas::Coin`
+# - `WhittakerTech::Midas::FormHelper`
+# @since 0.1.0
+class WhittakerTech::Midas::Engine < Rails::Engine
+  isolate_namespace WhittakerTech::Midas
 
-      config.eager_load_paths += Dir["#{config.root}/app/models"]
+  config.eager_load_paths += Dir["#{config.root}/app/models"]
 
-      initializer 'midas.helpers' do
-        ActiveSupport.on_load(:action_view) do
-          include WhittakerTech::Midas::FormHelper
-        end
-      end
-
-      rake_tasks do
-        tasks_path = root.join('tasks/**/*.rake')
-        Dir[tasks_path].each { |file| load file }
-      end
+  initializer 'midas.helpers' do
+    ActiveSupport.on_load(:action_view) do
+      include WhittakerTech::Midas::FormHelper
     end
   end
+
+  rake_tasks do
+    tasks_path = root.join('tasks/**/*.rake')
+    Dir[tasks_path].each { |file| load file }
+  end
 end

data/lib/whittaker_tech/midas/version.rb

@@ -1,5 +1,5 @@
-module WhittakerTech
-  module Midas
-    VERSION = '0.1.1'.freeze
-  end
+module WhittakerTech; end
+
+module WhittakerTech::Midas
+  VERSION = '0.3.0'.freeze
 end

data/lib/whittaker_tech/midas.rb

@@ -1,11 +1,128 @@
 # frozen_string_literal: true
 
 require 'whittaker_tech/midas/version'
+require 'whittaker_tech/midas/deprecation'
 require 'whittaker_tech/midas/engine'
 require 'money'
+require 'poly'
 
-module WhittakerTech
-  module Midas
-    # Your code goes here...
+# WhittakerTech::Midas is a Rails engine for multi-currency monetary value
+# management. It replaces scattered `*_cents` and `*_currency` columns with a
+# single polymorphic `Coin` model backed by a centralized `midas_coins`
+# table.
+#
+# ## Configuration
+#
+# ### Table namespace (PostgreSQL schema)
+#
+# By default all coins are stored in `midas_coins`. To place the table
+# inside a PostgreSQL schema set `table_namespace` in an initializer:
+#
+#   WhittakerTech::Midas.table_namespace = 'finance'
+#   # => table becomes finance.coins
+#
+# ### Bidirectional text
+#
+# Currency display direction defaults to LTR for every currency code.
+# Override individual currencies as needed:
+#
+#   WhittakerTech::Midas.currency_directions['ILS'] = :rtl
+#   WhittakerTech::Midas.currency_directions['AED'] = :rtl
+#
+# See also:
+#
+# - `Coin`
+# - `Coin::Arithmetic`
+# - `Bankable`
+# @since 0.1.0
+module WhittakerTech::Midas
+  # Rounding strategies available for division operations.
+  #
+  # Each value is a lambda that accepts a Float and returns a rounded value.
+  #
+  # Rounding keys:
+  #
+  # - `:round`: Round half-up (standard commercial rounding)
+  # - `:ceil`: Always round up (ceiling)
+  # - `:floor`: Always round down (floor / truncate)
+  # - `:bankers`: Round half-to-even (banker's rounding)
+  #
+  # @return [Hash{Symbol => Proc}]
+  ROUNDING_POLICIES = {
+    round: ->(v) { v.round },
+    ceil: ->(v) { v.ceil },
+    floor: ->(v) { v.floor },
+    bankers: ->(v) { v.round(0, half: :even) }
+  }.freeze
+
+  # The rounding policy applied when no explicit policy is supplied.
+  # @return [Symbol]
+  DEFAULT_ROUNDING_POLICY = :round
+
+  # Optional PostgreSQL schema name used to namespace the coins table.
+  #
+  # When `nil` (default) the table is created as `midas_coins`.
+  # When set, the table becomes `<namespace>.coins` and requires a PostgreSQL
+  # adapter.
+  #
+  # @return [String, nil]
+  mattr_accessor :table_namespace, default: nil
+
+  # Controls how deprecation notices are emitted.
+  #
+  # Allowed values:
+  #
+  # - `:warn`: Prints to STDERR via `Kernel.warn` (default)
+  # - `:raise`: Raises `Deprecation::DeprecationError`
+  # - `:silence`: Suppresses all notices
+  #
+  # @return [Symbol]
+  mattr_accessor :deprecation_behavior, default: :warn
+
+  # Resolves the fully-qualified table name for a given base name.
+  #
+  # @param name [String] base table name, e.g. `"coins"`
+  # @return [String] the namespaced table name
+  # @raise [RuntimeError] if `table_namespace` is set and the adapter is not PostgreSQL
+  def self.table_name(name)
+    return "midas_#{name}" if table_namespace.blank?
+
+    adapter = ActiveRecord::Base.connection.adapter_name
+    raise "WhittakerTech::Midas.table_namespace requires PostgreSQL (got #{adapter})" unless adapter == 'PostgreSQL'
+
+    "#{table_namespace}.#{name}"
+  end
+
+  # Per-currency display direction map. Defaults all currencies to `:ltr`.
+  #
+  # Modify to configure RTL currencies in your initializer:
+  #
+  #   WhittakerTech::Midas.currency_directions['ILS'] = :rtl
+  #
+  # @return [Hash{String => Symbol}] maps uppercased ISO currency code to `:ltr` or `:rtl`
+  def self.currency_directions
+    @currency_directions ||= Hash.new(:ltr)
+  end
+
+  # Returns the configured display direction for the given currency code.
+  #
+  # Falls back to `:ltr` for any currency not explicitly configured.
+  #
+  # @param currency_code [String] ISO 4217 currency code, e.g. `"USD"`
+  # @return [Symbol] `:ltr` or `:rtl`
+  def self.currency_direction_for(currency_code)
+    currency_directions[currency_code.to_s.upcase]
+  end
+
+  # Resets all mutable configuration to defaults.
+  #
+  # Intended for use in test suite `after` blocks when specs mutate
+  # engine-level configuration.
+  #
+  # @return [void]
+  def self.reset_configuration!
+    self.table_namespace      = nil
+    self.deprecation_behavior = :warn
+    @currency_directions      = nil
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whittaker_tech-midas
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Lee Whittaker
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 6.19.0
+- !ruby/object:Gem::Dependency
+  name: poly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -135,6 +163,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   WhittakerTech Midas is a Rails engine that provides elegant multi-currency support
   through a single polymorphic Coin model. Instead of adding price_cents/price_currency
@@ -160,13 +216,26 @@ files:
 - app/models/concerns/whittaker_tech/midas/bankable.rb
 - app/models/whittaker_tech/midas/application_record.rb
 - app/models/whittaker_tech/midas/coin.rb
+- app/models/whittaker_tech/midas/coin/allocation.rb
+- app/models/whittaker_tech/midas/coin/arithmetic.rb
+- app/models/whittaker_tech/midas/coin/bidi.rb
+- app/models/whittaker_tech/midas/coin/converter.rb
+- app/models/whittaker_tech/midas/coin/converter/bank_provider.rb
+- app/models/whittaker_tech/midas/coin/parser.rb
+- app/models/whittaker_tech/midas/coin/presenter.rb
+- app/models/whittaker_tech/midas/exchange.rb
 - app/views/layouts/whittaker_tech/midas/application.html.erb
 - app/views/layouts/whittaker_tech/midas/shared/_currency_field.html.erb
 - config/locales/midas.en.yml
-- db/migrate/create_wt_midas_coins.rb
+- db/migrate/20260101000000_create_whittaker_tech_schema.rb
+- db/migrate/20260101000001_create_midas_coins.rb
+- db/migrate/20260219120000_rename_resource_label_to_resource_role_in_wt_midas_coins.rb
+- db/migrate/20260219150000_rename_wt_midas_coins_to_midas_coins.rb
+- db/migrate/20260707000000_create_midas_exchanges.rb
 - lib/generators/whittaker_tech/midas/install/install_generator.rb
 - lib/tasks/whittaker_tech/midas_tasks.rake
 - lib/whittaker_tech/midas.rb
+- lib/whittaker_tech/midas/deprecation.rb
 - lib/whittaker_tech/midas/engine.rb
 - lib/whittaker_tech/midas/version.rb
 homepage: https://github.com/whittakertech/midas
@@ -185,7 +254,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="