plutonium 0.13.2 → 0.14.0

data/lib/plutonium/railtie.rb

@@ -1,45 +1,88 @@
+# frozen_string_literal: true
+
 require "view_component"
 
 module Plutonium
+  # Plutonium::Railtie integrates Plutonium with Rails applications.
+  #
+  # 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 = defined?(Rails.env) && !Rails.env.development?
-    config.plutonium.enable_hotreload = defined?(Rails.env) && Rails.env.development?
+    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),
     # you can do this in an intiailzer:
     #
     # config.after_initialize do
     #   config.assets.precompile -= Plutonium::Railtie::PRECOMPILE_ASSETS
     # end
-    PRECOMPILE_ASSETS = %w[plutonium.js plutonium.js.map plutonium.min.js plutonium.min.js.map plutonium.css plutonium.png plutonium.ico]
+    PRECOMPILE_ASSETS = %w[
+      plutonium.js plutonium.js.map plutonium.min.js plutonium.min.js.map
+      plutonium.css plutonium.png plutonium.ico
+    ].freeze
 
     initializer "plutonium.assets" do
-      next unless Rails.application.config.respond_to?(:assets)
+      setup_asset_pipeline if Rails.application.config.respond_to?(:assets)
+    end
+
+    initializer "plutonium.load_components" do
+      load_base_component
+    end
+
+    initializer "plutonium.initializers" do
+      load_plutonium_initializers
+    end
+
+    initializer "plutonium.asset_server" do
+      setup_development_asset_server if Plutonium.development?
+    end
+
+    initializer "plutonium.view_components_capture_compat" do
+      config.view_component.capture_compatibility_patch_enabled = true
+    end
+
+    initializer "plutonium.action_dispatch_extensions" do
+      extend_action_dispatch
+    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?
+    end
+
+    private
+
+    def setup_asset_pipeline
       Rails.application.config.assets.precompile += PRECOMPILE_ASSETS
       Rails.application.config.assets.paths << Plutonium.root.join("app/assets").to_s
     end
 
-    initializer "plutonium.load_components" do
+    def load_base_component
       load Plutonium.root.join("app", "views", "components", "base.rb")
     end
 
-    initializer "plutonium.initializers" do
+    def load_plutonium_initializers
       Dir.glob(Plutonium.root.join("config", "initializers", "**", "*.rb")) { |file| load file }
     end
 
-    initializer "plutonium.asset_server" do
-      next unless Plutonium.development?
-
+    def setup_development_asset_server
       puts "=> [plutonium] starting assets server"
-      # setup a middleware to serve our assets
       config.app_middleware.insert_before(
         ActionDispatch::Static,
         Rack::Static,
@@ -47,23 +90,15 @@ module Plutonium
         root: Plutonium.root.join("src").to_s,
         cascade: true,
         header_rules: [
-          # Cache all static files in public caches (e.g. Rack::Cache) as well as in the browser
           [:all, {"cache-control" => "public, max-age=31536000"}]
         ]
       )
     end
 
-    initializer "plutonium.view_components_capture_compat" do
-      config.view_component.capture_compatibility_patch_enabled = true
-    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?
+    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
   end
 end

data/lib/plutonium/resource/controller.rb

@@ -123,7 +123,7 @@ module Plutonium
 
         @current_parent ||= begin
           parent_route_key = parent_route_param.to_s.gsub(/_id$/, "").to_sym
-          parent_class = current_engine.registered_resource_route_key_lookup[parent_route_key]
+          parent_class = current_engine.resource_register.route_key_lookup[parent_route_key]
           parent_scope = parent_class.from_path_param(params[parent_route_param])
           parent_scope = parent_scope.associated_with(current_scoped_entity) if scoped_to_entity?
           parent_scope.first!

