better_controller 0.1.0

data/examples/products_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Example of a controller using BetterController's standard_actions
+class ProductsController < ApplicationController
+  include BetterController
+
+  # Use the standard_actions helper to generate CRUD actions
+  standard_actions Product, paginate: true
+
+  private
+
+  # Strong parameters for Product
+  def product_params
+    params.require(:product).permit(:name, :description, :price, :category_id)
+  end
+
+  # You can still override any of the standard actions if needed
+  # For example:
+  # def index
+  #   execute_action do
+  #     products = Product.where(category_id: params[:category_id])
+  #     respond_with_pagination(products)
+  #   end
+  # end
+end

data/examples/user_serializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Example of a serializer for User resources
+class UserSerializer
+  include BetterController::Serializer
+
+  # Define the attributes to include in the serialized output
+  attributes :id, :name, :email, :role, :created_at, :updated_at
+
+  # Define methods to include in the serialized output
+  methods :full_name, :active_status
+
+  # Define associations to include in the serialized output
+  # associations posts: PostSerializer, comments: CommentSerializer
+end

data/examples/user_service.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Example of a service class for User resources
+class UserService < BetterController::Service
+  protected
+
+  # Define the resource class for this service
+  def resource_class
+    User
+  end
+
+  # Customize the resource scope if needed
+  def resource_scope(ancestry_params = {})
+    scope = super
+
+    # Example of adding custom scoping
+    scope = scope.active if ancestry_params[:active_only]
+
+    scope
+  end
+
+  # Customize attribute preparation if needed
+  def prepare_attributes(attributes, ancestry_params = {})
+    prepared = super
+
+    # Example of adding custom attribute preparation
+    prepared[:created_by] = ancestry_params[:current_user_id] if ancestry_params[:current_user_id]
+
+    prepared
+  end
+end

data/examples/users_controller.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'user_service'
+require_relative 'user_serializer'
+
+# Example of a Rails controller using BetterController::ResourcesController
+class UsersController < ApplicationController
+  include BetterController::ResourcesController
+
+  # Define required parameters for actions
+  requires_params :create, :name, :email
+  requires_params :update, :id
+
+  # Define parameter schema for validation
+  param_schema :create, {
+    name:  { required: true, type: String },
+    email: { required: true, format: /\A[^@\s]+@[^@\s]+\z/ },
+    role:  { in: %w[admin user guest] },
+  }
+
+  # You can override any of the ResourcesController methods if needed
+  # For example, to customize the index action:
+  def index
+    execute_action do
+      @resource_collection = resource_collection_resolver
+
+      # Add pagination metadata
+      if @resource_collection.respond_to?(:page)
+        paginated            = @resource_collection.page(params[:page] || 1).per(params[:per_page] || 25)
+        add_meta(:pagination, {
+                   current_page: paginated.current_page,
+                   total_pages:  paginated.total_pages,
+                   total_count:  paginated.total_count,
+                 })
+        @resource_collection = paginated
+      end
+
+      respond_with_success(@resource_collection, options: { meta: meta })
+    end
+  end
+
+  # You can also add custom actions
+  def activate
+    execute_action do
+      @resource = resource_finder
+      @resource.update(active: true)
+
+      respond_with_success(@resource, options: {
+                             message: "User #{@resource.name} has been activated",
+                           })
+    end
+  end
+
+  protected
+
+  # Define the resource service class
+  def resource_service_class
+    UserService
+  end
+
+  # Define the root key for resource parameters
+  def resource_params_root_key
+    :user
+  end
+
+  # Customize the ancestry parameters if needed
+  def ancestry_key_params
+    # Example: passing the current user ID to the service
+    { current_user_id: current_user&.id }
+  end
+
+  # Customize create message
+  def create_message
+    "User #{@resource.name} has been created successfully"
+  end
+
+  # Customize update message
+  def update_message
+    "User #{@resource.name} has been updated successfully"
+  end
+
+  # Customize destroy message
+  def destroy_message
+    'User has been deleted successfully'
+  end
+end

