fetcheable_on_api 0.4.1 → 0.6.1

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]

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.1'.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.6.1'.freeze
 end