fetcheable_on_api 0.4 → 0.5.0

data/lib/fetcheable_on_api/configuration.rb

@@ -1,12 +1,43 @@
 # frozen_string_literal: true
 
 module FetcheableOnApi
-  # FetcheableOnApi configuration object.
+  # Configuration class for FetcheableOnApi gem settings.
   #
+  # This class holds global configuration options that affect the behavior
+  # of filtering, sorting, and pagination across all controllers that use
+  # the FetcheableOnApi module.
+  #
+  # Configuration is typically set in a Rails initializer file, but can
+  # also be modified at runtime if needed.
+  #
+  # @example Setting configuration in an initializer
+  #   # config/initializers/fetcheable_on_api.rb
+  #   FetcheableOnApi.configure do |config|
+  #     config.pagination_default_size = 50
+  #   end
+  #
+  # @example Runtime configuration changes
+  #   FetcheableOnApi.configuration.pagination_default_size = 100
+  #
+  # @since 0.1.0
   class Configuration
-    # @attribute [Integer] Default pagination size
+    # Default number of records per page when no page[size] parameter is provided.
+    # This value is used by the Pageable module when clients don't specify
+    # a page size in their requests.
+    #
+    # @return [Integer] The default pagination size
+    # @example
+    #   # With default configuration (25):
+    #   # GET /users?page[number]=2
+    #   # Returns 25 records starting from record 26
+    #
+    #   # With custom configuration (50):
+    #   # GET /users?page[number]=2
+    #   # Returns 50 records starting from record 51
     attr_accessor :pagination_default_size
 
+    # Initialize configuration with default values.
+    # Sets up sensible defaults that work well for most applications.
     def initialize
       @pagination_default_size = 25
     end

data/lib/fetcheable_on_api/filterable.rb

@@ -1,11 +1,66 @@
 # frozen_string_literal: true
 
 module FetcheableOnApi
-  # Filterable implements `filter` parameter support.
+  # Filterable implements support for JSONAPI-compliant filtering via `filter` query parameters.
+  #
+  # This module enables controllers to process filter parameters in the format:
+  # `filter[attribute]=value` or `filter[attribute]=value1,value2` for multiple values
+  #
+  # It supports:
+  # - 30+ Arel predicates (eq, ilike, between, in, gt, lt, matches, etc.)
+  # - Association filtering with custom class names
+  # - Custom lambda predicates for complex filtering logic
+  # - Multiple filter values with OR logic
+  # - Date/time filtering with custom formats
+  #
+  # @example Basic filtering setup
+  #   class UsersController < ApplicationController
+  #     filter_by :name, :email, :status
+  #
+  #     def index
+  #       users = apply_fetcheable(User.all)
+  #       render json: users
+  #     end
+  #   end
+  #
+  #   # GET /users?filter[name]=john&filter[status]=active
+  #
+  # @example Association filtering
+  #   class PostsController < ApplicationController
+  #     filter_by :title
+  #     filter_by :author, class_name: User, as: 'name'
+  #
+  #     def index
+  #       posts = apply_fetcheable(Post.joins(:author))
+  #       render json: posts
+  #     end
+  #   end
+  #
+  #   # GET /posts?filter[author]=john&filter[title]=rails
+  #
+  # @example Custom predicates
+  #   class ProductsController < ApplicationController
+  #     filter_by :price, with: :gteq  # Greater than or equal
+  #     filter_by :created_at, with: :between, format: :datetime
+  #
+  #     def index
+  #       products = apply_fetcheable(Product.all)
+  #       render json: products
+  #     end
+  #   end
+  #
+  #   # GET /products?filter[price]=100&filter[created_at]=1609459200,1640995200
+  #
+  # @see https://jsonapi.org/format/#fetching-filtering JSONAPI Filtering Specification
   module Filterable
+    # Arel predicates that expect array values instead of single values.
+    # These predicates work with multiple values and are handled differently
+    # during parameter validation and processing.
     #
-    # Predicates supported for filtering.
-    #
+    # @example Usage with array predicates
+    #   filter_by :tags, with: :in_all
+    #   # Expects: filter[tags][]= or filter[tags]=value1,value2
+    # Arel predicates that expect array values instead of single values.
     PREDICATES_WITH_ARRAY = %i[
       does_not_match_all
       does_not_match_any
@@ -29,149 +84,278 @@ module FetcheableOnApi
       not_in_any
     ].freeze
 
