kiroshi 0.1.0 → 0.2.0

data/lib/kiroshi/filter_runner.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  # @api private
+  # @author darthjee
+  #
+  # A filter runner that applies filtering logic to ActiveRecord scopes
+  #
+  # This class handles the actual application of filter logic to database queries,
+  # supporting both exact matches and partial matches using SQL LIKE operations.
+  # It separates the filter configuration from the filter execution logic.
+  #
+  # @example Creating and running a filter
+  #   filter = Kiroshi::Filter.new(:name, match: :like)
+  #   runner = Kiroshi::FilterRunner.new(filter: filter, scope: User.all, value: 'John')
+  #   result = runner.apply
+  #
+  # @example Creating and running a filter with specific value
+  #   filter = Kiroshi::Filter.new(:status)
+  #   runner = Kiroshi::FilterRunner.new(filter: filter, scope: User.all, value: 'active')
+  #   result = runner.apply
+  #
+  # @since 0.1.0
+  class FilterRunner
+    # Creates a new FilterRunner instance
+    #
+    # @param filter [Kiroshi::Filter] the filter configuration
+    # @param scope [ActiveRecord::Relation] the scope to filter
+    # @param value [Object, nil] the specific value to use for filtering, defaults to nil
+    #
+    # @since 0.2.0
+    def initialize(filter:, scope:, value: nil)
+      @filter = filter
+      @scope = scope
+      @value = value
+    end
+
+    # Applies the filter logic to the scope
+    #
+    # This method contains the actual filtering logic, checking the filter's
+    # match type and applying the appropriate WHERE clause to the scope.
+    #
+    # @return [ActiveRecord::Relation] the filtered scope
+    #
+    # @example Applying exact match filter
+    #   runner = FilterRunner.new(filter: filter, scope: scope, value: 'John')
+    #   runner.apply
+    #
+    # @example Applying LIKE filter
+    #   runner = FilterRunner.new(filter: filter, scope: scope, value: 'Ruby')
+    #   runner.apply
+    #
+    # @example With specific value provided
+    #   runner = FilterRunner.new(filter: filter, scope: scope, value: 'specific_value')
+    #   runner.apply
+    #
+    # @example With no value (returns unchanged scope)
+    #   runner = FilterRunner.new(filter: filter, scope: scope, value: nil)
+    #   runner.apply
+    #   # Returns the original scope unchanged
+    #
+    # @since 0.1.1
+    def apply
+      return scope unless value.present?
+
+      query_strategy = FilterQuery.for(filter.match).new(self)
+      query_strategy.apply
+    end
+
+    attr_reader :scope, :value
+
+    # @!method scope
+    #   @api private
+    #
+    #   Returns the current scope being filtered
+    #
+    #   @return [ActiveRecord::Relation] the scope
+    #
+    #   @since 0.1.1
+
+    # @!method value
+    #   @api private
+    #
+    #   Returns the filter value for the current filter
+    #
+    #   @return [Object] the filter value or nil if not present
+    #
+    #   @since 0.2.0
+
+    # Returns the table name to use for the filter
+    #
+    # This method prioritizes the filter's table_name over the scope's table_name.
+    # If the filter has a specific table_name configured, it uses that;
+    # otherwise, it falls back to the scope's table_name.
+    #
+    # @return [String] the table name to use for filtering
+    #
+    # @example With filter table_name specified
+    #   filter = Kiroshi::Filter.new(:name, table: 'tags')
+    #   runner = FilterRunner.new(filter: filter, scope: Document.joins(:tags), value: 'ruby')
+    #   runner.table_name # => 'tags'
+    #
+    # @example Without filter table_name (fallback to scope)
+    #   filter = Kiroshi::Filter.new(:name)
+    #   runner = FilterRunner.new(filter: filter, scope: Document.all, value: 'test')
+    #   runner.table_name # => 'documents'
+    #
+    # @since 0.1.1
+    def table_name
+      filter_table_name || scope_table_name
+    end
+
+    # @!method scope
+    #   @api private
+    #
+    #   Returns the current scope being filtered
+    #
+    #   @return [ActiveRecord::Relation] the scope
+
+    # @!method value
+    #   @api private
+    #
+    #   Returns the filter value for the current filter
+    #
+    #   @return [Object, nil] the filter value or nil if not present
+
+    private
+
+    attr_reader :filter
+
+    # @!method filter
+    #   @api private
+    #   @private
+    #
+    #   Returns the filter configuration
+    #
+    #   @return [Kiroshi::Filter] the filter configuration
+
+    delegate :attribute, to: :filter
+    delegate :table_name, to: :scope, prefix: true
+    delegate :table_name, to: :filter, prefix: true
+
+    # @!method attribute
+    #   @api private
+    #
+    #   Returns the attribute name to filter by
+    #
+    #   @return [Symbol] the attribute name to filter by
+
+    # @!method scope_table_name
+    #   @api private
+    #
+    #   Returns the table name from the scope
+    #
+    #   @return [String] the table name from the scope
+
+    # @!method filter_table_name
+    #   @api private
+    #
+    #   Returns the table name from the filter configuration
+    #
+    #   @return [String, nil] the table name from the filter or nil if not specified
+  end
+end

