plutonium 0.10.0 → 0.10.2

data/lib/plutonium/resource/policy.rb

@@ -1,108 +1,155 @@
 module Plutonium
   module Resource
+    # Policy class to define permissions and attributes for a resource
     class Policy
       include Plutonium::Policy::Initializer
 
       class Scope < Plutonium::Policy::Scope
       end
 
+      # Sends a method and raises an error if the method is not implemented
+      # @param [Symbol] method The method to send
       def send_with_report(method)
-        raise NotImplementedError, "#{self.class.name} does not implement the required #{method}" unless respond_to? method
+        unless respond_to?(method)
+          raise NotImplementedError, "#{self.class.name} does not implement the required #{method}"
+        end
 
-        send method
+        send(method)
       end
 
       # Core actions
 
+      # Checks if the create action is permitted
+      # @return [Boolean]
       def create?
         false
       end
 
+      # Checks if the read action is permitted
+      # @return [Boolean]
       def read?
         false
       end
 
+      # Checks if the update action is permitted
+      # @return [Boolean]
       def update?
         create?
       end
 
+      # Checks if the destroy action is permitted
+      # @return [Boolean]
       def destroy?
         create?
       end
 
       # Inferred actions
 
+      # Checks if the index action is permitted
+      # @return [Boolean]
       def index?
         read?
       end
 
+      # Checks if the new action is permitted
+      # @return [Boolean]
       def new?
         create?
       end
 
+      # Checks if the show action is permitted
+      # @return [Boolean]
       def show?
         read?
       end
 
+      # Checks if the edit action is permitted
+      # @return [Boolean]
       def edit?
         update?
       end
 
+      # Checks if the search action is permitted
+      # @return [Boolean]
       def search?
         index?
       end
 
       # Core attributes
 