+    # Hook called when Filterable is included in a class.
+    # Sets up the class to support filter configuration and provides
+    # the filter_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 filter configurations per class to avoid conflicts between controllers
         class_attribute :filters_configuration, instance_writer: false
         self.filters_configuration = {}
       end
     end
 
-    # Class methods made available to your controllers.
+    # Class methods made available to controllers when Filterable is included.
     module ClassMethods
-      # Define a filterable attribute.
+      # Define one or more filterable attributes for the controller.
+      #
+      # This method configures which model attributes can be filtered via query parameters
+      # and how those filters should be processed.
+      #
+      # @param attrs [Array<Symbol>] List of attribute names to make filterable
+      # @param options [Hash] Configuration options for the filters
+      # @option options [String, Symbol] :as Alias for the database column name
+      # @option options [Class] :class_name Model class for association filtering (defaults to collection class)
+      # @option options [Symbol, Proc] :with Arel predicate to use (:ilike, :eq, :between, etc.) or custom lambda
+      # @option options [Symbol] :format Value format (:string, :array, :datetime) for parameter processing
+      # @option options [Symbol] :association Association name when different from inferred name
+      #
+      # @example Basic attribute filtering
+      #   filter_by :name, :email, :status
+      #   # Allows: filter[name]=john&filter[email]=john@example.com&filter[status]=active
+      #
+      # @example Custom predicate
+      #   filter_by :age, with: :gteq  # Greater than or equal
+      #   filter_by :created_at, with: :between, format: :datetime
+      #   # Allows: filter[age]=18&filter[created_at]=1609459200,1640995200
+      #
+      # @example Association filtering
+      #   filter_by :author, class_name: User, as: 'name'
+      #   # Allows: filter[author]=john (filters by users.name)
       #
-      # @see FetcheableOnApi::Filterable::PREDICATES_WITH_ARRAY
+      # @example Custom lambda predicate
+      #   filter_by :full_name, with: -> (collection, value) {
+      #     collection.arel_table[:first_name].matches("%#{value}%").or(
+      #       collection.arel_table[:last_name].matches("%#{value}%")
+      #     )
+      #   }
       #
-      # @param attrs [Array] options to define one or more filters.
-      # @option attrs [String, nil] :as Alias the filtered attribute
-      # @option attrs [String, nil] :class_name Override the class of the filter target
-      # @option attrs [String, nil] :with Use a specific predicate
+      # @raise [ArgumentError] When invalid options are provided
+      # @see PREDICATES_WITH_ARRAY For list of array-based predicates
       def filter_by(*attrs)
         options = attrs.extract_options!
         options.symbolize_keys!
-        options.assert_valid_keys(:as, :class_name, :with, :format)
 
+        # Validate that only supported options are provided
+        options.assert_valid_keys(:as, :class_name, :with, :format, :association)
+
+        # Create a new configuration hash to avoid modifying parent class config
         self.filters_configuration = filters_configuration.dup
 
         attrs.each do |attr|
+          # Initialize default configuration for this attribute
           filters_configuration[attr] ||= {
-            as: options[:as] || attr,
+            as: options[:as] || attr
           }
 
+          # Merge in the provided options
           filters_configuration[attr].merge!(options)
         end
       end
     end
 
-    #
-    # Public instance methods
-    #
+    # Protected instance methods for filtering functionality
 
-    #
-    # Protected instance methods
-    #
     protected
 
+    # Generate the list of valid parameter keys for Rails strong parameters.
+    # This method examines the filter configuration to determine which parameters
+    # should be permitted, taking into account predicates that expect arrays.
+    #
+    # @return [Array] Array of parameter keys, with Hash format for array predicates
+    # @example
+    #   # For filter_by :name, :tags (where tags uses in_any predicate)
+    #   # Returns: [:name, {tags: []}]
+    # @private
     def valid_keys
       keys = filters_configuration.keys
       keys.each_with_index do |key, index|
         predicate = filters_configuration[key.to_sym].fetch(:with, :ilike)
 
