fetcheable_on_api 0.4.1 → 0.6.1

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fetcheable_on_api
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Fabien
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-13 00:00:00.000000000 Z
+date: 2025-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -87,6 +87,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ASSOCIATION_SORTING_SOLUTION.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -121,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A controller filters engine gem based on jsonapi spec.