data/lib/plutonium/resource_register.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Plutonium
+  # ResourceRegister manages the registration and lookup of resources.
+  class ResourceRegister
+    include Plutonium::SmartCache
+    include Concerns::ResourceValidatable
+
+    # Custom error class for frozen register operations
+    class FrozenRegisterError < StandardError; end
+
+    def initialize
+      @resources = Set.new
+      @frozen = false
+    end
+
+    # Registers a new resource with the register.
+    #
+    # @param resource [Class] The resource class to be registered.
+    # @raise [Plutonium::Concerns::ResourceValidatable::InvalidResourceError] If the resource is not a valid Plutonium::Resource::Record.
+    # @raise [FrozenRegisterError] If the register is frozen.
+    # @return [void]
+    def register(resource)
+      raise FrozenRegisterError, "Cannot modify frozen resource register" if @frozen
+
+      validate_resource!(resource)
+      @resources.add(resource.to_s)
+    end
+
+    # Returns an array of all registered resource classes and freezes the register.
+    #
+    # @return [Array<Class>] An array of registered resource classes.
+    def resources
+      freeze
+      @resources.map(&:constantize)
+    end
+    memoize_unless_reloading :resources
+
+    # Returns a hash mapping route keys to their corresponding resource classes.
+    # This method will freeze the register if it hasn't been frozen already.
+    #
+    # @return [Hash{Symbol => Class}] A hash where keys are route keys and values are resource classes.
+    def route_key_lookup
+      freeze
+      resources.to_h do |resource|
+        [resource.model_name.singular_route_key.to_sym, resource]
+      end
+    end
+    memoize_unless_reloading :route_key_lookup
+
+    # Clears all registered resources and invalidates the cache.
+    #
+    # @return [void]
+    def clear
+      @resources.clear
+      @frozen = false
+      invalidate_cache
+    end
+
+    # Checks if the register is frozen.
+    #
+    # @return [Boolean] True if the register is frozen, false otherwise.
+    def frozen?
+      @frozen
+    end
+
+    private
+
+    # Freezes the register
+    #
+    # @return [Boolean] Always returns true
+    def freeze
+      @frozen ||= true
+    end
+
+    # Invalidates the memoization cache
+    #
+    # @return [void]
+    def invalidate_cache
+      flush_smart_cache
+    end
+  end
+end

data/lib/plutonium/routing/mapper_extensions.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Routing
+    # MapperExtensions module provides additional functionality for route mapping in Plutonium applications.
+    #
+    # This module extends the functionality of Rails' routing mapper to support Plutonium-specific features,
+    # such as resource registration and custom route materialization.
+    #
+    # @example Usage in a Rails routes file
+    #   Blorgh::Engine.routes.draw do
+    #     register_resource SomeModel
+    #   end
+    module MapperExtensions
+      # Registers a resource for routing and sets up associated routes.
+      #
+      # @param resource [Class] The resource class to be registered.
+      # @param options [Hash] Additional options for resource registration.
+      # @yield An optional block for additional resource configuration.
+      # @return [void]
+      def register_resource(resource, options = {}, &)
+        route_config = route_set.register_resource(resource, &)
+        define_resource_routes(route_config, resource)
+        resource_route_concern_names << route_config[:concern_name]
+      end
+
+      private
+
+      # @return [Array<Symbol>] Names of resource route concerns.
+      def resource_route_concern_names
+        @resource_route_concern_names ||= []
+      end
+
+      # Sets up shared concerns for interactive resource actions.
+      #
+      # @return [void]
+      def setup_shared_resource_concerns
+        concern :interactive_resource_actions do
+          define_member_interactive_actions
+          define_collection_interactive_actions
+        end
+      end
+
+      # Materializes all registered resource routes.
+      #
+      # @return [void]
+      def materialize_resource_routes
+        engine = route_set.engine
+        scope_params = determine_scope_params(engine)
+
+        scope scope_params[:name], scope_params[:options] do
+          concerns resource_route_concern_names.sort
+        end
+      end
+
+      # @return [ActionDispatch::Routing::RouteSet] The current route set.
+      def route_set
+        @set
+      end
+
+      # Defines routes for a registered resource.
+      #
+      # @param route_config [Hash] Configuration for the resource routes.
+      # @param resource [Class] The resource class.
+      # @return [void]
+      def define_resource_routes(route_config, resource)
+        concern route_config[:concern_name] do
+          resources route_config[:route_name], **route_config[:route_options] do
+            instance_exec(&route_config[:block]) if route_config[:block]
+            define_nested_resource_routes(resource)
+          end
+        end
+      end
+
+      # Defines nested resource routes for a given resource.
+      #
+      # @param resource [Class] The parent resource class.
+      # @return [void]
+      def define_nested_resource_routes(resource)
+        nested_configs = route_set.resource_route_config_for(*resource.has_many_association_routes)
+        nested_configs.each do |nested_config|
+          resources nested_config[:route_name], **nested_config[:route_options] do
+            instance_exec(&nested_config[:block]) if nested_config[:block]
+          end
+        end
+      end
+
+      # Defines member-level interactive actions.
+      #
+      # @return [void]
+      def define_member_interactive_actions
+        member do
+          get "record_actions/:interactive_action", action: :begin_interactive_resource_record_action,
+            as: :interactive_resource_record_action
+          post "record_actions/:interactive_action", action: :commit_interactive_resource_record_action
+        end
+      end
+
+      # Defines collection-level interactive actions.
+      #
+      # @return [void]
+      def define_collection_interactive_actions
+        collection do
+          get "collection_actions/:interactive_action", action: :begin_interactive_resource_collection_action,
+            as: :interactive_resource_collection_action
+          post "collection_actions/:interactive_action", action: :commit_interactive_resource_collection_action
+
+          get "recordless_actions/:interactive_action", action: :begin_interactive_resource_recordless_action,
+            as: :interactive_resource_recordless_action
+          post "recordless_actions/:interactive_action", action: :commit_interactive_resource_recordless_action
+        end
+      end
+
+      # Determines the scope parameters based on the engine configuration.
+      #
+      # @param engine [Class] The current engine.
+      # @return [Hash] Scope name and options.
+      def determine_scope_params(engine)
+        scoped_entity_param_key = engine.scoped_entity_param_key if engine.scoped_entity_strategy == :path
+        {
+          name: scoped_entity_param_key.present? ? ":#{scoped_entity_param_key}" : "",
+          options: scoped_entity_param_key.present? ? {as: scoped_entity_param_key} : {}
+        }
+      end
+    end
+  end
+end