-        if(%i[between not_between in in_all in_any].include?(predicate))
+        # Special handling for predicates that work with ranges or arrays
+        if %i[between not_between in in_all in_any].include?(predicate)
           format = filters_configuration[key.to_sym].fetch(:format) { nil }
-          keys[index] = {key => []} if format == :array
+          # Use array format for explicit array formatting or for array predicates
+          if format == :array || PREDICATES_WITH_ARRAY.include?(predicate.to_sym)
+            keys[index] = { key => [] }
+          end
           next
         end
 
+        # Skip if it's a custom lambda predicate or doesn't expect arrays
         next if predicate.respond_to?(:call) ||
                 PREDICATES_WITH_ARRAY.exclude?(predicate.to_sym)
 
-        keys[index] = {key => []}
+        # Convert to array format for predicates that expect multiple values
+        keys[index] = { key => [] }
       end
 
       keys
     end
 
+    # Apply filtering to the collection based on filter query parameters.
+    # This is the main method that processes all configured filters and
+    # applies them to the ActiveRecord relation.
+    #
+    # @param collection [ActiveRecord::Relation] The collection to filter
+    # @return [ActiveRecord::Relation] The filtered collection
+    # @raise [FetcheableOnApi::ArgumentError] When filter parameters are invalid
+    #
+    # @example
+    #   # With params: { filter: { name: 'john', status: 'active' } }
+    #   filtered_users = apply_filters(User.all)
+    #   # Generates: WHERE users.name ILIKE '%john%' AND users.status ILIKE '%active%'
     def apply_filters(collection)
+      # Return early if no filter parameters are provided
       return collection if params[:filter].blank?
 
+      # Validate that filter parameters are properly formatted
       foa_valid_parameters!(:filter)
 
+      # Extract and permit only configured filter parameters
       filter_params = params.require(:filter)
-                            .permit(valid_keys)
+                            .permit(*valid_keys)
                             .to_hash
 
+      # Process each filter parameter and build Arel predicates
       filtering = filter_params.map do |column, values|
-        format = filters_configuration[column.to_sym].fetch(:format, :string)
-        column_name = filters_configuration[column.to_sym].fetch(:as, column)
-        klass = filters_configuration[column.to_sym].fetch(:class_name, collection.klass)
+        config = filters_configuration[column.to_sym]
+
+        # Extract configuration for this filter
+        format = config.fetch(:format, :string)
+        column_name = config.fetch(:as, column)
+        klass = config.fetch(:class_name, collection.klass)
         collection_klass = collection.name.constantize
-        predicate = filters_configuration[column.to_sym].fetch(:with, :ilike)
+        association_class_or_name = config.fetch(
+          :association, klass.table_name.to_sym
+        )
+
+        predicate = config.fetch(:with, :ilike)
 
+        # Join association table if filtering on a different model
         if collection_klass != klass
-          collection = collection.joins(klass.table_name.to_sym)
+          collection = collection.joins(association_class_or_name)
         end
 
+        # Skip if values is nil or empty
+        next if values.nil? || values == ""
+        
+        # Handle range-based predicates (between, not_between)
         if %i[between not_between].include?(predicate)
           if values.is_a?(String)
-            predicates(predicate, collection, klass, column_name, values.split(","))
+            # Single range: "start,end"
+            predicates(predicate, collection, klass, column_name, values.split(','))
           else
+            # Multiple ranges: ["start1,end1", "start2,end2"] with OR logic
             values.map do |value|
-              predicates(predicate, collection, klass, column_name, value.split(","))
+              predicates(predicate, collection, klass, column_name, value.split(','))
             end.inject(:or)
           end
         elsif values.is_a?(String)
-          values.split(",").map do |value|
+          # Single value or comma-separated values with OR logic
+          values.split(',').map do |value|
             predicates(predicate, collection, klass, column_name, value)
           end.inject(:or)
         else
-          values.map! { |el| el.split(",") }
+          # Array of values, each potentially comma-separated
+          values.map! { |el| el.split(',') }
           predicates(predicate, collection, klass, column_name, values)
         end
       end
 
+      # Combine all filter predicates with AND logic
       collection.where(filtering.flatten.compact.inject(:and))
     end
 