+      # Returns the permitted attributes for the create action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_create
-        autodetect_fields_for(:permitted_attributes_for_create) - [
+        autodetect_permitted_fields(:permitted_attributes_for_create) - [
           context.resource_context.resource_class.primary_key.to_sym, # primary_key
           :created_at, :updated_at # timestamps
         ]
       end
 
+      # Returns the permitted attributes for the read action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_read
-        autodetect_fields_for :permitted_attributes_for_read
+        autodetect_permitted_fields(:permitted_attributes_for_read)
       end
 
+      # Returns the permitted attributes for the update action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_update
         permitted_attributes_for_create
       end
 
       # Inferred attributes
 
+      # Returns the permitted attributes for the index action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_index
         permitted_attributes_for_read
       end
 
+      # Returns the permitted attributes for the show action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_show
         permitted_attributes_for_read
       end
 
+      # Returns the permitted attributes for the new action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_new
         permitted_attributes_for_create
       end
 
+      # Returns the permitted attributes for the edit action
+      # @return [Array<Symbol>]
       def permitted_attributes_for_edit
         permitted_attributes_for_update
       end
 
+      # # Returns the permitted associations
+      # # @return [Array<Symbol>]
       # def permitted_associations
       #   []
       # end
 
       private
 
-      def autodetect_fields_for(method_name)
-        maybe_warn_autodetect_usage method_name
+      # Autodetects the permitted fields for a given method
+      # @param [Symbol] method_name The name of the method
+      # @return [Array<Symbol>]
+      def autodetect_permitted_fields(method_name)
+        warn_about_autodetect_usage(method_name)
 
         context.resource_context.resource_class.resource_field_names
       end
 
-      def maybe_warn_autodetect_usage(method)
-        raise "Resource field auto-detection: #{self.class}##{method} outside development" unless Rails.env.development?
+      # Warns about the usage of auto-detection of fields
+      # @param [Symbol] method The method name
+      # @raise [RuntimeError] if not in development environment
+      def warn_about_autodetect_usage(method)
+        unless Rails.env.development?
+          raise "Resource field auto-detection: #{self.class}##{method} outside development"
+        end
 
-        Rails.logger.warn %(
+        Plutonium.logger.warn %(
           🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨
 
           Resource field auto-detection: #{self.class}##{method}

data/lib/plutonium/resource/presenter.rb

@@ -1,9 +1,14 @@
 module Plutonium
   module Resource
+    # Presenter class to define actions and fields for a resource
+    # @abstract
     class Presenter
       include Plutonium::Core::Definers::FieldDefiner
       include Plutonium::Core::Definers::ActionDefiner
 
+      # Initializes the presenter with context and resource record
+      # @param [Object] context The context in which the presenter is used
+      # @param [ActiveRecord::Base] resource_record The resource record being presented
       def initialize(context, resource_record)
         @context = context
         @resource_record = resource_record
@@ -17,14 +22,17 @@ module Plutonium
 
       attr_reader :context, :resource_record
 
+      # Define fields for the resource
+      # @note Override this in child presenters for custom field definitions
       def define_fields
-        # override this in child presenters for custom field definitions
       end
 
+      # Define actions for the resource
+      # @note Override this in child presenters for custom action definitions
       def define_actions
-        # override this in child presenters for custom action definitions
       end
 
+      # Define standard actions for the resource
       def define_standard_actions
         define_action Plutonium::Core::Actions::NewAction.new(:new)
         define_action Plutonium::Core::Actions::ShowAction.new(:show)
@@ -32,12 +40,23 @@ module Plutonium
         define_action Plutonium::Core::Actions::DestroyAction.new(:destroy)
       end
 
-      # TODO: move this to its own definer
+      # Define an interactive action
+      # @param [Symbol] name The name of the action
+      # @param [Object] interaction The interaction object
+      # @param [Hash] options Additional options for the action
+      # @note This should be moved to its own definer
       def define_interactive_action(name, interaction:, **)
         define_action Plutonium::Core::Actions::InteractiveAction.new(name, interaction:, **)
       end
 
-      # TODO: move this to its own definer
+      # Define a nested input for the resource
+      # @param [Symbol] name The name of the input
+      # @param [Array] inputs The inputs for the nested field
+      # @param [Class, nil] model_class The model class for the nested field
+      # @param [Hash] options Additional options for the nested field
+      # @yield [input] Gives the input object to the block
+      # @note This should be moved to its own definer
+      # @raise [ArgumentError] if model_class is not provided for polymorphic associations
       def define_nested_input(name, inputs:, model_class: nil, **options)
         nested_attribute_options = resource_class.all_nested_attributes_options[name]
 
@@ -50,13 +69,7 @@ module Plutonium
         macro = nested_attribute_options&.[](:macro)
         allow_destroy = nested_attribute_options&.[](:allow_destroy).presence
         update_only = nested_attribute_options&.[](:update_only).presence
-        limit = if macro == :has_one
-          1
-        elsif options.key?(:limit)
-          options[:limit]
-        else
-          nested_attribute_options&.[](:limit)
-        end
+        limit = determine_nested_input_limit(macro, options[:limit], nested_attribute_options&.[](:limit))
 
         input = Plutonium::Core::Fields::Inputs::NestedInput.new(
           name,
@@ -72,7 +85,26 @@ module Plutonium
         define_input name, input:
       end
 
-      def resource_class = context.resource_class
+      # Determines the limit for a nested input
+      # @param [Symbol, nil] macro The macro of the association
+      # @param [Integer, nil] option_limit The limit provided in options
+      # @param [Integer, nil] nested_attribute_limit The limit from nested attributes
+      # @return [Integer, nil] The determined limit
+      def determine_nested_input_limit(macro, option_limit, nested_attribute_limit)
+        if macro == :has_one
+          1
+        elsif option_limit
+          option_limit
+        else
+          nested_attribute_limit
+        end
+      end
+
+      # Returns the resource class
+      # @return [Class] The resource class
+      def resource_class
+        context.resource_class
+      end
     end
   end
 end

data/lib/plutonium/resource/query_object.rb

@@ -1,41 +1,61 @@
-# TODO: refactor
+# TODO: make standard query type names e.g. search and scope configurable
 
 module Plutonium
-  # TODO: make standard query type names e.g. search and scope configurable
   module Resource
+    # The QueryObject class is responsible for handling various query types and applying them to the given scope.
     class QueryObject
       class << self
       end
 
+      # The Query class serves as a base for different types of queries.
       class Query
         include Plutonium::Core::Definers::InputDefiner
 
+        # Applies the query to the given scope with the provided parameters.
+        #
+        # @param scope [Object] the scope to apply the query on
+        # @param params [Hash] the parameters for the query
+        # @return [Object] the modified scope
         def apply(scope, params)
-          params = extract_query_params params
-
-          if input_definitions.size == params.size
-            apply_internal scope, params
-          else
-            scope
-          end
+          params = extract_query_params(params)
+          (input_definitions.size == params.size) ? apply_internal(scope, params) : scope
         end
 
         private
 
+        # Raises an error, should be implemented by subclasses.
+        #
+        # @param scope [Object] the scope to apply the query on
+        # @param params [Hash] the parameters for the query
+        # @raise [NotImplementedError] if not implemented by subclass
         def apply_internal(scope, params)
           raise NotImplementedError, "#{self.class}#apply_internal"
         end
 
+        # Extracts and processes query parameters.
+        #
+        # @param params [Hash] the parameters to process
+        # @return [Hash] the processed parameters
         def extract_query_params(params)
-          input_definitions.collect_all(params).symbolize_keys
+          input_definitions.collect_all(params).compact.symbolize_keys
         end
 
-        def resource_class = nil
+        # Returns the resource class, to be implemented by subclasses.
+        #
+        # @return [Class, nil] the resource class
+        def resource_class
+          nil
+        end
       end
 
+      # The ScopeQuery class represents a query based on a scope.
       class ScopeQuery < Query
         attr_reader :name
 
+        # Initializes a ScopeQuery.
+        #
+        # @param name [Symbol] the name of the scope
+        # @yield [self] optional block to configure the query
         def initialize(name)
           @name = name
           yield self if block_given?
@@ -43,30 +63,47 @@ module Plutonium
 
         private
 
+        # Applies the scope query to the given scope with the provided parameters.
+        #
+        # @param scope [Object] the scope to apply the query on
+        # @param params [Hash] the parameters for the query
+        # @return [Object] the modified scope
         def apply_internal(scope, params)
-          scope.send name, **params
+          scope.send(name, **params)
         end
       end
 
+      # The BlockQuery class represents a query based on a block.
       class BlockQuery < Query
         attr_reader :body
 
+        # Initializes a BlockQuery.
+        #
+        # @param body [Proc] the block to apply
+        # @yield [self] optional block to configure the query
         def initialize(body)
           @body = body
           yield self if block_given?
         end
 
+        private
+
+        # Applies the block query to the given scope with the provided parameters.
+        #
+        # @param scope [Object] the scope to apply the query on
+        # @param params [Hash] the parameters for the query
+        # @return [Object] the modified scope
         def apply_internal(scope, params)
-          if body.arity == 1
-            body.call scope
-          else
-            body.call scope, **params
-          end
+          (body.arity == 1) ? body.call(scope) : body.call(scope, **params)
         end
       end
 
-      attr_reader :search_filter, :search_query
+      attr_reader :search_filter, :search_query, :context, :selected_sort_fields, :selected_sort_directions, :selected_scope_filter
 
+      # Initializes a QueryObject.
+      #
+      # @param context [Object] the context in which the queries are defined
+      # @param params [Hash] the initial parameters for the query object
       def initialize(context, params)
         @context = context
 
@@ -77,58 +114,61 @@ module Plutonium
 
         extract_filter_params(params)
         extract_sort_params(params)
-        # @params = params.except(:scope, :search, :sort_fields, :sort_directions)
       end
 
+      # Builds a URL with the current query parameters.
+      #
+      # @param options [Hash] additional options for building the URL
+      # @return [String] the built URL
       def build_url(**options)
         q = {}
-
-        q[:search] = options.key?(:search) ? options[:search].presence : search_query
-        q[:scope] = options.key?(:scope) ? options[:scope].presence : selected_scope_filter
-
+        q[:search] = options.fetch(:search, search_query).presence
+        q[:scope] = options.fetch(:scope, selected_scope_filter).presence
         q[:sort_directions] = selected_sort_directions.dup
         q[:sort_fields] = selected_sort_fields.dup
+
         if (sort = options[:sort])
-          if options[:reset]
-            q[:sort_fields].delete_if { |e| e == sort.to_s }
-            q[:sort_directions].delete sort
-          else
-            q[:sort_fields] << sort.to_s unless q[:sort_fields].include?(sort.to_s)
-
-            sort_direction = selected_sort_directions[sort]
-            if sort_direction.nil?
-              q[:sort_directions][sort] = "ASC"
-            elsif sort_direction == "ASC"
-              q[:sort_directions][sort] = "DESC"
-            else
-              q[:sort_fields].delete_if { |e| e == sort.to_s }
-              q[:sort_directions].delete sort
-            end
-          end
+          handle_sort_options(q, sort, options[:reset])
         end
 
         "?#{{q: q}.to_param}"
       end
 
+      # Applies the queries to the given scope.
+      #
+      # @param scope [Object] the scope to apply the queries on
+      # @return [Object] the modified scope
       def apply(scope)
         scope = search_filter.apply(scope, {search: search_query}) if search_filter.present?
         scope = scope_definitions[selected_scope_filter].apply(scope, {}) if selected_scope_filter.present?
-        selected_sort_fields.each do |name|
-          sorter = sort_definitions[name]
-          next unless sorter.present?
-
-          params = {direction: selected_sort_directions[name] || "ASC"}
-          scope = sorter.apply(scope, params)
-        end
-        scope
+        apply_sorters(scope)
       end
 
-      def scope_definitions = @scope_definitions ||= {}.with_indifferent_access
+      # Retrieves the scope definitions.
+      #
+      # @return [HashWithIndifferentAccess] the scope definitions
+      def scope_definitions
+        @scope_definitions ||= {}.with_indifferent_access
+      end
 
-      def filter_definitions = @filter_definitions ||= {}.with_indifferent_access
+      # Retrieves the filter definitions.
+      #
+      # @return [HashWithIndifferentAccess] the filter definitions
+      def filter_definitions
+        @filter_definitions ||= {}.with_indifferent_access
+      end
 
-      def sort_definitions = @sort_definitions ||= {}.with_indifferent_access
+      # Retrieves the sort definitions.
+      #
+      # @return [HashWithIndifferentAccess] the sort definitions
+      def sort_definitions
+        @sort_definitions ||= {}.with_indifferent_access
+      end
 
+      # Retrieves the sort parameters for a given name.
+      #
+      # @param name [Symbol] the name of the sort field
+      # @return [Hash, nil] the sort parameters or nil if not defined
       def sort_params_for(name)
         return unless sort_definitions[name]
 
@@ -142,78 +182,151 @@ module Plutonium
 
       private
 
-      attr_reader :context, :selected_sort_fields, :selected_sort_directions, :selected_scope_filter
-
+      # Placeholder method for defining filters.
       def define_filters
       end
 
+      # Placeholder method for defining scopes.
       def define_scopes
       end
 
+      # Placeholder method for defining sorters.
       def define_sorters
       end
 
+      # Defines standard queries.
       def define_standard_queries
         define_search(:search) if resource_class.respond_to?(:search)
       end
 
-      def define_filter(name, body = nil, &)
+      # Defines a filter.
+      #
+      # @param name [Symbol] the name of the filter
+      # @param body [Proc, nil] the body of the filter
+      # @yield [Query] optional block to configure the query
+      def define_filter(name, body = nil, &block)
         body ||= name
-        filter_definitions[name] = build_query(body, &)
+        filter_definitions[name] = build_query(body, &block)
       end
 
+      # Defines a scope.
+      #
+      # @param name [Symbol] the name of the scope
+      # @param body [Proc, nil] the body of the scope
       def define_scope(name, body = nil)
         body ||= name
         scope_definitions[name] = build_query(body)
       end
 
+      # Defines a sort.
+      #
+      # @param name [Symbol] the name of the sort field
+      # @param body [Proc, nil] the body of the sort
       def define_sort(name, body = nil)
         if body.nil?
-          sort_field = if resource_class.primary_key == name.to_s || resource_class.content_column_field_names.include?(name)
-            name
-          elsif resource_class.belongs_to_association_field_names.include? name
-            resource_class.reflect_on_association(name).foreign_key.to_sym
-          else
-            raise "Unable to determine sort logic for '#{body}'"
-          end
-          body = lambda { |scope, direction:| scope.order(sort_field => direction) }
+          sort_field = determine_sort_field(name)
+          body = ->(scope, direction:) { scope.order(sort_field => direction) }
         end
-
         sort_definitions[name] = build_query(body) do |query|
           query.define_input :direction
         end
       end
 
+      # Defines a search filter.
+      #
+      # @param body [Proc] the body of the search filter
       def define_search(body)
         @search_filter = build_query(body) do |query|
           query.define_input :search
         end
       end
 
+      # Extracts filter parameters from the given params.
+      #
+      # @param params [Hash] the parameters to extract from
       def extract_filter_params(params)
         @search_query = params[:search]
         @selected_scope_filter = params[:scope]
       end
 
+      # Extracts sort parameters from the given params.
+      #
+      # @param params [Hash] the parameters to extract from
       def extract_sort_params(params)
-        @selected_sort_fields = Array(params[:sort_fields])
-        @selected_sort_fields &= sort_definitions.keys
-
-        @selected_sort_directions = params[:sort_directions]&.slice(*sort_definitions.keys) || {}
-        @selected_sort_directions = @selected_sort_directions.map { |key, value| [key, {"DESC" => "DESC"}[value.upcase] || "ASC"] }.to_h.with_indifferent_access
+        @selected_sort_fields = Array(params[:sort_fields]) & sort_definitions.keys
+        @selected_sort_directions = (params[:sort_directions]&.slice(*sort_definitions.keys) || {}).transform_values { |v| (v.upcase == "DESC") ? "DESC" : "ASC" }.with_indifferent_access
       end
 
-      def build_query(body, &)
+      # Builds a query object.
+      #
+      # @param body [Symbol, Proc] the body of the query
+      # @yield [Query] optional block to configure the query
+      # @return [Query] the built query object
+      def build_query(body, &block)
         case body
         when Symbol
-          raise "Cannot find scope :#{body} on #{resource_class}" unless resource_class.respond_to? body
-          ScopeQuery.new(body, &)
+          raise "Cannot find scope :#{body} on #{resource_class}" unless resource_class.respond_to?(body)
+          ScopeQuery.new(body, &block)
+        else
+          BlockQuery.new(body, &block)
+        end
+      end
+
+      # Retrieves the resource class.
+      #
+      # @return [Class] the resource class
+      def resource_class
+        context.resource_class
+      end
+
+      # Determines the sort field for a given name.
+      #
+      # @param name [Symbol] the name of the sort field
+      # @return [Symbol] the determined sort field
+      # @raise [RuntimeError] if unable to determine sort logic for the field
+      def determine_sort_field(name)
+        if resource_class.primary_key == name.to_s || resource_class.content_column_field_names.include?(name)
+          name
+        elsif resource_class.belongs_to_association_field_names.include?(name)
+          resource_class.reflect_on_association(name).foreign_key.to_sym
+        else
+          raise "Unable to determine sort logic for '#{name}'"
+        end
+      end
+
+      # Handles sorting options.
+      #
+      # @param query [Hash] the query parameters
+      # @param sort [Symbol] the sort field
+      # @param reset [Boolean] whether to reset the sorting
+      def handle_sort_options(query, sort, reset)
+        if reset
+          query[:sort_fields].delete_if { |e| e == sort.to_s }
+          query[:sort_directions].delete(sort)
         else
-          BlockQuery.new(body, &)
+          query[:sort_fields] << sort.to_s unless query[:sort_fields].include?(sort.to_s)
+          sort_direction = selected_sort_directions[sort]
+          query[:sort_directions][sort] = if sort_direction.nil?
+            "ASC"
+          else
+            ((sort_direction == "ASC") ? "DESC" : "ASC")
+          end
+          query[:sort_fields].delete_if { |e| e == sort.to_s } if query[:sort_directions][sort] == "ASC"
         end
       end
 
-      def resource_class = context.resource_class
+      # Applies sorters to the scope.
+      #
+      # @param scope [Object] the scope to apply sorters on
+      # @return [Object] the modified scope
+      def apply_sorters(scope)
+        selected_sort_fields.each do |name|
+          sorter = sort_definitions[name]
+          next unless sorter.present?
+          scope = sorter.apply(scope, {direction: selected_sort_directions[name] || "ASC"})
+        end
+        scope
+      end
     end
   end
 end