fetcheable_on_api 0.4 → 0.5.0

data/lib/fetcheable_on_api/sortable.rb

@@ -1,113 +1,274 @@
 # frozen_string_literal: true
 
 module FetcheableOnApi
-  # Sortable implements `pagination` support.
+  # Sortable implements support for JSONAPI-compliant sorting via `sort` query parameters.
+  #
+  # This module enables controllers to process sort parameters in the format:
+  # `sort=field1,-field2,+field3` where:
+  # - No prefix or `+` prefix means ascending order
+  # - `-` prefix means descending order
+  # - Multiple fields are comma-separated and applied in order
+  #
+  # It supports:
+  # - Single and multiple field sorting
+  # - Ascending and descending sort directions
+  # - Association sorting with custom class names
+  # - Case-insensitive sorting with the `lower` option
+  # - Field aliasing for different database column names
+  #
+  # @example Basic sorting setup
+  #   class UsersController < ApplicationController
+  #     sort_by :name, :email, :created_at
+  #
+  #     def index
+  #       users = apply_fetcheable(User.all)
+  #       render json: users
+  #     end
+  #   end
+  #
+  #   # GET /users?sort=name,-created_at (name asc, created_at desc)
+  #
+  # @example Association sorting
+  #   class PostsController < ApplicationController
+  #     sort_by :title, :created_at
+  #     sort_by :author, class_name: User, as: 'name'
+  #
+  #     def index
+  #       posts = apply_fetcheable(Post.joins(:author))
+  #       render json: posts
+  #     end
+  #   end
+  #
+  #   # GET /posts?sort=author,-created_at (by author name asc, then created_at desc)
+  #
+  # @example Case-insensitive sorting
+  #   class UsersController < ApplicationController
+  #     sort_by :name, lower: true  # Sort by lowercase name
+  #     sort_by :email, :created_at
+  #
+  #     def index
+  #       users = apply_fetcheable(User.all)
+  #       render json: users
+  #     end
+  #   end
+  #
+  #   # GET /users?sort=name (sorts by LOWER(users.name))
+  #
+  # @see https://jsonapi.org/format/#fetching-sorting JSONAPI Sorting Specification
   module Sortable
+    # Maps sort direction prefixes to Arel sort methods.
+    # Used to parse the sort parameter and determine ascending vs descending order.
     #
-    # Map of symbol to sorting direction supported by the module.
-    #
+    # @example
+    #   # "+name" or "name" -> :asc (ascending)
+    #   # "-name" -> :desc (descending)
     SORT_ORDER = {
-      "+" => :asc,
-      "-" => :desc,
+      '+' => :asc,   # Explicit ascending (same as no prefix)
+      '-' => :desc,  # Explicit descending
     }.freeze
 
+    # Hook called when Sortable is included in a class.
+    # Sets up the class to support sort configuration and provides
+    # the sort_by class method.
     #
-    # Public class methods
-    #
+    # @param base [Class] The class including this module
+    # @private
     def self.included(base)
       base.class_eval do
         extend ClassMethods
+        # Store sort configurations per class to avoid conflicts between controllers
         class_attribute :sorts_configuration, instance_writer: false
         self.sorts_configuration = {}
       end
     end
 
-    # Class methods made available to your controllers.
+    # Class methods made available to controllers when Sortable is included.
     module ClassMethods
-      # Define one ore more sortable attribute configurations.
+      # Define one or more sortable attributes for the controller.
+      #
+      # This method configures which model attributes can be sorted via query parameters
+      # and how those sorts should be processed.
+      #
+      # @param attrs [Array<Symbol>] List of attribute names to make sortable
+      # @param options [Hash] Configuration options for the sorts
+      # @option options [String, Symbol] :as Alias for the database column name
+      # @option options [Boolean] :lower Whether to sort on the lowercase version of the attribute
+      # @option options [Class] :class_name Model class for association sorting (defaults to collection class)
+      # @option options [Symbol] :association Association name when different from inferred name
+      #
+      # @example Basic attribute sorting
+      #   sort_by :name, :email, :created_at
+      #   # Allows: sort=name,-email,created_at
+      #
+      # @example Case-insensitive sorting
+      #   sort_by :name, lower: true
+      #   # Generates: ORDER BY LOWER(users.name)
+      #
+      # @example Association sorting
+      #   sort_by :author, class_name: User, as: 'name'
+      #   # Allows: sort=author (sorts by users.name)
       #
