better_controller 0.1.0

data/lib/better_controller/params_helpers.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing enhanced parameter handling for controllers
+  module ParamsHelpers
+    extend ActiveSupport::Concern
+
+    # Get parameters with type casting
+    # @param key [Symbol, String] The parameter key
+    # @param type [Class] The type to cast to
+    # @param default [Object] The default value if parameter is missing
+    # @return [Object] The parameter value
+    def param(key, type: nil, default: nil)
+      value = params[key]
+      return default if value.nil?
+
+      case type
+      when :integer, Integer
+        value.to_i
+      when :float, Float
+        value.to_f
+      when :string, String
+        value.to_s
+      when :boolean, :bool
+        ActiveModel::Type::Boolean.new.cast(value)
+      when :date, Date
+        begin
+          Date.parse(value)
+        rescue ArgumentError
+          default
+        end
+      when :datetime, DateTime
+        begin
+          DateTime.parse(value)
+        rescue ArgumentError
+          default
+        end
+      when :array, Array
+        value.is_a?(Array) ? value : [value]
+      when :hash, Hash
+        value.is_a?(Hash) ? value : default
+      when :json, :JSON
+        begin
+          value.is_a?(Hash) ? value : JSON.parse(value)
+        rescue JSON::ParserError
+          default
+        end
+      else
+        value
+      end
+    end
+
+    # Get a boolean parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [Boolean] The default value if parameter is missing
+    # @return [Boolean] The parameter value
+    def boolean_param(key, default: false)
+      param(key, type: :boolean, default: default)
+    end
+
+    # Get an integer parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [Integer] The default value if parameter is missing
+    # @return [Integer] The parameter value
+    def integer_param(key, default: nil)
+      param(key, type: :integer, default: default)
+    end
+
+    # Get a float parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [Float] The default value if parameter is missing
+    # @return [Float] The parameter value
+    def float_param(key, default: nil)
+      param(key, type: :float, default: default)
+    end
+
+    # Get a date parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [Date] The default value if parameter is missing
+    # @return [Date] The parameter value
+    def date_param(key, default: nil)
+      param(key, type: :date, default: default)
+    end
+
+    # Get a datetime parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [DateTime] The default value if parameter is missing
+    # @return [DateTime] The parameter value
+    def datetime_param(key, default: nil)
+      param(key, type: :datetime, default: default)
+    end
+
+    # Get an array parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [Array] The default value if parameter is missing
+    # @return [Array] The parameter value
+    def array_param(key, default: [])
+      param(key, type: :array, default: default)
+    end
+
+    # Get a JSON parameter
+    # @param key [Symbol, String] The parameter key
+    # @param default [Hash] The default value if parameter is missing
+    # @return [Hash] The parameter value
+    def json_param(key, default: {})
+      param(key, type: :json, default: default)
+    end
+  end
+end

data/lib/better_controller/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Railtie for Rails integration
+  class Railtie < Rails::Railtie
+    initializer 'better_controller.configure_rails_initialization' do
+      ActiveSupport.on_load(:action_controller) do
+        # Make BetterController modules available to ActionController
+        ActiveSupport.on_load(:action_controller) { include BetterController }
+      end
+    end
+
+    # Add custom rake tasks if needed
+    rake_tasks do
+      load 'tasks/better_controller_tasks.rake'
+    end
+  end
+end