data/lib/kiroshi/filters/class_methods.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  class Filters
+    # @api public
+    # Class-level methods for configuring filters in Kiroshi::Filters
+    #
+    # This module provides the DSL methods that allow filter classes to
+    # define their filtering behavior using class-level method calls.
+    # These methods are automatically available when extending Kiroshi::Filters.
+    #
+    # The primary interface is the {.filter_by} method, which registers
+    # filters that will be applied when {Filters#apply} is called on
+    # instances of the filter class.
+    #
+    # @example Basic filter configuration
+    #   class DocumentFilters < Kiroshi::Filters
+    #     filter_by :name, match: :like
+    #     filter_by :status
+    #     filter_by :category, table: :documents
+    #   end
+    #
+    # @example Accessing filter configurations
+    #   DocumentFilters.filter_configs.keys # => [:name, :status, :category]
+    #   DocumentFilters.filter_configs[:name].match # => :like
+    #
+    # @since 0.2.0
+    # @author darthjee
+    module ClassMethods
+      # Defines a filter for the current filter class
+      #
+      # This method is used at the class level to configure filters that will
+      # be applied when {Filters#apply} is called. Each call creates a new {Filter}
+      # instance with the specified configuration and stores it in the class's
+      # filter registry for later use during filtering operations.
+      #
+      # The method supports various matching strategies and table qualification
+      # options to handle complex database queries with joins and ambiguous
+      # column names.
+      #
+      # @overload filter_by(attribute, **options)
+      #   @param attribute [Symbol] the attribute name to filter by
+      #   @param options [Hash] additional options passed to {Filter#initialize}
+      #   @option options [Symbol] :match (:exact) the matching type
+      #     - +:exact+ for exact matching (default)
+      #     - +:like+ for partial matching using SQL LIKE with wildcards
+      #   @option options [String, Symbol, nil] :table (nil) the table name to qualify the attribute
+      #     when dealing with joined tables that have conflicting column names
+      #
+      # @return (see Filters.filter_by)
+      # @example (see Filters.filter_by)
+      # @note (see Filters.filter_by)
+      # @see (see Filters.filter_by)
+      # @since (see Filters.filter_by)
+      def filter_by(attribute, **)
+        Filter.new(attribute, **).tap do |filter|
+          filter_configs[attribute] = filter
+        end
+      end
+
+      # @api private
+      # Returns the filter configuration for a specific attribute
+      #
+      # This method provides a convenient way to retrieve a specific filter
+      # by its attribute name. It's a shorthand for accessing the filter_configs
+      # hash directly and is used internally by the filtering system.
+      #
+      # @param attribute [Symbol] the attribute name to look up
+      #
+      # @return [Filter, nil] the filter instance for the given attribute,
+      #   or nil if no filter is configured for that attribute
+      #
+      # @example Retrieving a specific filter
+      #   class MyFilters < Kiroshi::Filters
+      #     filter_by :name, match: :like
+      #     filter_by :status
+      #   end
+      #
+      #   MyFilters.filter_for(:name)    # => #<Kiroshi::Filter:0x... @attribute=:name @match=:like>
+      #   MyFilters.filter_for(:status)  # => #<Kiroshi::Filter:0x... @attribute=:status @match=:exact>
+      #   MyFilters.filter_for(:unknown) # => nil
+      #
+      # @see .filter_configs for accessing the complete filter registry
+      # @see Filters#apply for how this method is used during filtering
+      #
+      # @since 0.2.0
+      def filter_for(attribute)
+        filter_configs[attribute] || inherited_filter_for(attribute)
+      end
+
+      private
+
+      # @api private
+      # @private
+      #
+      # Searches for a filter in the inheritance chain
+      #
+      # This method looks up the inheritance chain to find a filter configuration
+      # for the given attribute. It only searches in superclasses that inherit
+      # from Kiroshi::Filters, stopping when it reaches a non-Filters class.
+      #
+      # @param attribute [Symbol] the attribute name to look up
+      # @return [Filter, nil] the filter instance from a parent class, or nil if not found
+      #
+      # @since 0.2.0
+      def inherited_filter_for(attribute)
+        return nil unless superclass < Kiroshi::Filters
+
+        superclass.filter_for(attribute)
+      end
+
+      # @api private
+      # @private
+      #
+      # Returns the hash of configured filters for this filter class
+      #
+      # This method provides access to the internal registry of filters
+      # that have been configured using {.filter_by}. The returned hash
+      # contains {Filter} instances keyed by their attribute names, allowing
+      # for efficient O(1) lookup during filter application.
+      #
+      # This method is primarily used internally by {Filters#apply} to
+      # iterate through and apply all configured filters to a scope.
+      # While marked as private API, it may be useful for introspection
+      # and testing purposes.
+      #
+      # @return [Hash<Symbol, Filter>] hash of {Filter} instances configured
+      #   for this filter class, keyed by attribute name for efficient access
+      #
+      # @example Accessing configured filters for introspection
+      #   class MyFilters < Kiroshi::Filters
+      #     filter_by :name, match: :like
+      #     filter_by :status
+      #     filter_by :category, table: :categories
+      #   end
+      #
+      #   MyFilters.filter_configs.length                    # => 3
+      #   MyFilters.filter_configs.keys                      # => [:name, :status, :category]
+      #   MyFilters.filter_configs[:name].attribute          # => :name
+      #   MyFilters.filter_configs[:name].match              # => :like
+      #   MyFilters.filter_configs[:status].match            # => :exact
+      #   MyFilters.filter_configs[:category].table_name     # => :categories
+      #
+      # @example Using in tests to verify filter configuration
+      #   RSpec.describe ProductFilters do
+      #     it 'configures the expected filters' do
+      #       expect(described_class.filter_configs).to have_key(:name)
+      #       expect(described_class.filter_configs[:name].match).to eq(:like)
+      #     end
+      #   end
+      #
+      # @note This method returns a reference to the actual internal hash.
+      #   Modifying the returned hash directly will affect the filter class
+      #   configuration. Use {.filter_by} for proper filter registration.
+      #
+      # @note The hash is lazily initialized on first access and persists
+      #   for the lifetime of the class. Each filter class maintains its
+      #   own separate filter_configs hash.
+      #
+      # @see .filter_by for adding filters to this configuration
+      # @see Filters#apply for how these configurations are used
+      #
+      # @since 0.2.0
+      def filter_configs
+        @filter_configs ||= {}
+      end
+    end
+  end
+end