-      # @param attrs [Array] options to define one or more sorting
-      #   configurations.
-      # @option attrs [String, nil] :as Alias the sorted attribute
-      # @option attrs [true, false, nil] :with Wether to sort on the lowercase
-      #   attribute value.
+      # @example Association sorting with custom association name
+      #   sort_by :author_name, class_name: User, as: 'name', association: :author
+      #   # Allows: sort=author_name (sorts by users.name via author association)
+      #   # Note: Make sure your collection is joined: Book.joins(:author)
+      #
+      # @example Field aliasing
+      #   sort_by :full_name, as: 'name'
+      #   # Maps sort=full_name to ORDER BY users.name
       def sort_by(*attrs)
         options = attrs.extract_options!
         options.symbolize_keys!
 
+        # Validate that only supported options are provided
+        options.assert_valid_keys(:as, :class_name, :lower, :association)
+
+        # Create a new configuration hash to avoid modifying parent class config
         self.sorts_configuration = sorts_configuration.dup
 
         attrs.each do |attr|
+          # Initialize default configuration for this attribute
           sorts_configuration[attr] ||= {
-            as: attr,
+            as: attr
           }
 
+          # Merge in the provided options, overriding defaults
           sorts_configuration[attr] = sorts_configuration[attr].merge(options)
         end
       end
     end
 
-    #
-    # Public instance methods
-    #
+    # Protected instance methods for sorting functionality
 
-    #
-    # Protected instance methods
-    #
     protected
 
+    # Apply sorting to the collection based on sort query parameters.
+    # This is the main method that processes the sort parameter and
+    # applies ordering to the ActiveRecord relation.
+    #
+    # @param collection [ActiveRecord::Relation] The collection to sort
+    # @return [ActiveRecord::Relation] The sorted collection
+    # @raise [FetcheableOnApi::ArgumentError] When sort parameters are invalid
+    #
+    # @example
+    #   # With params: { sort: 'name,-created_at' }
+    #   sorted_users = apply_sort(User.all)
+    #   # Generates: ORDER BY users.name ASC, users.created_at DESC
     def apply_sort(collection)
+      # Return early if no sort parameters are provided
       return collection if params[:sort].blank?
 
+      # Validate that sort parameter is a string
       foa_valid_parameters!(:sort, foa_permitted_types: [String])
 
+      # Parse the sort parameter and build Arel ordering expressions
       ordering = format_params(params[:sort]).map do |attr_name, sort_method|
         arel_sort(attr_name, sort_method, collection)
       end
 
+      # Apply the ordering, filtering out any nil values (unconfigured sorts)
       collection.order(ordering.compact)
     end
 
     private
 
+    # Build an Arel ordering expression for the given attribute and sort direction.
+    # Returns nil if the attribute is not configured for sorting or doesn't exist on the model.
+    #
+    # @param attr_name [Symbol] The attribute name to sort by
+    # @param sort_method [Symbol] The sort direction (:asc or :desc)
+    # @param collection [ActiveRecord::Relation] The collection being sorted
+    # @return [Arel::Node, nil] An Arel ordering node or nil if invalid
+    # @private
     def arel_sort(attr_name, sort_method, collection)
+      # Skip if this attribute is not configured for sorting
       return if sorts_configuration[attr_name].blank?
 
       klass = class_for(attr_name, collection)
       field = field_for(attr_name)