data/lib/better_controller/resources_controller.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing standardized RESTful resource controller functionality
+  module ResourcesController
+    extend ActiveSupport::Concern
+
+    included do
+      # Include the base BetterController modules
+      include BetterController::Base
+      include BetterController::ResponseHelpers
+      include BetterController::ParameterValidation
+      include BetterController::Pagination
+
+      # Configure default pagination
+      configure_pagination enabled: true, per_page: 25
+    end
+
+    # Index action to list all resources
+    def index
+      execute_action do
+        collection = resource_collection_resolver
+
+        # Apply pagination if enabled
+        if self.class.pagination_options[:enabled] && collection.respond_to?(:page)
+          @resource_collection = paginate(collection,
+                                          page:     params[:page],
+                                          per_page: params[:per_page] || self.class.pagination_options[:per_page])
+        else
+          @resource_collection = collection
+        end
+
+        data = serialize_resource(@resource_collection, index_serializer)
+        respond_with_success(data, options: { meta: meta })
+      end
+    end
+
+    # Show action to display a specific resource
+    def show
+      execute_action do
+        @resource = resource_finder
+
+        data = serialize_resource(@resource, show_serializer)
+        respond_with_success(data, options: { meta: meta })
+      end
+    end
+
+    # Create action to create a new resource
+    def create
+      execute_action do
+        @resource = resource_creator
+
+        if @resource.errors.any?
+          respond_with_error(@resource.errors, status: :unprocessable_entity)
+        else
+          data = serialize_resource(@resource, create_serializer)
+          respond_with_success(data, status: :created, options: {
+                                 message: create_message,
+                                 meta:    meta,
+                               })
+        end
+      end
+    end
+
+    # Update action to update an existing resource
+    def update
+      execute_action do
+        @resource = resource_updater
+
+        if @resource.errors.any?
+          respond_with_error(@resource.errors, status: :unprocessable_entity)
+        else
+          data = serialize_resource(@resource, update_serializer)
+          respond_with_success(data, options: {
+                                 message: update_message,
+                                 meta:    meta,
+                               })
+        end
+      end
+    end
+
+    # Destroy action to delete a resource
+    def destroy
+      execute_action do
+        @resource = resource_destroyer
+
+        if @resource.errors.any?
+          respond_with_error(@resource.errors, status: :unprocessable_entity)
+        else
+          data = serialize_resource(@resource, destroy_serializer)
+          respond_with_success(data, options: {
+                                 message: destroy_message,
+                                 meta:    meta,
+                               })
+        end
+      end
+    end
+
+    protected
+
+    # Serialize a resource using the specified serializer
+    # @param resource [Object] The resource to serialize
+    # @param serializer_class [Class] The serializer class
+    # @return [Hash, Array<Hash>] The serialized resource
+    def serialize_resource(resource, serializer_class)
+      return resource unless serializer_class && defined?(serializer_class)
+
+      serializer = serializer_class.new
+      serializer.serialize(resource, serialization_options)
+    end
+
+    # Get serialization options
+    # @return [Hash] The serialization options
+    def serialization_options
+      {}
+    end
+
+    # Get the serializer for index action
+    # @return [Class] The serializer class
+    def index_serializer
+      resource_serializer
+    end
+
+    # Get the serializer for show action
+    # @return [Class] The serializer class
+    def show_serializer
+      resource_serializer
+    end
+
+    # Get the serializer for create action
+    # @return [Class] The serializer class
+    def create_serializer
+      resource_serializer
+    end
+
+    # Get the serializer for update action
+    # @return [Class] The serializer class
+    def update_serializer
+      resource_serializer
+    end
+
+    # Get the serializer for destroy action
+    # @return [Class] The serializer class
+    def destroy_serializer
+      resource_serializer
+    end
+
+    # Get the resource serializer class
+    # @return [Class] The serializer class
+    def resource_serializer
+      nil
+    end
+
+    # Add metadata to the response
+    # @param key [Symbol] The metadata key
+    # @param value [Object] The metadata value
+    def add_meta(key, value)
+      meta[key] = value
+    end
+
+    # Get the metadata hash
+    # @return [Hash] The metadata
+    def meta
+      @meta ||= {}
+    end
+
+    # Get the resource service
+    # @return [Object] The resource service
+    def resource_service
+      resource_service_class.new
+    end
+
+    # Get the resource service class
+    # @return [Class] The resource service class
+    def resource_service_class
+      raise NotImplementedError, "#{self.class.name} must implement #{__method__}"
+    end
+
+    # Get the root key for resource parameters
+    # @return [Symbol] The root key
+    def resource_params_root_key
+      raise NotImplementedError, "#{self.class.name} must implement #{__method__}"
+    end
+
+    # Get the message for create action
+    # @return [String, nil] The message
+    def create_message
+      nil
+    end
+
+    # Get the message for update action
+    # @return [String, nil] The message
+    def update_message
+      nil
+    end
+
+    # Get the message for destroy action
+    # @return [String, nil] The message
+    def destroy_message
+      nil
+    end
+
+    # Get the resource parameters
+    # @return [Hash] The resource parameters
+    def resource_params
+      @resource_params ||= params.require(resource_params_root_key).permit!
+    end
+
+    # Resolve the resource collection
+    # @return [Object] The resource collection
+    def resource_collection_resolver
+      resource_service.all(ancestry_key_params)
+    end
+
+    # Find a specific resource
+    # @return [Object] The resource
+    def resource_finder
+      resource_service.find(ancestry_key_params, resource_key_param)
+    end
+
+    # Create a new resource
+    # @return [Object] The created resource
+    def resource_creator
+      resource_service.create(ancestry_key_params, resource_create_params)
+    end
+
+    # Update an existing resource
+    # @return [Object] The updated resource
+    def resource_updater
+      resource_service.update(ancestry_key_params, resource_key_param, resource_update_params)
+    end
+
+    # Destroy a resource
+    # @return [Object] The destroyed resource
+    def resource_destroyer
+      resource_service.destroy(ancestry_key_params, resource_key_param)
+    end
+
+    # Get the resource key parameter
+    # @return [String, Integer] The resource key
+    def resource_key_param
+      params[:id]
+    end
+
+    # Get the ancestry key parameters
+    # @return [Hash] The ancestry key parameters
+    def ancestry_key_params
+      {}
+    end
+
+    # Get the parameters for creating a resource
+    # @return [Hash] The create parameters
+    def resource_create_params
+      resource_params
+    end
+
+    # Get the parameters for updating a resource
+    # @return [Hash] The update parameters
+    def resource_update_params
+      resource_params
+    end
+  end
+end

