plutonium 0.14.0 → 0.15.0.pre.rc1

data/lib/plutonium/lib/smart_cache.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Lib
+    # The SmartCache module provides flexible caching mechanisms for classes and objects,
+    # allowing for both inline caching and method-level memoization.
+    #
+    # This module is designed to optimize performance by caching results
+    # when class caching is enabled (typically in production),
+    # while ensuring fresh results when caching is disabled (typically in development).
+    #
+    # This implementation is thread-safe.
+    #
+    # @example Including SmartCache in a class
+    #   class MyClass
+    #     include Plutonium::Lib::SmartCache
+    #
+    #     def my_method(arg)
+    #       cache_unless_reloading("my_method_#{arg}") { expensive_operation(arg) }
+    #     end
+    #
+    #     def another_method(arg)
+    #       # Method implementation
+    #     end
+    #     memoize_unless_reloading :another_method
+    #   end
+    module SmartCache
+      extend ::ActiveSupport::Concern
+
+      # Class-level thread-local storage for force caching (useful for testing)
+      thread_mattr_accessor :force_caching
+
+      included do
+        mattr_accessor :_smart_cache, instance_writer: false, default: Concurrent::Map.new
+      end
+
+      private
+
+      # Caches the result of the given block unless class caching is disabled.
+      #
+      # @param cache_key [String] A unique key to identify the cached result
+      # @yield The block whose result will be cached
+      # @return [Object] The result of the block, either freshly computed or from cache
+      #
+      # @example Using cache_unless_reloading inline
+      #   def fetch_user_data(user_id)
+      #     cache_unless_reloading("user_data_#{user_id}") do
+      #       UserDataService.fetch(user_id)
+      #     end
+      #   end
+      def cache_unless_reloading(cache_key, &block)
+        return yield unless should_smart_cache?
+
+        self.class._smart_cache.compute_if_absent(cache_key.to_sym) { yield }
+      end
+
+      # Flushes the smart cache for the specified keys or all keys if none are specified.
+      #
+      # @param keys [Array<Symbol, String>, Symbol, String] The cache key(s) to flush
+      # @return [void]
+      #
+      # @example Flushing specific cache keys
+      #   flush_smart_cache([:user_data, :product_list])
+      #
+      # @example Flushing all cache keys
+      #   flush_smart_cache
+      def flush_smart_cache(keys = nil)
+        self.class.flush_smart_cache(keys)
+      end
+
+      # Determines whether caching should be performed based on the current Rails configuration
+      # or the force_caching flag.
+      #
+      # @return [Boolean] true if caching should be performed, false otherwise
+      def should_smart_cache?
+        Plutonium::Lib::SmartCache.force_caching.nil? ? Rails.application.config.cache_classes : Plutonium::Lib::SmartCache.force_caching
+      end
+
+      class_methods do
+        # Memoizes the result of the specified method unless class caching is disabled.
+        #
+        # @param method_name [Symbol] The name of the method to memoize
+        # @return [void]
+        #
+        # @example Memoizing a method
+        #   class User
+        #     include Plutonium::Lib::SmartCache
+        #
+        #     def expensive_full_name_calculation
+        #       # Complex name calculation
+        #     end
+        #     memoize_unless_reloading :expensive_full_name_calculation
+        #   end
+        def memoize_unless_reloading(method_name)
+          return if method_defined?(:"#{method_name}_without_memoization")
+
+          original_method = instance_method(method_name)
+          alias_method :"#{method_name}_without_memoization", method_name
+
+          define_method(method_name) do |*args|
+            if should_smart_cache?
+              cache = self.class._smart_cache.compute_if_absent(method_name.to_sym) { Concurrent::Map.new }
+              if args.empty?
+                cache.compute_if_absent(:no_args) { original_method.bind_call(self) }
+              else
+                cache.compute_if_absent(args.hash.to_s) { original_method.bind_call(self, *args) }
+              end
+            else
+              original_method.bind_call(self, *args)
+            end
+          end
+        end
+
+        # Flushes the smart cache for the specified keys or all keys if none are specified.
+        #
+        # @param keys [Array<Symbol, String>, Symbol, String] The cache key(s) to flush
+        # @return [void]
+        #
+        # @example Flushing specific cache keys
+        #   flush_smart_cache([:user_data, :product_list])
+        #
+        # @example Flushing all cache keys
+        #   flush_smart_cache
+        def flush_smart_cache(keys = nil)
+          keys = Array(keys).map(&:to_sym)
+          if keys.present?
+            keys.each { |key| _smart_cache.delete(key) }
+          else
+            _smart_cache.clear
+          end
+        end
+      end
+    end
+
+    # Configuration:
+    #  The caching behavior is controlled by the Rails configuration option config.cache_classes
+    #  or can be overridden using the SmartCache.force_caching flag:
+    #
+    #  - When false (typical in development):
+    #    - Classes are reloaded on each request.
+    #    - cache_unless_reloading always yields fresh results.
+    #    - memoize_unless_reloading always calls the original method.
+    #
+    #  - When true (typical in production):
+    #    - Classes are cached.
+    #    - cache_unless_reloading uses cached results.
+    #    - memoize_unless_reloading uses memoized results, caching for each unique set of arguments.
+    #
+    # Best Practices:
+    #  - Use meaningful and unique cache keys to avoid collisions.
+    #  - Be mindful of memory usage, especially with large cached results.
+    #  - Consider cache expiration strategies for long-running processes.
+    #  - Use cache_unless_reloading for fine-grained control within methods.
+    #  - Use memoize_unless_reloading for entire methods, especially those with expensive computations.
+    #
+    # Thread Safety:
+    #  - This implementation is thread-safe.
+    #  - It uses Concurrent::Map from the concurrent-ruby gem for thread-safe caching.
+    #
+    # Testing:
+    #  - In your test environment, you can control caching behavior explicitly using SmartCache.force_caching.
+    #  - Example:
+    #      describe "MyClass" do
+    #        before { Plutonium::Lib::SmartCache.force_caching = true }
+    #        after { Plutonium::Lib::SmartCache.force_caching = nil }
+    #        it "caches results" do
+    #          # Test caching behavior
+    #        end
+    #      end
+  end
+end