data/lib/plutonium/routing/resource_registration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Routing
+    # The ResourceRegistration module provides functionality for registering and managing resources
+    module ResourceRegistration
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def resource_register
+          @resource_register ||= Plutonium::ResourceRegister.new
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/routing/route_set_extensions.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Routing
+    # RouteSetExtensions module provides additional functionality for route management in Plutonium applications.
+    #
+    # This module extends the functionality of Rails' routing system to support Plutonium-specific features,
+    # such as resource registration and custom route drawing.
+    #
+    # @example Usage in a Rails application
+    #   Blorgh::Engine.routes.draw do
+    #     register_resource SomeModel
+    #   end
+    module RouteSetExtensions
+      # Clears all registered resources and route configurations.
+      #
+      # This method should be called when you want to reset all registered resources
+      # and start with a clean slate for route definition.
+      #
+      # @return [void]
+      def clear!
+        resource_route_config_lookup.clear
+        engine.resource_register.clear
+        super
+      end
+
+      # Draws routes with additional Plutonium-specific setup and resource materialization.
+      #
+      # @param block [Proc] The block containing route definitions.
+      # @return [void]
+      # @yield Executes the given block in the context of route drawing.
+      def draw(&block)
+        if supported_engine?
+          ActiveSupport::Notifications.instrument("plutonium.resource_routes.draw", app: engine.to_s) do
+            super do
+              setup_shared_resource_concerns
+              instance_exec(&block)
+              materialize_resource_routes
+            end
+          end
+        else
+          super(&block)
+        end
+      end
+
+      # Registers a resource for routing.
+      #
+      # @param resource [Class] The resource class to be registered.
+      # @yield An optional block for additional resource configuration.
+      # @return [Hash] The configuration for the registered resource.
+      # @raise [ArgumentError] If the engine doesn't support Plutonium::Pkg::App.
+      def register_resource(resource, &)
+        validate_engine!
+        engine.resource_register.register(resource)
+
+        route_name = resource.model_name.plural
+        concern_name = :"#{route_name}_routes"
+
+        config = create_resource_config(resource, route_name, concern_name, &)
+        resource_route_config_lookup[route_name] = config
+
+        config
+      end
+
+      # Retrieves the route configuration for specified routes.
+      #
+      # @param routes [Array<Symbol>] The route names to fetch configurations for.
+      # @return [Array<Hash>] An array of route configurations.
+      def resource_route_config_for(*routes)
+        routes = Array(routes)
+        resource_route_config_lookup.slice(*routes).values
+      end
+
+      # Returns the current engine for the routes.
+      #
+      # @return [Class] The engine class (Rails application or custom engine).
+      def engine
+        @engine ||= determine_engine
+      end
+
+      private
+
+      # @return [Hash] A lookup table for resource route configurations.
+      def resource_route_config_lookup
+        @resource_route_config_lookup ||= {}
+      end
+
+      # Validates that the current engine supports Plutonium features.
+      #
+      # @raise [ArgumentError] If the engine doesn't include Plutonium::Pkg::App.
+      # @return [void]
+      def validate_engine!
+        raise ArgumentError, "#{engine} must include Plutonium::Pkg::App to register resources" unless supported_engine?
+      end
+
+      # Checks if the current engine supports Plutonium features.
+      #
+      # @return [Boolean] True if the engine includes Plutonium::Pkg::App, false otherwise.
+      def supported_engine?
+        engine.include?(Plutonium::Pkg::App)
+      end
+
+      # Determines the appropriate engine based on the current scope.
+      #
+      # @return [Class] The determined engine class.
+      def determine_engine
+        engine_module = default_scope&.fetch(:module)
+        engine_module.present? ? "#{engine_module.camelize}::Engine".constantize : Rails.application.class
+      end
+
+      # Creates a resource configuration hash.
+      #
+      # @param resource_name [String] The name of the resource.
+      # @param route_name [String] The pluralized name for routes.
+      # @param concern_name [Symbol] The name of the concern for this resource.
+      # @yield An optional block for additional resource configuration.
+      # @return [Hash] The complete resource configuration.
+      def create_resource_config(resource, route_name, concern_name, &block)
+        {
+          route_name: route_name,
+          concern_name: concern_name,
+          route_options: {
+            controller: resource.to_s.pluralize.underscore,
+            path: resource.model_name.collection,
+            concerns: %i[interactive_resource_actions]
+          },
+          block: block
+        }
+      end
+    end
+  end
+end