data/lib/better_controller/response_helpers.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Module providing helper methods for standardized API responses
+  module ResponseHelpers
+    extend ActiveSupport::Concern
+
+    # Respond with a success response
+    # @param data [Object] The data to include in the response
+    # @param status [Symbol, Integer] The HTTP status code
+    # @param options [Hash] Additional options for the response
+    # @return [Object] The formatted response
+    def respond_with_success(data = nil, status: :ok, options: {})
+      response = {
+        success: true,
+        data:    data,
+      }.merge(options)
+
+      if defined?(render)
+        render json: response, status: status
+      else
+        response
+      end
+    end
+
+    # Respond with an error response
+    # @param error [Exception, String] The error or error message
+    # @param status [Symbol, Integer] The HTTP status code
+    # @param options [Hash] Additional options for the response
+    # @return [Object] The formatted error response
+    def respond_with_error(error = nil, status: :unprocessable_entity, options: {})
+      error_message = error.is_a?(Exception) ? error.message : error.to_s
+      error_type    = error.is_a?(Exception) ? error.class.name : 'Error'
+
+      response = {
+        success: false,
+        error:   {
+          type:    error_type,
+          message: error_message,
+        },
+      }.merge(options)
+
+      if defined?(render)
+        render json: response, status: status
+      else
+        response
+      end
+    end
+
+    # Respond with a paginated collection
+    # @param collection [Object] The collection to paginate
+    # @param options [Hash] Pagination options
+    # @return [Object] The paginated response
+    def respond_with_pagination(collection, options = {})
+      page     = (options[:page] || 1).to_i
+      per_page = (options[:per_page] || 25).to_i
+
+      paginated = collection.page(page).per(per_page)
+
+      respond_with_success(
+        paginated,
+        options: {
+          meta: {
+            pagination: {
+              current_page: paginated.current_page,
+              total_pages:  paginated.total_pages,
+              total_count:  paginated.total_count,
+            },
+          },
+        }
+      )
+    end
+  end
+end

data/lib/better_controller/serializer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Base module for serializing resources
+  module Serializer
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Define attributes to be included in the serialized output
+      # @param attrs [Array<Symbol>] The attributes to include
+      def attributes(*attrs)
+        @attributes ||= []
+        @attributes.concat(attrs) if attrs.any?
+        @attributes
+      end
+
+      # Define associations to be included in the serialized output
+      # @param assocs [Hash] The associations to include
+      def associations(assocs = {})
+        @associations ||= {}
+        @associations.merge!(assocs) if assocs.any?
+        @associations
+      end
+
+      # Define methods to be included in the serialized output
+      # @param meths [Array<Symbol>] The methods to include
+      def methods(*meths)
+        @methods ||= []
+        @methods.concat(meths) if meths.any?
+        @methods
+      end
+    end
+
+    # Serialize a resource
+    # @param resource [Object] The resource to serialize
+    # @param options [Hash] Serialization options
+    # @return [Hash] The serialized resource
+    def serialize(resource, options = {})
+      return nil if resource.nil?
+
+      if resource.respond_to?(:each) && !resource.is_a?(Hash)
+        serialize_collection(resource, options)
+      else
+        serialize_resource(resource, options)
+      end
+    end
+
+    # Serialize a collection of resources
+    # @param collection [Array, ActiveRecord::Relation] The collection to serialize
+    # @param options [Hash] Serialization options
+    # @return [Array<Hash>] The serialized collection
+    def serialize_collection(collection, options = {})
+      collection.map { |resource| serialize_resource(resource, options) }
+    end
+
+    # Serialize a single resource
+    # @param resource [Object] The resource to serialize
+    # @param options [Hash] Serialization options
+    # @return [Hash] The serialized resource
+    def serialize_resource(resource, options = {})
+      result = {}
+
+      # Add attributes
+      self.class.attributes.each do |attr|
+        result[attr] = resource.send(attr) if resource.respond_to?(attr)
+      end
+
+      # Add methods
+      self.class.methods.each do |meth|
+        result[meth] = resource.send(meth) if resource.respond_to?(meth)
+      end
+
+      # Add associations
+      self.class.associations.each do |name, serializer_class|
+        next unless resource.respond_to?(name)
+
+        association  = resource.send(name)
+        serializer   = serializer_class.new
+        result[name] = serializer.serialize(association, options)
+      end
+
+      result
+    end
+  end
+end