data/lib/plutonium/models/has_cents.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Models
+    # HasCents module provides functionality to handle monetary values stored as cents
+    # and expose them as decimal values. It also ensures that validations applied to
+    # the cents attribute are inherited by the decimal attribute.
+    #
+    # @example Usage
+    #   class Product < ApplicationRecord
+    #     include Plutonium::Models::HasCents
+    #
+    #     has_cents :price_cents
+    #     has_cents :cost_cents, name: :wholesale_price, rate: 1000
+    #     has_cents :quantity_cents, name: :quantity, rate: 1
+    #     has_cents :total_cents, suffix: "value"
+    #
+    #     validates :price_cents, numericality: { greater_than_or_equal_to: 0 }
+    #   end
+    #
+    # @example Basic Usage
+    #   product = Product.new(price: 10.99)
+    #
+    #   product.price_cents #=> 1099
+    #   product.price #=> 10.99
+    #
+    #   product.wholesale_price = 5.5
+    #   product.cost_cents #=> 5500
+    #
+    #   product.quantity = 3
+    #   product.quantity_cents #=> 3
+    #
+    # @example Truncation
+    #   product.price = 10.991
+    #   product.price_cents #=> 1099
+    #
+    #   product.price = 10.995
+    #   product.price_cents #=> 1099
+    #
+    #   product.price = 10.999
+    #   product.price_cents #=> 1099
+    #
+    #   product.total_value = 100.50
+    #   product.total_cents #=> 10050
+    #
+    # @example Validation Inheritance
+    #   product = Product.new(price: -10.99)
+    #   product.valid? #=> false
+    #   product.errors[:price_cents] #=> ["must be greater than or equal to 0"]
+    #   product.errors[:price] #=> ["is invalid"]
+    #
+    # @example Reflection
+    #   Product.has_cents_attributes
+    #   #=> {
+    #   #     price_cents: { name: :price, rate: 100 },
+    #   #     cost_cents: { name: :wholesale_price, rate: 1000 },
+    #   #     quantity_cents: { name: :quantity, rate: 1 },
+    #   #     total_cents: { name: :total_value, rate: 100 }
+    #   #   }
+    #
+    #   Product.has_cents_attribute?(:price_cents) #=> true
+    #   Product.has_cents_attribute?(:name) #=> false
+    #   Product.has_cents_attributes[:cost_cents] #=> {name: :wholesale_price, rate: 1000}
+    #
+    # @note This module automatically handles validation propagation. If a validation error
+    #   is applied to the cents attribute, the decimal attribute will be marked as invalid.
+    #
+    # @note The module uses BigDecimal for internal calculations to ensure precision
+    #   in monetary operations.
+    #
+    # @see ClassMethods#has_cents for details on setting up attributes
+    module HasCents
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :has_cents_attributes, instance_writer: false, default: {}
+      end
+
+      module ClassMethods
+        # # Inherit validations from cents attribute to decimal attribute
+        # def validate(*args, &block)
+        #   options = args.extract_options!
+        #   Array(options[:attributes]).each do |attribute|
+        #     attribute = attribute.to_sym
+        #     if has_cents_attribute?(attribute)
+        #       decimal_attribute = has_cents_attributes[attribute][:name]
+        #       options[:attributes] += [decimal_attribute]
+        #       args = args.map do |validator|
+        #         if validator.respond_to?(:attributes)
+        #           validator.instance_variable_set(:@attributes, validator.attributes + [decimal_attribute])
+        #           _validators[decimal_attribute] << validator
+        #           validator
+        #         end
+        #       end
+        #     end
+        #   end
+
+        #   super(*args, options, &block)
+        # end
+        # Defines getter and setter methods for a monetary value stored as cents,
+        # and ensures validations are applied to both cents and decimal attributes.
+        #
+        # @param cents_name [Symbol] The name of the attribute storing the cents value.
+        # @param name [Symbol, nil] The name for the generated methods. If nil, it's derived from cents_name.
+        # @param rate [Integer] The conversion rate from the decimal value to cents (default: 100).
+        #   This represents how many cents are in one unit of the decimal value.
+        #   For example:
+        #   - rate: 100 for dollars/cents (1 dollar = 100 cents)
+        #   - rate: 1000 for dollars/mils (1 dollar = 1000 mils)
+        #   - rate: 1 for a whole number representation
+        # @param suffix [String] The suffix to append to the cents_name if name is not provided (default: "amount").
+        #
+        # @example Standard currency (dollars and cents)
+        #   has_cents :price_cents
+        #
+        # @example Custom rate for a different currency division
+        #   has_cents :amount_cents, name: :cost, rate: 1000
+        #
+        # @example Whole number storage without decimal places
+        #   has_cents :quantity_cents, name: :quantity, rate: 1
+        #
+        # @example Using custom suffix
+        #   has_cents :total_cents, suffix: "value"
+        def has_cents(cents_name, name: nil, rate: 100, suffix: "amount")
+          cents_name = cents_name.to_sym
+          name ||= cents_name.to_s.gsub(/_cents$/, "")
+          name = name.to_sym
+          name = (name == cents_name) ? :"#{cents_name}_#{suffix}" : name
+
+          self.has_cents_attributes = has_cents_attributes.merge(
+            cents_name => {name: name, rate: rate}
+          )
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            # Getter method for the decimal representation of the cents value.
+            #
+            # @return [BigDecimal, nil] The decimal value or nil if cents_name is not present.
+            def #{name}
+              #{cents_name}.to_d / #{rate} if #{cents_name}.present?
+            end
+
+            # Setter method for the decimal representation of the cents value.
+            #
+            # @param value [Numeric, nil] The decimal value to be set.
+            def #{name}=(value)
+              self.#{cents_name} = if value.present?
+                (BigDecimal(value.to_s) * #{rate}).to_i
+              end
+            end
+
+            # Mark decimal field as invalid if cents field is not valid
+            after_validation do
+              next unless errors[#{cents_name.inspect}].present?
+
+              errors.add(#{name.inspect}, :invalid)
+            end
+          RUBY
+        end
+
+        # Checks if a given attribute is defined with has_cents
+        #
+        # @param attribute [Symbol] The attribute to check
+        # @return [Boolean] true if the attribute is defined with has_cents, false otherwise
+        def has_cents_attribute?(attribute)
+          has_cents_attributes.key?(attribute.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/{pkg/base.rb → package/engine.rb}

@@ -1,6 +1,6 @@
 module Plutonium
-  module Pkg
-    module Base
+  module Package
+    module Engine
       extend ActiveSupport::Concern
 
       included do
@@ -16,6 +16,14 @@ module Plutonium
           end
           add_view_paths_initializer.instance_variable_set(:@block, ->(app) {})
         end
+
+        initializer :append_migrations do |app|
+          unless app.root.to_s.match root.to_s
+            config.paths["db/migrate"].expanded.each do |expanded_path|
+              app.config.paths["db/migrate"] << expanded_path
+            end
+          end
+        end
       end
     end
   end

data/lib/plutonium/{application → portal}/controller.rb

@@ -1,14 +1,10 @@
 module Plutonium
-  module Application
+  module Portal
     module Controller
       extend ActiveSupport::Concern
-      include Plutonium::Core::Controllers::Base
+      include Plutonium::Core::Controller
 
-      included do
-        helper_method :registered_resources
-      end
-
-      private
+      # private
 
       # # Menu Builder
       # def build_namespace_node(namespaces, resource, parent)
@@ -34,10 +30,6 @@ module Plutonium
       # def build_sidebar_menu
       #   build_namespace_tree(current_engine.resource_register)
       # end
-
-      def registered_resources
-        current_engine.resource_register.resources
-      end
     end
   end
 end

data/lib/plutonium/{application → portal}/dynamic_controllers.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 module Plutonium
-  module Application
+  module Portal
     # DynamicControllers module provides functionality for dynamically creating controller classes
     # when they are missing in the current module's namespace.
     #
     # @example Usage
     #   module MyApp
-    #     include Plutonium::Application::DynamicControllers
+    #     include Plutonium::Portal::DynamicControllers
     #   end
     #
     #   # Now, MyApp::SomeController will be dynamically created if it doesn't exist,
@@ -74,7 +74,7 @@ module Plutonium
           log_controller_creation(const_full_name, parent_controller)
           const_full_name.constantize
         rescue => e
-          Plutonium.logger.error "[plutonium] Failed to create dynamic controller: #{e.message}"
+          Plutonium.logger.error { "[plutonium] Failed to create dynamic controller: #{e.message}" }
           raise
         end
 
@@ -100,7 +100,7 @@ module Plutonium
         # @param const_full_name [String] The full name of the created controller
         # @param parent_controller [Class] The parent controller class
         def log_controller_creation(const_full_name, parent_controller)
-          Plutonium.logger.info "[plutonium] Dynamically created #{const_full_name} < #{parent_controller}"
+          Plutonium.logger.info { "[plutonium] Dynamically created #{const_full_name} < #{parent_controller}" }
         end
       end
     end

data/lib/plutonium/portal/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Portal
+    module Engine
+      extend ActiveSupport::Concern
+      include Plutonium::Engine
+      include Plutonium::Package::Engine
+
+      included do
+        isolate_namespace to_s.deconstantize.constantize
+      end
+    end
+  end
+end

data/lib/plutonium/railtie.rb

@@ -8,18 +8,6 @@ module Plutonium
   # This Railtie sets up configurations, initializers, and tasks for Plutonium
   # to work seamlessly within a Rails environment.
   class Railtie < Rails::Railtie
-    # Configuration options for Plutonium
-    config.plutonium = ActiveSupport::OrderedOptions.new
-    config.plutonium.cache_discovery = !Rails.env.development?
-    config.plutonium.enable_hotreload = Rails.env.development?
-
-    # Asset configuration
-    config.plutonium.assets = ActiveSupport::OrderedOptions.new
-    config.plutonium.assets.logo = "plutonium.png"
-    config.plutonium.assets.favicon = "plutonium.ico"
-    config.plutonium.assets.stylesheet = "plutonium.css"
-    config.plutonium.assets.script = "plutonium.min.js"
-
     # Assets to be precompiled
     #
     # If you don't want to precompile Plutonium's assets (eg. because you're using webpack),
@@ -33,6 +21,14 @@ module Plutonium
       plutonium.css plutonium.png plutonium.ico
     ].freeze
 
+    initializer "plutonium.base" do
+      Rails.application.class.include Plutonium::Engine
+    end
+
+    initializer "plutonium.deprecator" do |app|
+      app.deprecators[:plutonium] = Plutonium.deprecator
+    end
+
     initializer "plutonium.assets" do
       setup_asset_pipeline if Rails.application.config.respond_to?(:assets)
     end
@@ -46,7 +42,7 @@ module Plutonium
     end
 
     initializer "plutonium.asset_server" do
-      setup_development_asset_server if Plutonium.development?
+      setup_development_asset_server if Plutonium.configuration.development?
     end
 
     initializer "plutonium.view_components_capture_compat" do
@@ -57,13 +53,22 @@ module Plutonium
       extend_action_dispatch
     end
 
+    initializer "plutonium.active_record_extensions" do
+      extend_active_record
+    end
+
+    initializer "plutonium.phlexi_themes" do
+      setup_phlexi_themes
+    end
+
     rake_tasks do
       load "tasks/create_rodauth_admin.rake"
     end
 
     config.after_initialize do
-      Plutonium::Reloader.start! if Rails.application.config.plutonium.enable_hotreload
-      Plutonium::ZEITWERK_LOADER.eager_load if Rails.env.production?
+      Plutonium::Reloader.start! if Plutonium.configuration.enable_hotreload
+      Plutonium::Loader.eager_load if Rails.env.production?
+      ActionPolicy::PerThreadCache.enabled = !Rails.env.local?
     end
 
     private
@@ -95,10 +100,25 @@ module Plutonium
       )
     end
 
+    def setup_phlexi_themes
+      Rails.application.config.to_prepare do
+        Phlexi::Form::Theme.instance = Plutonium::UI::Form::Theme.instance
+        Phlexi::Display::Theme.instance = Plutonium::UI::Display::Theme.instance
+        Phlexi::Table::Theme.instance = Plutonium::UI::Table::Theme.instance
+        Phlexi::Table::DisplayTheme.instance = Plutonium::UI::Table::DisplayTheme.instance
+      end
+    end
+
     def extend_action_dispatch
       ActionDispatch::Routing::Mapper.prepend Plutonium::Routing::MapperExtensions
       ActionDispatch::Routing::RouteSet.prepend Plutonium::Routing::RouteSetExtensions
       Rails::Engine.include Plutonium::Routing::ResourceRegistration
     end
+
+    def extend_active_record
+      ActiveSupport.on_load(:active_record) do
+        include Plutonium::Resource::Record
+      end
+    end
   end
 end