data/lib/plutonium/smart_cache.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Plutonium
+  # 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::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
+
+    included do
+      class_attribute :_memoized_results, instance_writer: false, default: Concurrent::Map.new
+    end
+
+    # 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
+    #
+    # @note This method uses Rails.application.config.cache_classes
+    #       to determine whether to cache or not. When cache_classes is false
+    #       (typical in development), it will always yield to get a fresh result.
+    #       When true (typical in production), it will use the cache.
+    def cache_unless_reloading(cache_key, &block)
+      return yield unless should_cache?
+
+      @cached_results ||= Concurrent::Map.new
+      @cached_results.compute_if_absent(cache_key) { 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
+    #
+    # @note This method clears both inline caches and memoized method results.
+    def flush_smart_cache(keys = nil)
+      keys = Array(keys).map(&:to_sym)
+      if keys.present?
+        @cached_results&.delete_if { |k, _| keys.include?(k.to_sym) }
+        keys.each { |key| self.class._memoized_results.delete(key) }
+      else
+        @cached_results&.clear
+        self.class._memoized_results.clear
+      end
+    end
+
+    # Determines whether caching should be performed based on the current Rails configuration.
+    #
+    # @return [Boolean] true if caching should be performed, false otherwise
+    # @note This method uses Rails.application.config.cache_classes to determine caching behavior.
+    #       When cache_classes is false (typical in development), it returns false.
+    #       When true (typical in production), it returns true.
+    def should_cache?
+      Rails.application.config.cache_classes
+    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::SmartCache
+      #
+      #     def expensive_full_name_calculation
+      #       # Complex name calculation
+      #     end
+      #     memoize_unless_reloading :expensive_full_name_calculation
+      #   end
+      #
+      # @note This method uses Rails.application.config.cache_classes to determine
+      #       whether to memoize or not. When cache_classes is false (typical in development),
+      #       it will always call the original method. When true (typical in production),
+      #       it will use memoization, caching results for each unique set of arguments.
+      def memoize_unless_reloading(method_name)
+        original_method = instance_method(method_name)
+        define_method(method_name) do |*args|
+          if should_cache?
+            cache = self.class._memoized_results[method_name] ||= Concurrent::Map.new
+            cache.compute_if_absent(args.hash.to_s) { original_method.bind_call(self, *args) }
+          else
+            original_method.bind_call(self, *args)
+          end
+        end
+      end
+    end
+  end
+
+  # Configuration:
+  #  The caching behavior is controlled by the Rails configuration option config.cache_classes:
+  #
+  #  - 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 may want to control caching behavior explicitly.
+  #  - You can mock or stub Rails.application.config.cache_classes or override should_cache? as needed in your tests.
+end

data/lib/plutonium/version.rb

@@ -1,3 +1,3 @@
 module Plutonium
-  VERSION = "0.13.2"
+  VERSION = "0.14.0"
 end