+
+      # Skip if the field doesn't exist on the model
       return unless belong_to_attributes_for?(klass, field)
 
+      # Build the Arel attribute reference using the appropriate table
       attribute = klass.arel_table[field]
-      attribute = attribute.lower if sorts_configuration[attr_name].fetch(:lower, false)
 
+      # Apply lowercase transformation if configured
+      config = sorts_configuration[attr_name] || {}
+      attribute = attribute.lower if config.fetch(:lower, false)
+
+      # Apply the sort direction (asc or desc)
       attribute.send(sort_method)
     end
 
+    # Determine the model class to use for this sort attribute.
+    # Uses the configured class_name or falls back to the collection's class.
+    #
+    # @param attr_name [Symbol] The attribute name
+    # @param collection [ActiveRecord::Relation] The collection being sorted
+    # @return [Class] The model class to use
+    # @private
     def class_for(attr_name, collection)
-      sorts_configuration[attr_name].fetch(:class_name, collection.klass)
+      config = sorts_configuration[attr_name] || {}
+      config.fetch(:class_name, collection.klass)
     end
 
+    # Get the database field name for this sort attribute.
+    # Uses the configured alias (:as option) or the attribute name itself.
+    #
+    # @param attr_name [Symbol] The attribute name
+    # @return [String] The database column name
+    # @private
     def field_for(attr_name)
-      sorts_configuration[attr_name].fetch(:as, attr_name).to_s
+      config = sorts_configuration[attr_name] || {}
+      config.fetch(:as, attr_name).to_s
     end
 
+    # Check if the given field exists as an attribute on the model class.
+    # This prevents SQL errors from trying to sort by non-existent columns.
+    #
+    # @param klass [Class] The model class
+    # @param field [String] The field name to check
+    # @return [Boolean] True if the field exists on the model
+    # @private
     def belong_to_attributes_for?(klass, field)
       klass.attribute_names.include?(field)
     end
 
+    # Parse the sort parameter string into a hash of attributes and directions.
     #
-    # input: "-email,first_name"
-    # return: { email: :desc, first_name: :asc }
+    # This method takes a comma-separated string of sort fields (with optional
+    # direction prefixes) and converts it into a hash mapping field names to
+    # sort directions.
     #
+    # @param params [String] The sort parameter string
+    # @return [Hash{Symbol => Symbol}] Hash mapping attribute names to sort directions
+    #
+    # @example
+    #   format_params("-email,first_name,+last_name")
+    #   # => { email: :desc, first_name: :asc, last_name: :asc }
+    #
+    #   format_params("name")
+    #   # => { name: :asc }
+    #
+    # @private
     def format_params(params)
-      res = {}
+      result = {}
+
       params
-        .split(",")
+        .split(',') # Split on commas to get individual fields
         .each do |attribute|
-        sort_sign = attribute =~ /\A[+-]/ ? attribute.slice!(0) : "+"
-        res[attribute.to_sym] = SORT_ORDER[sort_sign]
+        # Trim whitespace
+        attribute = attribute.strip
+        
+        # Extract the direction prefix (+ or -) or default to +
+        sort_sign = attribute =~ /\A[+-]/ ? attribute.slice!(0) : '+'
+
+        # Map the field name to its sort direction
+        result[attribute.to_sym] = SORT_ORDER[sort_sign]
       end
-      res
+
+      result
     end
   end
 end

data/lib/fetcheable_on_api/version.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
 module FetcheableOnApi
-  VERSION = '0.4'.freeze
+  # Current version of the FetcheableOnApi gem.
+  # Follows semantic versioning (semver.org) principles.
+  #
+  # @return [String] The version string in format "MAJOR.MINOR.PATCH"
+  VERSION = '0.5.0'.freeze
 end

data/lib/fetcheable_on_api.rb

@@ -1,49 +1,96 @@
 # frozen_string_literal: true
 