data/lib/better_controller/action_helpers.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing helper methods for common controller actions
+  module ActionHelpers
+    extend ActiveSupport::Concern
+
+    # Define standard CRUD actions for a resource
+    # @param resource_class [Class] The resource class (e.g., User)
+    # @param options [Hash] Options for customizing the actions
+    module ClassMethods
+      def standard_actions(resource_class, options = {})
+        resource_name   = resource_class.name.underscore
+        resource_name.pluralize
+
+        # Define index action
+        define_method(:index) do
+          execute_action do
+            collection = resource_class.all
+
+            # Apply scopes if provided
+            collection = apply_scopes(collection) if respond_to?(:apply_scopes)
+
+            # Apply pagination if requested
+            if options[:paginate]
+              respond_with_pagination(collection, page: params[:page], per_page: params[:per_page])
+            else
+              respond_with_success(collection)
+            end
+          end
+        end
+
+        # Define show action
+        define_method(:show) do
+          execute_action do
+            resource = resource_class.find(params[:id])
+            respond_with_success(resource)
+          end
+        end
+
+        # Define create action
+        define_method(:create) do
+          execute_action do
+            resource = resource_class.new(send(:"#{resource_name}_params"))
+
+            with_transaction do
+              resource.save!
+              respond_with_success(resource, status: :created)
+            end
+          end
+        end
+
+        # Define update action
+        define_method(:update) do
+          execute_action do
+            resource = resource_class.find(params[:id])
+
+            with_transaction do
+              resource.update!(send(:"#{resource_name}_params"))
+              respond_with_success(resource)
+            end
+          end
+        end
+
+        # Define destroy action
+        define_method(:destroy) do
+          execute_action do
+            resource = resource_class.find(params[:id])
+            resource.destroy
+            respond_with_success(nil, status: :no_content)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_controller/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Base module that provides core functionality for enhanced controllers
+  module Base
+    extend ActiveSupport::Concern
+
+    included do
+      # Class methods and configurations to be included in the controller
+      class_attribute :better_controller_options, default: {}
+
+      # Set up rescue handlers if enabled
+      if defined?(rescue_from) && BetterController.config.error_handling[:detailed_errors]
+        rescue_from StandardError, with: :better_controller_handle_error
+      end
+    end
+
+    # Instance methods for controllers
+
+    # Execute an action with enhanced error handling and response formatting
+    # @param action_block [Proc] The block containing the action logic
+    # @return [Object] The formatted response
+    def execute_action(&)
+      log_debug("Executing action: #{action_name}") if respond_to?(:action_name)
+      result = instance_eval(&)
+      respond_with_success(result)
+    rescue StandardError => e
+      handle_exception(e)
+    end
+
+    # Helper method to simplify common controller patterns
+    # @param options [Hash] Options for the action
+    # @return [Object] The result of the action
+    def with_transaction(options = {}, &)
+      ActiveRecord::Base.transaction(&)
+    rescue StandardError => e
+      handle_exception(e, options)
+    end
+
+    # Handle exceptions raised by the controller
+    # @param exception [Exception] The exception to handle
+    def better_controller_handle_error(exception)
+      handle_exception(exception)
+    end
+
+    private
+
+    # Handle exceptions in a standardized way
+    # @param exception [Exception] The exception to handle
+    # @param options [Hash] Options for handling the exception
+    # @return [Object] The error response
+    def handle_exception(exception, options = {})
+      # Log the exception if logging is enabled
+      if respond_to?(:log_exception) && BetterController.config.error_handling[:log_errors]
+        log_exception(exception, { controller: self.class.name, action: action_name })
+      end
+
+      respond_with_error(exception, options)
+    end
+  end
+end