-    # Apply arel predicate on collection
+    # Build an Arel predicate for the given parameters.
+    # This method translates filter predicates into Arel expressions that can
+    # be used in ActiveRecord where clauses.
+    #
+    # @param predicate [Symbol, Proc] The predicate type (:eq, :ilike, :between, etc.) or custom lambda
+    # @param collection [ActiveRecord::Relation] The collection being filtered (used for lambda predicates)
+    # @param klass [Class] The model class for the attribute being filtered
+    # @param column_name [String, Symbol] The database column name to filter on
+    # @param value [Object] The filter value(s) to compare against
+    # @return [Arel::Node] An Arel predicate node
+    # @raise [ArgumentError] When an unsupported predicate is used
+    #
+    # @example
+    #   # predicates(:eq, collection, User, 'name', 'john')
+    #   # Returns: users.name = 'john'
+    #
+    #   # predicates(:between, collection, User, 'age', [18, 65])
+    #   # Returns: users.age BETWEEN 18 AND 65
+    #
+    # @private
     def predicates(predicate, collection, klass, column_name, value)
       case predicate
+      # Range predicates - work with two values (start, end)
       when :between
         klass.arel_table[column_name].between(value.first..value.last)
-      when :does_not_match
-        klass.arel_table[column_name].does_not_match("%#{value}%")
-      when :does_not_match_all
-        klass.arel_table[column_name].does_not_match_all(value)
-      when :does_not_match_any
-        klass.arel_table[column_name].does_not_match_any(value)
+      when :not_between
+        klass.arel_table[column_name].not_between(value.first..value.last)
+
+      # Equality predicates - exact matching
       when :eq
         klass.arel_table[column_name].eq(value)
+      when :not_eq
+        klass.arel_table[column_name].not_eq(value)
+
+      # Comparison predicates - numeric/date comparisons
+      when :gt
+        klass.arel_table[column_name].gt(value)
+      when :gteq
+        klass.arel_table[column_name].gteq(value)
+      when :lt
+        klass.arel_table[column_name].lt(value)
+      when :lteq
+        klass.arel_table[column_name].lteq(value)
+
+      # Array inclusion predicates - check if value is in a set
+      when :in
+        if value.is_a?(Array)
+          klass.arel_table[column_name].in(value.flatten.compact.uniq)
+        else
+          klass.arel_table[column_name].in(value)
+        end
+      when :not_in
+        klass.arel_table[column_name].not_in(value)
+
+      # Pattern matching predicates - for text search
+      when :ilike
+        # Default predicate - case-insensitive partial matching
+        klass.arel_table[column_name].matches("%#{value}%")
+      when :matches
+        # Exact pattern matching (supports SQL wildcards)
+        klass.arel_table[column_name].matches(value)
+      when :does_not_match
+        klass.arel_table[column_name].does_not_match("%#{value}%")
+
+      # Array-based predicates (work with multiple values)
       when :eq_all
         klass.arel_table[column_name].eq_all(value)
       when :eq_any
         klass.arel_table[column_name].eq_any(value)
-      when :gt
-        klass.arel_table[column_name].gt(value)
       when :gt_all
         klass.arel_table[column_name].gt_all(value)
       when :gt_any
         klass.arel_table[column_name].gt_any(value)
-      when :gteq
-        klass.arel_table[column_name].gteq(value)
       when :gteq_all
         klass.arel_table[column_name].gteq_all(value)
       when :gteq_any
         klass.arel_table[column_name].gteq_any(value)
-      when :in
-        if value.is_a?(Array)
-          klass.arel_table[column_name].in(value.flatten.compact.uniq)
-        else
-          klass.arel_table[column_name].in(value)
-        end
+      when :lt_all
+        klass.arel_table[column_name].lt_all(value)
+      when :lt_any
+        klass.arel_table[column_name].lt_any(value)
+      when :lteq_all
+        klass.arel_table[column_name].lteq_all(value)
+      when :lteq_any
+        klass.arel_table[column_name].lteq_any(value)
       when :in_all
         if value.is_a?(Array)
           klass.arel_table[column_name].in_all(value.flatten.compact.uniq)