-require "fetcheable_on_api/configuration"
-require "fetcheable_on_api/filterable"
-require "fetcheable_on_api/pageable"
-require "fetcheable_on_api/sortable"
-require "fetcheable_on_api/version"
-require "active_support"
-require "date"
+require 'fetcheable_on_api/configuration'
+require 'fetcheable_on_api/filterable'
+require 'fetcheable_on_api/pageable'
+require 'fetcheable_on_api/sortable'
+require 'fetcheable_on_api/version'
+require 'active_support'
+require 'date'
 
 # FetcheableOnApi provides standardized sorting, filtering and pagination for
-# you API controllers.
+# Rails API controllers following the JSONAPI specification.
 #
+# This gem automatically adds support for query parameters like:
+# - `filter[attribute]=value` for filtering data
+# - `sort=attribute1,-attribute2` for sorting (- prefix for descending)
+# - `page[number]=1&page[size]=25` for pagination
+#
+# @example Basic usage in a controller
+#   class UsersController < ApplicationController
+#     # Configure allowed filters and sorts
+#     filter_by :name, :email, :status
+#     sort_by :name, :created_at, :updated_at
+#
+#     def index
+#       users = apply_fetcheable(User.all)
+#       render json: users
+#     end
+#   end
+#
+# @example Using with associations
+#   class PostsController < ApplicationController
+#     filter_by :title
+#     filter_by :author, class_name: User, as: 'name'
+#     sort_by :title, :created_at
+#     sort_by :author, class_name: User, as: 'name'
+#
+#     def index
+#       posts = apply_fetcheable(Post.joins(:author).includes(:author))
+#       render json: posts
+#     end
+#   end
+#
+# @author Fabien Piette
+# @since 0.1.0
 module FetcheableOnApi
-  #
-  # Global configuration settings for FetcheableOnApi
+  # Global configuration settings for FetcheableOnApi.
+  # This method provides access to the singleton configuration instance
+  # that can be used to customize default behavior across the application.
   #
   # @example Set default pagination size
   #   FetcheableOnApi.configuration.pagination_default_size = 25
   #
   # @return [Configuration] The global configuration instance
+  # @see Configuration
   def self.configuration
     @configuration ||= Configuration.new
   end
 
   # Configure FetcheableOnApi using a block.
+  # This is the recommended way to set up configuration in an initializer.
   #
-  # @example Set default pagination size
+  # @example Set default pagination size in config/initializers/fetcheable_on_api.rb
   #   FetcheableOnApi.configure do |config|
-  #     config.pagination_default_size = 25
+  #     config.pagination_default_size = 50
   #   end
   #
-  # @yield [Configuration] Gives the global instance to the block.
+  # @yield [Configuration] Gives the global configuration instance to the block
+  # @see Configuration
   def self.configure
     yield(configuration)
   end
 
-  #
-  # Supports
-  #
+  # Custom exception classes for FetcheableOnApi-specific errors.
+  # These inherit from standard Ruby exceptions but allow for more
+  # specific error handling in applications using this gem.
+
+  # Raised when invalid parameters are provided to filtering, sorting, or pagination
+  # @example
+  #   raise FetcheableOnApi::ArgumentError, "Invalid filter parameter type"
   ArgumentError = Class.new(ArgumentError)
+
+  # Raised when a feature is not yet implemented or supported
+  # @example
+  #   raise FetcheableOnApi::NotImplementedError, "Custom predicate not supported"
   NotImplementedError = Class.new(NotImplementedError)
 
+  # Hook called when this module is included in a class.
+  # Automatically includes the three main concern modules that provide
+  # filtering, sorting, and pagination functionality.
   #
-  # Public class methods
-  #
+  # @param klass [Class] The class that is including FetcheableOnApi
+  # @private
   def self.included(klass)
     klass.class_eval do
       include Filterable