data/lib/better_controller/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Configuration module for BetterController
+  module Configuration
+    # Default configuration options
+    DEFAULTS = {
+      pagination:     {
+        enabled:  true,
+        per_page: 25,
+      },
+      serialization:  {
+        include_root:  false,
+        camelize_keys: true,
+      },
+      error_handling: {
+        log_errors:      true,
+        detailed_errors: true,
+      },
+    }.freeze
+
+    class << self
+      # Get the current configuration
+      # @return [Hash] The current configuration
+      def options
+        @options ||= DEFAULTS.deep_dup
+      end
+
+      # Configure BetterController
+      # @yield [config] The configuration block
+      def configure
+        yield(options) if block_given?
+      end
+
+      # Reset the configuration to defaults
+      def reset!
+        @options = DEFAULTS.deep_dup
+      end
+
+      # Get a specific configuration option
+      # @param key [Symbol] The configuration key
+      # @return [Object] The configuration value
+      delegate :[], to: :options
+
+      # Set a specific configuration option
+      # @param key [Symbol] The configuration key
+      # @param value [Object] The configuration value
+      delegate :[]=, to: :options
+    end
+
+    # Get the pagination configuration
+    # @return [Hash] The pagination configuration
+    def self.pagination
+      options[:pagination]
+    end
+
+    # Get the serialization configuration
+    # @return [Hash] The serialization configuration
+    def self.serialization
+      options[:serialization]
+    end
+
+    # Get the error handling configuration
+    # @return [Hash] The error handling configuration
+    def self.error_handling
+      options[:error_handling]
+    end
+  end
+end

data/lib/better_controller/logging.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing logging capabilities
+  module Logging
+    extend ActiveSupport::Concern
+
+    included do
+      # Set up a logger for the controller
+      class_attribute :better_controller_logger, default: Rails.logger if defined?(Rails)
+    end
+
+    # Log a message at the info level
+    # @param message [String] The message to log
+    # @param tags [Hash] Additional tags for the log
+    def log_info(message, tags = {})
+      log(:info, message, tags)
+    end
+
+    # Log a message at the debug level
+    # @param message [String] The message to log
+    # @param tags [Hash] Additional tags for the log
+    def log_debug(message, tags = {})
+      log(:debug, message, tags)
+    end
+
+    # Log a message at the warn level
+    # @param message [String] The message to log
+    # @param tags [Hash] Additional tags for the log
+    def log_warn(message, tags = {})
+      log(:warn, message, tags)
+    end
+
+    # Log a message at the error level
+    # @param message [String] The message to log
+    # @param tags [Hash] Additional tags for the log
+    def log_error(message, tags = {})
+      log(:error, message, tags)
+    end
+
+    # Log a message at the fatal level
+    # @param message [String] The message to log
+    # @param tags [Hash] Additional tags for the log
+    def log_fatal(message, tags = {})
+      log(:fatal, message, tags)
+    end
+
+    # Log an exception
+    # @param exception [Exception] The exception to log
+    # @param tags [Hash] Additional tags for the log
+    def log_exception(exception, tags = {})
+      return unless BetterController.config.error_handling[:log_errors]
+
+      tags = tags.merge(
+        exception_class: exception.class.name,
+        backtrace:       exception.backtrace&.join("\n")
+      )
+
+      log_error(exception.message, tags)
+    end
+
+    private
+
+    # Log a message at the specified level
+    # @param level [Symbol] The log level
+    # @param message [String] The message to log
+    # @param tags [Hash] Additional tags for the log
+    def log(level, message, tags = {})
+      return unless logger
+
+      tags = tags.merge(controller: self.class.name, action: action_name) if respond_to?(:action_name)
+
+      if tags.empty?
+        logger.send(level, message)
+      else
+        logger.send(level) { "[BetterController] #{message} #{tags.inspect}" }
+      end
+    end
+
+    # Get the logger
+    # @return [Logger] The logger
+    def logger
+      self.class.better_controller_logger
+    end
+
+    # Module providing class methods for logging
+    module ClassMethods
+      # Set the logger for the controller
+      # @param logger [Logger] The logger to use
+      def logger=(logger)
+        self.better_controller_logger = logger
+      end
+
+      # Get the logger for the controller
+      # @return [Logger] The logger
+      def logger
+        better_controller_logger
+      end
+    end
+  end
+end