@@ -184,51 +368,40 @@ module FetcheableOnApi
         else
           klass.arel_table[column_name].in_any(value)
         end
-      when :lt
-        klass.arel_table[column_name].lt(value)
-      when :lt_all
-        klass.arel_table[column_name].lt_all(value)
-      when :lt_any
-        klass.arel_table[column_name].lt_any(value)
-      when :lteq
-        klass.arel_table[column_name].lteq(value)
-      when :lteq_all
-        klass.arel_table[column_name].lteq_all(value)
-      when :lteq_any
-        klass.arel_table[column_name].lteq_any(value)
-      when :ilike
-        klass.arel_table[column_name].matches("%#{value}%")
-      when :matches
-        klass.arel_table[column_name].matches(value)
-      when :matches_all
-        klass.arel_table[column_name].matches_all(value)
-      when :matches_any
-        klass.arel_table[column_name].matches_any(value)
-      when :not_between
-        klass.arel_table[column_name].not_between(value.first..value.last)
-      when :not_eq
-        klass.arel_table[column_name].not_eq(value)
       when :not_eq_all
         klass.arel_table[column_name].not_eq_all(value)
       when :not_eq_any
         klass.arel_table[column_name].not_eq_any(value)
-      when :not_in
-        klass.arel_table[column_name].not_in(value)
       when :not_in_all
         klass.arel_table[column_name].not_in_all(value)
       when :not_in_any
         klass.arel_table[column_name].not_in_any(value)
+      when :matches_all
+        klass.arel_table[column_name].matches_all(value)
+      when :matches_any
+        klass.arel_table[column_name].matches_any(value)
+      when :does_not_match_all
+        klass.arel_table[column_name].does_not_match_all(value)
+      when :does_not_match_any
+        klass.arel_table[column_name].does_not_match_any(value)
       else
+        # Handle custom lambda predicates
         unless predicate.respond_to?(:call)
           raise ArgumentError,
                 "unsupported predicate `#{predicate}`"
         end
 
+        # Call the custom predicate with collection and value
         predicate.call(collection, value)
       end
     end
 
-    # Types allowed by default for filter action.
+    # Override the default permitted types to allow Arrays for filter parameters.
+    # Filtering supports more flexible parameter types compared to sorting/pagination
+    # since filter values can be arrays of values for certain predicates.
+    #
+    # @return [Array<Class>] Array of permitted parameter types for filtering
+    # @private
     def foa_default_permitted_types
       [ActionController::Parameters, Hash, Array]
     end

data/lib/fetcheable_on_api/pageable.rb

@@ -1,68 +1,126 @@
 # frozen_string_literal: true
 
 module FetcheableOnApi
-  # Pageable implements pagination support.
+  # Pageable implements support for JSONAPI-compliant pagination via `page` query parameters.
+  #
+  # This module enables controllers to process pagination parameters in the format:
+  # `page[number]=2&page[size]=25` following the JSONAPI specification for page-based pagination.
   #
   # It handles the controller parameters:
+  # - `page[number]` - The requested page number (default: 1)
+  # - `page[size]` - Number of records per page (default: from configuration)
+  #
+  # If no `page` parameter is present on the request, the full collection is returned.
+  #
+  # The following pagination information is automatically added to response headers:
+  # - `Pagination-Current-Page` - The page number that is returned
+  # - `Pagination-Per` - The number of records included in the page
+  # - `Pagination-Total-Pages` - The total number of pages available
+  # - `Pagination-Total-Count` - The total number of records available
   #
-  # - <code>page[:number]</code> the requested page (default: 1).
-  # - <code>page[:size]</code> number of records per page.
+  # @example Basic pagination setup
+  #   class UsersController < ApplicationController
+  #     def index
+  #       users = apply_fetcheable(User.all)
+  #       render json: users
+  #       # Response headers will include pagination info
+  #     end
+  #   end
   #
-  # If no <code>page</code> parameter is present on the request, the full collection is
-  # returned.
+  #   # GET /users?page[number]=2&page[size]=10
   #
-  # The following pagination information is add to the response headers:
+  # @example With custom default page size
+  #   # In config/initializers/fetcheable_on_api.rb
+  #   FetcheableOnApi.configure do |config|
+  #     config.pagination_default_size = 50
+  #   end
   #