data/lib/kiroshi/filters.rb

@@ -36,66 +36,69 @@ module Kiroshi
   #
   # @since 0.1.0
   class Filters
-    class << self
-      # Defines a filter for the current filter class
-      #
-      # This method is used at the class level to configure filters that will
-      # be applied when {#apply} is called. Each call creates a new {Filter}
-      # instance with the specified configuration.
-      #
-      # @param attribute [Symbol] the attribute name to filter by
-      # @param options [Hash] additional options passed to {Filter#initialize}
-      # @option options [Symbol] :match (:exact) the matching type
-      #   - +:exact+ for exact matching (default)
-      #   - +:like+ for partial matching using SQL LIKE
-      #
-      # @return [Filter] the new filter instance
-      #
-      # @example Defining exact match filters
-      #   class ProductFilters < Kiroshi::Filters
-      #     filter_by :category
-      #     filter_by :brand
-      #   end
-      #
-      # @example Defining partial match filters
-      #   class SearchFilters < Kiroshi::Filters
-      #     filter_by :title, match: :like
-      #     filter_by :description, match: :like
-      #   end
-      #
-      # @example Mixed filter types
-      #   class OrderFilters < Kiroshi::Filters
-      #     filter_by :customer_name, match: :like
-      #     filter_by :status, match: :exact
-      #     filter_by :payment_method
-      #   end
-      #
-      # @since 0.1.0
-      def filter_by(attribute, **)
-        Filter.new(attribute, **).tap do |filter|
-          filter_configs << filter
-        end
-      end
+    autoload :ClassMethods, 'kiroshi/filters/class_methods'
 