@@ -52,60 +99,131 @@ module FetcheableOnApi
     end
   end
 
+  # Protected instance methods available to controllers that include this module
+
+  protected
+
+  # Apply filters, sorting, and pagination to a collection in sequence.
+  # This is the main entry point for processing JSONAPI query parameters.
   #
-  # Public instance methods
+  # The operations are applied in this specific order:
+  # 1. Filtering (apply_filters) - reduces the dataset
+  # 2. Sorting (apply_sort) - orders the results
+  # 3. Pagination (apply_pagination) - limits and offsets for page
   #
-
+  # @param collection [ActiveRecord::Relation] The base collection to process
+  # @return [ActiveRecord::Relation] The processed collection with filters, sorting, and pagination applied
   #
-  # Protected instance methods
+  # @example Basic usage
+  #   def index
+  #     users = apply_fetcheable(User.all)
+  #     render json: users
+  #   end
   #
-  protected
-
-  # Apply filters, sort and page on a collection.
+  # @example With joins for association filtering/sorting
+  #   def index
+  #     posts = apply_fetcheable(Post.joins(:author).includes(:author))
+  #     render json: posts
+  #   end
   def apply_fetcheable(collection)
+    # Apply filtering first to reduce dataset size
     collection = apply_filters(collection)
+
+    # Apply sorting to the filtered results
     collection = apply_sort(collection)
 
+    # Apply pagination last to get the final page
     apply_pagination(collection)
   end
 
-  # Checks if the type of arguments is included in the permitted types
-  def foa_valid_parameters!(
-                            *keys, foa_permitted_types: foa_default_permitted_types)
-    return if foa_valid_params_types(
-      *keys,
-    foa_permitted_types: foa_permitted_types,
-    )
+  # Validates that the specified parameter keys contain values of permitted types.
+  # This is used internally by the filtering, sorting, and pagination modules
+  # to ensure that malformed or malicious parameters don't cause errors.
+  #
+  # @param keys [Array<Symbol>] Path to the parameter to validate (e.g., [:filter], [:page, :number])
+  # @param foa_permitted_types [Array<Class>] Array of allowed parameter types
+  # @raise [FetcheableOnApi::ArgumentError] When parameter type is not in permitted types
+  #
+  # @example
+  #   # Validates that params[:filter] is a Hash or ActionController::Parameters
+  #   foa_valid_parameters!(:filter)
+  #
+  #   # Validates that params[:sort] is a String
+  #   foa_valid_parameters!(:sort, foa_permitted_types: [String])
+  #
+  # @private
+  def foa_valid_parameters!(*keys, foa_permitted_types: foa_default_permitted_types)
+    return if foa_valid_params_types(*keys, foa_permitted_types: foa_permitted_types)
 
+    actual_type = params.dig(*keys).class
     raise FetcheableOnApi::ArgumentError,
-          "Incorrect type #{params.dig(*keys).class} for params #{keys}"
+          "Incorrect type #{actual_type} for params #{keys}"
   end
 
-  def foa_valid_params_types(
-                             *keys, foa_permitted_types: foa_default_permitted_types)
-    foa_permitted_types.inject(false) do |res, type|
-      res || foa_valid_params_type(params.dig(*keys), type)
+  # Checks if the parameter value at the specified keys matches any of the permitted types.
+  #
+  # @param keys [Array<Symbol>] Path to the parameter to check
+  # @param foa_permitted_types [Array<Class>] Array of allowed parameter types
+  # @return [Boolean] True if the parameter type is valid, false otherwise
+  # @private
+  def foa_valid_params_types(*keys, foa_permitted_types: foa_default_permitted_types)
+    foa_permitted_types.inject(false) do |result, type|
+      result || foa_valid_params_type(params.dig(*keys), type)
     end
   end
 
