plutonium 0.13.3 → 0.14.1

data/lib/plutonium/reloader.rb

@@ -1,15 +1,21 @@
-require "active_support/notifications"
+# frozen_string_literal: true
 
-# Be sure to restart your server when you modify this file.
+require "active_support/notifications"
 
 module Plutonium
+  # Reloader class for Plutonium
+  #
+  # This class is responsible for managing the reloading of Plutonium components
+  # and related files during development.
   class Reloader
     class << self
+      # Start the reloader
+      #
+      # @return [void]
       def start!
         puts "=> [plutonium] starting reloader"
 
         ActiveSupport::Notifications.instrument("plutonium.reloader.start") do
-          # Task code here
           @listener&.stop
           @listener = initialize_listener
         end
@@ -17,34 +23,46 @@ module Plutonium
 
       private
 
+      # Initialize the file listener
+      #
+      # @return [Listen::Listener, nil] the initialized listener or nil if no paths to watch
       def initialize_listener
         require "listen"
 
         reload_paths = gather_reload_paths
-        return unless reload_paths.any?
+        return if reload_paths.empty?
 
-        listener = Listen.to(*reload_paths, only: /\.rb$/) do |modified, added, removed|
+        Listen.to(*reload_paths, only: /\.rb$/) { |modified, added, removed|
           handle_file_changes(modified, added, removed)
-        end
-        listener.start
-        listener
+        }.tap(&:start)
       end
 
+      # Gather paths to be watched for changes
+      #
+      # @return [Array<String>] list of paths to watch
       def gather_reload_paths
         reload_paths = []
 
-        if Plutonium.development?
-          reload_paths << Plutonium.lib_root.to_s
-          reload_paths << Plutonium.root.join("app", "views", "components").to_s
-          reload_paths << Plutonium.root.join("config", "initializers").to_s
+        if Plutonium.configuration.development?
+          reload_paths.concat([
+            Plutonium.lib_root.to_s,
+            Plutonium.root.join("app", "views", "components").to_s,
+            Plutonium.root.join("config", "initializers").to_s
+          ])
         end
 
-        packages_dir = Rails.root.join("packages/").to_s
+        packages_dir = Rails.root.join("packages").to_s
         reload_paths << packages_dir if File.directory?(packages_dir)
 
         reload_paths
       end
 
+      # Handle file changes detected by the listener
+      #
+      # @param modified [Array<String>] list of modified files
+      # @param added [Array<String>] list of added files
+      # @param removed [Array<String>] list of removed files
+      # @return [void]
       def handle_file_changes(modified, added, removed)
         (modified + added).each do |file|
           Plutonium.logger.debug "[plutonium] change detected: #{file}"
@@ -62,46 +80,70 @@ module Plutonium
         end
       end
 
+      # Check if the file is within the packages directory
+      #
+      # @param file [String] path to the file
+      # @return [Boolean] true if the file is within the packages directory
       def file_starts_with_packages_dir?(file)
-        packages_dir = Rails.root.join("packages/").to_s
-        file.starts_with?(packages_dir)
+        file.start_with?(Rails.root.join("packages").to_s)
       end
 
+      # Handle changes to files within the packages directory
+      #
+      # @param file [String] path to the changed file
+      # @param added [Array<String>] list of added files
+      # @return [void]
       def handle_package_file_changes(file, added)
         return if added.include?(file)
 
         case File.basename(file)
         when "engine.rb"
           reload_engine_and_routes(file)
-        else
-          # Non-engine package files are reloaded by Rails automatically
         end
       end
 
+      # Reload engine and routes
+      #
+      # @param file [String] path to the engine file
+      # @return [void]
       def reload_engine_and_routes(file)
         Plutonium.logger.debug "[plutonium] reloading: engine+routes"
         load file
         Rails.application.reload_routes!
       end
 
+      # Reload the framework and file
+      #
+      # @param file [String] path to the file
+      # @return [void]
       def reload_framework_and_file(file)
-        # # Ensure that the file loads correctly before we do any reloading
-        # load file
-
         Plutonium.logger.debug "[plutonium] reloading: app+framework"
         Rails.application.reloader.reload!
         Plutonium::ZEITWERK_LOADER.reload
-        # reload components
+        reload_components
+      end
+
+      # Reload components
+      #
+      # @return [void]
+      def reload_components
         Object.send(:remove_const, "PlutoniumUi")
         load Plutonium.root.join("app", "views", "components", "base.rb")
-        # # Ensure files that do not contain constants are loaded again e.g. initializers
-        # load file
       end
 
+      # Reload a single file
+      #
+      # @param file [String] path to the file
+      # @return [Boolean] true if the file was successfully loaded
       def reload_file(file)
-        load file
+        load(file)
       end
 
+      # Log reload failure
+      #
+      # @param file [String] path to the file that failed to reload
+      # @param error [StandardError] the error that occurred during reloading
+      # @return [void]
       def log_reload_failure(file, error)
         Plutonium.logger.error "\n[plutonium] reloading failed\n\n#{error.message}\n"
       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.3"
+  VERSION = "0.14.1"
 end