-      # Returns the list of configured filters for this class
-      #
-      # @return [Array<Filter>] array of {Filter} instances configured
-      #   for this filter class
-      #
-      # @example Accessing configured filters
-      #   class MyFilters < Kiroshi::Filters
-      #     filter_by :name
-      #     filter_by :status, match: :like
-      #   end
-      #
-      #   MyFilters.filter_configs.length # => 2
-      #   MyFilters.filter_configs.first.attribute # => :name
-      #
-      # @since 0.1.0
-      def filter_configs
-        @filter_configs ||= []
-      end
-    end
+    extend ClassMethods
+
+    # @method self.filter_by(attribute, **options)
+    #   @api public
+    #   @param attribute [Symbol] the attribute name to filter by
+    #   @param options [Hash] additional options passed to {Filter#initialize}
+    #   @option options [Symbol] :match (:exact) the matching type
+    #     - +:exact+ for exact matching (default)
+    #     - +:like+ for partial matching using SQL LIKE with wildcards
+    #   @option options [String, Symbol, nil] :table (nil) the table name to qualify the attribute
+    #     when dealing with joined tables that have conflicting column names
+    #
+    #   @return [Filter] the new filter instance that was created and registered
+    #
+    #   @example Defining exact match filters
+    #     class ProductFilters < Kiroshi::Filters
+    #       filter_by :category      # Exact match on category
+    #       filter_by :brand         # Exact match on brand
+    #       filter_by :active        # Exact match on active status
+    #     end
+    #
+    #   @example Defining partial match filters
+    #     class SearchFilters < Kiroshi::Filters
+    #       filter_by :title, match: :like         # Partial match on title
+    #       filter_by :description, match: :like   # Partial match on description
+    #       filter_by :author_name, match: :like   # Partial match on author name
+    #     end
+    #
+    #   @example Mixed filter types with different matching strategies
+    #     class OrderFilters < Kiroshi::Filters
+    #       filter_by :customer_name, match: :like  # Partial match for customer search
+    #       filter_by :status, match: :exact        # Exact match for order status
+    #       filter_by :payment_method               # Exact match (default) for payment
+    #     end
+    #
+    #   @example Filters with table qualification for joined queries
+    #     class DocumentTagFilters < Kiroshi::Filters
+    #       filter_by :name, table: :documents      # Filter by document name
+    #       filter_by :tag_name, table: :tags       # Filter by tag name
+    #       filter_by :category, table: :categories # Filter by category name
+    #     end
+    #
+    #   @example Complex real-world filter class
+    #     class ProductSearchFilters < Kiroshi::Filters
+    #       filter_by :name, match: :like                    # Product name search
+    #       filter_by :category_id                           # Exact category match
+    #       filter_by :brand, match: :like                   # Brand name search
+    #       filter_by :price_min                             # Minimum price
+    #       filter_by :price_max                             # Maximum price
+    #       filter_by :in_stock                              # Availability filter
+    #       filter_by :category_name, table: :categories     # Category name via join
+    #     end
+    #
+    #   @note When using table qualification, ensure that the specified table
+    #     is properly joined in the scope being filtered. The filter will not
+    #     automatically add joins - it only qualifies the column name.
+    #
+    #   @see Filter#initialize for detailed information about filter options
+    #   @see Filters#apply for how these filters are used during query execution
+    #
+    #   @since 0.1.0
 
     # Creates a new Filters instance
     #
@@ -153,10 +156,13 @@ module Kiroshi
     #   filtered_articles = filters.apply(Article.all)
     #   # Generates: WHERE title LIKE '%Ruby%'
     #
-    # @since 0.1.0
+    # @since 0.2.0
     def apply(scope)
-      self.class.filter_configs.each do |filter|
-        scope = filter.apply(scope, filters)
+      filters.compact.each do |attribute, value|
+        filter = self.class.filter_for(attribute)
+        next unless filter
+
+        scope = filter.apply(scope: scope, value: value)
       end
 
       scope

data/lib/kiroshi/version.rb

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

data/lib/kiroshi.rb

@@ -2,8 +2,143 @@
 
 # @api public
 # @author darthjee