-  # - <code>Pagination-Current-Page</code> the page that is returned.
-  # - <code>Pagination-Per</code> the number of records included in the page.
-  # - <code>Pagination-Total-Pages</code> the total number of pages available.
-  # - <code>Pagination-Total-Count</code> the total number of records available.
+  # @example Response headers
+  #   # Pagination-Current-Page: 2
+  #   # Pagination-Per: 10
+  #   # Pagination-Total-Pages: 15
+  #   # Pagination-Total-Count: 150
   #
+  # @see https://jsonapi.org/format/#fetching-pagination JSONAPI Pagination Specification
   module Pageable
-    #
-    # Supports
-    #
+    # Protected instance methods for pagination functionality
 
-    #
-    # Public class methods
-    #
-
-    #
-    # Public instance methods
-    #
+    protected
 
+    # Apply pagination to the collection based on page query parameters.
+    # This is the main method that processes page parameters and applies
+    # limit/offset to the ActiveRecord relation while setting response headers.
     #
-    # Protected instance methods
+    # @param collection [ActiveRecord::Relation] The collection to paginate
+    # @return [ActiveRecord::Relation] The paginated collection with limit and offset applied
+    # @raise [FetcheableOnApi::ArgumentError] When page parameters are invalid
     #
-    protected
-
+    # @example
+    #   # With params: { page: { number: 2, size: 10 } }
+    #   paginated_users = apply_pagination(User.all)
+    #   # Generates: LIMIT 10 OFFSET 10
+    #   # Sets headers: Pagination-Current-Page: 2, Pagination-Per: 10, etc.
     def apply_pagination(collection)
+      # Return early if no pagination parameters are provided
       return collection if params[:page].blank?
 
+      # Validate that page parameters are properly formatted
       foa_valid_parameters!(:page)
 
+      # Extract pagination values and count total records
       limit, offset, count, page = extract_pagination_informations(collection)
+
+      # Set pagination headers for the response
       define_header_pagination(limit, count, page)
 
+      # Apply limit and offset to the collection
       collection.limit(limit).offset(offset)
     end
 
     private
 
+    # Set pagination information in the response headers.
+    # These headers provide clients with information about the current page
+    # and total number of records/pages available.
+    #
+    # @param limit [Integer] Number of records per page
+    # @param count [Integer] Total number of records
+    # @param page [Integer] Current page number
+    # @private
     def define_header_pagination(limit, count, page)
-      response.headers["Pagination-Current-Page"] = page
-      response.headers["Pagination-Per"] = limit
-      response.headers["Pagination-Total-Pages"] = (count.to_f / limit.to_f).ceil
-      response.headers["Pagination-Total-Count"] = count
+      response.headers['Pagination-Current-Page'] = page
+      response.headers['Pagination-Per'] = limit
+      response.headers['Pagination-Total-Pages'] = limit > 0 ? (count.to_f / limit.to_f).ceil : 0
+      response.headers['Pagination-Total-Count'] = count
     end
 
+    # Extract and calculate pagination information from parameters and collection.
+    # This method processes the page parameters and calculates the appropriate
+    # limit, offset, total count, and current page number.
+    #
+    # @param collection [ActiveRecord::Relation] The collection to paginate
+    # @return [Array<Integer>] Array containing [limit, offset, count, page]
+    #
+    # @example
+    #   # With params: { page: { number: 3, size: 20 } }
+    #   limit, offset, count, page = extract_pagination_informations(User.all)
+    #   # => [20, 40, 150, 3] (20 per page, skip 40 records, 150 total, page 3)
+    #
+    # @private
     def extract_pagination_informations(collection)
+      # Get page size from parameters or use configured default
       limit = params[:page].fetch(
         :size, FetcheableOnApi.configuration.pagination_default_size
       ).to_i
 
+      # Get page number from parameters or default to 1
       page = params[:page].fetch(:number, 1).to_i
+
+      # Calculate offset based on page number and size
       offset = (page - 1) * limit
+
+      # Count total records excluding any existing pagination/ordering
+      # This ensures we get the total count before any pagination is applied
       count = collection.except(:offset, :limit, :order).count
 
       [limit, offset, count, page]