data/lib/better_controller/method_not_overridden_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Error raised when a required method is not overridden
+  class MethodNotOverriddenError < StandardError
+    # Initialize a new error
+    # @param method_name [Symbol, String] The method that should be overridden
+    # @param instance [Object] The instance where the method should be overridden
+    def initialize(method_name, instance)
+      super("Method '#{method_name}' must be overridden in #{instance.class.name}")
+    end
+  end
+end

data/lib/better_controller/pagination.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing pagination functionality for ActiveRecord collections
+  module Pagination
+    extend ActiveSupport::Concern
+
+    # Paginate a collection
+    # @param collection [ActiveRecord::Relation] The collection to paginate
+    # @param page [Integer] The page number
+    # @param per_page [Integer] The number of items per page
+    # @return [ActiveRecord::Relation] The paginated collection
+    def paginate(collection, page: nil, per_page: nil)
+      page     = (page || params[:page] || 1).to_i
+      per_page = (per_page || params[:per_page] || 25).to_i
+
+      paginated = collection.page(page).per(per_page)
+
+      # Add pagination metadata
+      if respond_to?(:add_meta)
+        add_meta(:pagination, {
+                   current_page: paginated.current_page,
+                   total_pages:  paginated.total_pages,
+                   total_count:  paginated.total_count,
+                   per_page:     per_page,
+                 })
+      end
+
+      paginated
+    end
+
+    # Module providing class methods for pagination
+    module ClassMethods
+      # Configure pagination defaults
+      # @param options [Hash] Pagination options
+      def configure_pagination(options = {})
+        class_attribute :pagination_options, default: {
+          enabled:  true,
+          per_page: 25,
+        }.merge(options)
+      end
+    end
+  end
+end

data/lib/better_controller/parameter_validation.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing parameter validation helpers for controllers
+  module ParameterValidation
+    extend ActiveSupport::Concern
+
+    # Class methods for parameter validation
+    module ClassMethods
+      # Define required parameters for an action
+      # @param action_name [Symbol] The name of the action
+      # @param params [Array<Symbol>] The required parameters
+      def requires_params(action_name, *params)
+        before_action only: action_name do
+          validate_required_params(*params)
+        end
+      end
+
+      # Define parameter schema for an action
+      # @param action_name [Symbol] The name of the action
+      # @param schema [Hash] The parameter schema
+      def param_schema(action_name, schema)
+        before_action only: action_name do
+          validate_param_schema(schema)
+        end
+      end
+    end
+
+    # Instance methods for parameter validation
+
+    # Validate that required parameters are present
+    # @param params [Array<Symbol>] The required parameters
+    # @raise [BetterController::Error] If a required parameter is missing
+    def validate_required_params(*params)
+      missing_params = []
+
+      params.each do |param|
+        missing_params << param unless parameter_present?(param)
+      end
+
+      unless missing_params.empty?
+        error_message = "Missing required parameters: #{missing_params.join(', ')}"
+        raise BetterController::Error, error_message
+      end
+
+      true
+    end
+
+    # Validate parameters against a schema
+    # @param schema [Hash] The parameter schema
+    # @raise [BetterController::Error] If parameters don't match the schema
+    def validate_param_schema(schema)
+      errors = []
+
+      schema.each do |param, rules|
+        value = params[param]
+
+        if rules[:required] && value.nil?
+          errors << "#{param} is required"
+          next
+        end
+
+        next if value.nil?
+
+        errors << "#{param} must be a #{rules[:type]}" if rules[:type] && !value.is_a?(rules[:type])
+
+        errors << "#{param} must be one of: #{rules[:in].join(', ')}" if rules[:in]&.exclude?(value)
+
+        errors << "#{param} has invalid format" if rules[:format] && rules[:format] !~ value.to_s
+      end
+
+      raise BetterController::Error, errors.join(', ') unless errors.empty?
+
+      true
+    end
+
+    private
+
+    # Check if a parameter is present
+    # @param param [Symbol] The parameter to check
+    # @return [Boolean] Whether the parameter is present
+    def parameter_present?(param)
+      params.key?(param.to_s) || params.key?(param.to_sym)
+    end
+  end
+end