+#
+# Kiroshi - Flexible ActiveRecord Query Filtering
+#
+# Kiroshi provides a clean and extensible way to filter ActiveRecord queries
+# using a declarative DSL. It supports multiple matching strategies and can
+# be easily integrated into Rails controllers and other components.
+#
+# The gem is designed around the main concept:
+# - {Filters}: A base class for creating reusable filter sets
+#
+# Individual filters are handled internally and don't require direct interaction.
+#
+# @example Basic filter class definition
+#   class DocumentFilters < Kiroshi::Filters
+#     filter_by :name, match: :like
+#     filter_by :status
+#     filter_by :category
+#   end
+#
+#   # Usage
+#   filters = DocumentFilters.new(name: 'report', status: 'published')
+#   filtered_documents = filters.apply(Document.all)
+#   # Generates: WHERE name LIKE '%report%' AND status = 'published'
+#
+# @example Controller integration
+#   # URL: /articles?filter[title]=ruby&filter[author]=john&filter[category]=tech
+#   class ArticlesController < ApplicationController
+#     def index
+#       @articles = article_filters.apply(Article.published)
+#       render json: @articles
+#     end
+#
+#     private
+#
+#     def article_filters
+#       ArticleFilters.new(filter_params)
+#     end
+#
+#     def filter_params
+#       params[:filter]&.permit(:title, :author, :category, :tag)
+#     end
+#   end
+#
+#   class ArticleFilters < Kiroshi::Filters
+#     filter_by :title, match: :like
+#     filter_by :author, match: :like
+#     filter_by :category
+#     filter_by :tag
+#   end
+#
+# @example Advanced filtering scenarios
+#   class UserFilters < Kiroshi::Filters
+#     filter_by :email, match: :like
+#     filter_by :role
+#     filter_by :active, match: :exact
+#     filter_by :department
+#   end
+#
+#   # Apply multiple filters
+#   filters = UserFilters.new(
+#     email: 'admin',
+#     role: 'moderator',
+#     active: true
+#   )
+#   filtered_users = filters.apply(User.includes(:department))
+#   # Generates: WHERE email LIKE '%admin%' AND role = 'moderator' AND active = true
+#
+# @example Empty value handling
+#   filters = DocumentFilters.new(name: '', status: 'published')
+#   result = filters.apply(Document.all)
+#   # Only status filter is applied, name is ignored due to empty value
+#
+# @example Chaining with existing scopes
+#   # URL: /orders?filter[status]=completed&filter[customer_name]=john
+#   class OrderFilters < Kiroshi::Filters
+#     filter_by :customer_name, match: :like
+#     filter_by :status
+#     filter_by :payment_method
+#   end
+#
+#   # Apply to pre-filtered scope
+#   recent_orders = Order.where('created_at > ?', 1.month.ago)
+#   filters = OrderFilters.new(status: 'completed', customer_name: 'john')
+#   filtered_orders = filters.apply(recent_orders)
+#
+# @example Complex controller with pagination
+#   # URL: /products?filter[name]=laptop&filter[category]=electronics&filter[in_stock]=true&page=2
+#   class ProductsController < ApplicationController
+#     def index
+#       @products = filtered_products.page(params[:page])
+#       render json: {
+#         products: @products,
+#         total: filtered_products.count,
+#         filters_applied: applied_filter_count
+#       }
+#     end
+#
+#     private
+#
+#     def filtered_products
+#       @filtered_products ||= product_filters.apply(base_scope)
+#     end
+#
+#     def base_scope
+#       Product.includes(:category, :brand).available
+#     end
+#
+#     def product_filters
+#       ProductFilters.new(filter_params)
+#     end
+#
+#     def filter_params
+#       params[:filter]&.permit(:name, :category, :brand, :price_range, :in_stock)
+#     end
+#
+#     def applied_filter_count
+#       filter_params.compact.count
+#     end
+#   end
+#
+#   class ProductFilters < Kiroshi::Filters
+#     filter_by :name, match: :like
+#     filter_by :category
+#     filter_by :brand
+#     filter_by :in_stock, match: :exact
+#   end
+#
+# @see Filters Base class for creating filter sets
+# @see https://github.com/darthjee/kiroshi GitHub repository
+# @see https://www.rubydoc.info/gems/kiroshi YARD documentation
+#
+# @since 0.1.0
 module Kiroshi
-  autoload :VERSION, 'kiroshi/version'
-  autoload :Filters, 'kiroshi/filters'
-  autoload :Filter,  'kiroshi/filter'
+  autoload :VERSION,      'kiroshi/version'
+
+  autoload :Filters,      'kiroshi/filters'
+  autoload :Filter,       'kiroshi/filter'
+  autoload :FilterRunner, 'kiroshi/filter_runner'
+  autoload :FilterQuery,  'kiroshi/filter_query'
 end