-  # Returns true if class is the class of value,
-  # or if class is one of the superclasses of value
-  # or modules included in value.
+  # Checks if a value is of the specified type using Ruby's is_a? method.
+  # This handles inheritance and module inclusion correctly.
+  #
+  # @param value [Object] The value to type-check
+  # @param type [Class] The expected type/class
+  # @return [Boolean] True if value is an instance of type (or its subclass/module)
+  # @private
   def foa_valid_params_type(value, type)
     value.is_a?(type)
   end
 
-  # Types allowed by default.
+  # Default permitted parameter types for most operations.
+  # ActionController::Parameters is the standard Rails params object,
+  # while Hash is allowed for direct hash parameters in tests or non-Rails usage.
+  #
+  # @return [Array<Class>] Array of default permitted parameter types
+  # @private
   def foa_default_permitted_types
     [ActionController::Parameters, Hash]
   end
 
-  # Convert string to datetime.
+  # Convert string timestamp to DateTime object.
+  # This is used for date/time filtering when the format is set to :datetime.
+  # By default, it expects Unix epoch timestamps as strings.
+  #
+  # This method can be overridden in controllers to support different date formats:
+  #
+  # @param string [String] The timestamp string to convert
+  # @return [DateTime] The parsed DateTime object
+  #
+  # @example Override in controller for custom date format
+  #   class UsersController < ApplicationController
+  #     private
+  #
+  #     def foa_string_to_datetime(string)
+  #       DateTime.strptime(string, '%Y-%m-%d %H:%M:%S')
+  #     end
+  #   end
+  #
+  # @example Default usage with epoch timestamps
+  #   foa_string_to_datetime('1609459200') # => 2021-01-01 00:00:00 +0000
   def foa_string_to_datetime(string)
-    DateTime.strptime(string, "%s")
+    DateTime.strptime(string, '%s')
   end
 end
 
+# Automatically include FetcheableOnApi in all ActionController classes when Rails loads.
+# This makes the filtering, sorting, and pagination functionality available
+# to all controllers without requiring manual inclusion.
+#
+# @note This uses ActiveSupport's lazy loading mechanism to ensure ActionController
+#       is fully loaded before including the module.
 ActiveSupport.on_load :action_controller do
   include FetcheableOnApi
 end

data/lib/generators/fetcheable_on_api/install_generator.rb

@@ -1,10 +1,24 @@
 module FetcheableOnApi
   module Generators
-    # Create conf file
+    # Rails generator for creating FetcheableOnApi initializer file.
+    #
+    # This generator creates a configuration initializer file that allows
+    # developers to customize FetcheableOnApi settings for their application.
+    #
+    # @example Running the generator
+    #   rails generate fetcheable_on_api:install
+    #   # Creates: config/initializers/fetcheable_on_api.rb
+    #
+    # @since 0.1.0
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('../templates', __dir__)
       desc 'Creates FetcheableOnApi initializer for your application'
 
+      # Copy the initializer template to the Rails application's config/initializers directory.
+      # The generated file contains configuration options with sensible defaults and
+      # documentation about available settings.
+      #
+      # @return [void]
       def copy_initializer
         template 'fetcheable_on_api_initializer.rb',
                  'config/initializers/fetcheable_on_api.rb'

data/lib/generators/templates/fetcheable_on_api_initializer.rb

@@ -1,3 +1,17 @@
+# FetcheableOnApi configuration
+#
+# This initializer configures the FetcheableOnApi gem settings for your application.
+# These settings affect the behavior of filtering, sorting, and pagination across
+# all controllers that use the FetcheableOnApi module.
+
 FetcheableOnApi.configure do |config|
+  # Default number of records per page when no page[size] parameter is provided.
+  # This affects the Pageable module when clients don't specify a page size.
+  #
+  # Examples:
+  #   - With default (25): GET /users?page[number]=2 returns 25 records
+  #   - With custom (50): GET /users?page[number]=2 returns 50 records
+  #
+  # Default: 25
   config.pagination_default_size = 25
 end