data/lib/better_controller/service.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module BetterController
+  # Base service class for resource operations
+  class Service
+    # Get all resources
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @return [ActiveRecord::Relation] Collection of resources
+    def all(ancestry_params = {})
+      resource_scope(ancestry_params).all
+    end
+
+    # Find a specific resource
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @param id [Integer, String] The resource ID
+    # @return [Object] The found resource
+    def find(ancestry_params = {}, id)
+      resource_scope(ancestry_params).find(id)
+    end
+
+    # Create a new resource
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @param attributes [Hash] The resource attributes
+    # @return [Object] The created resource
+    def create(ancestry_params = {}, attributes)
+      resource = resource_class.new(prepare_attributes(attributes, ancestry_params))
+
+      resource.save if resource.respond_to?(:save)
+
+      resource
+    end
+
+    # Update an existing resource
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @param id [Integer, String] The resource ID
+    # @param attributes [Hash] The resource attributes
+    # @return [Object] The updated resource
+    def update(ancestry_params = {}, id, attributes)
+      resource = find(ancestry_params, id)
+
+      resource.update(prepare_attributes(attributes, ancestry_params)) if resource.respond_to?(:update)
+
+      resource
+    end
+
+    # Destroy a resource
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @param id [Integer, String] The resource ID
+    # @return [Object] The destroyed resource
+    def destroy(ancestry_params = {}, id)
+      resource = find(ancestry_params, id)
+
+      resource.destroy if resource.respond_to?(:destroy)
+
+      resource
+    end
+
+    protected
+
+    # Get the resource class
+    # @return [Class] The resource class
+    def resource_class
+      raise NotImplementedError, "#{self.class.name} must implement #{__method__}"
+    end
+
+    # Get the resource scope
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @return [ActiveRecord::Relation] The resource scope
+    def resource_scope(ancestry_params = {})
+      scope = resource_class
+
+      ancestry_params.each do |key, value|
+        key.to_s.sub(/_id$/, '')
+        scope       = scope.where("#{key}": value) if resource_class.column_names.include?(key.to_s)
+      end
+
+      scope
+    end
+
+    # Prepare attributes for create/update
+    # @param attributes [Hash] The resource attributes
+    # @param ancestry_params [Hash] Ancestry parameters for nested resources
+    # @return [Hash] The prepared attributes
+    def prepare_attributes(attributes, ancestry_params = {})
+      prepared = attributes.dup
+
+      ancestry_params.each do |key, value|
+        prepared[key] = value if resource_class.column_names.include?(key.to_s)
+      end
+
+      prepared
+    end
+  end
+end

data/lib/better_controller/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BetterController
+  VERSION = '0.1.0'
+end

data/lib/better_controller.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require 'active_support'
+require 'active_support/core_ext'
+
+# Set up Zeitwerk autoloading
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# Manually require core files
+require_relative 'better_controller/version'
+require_relative 'better_controller/method_not_overridden_error'
+require_relative 'better_controller/configuration'
+require_relative 'better_controller/logging'
+require_relative 'better_controller/base'
+require_relative 'better_controller/response_helpers'
+require_relative 'better_controller/parameter_validation'
+require_relative 'better_controller/action_helpers'
+require_relative 'better_controller/service'
+require_relative 'better_controller/serializer'
+require_relative 'better_controller/pagination'
+require_relative 'better_controller/params_helpers'
+require_relative 'better_controller/resources_controller'
+
+# Rails integration
+require_relative 'better_controller/railtie' if defined?(Rails)
+
+module BetterController
+  class Error < StandardError; end
+
+  # Configure BetterController
+  # @yield [config] The configuration block
+  def self.configure
+    yield(Configuration) if block_given?
+  end
+
+  # Get the current configuration
+  # @return [BetterController::Configuration] The current configuration
+  def self.config
+    Configuration
+  end
+
+  # Include BetterController modules in a controller
+  # @param base [Class] The controller class
+  def self.included(base)
+    base.include(BetterController::Base)
+    base.include(BetterController::ResponseHelpers)
+    base.include(BetterController::ParameterValidation)
+    base.include(BetterController::ParamsHelpers)
+    base.include(BetterController::Logging)
+    base.extend(BetterController::ActionHelpers::ClassMethods)
+    base.extend(BetterController::Logging::ClassMethods)
+  end
+end