kiroshi 0.1.1 → 0.3.0

data/lib/kiroshi/filter_runner.rb

@@ -12,7 +12,12 @@ module Kiroshi
   #
   # @example Creating and running a filter
   #   filter = Kiroshi::Filter.new(:name, match: :like)
-  #   runner = Kiroshi::FilterRunner.new(filter: filter, scope: User.all, filters: { name: 'John' })
+  #   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
@@ -21,13 +26,13 @@ module Kiroshi
     #
     # @param filter [Kiroshi::Filter] the filter configuration
     # @param scope [ActiveRecord::Relation] the scope to filter
-    # @param filters [Hash] a hash containing filter values
+    # @param value [Object, nil] the specific value to use for filtering, defaults to nil
     #
-    # @since 0.1.0
-    def initialize(filter:, scope:, filters:)
+    # @since 0.2.0
+    def initialize(filter:, scope:, value: nil)
       @filter = filter
       @scope = scope
-      @filters = filters
+      @value = value
     end
 
     # Applies the filter logic to the scope
@@ -38,41 +43,49 @@ module Kiroshi
     # @return [ActiveRecord::Relation] the filtered scope
     #
     # @example Applying exact match filter
-    #   runner = FilterRunner.new(filter: filter, scope: scope, filters: { name: 'John' })
+    #   runner = FilterRunner.new(filter: filter, scope: scope, value: 'John')
     #   runner.apply
     #
     # @example Applying LIKE filter
-    #   runner = FilterRunner.new(filter: filter, scope: scope, filters: { title: 'Ruby' })
+    #   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 matching value
-    #   runner = FilterRunner.new(filter: filter, scope: scope, filters: { name: nil })
+    # @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 filter_value.present?
+      return scope unless value.present?
 
       query_strategy = FilterQuery.for(filter.match).new(self)
       query_strategy.apply
     end
 
-    # Returns the filter value for the current filter's attribute
+    attr_reader :scope, :value
+
+    # @!method scope
+    #   @api private
     #
-    # @return [Object, nil] the filter value or nil if not present
+    #   Returns the current scope being filtered
     #
-    # @since 0.1.1
-    def filter_value
-      filters[filter.attribute]
-    end
+    #   @return [ActiveRecord::Relation] the scope
+    #
+    #   @since 0.1.1
 
-    # Returns the current scope being filtered
+    # @!method value
+    #   @api private
     #
-    # @return [ActiveRecord::Relation] the scope
+    #   Returns the filter value for the current filter
     #
-    # @since 0.1.1
-    attr_reader :scope
+    #   @return [Object] the filter value or nil if not present
+    #
+    #   @since 0.2.0
 
     # Returns the table name to use for the filter
     #
@@ -84,12 +97,12 @@ module Kiroshi
     #
     # @example With filter table_name specified
     #   filter = Kiroshi::Filter.new(:name, table: 'tags')
-    #   runner = FilterRunner.new(filter: filter, scope: Document.joins(:tags), filters: {})
+    #   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, filters: {})
+    #   runner = FilterRunner.new(filter: filter, scope: Document.all, value: 'test')
     #   runner.table_name # => 'documents'
     #
     # @since 0.1.1
@@ -104,9 +117,16 @@ module Kiroshi
     #
     #   @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, :filters
+    attr_reader :filter
 
     # @!method filter
     #   @api private
@@ -116,24 +136,16 @@ module Kiroshi
     #
     #   @return [Kiroshi::Filter] the filter configuration
 
-    # @!method filters
-    #   @api private
-    #   @private
-    #
-    #   Returns the hash of filter values
-    #
-    #   @return [Hash] the hash of filter values
-
-    delegate :attribute, to: :filter
+    delegate :column, to: :filter
     delegate :table_name, to: :scope, prefix: true
     delegate :table_name, to: :filter, prefix: true
 
-    # @!method attribute
+    # @!method column
     #   @api private
     #
-    #   Returns the attribute name to filter by
+    #   Returns the column name to use in database queries
     #
-    #   @return [Symbol] the attribute name to filter by
+    #   @return [Symbol] the column name to use in database queries
 
     # @!method scope_table_name
     #   @api private

data/lib/kiroshi/filters/class_methods.rb

@@ -0,0 +1,172 @@
+# 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(filter_key, **options)
+      #   @param filter_key [Symbol] the filter key name to identify this filter
+      #   @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 column
+      #     when dealing with joined tables that have conflicting column names
+      #   @option options [Symbol, nil] :column (nil) the column name to use in database queries,
+      #     defaults to filter_key if not specified
+      #
+      # @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(filter_key, **options)
+        Filter.new(filter_key, **options).tap do |filter|
+          filter_configs[filter_key.to_s] = filter
+        end
+      end
+
+      # @api private
+      # Returns the filter configuration for a specific filter key
+      #
+      # This method provides a convenient way to retrieve a specific filter
+      # by its filter key name. It's a shorthand for accessing the filter_configs
+      # hash directly and is used internally by the filtering system.
+      #
+      # @param filter_key [Symbol, String] the filter key name to look up
+      #
+      # @return [Filter, nil] the filter instance for the given filter key,
+      #   or nil if no filter is configured for that filter key
+      #
+      # @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... @filter_key=:name @match=:like>
+      #   MyFilters.filter_for(:status)  # => #<Kiroshi::Filter:0x... @filter_key=: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.3.0
+      def filter_for(filter_key)
+        filter_key_string = filter_key.to_s
+        filter_configs[filter_key_string] || inherited_filter_for(filter_key_string)
+      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 filter key. It only searches in superclasses that inherit
+      # from Kiroshi::Filters, stopping when it reaches a non-Filters class.
+      #
+      # @param filter_key_string [String] the filter key name to look up
+      # @return [Filter, nil] the filter instance from a parent class, or nil if not found
+      #
+      # @since 0.3.0
+      def inherited_filter_for(filter_key_string)
+        return nil unless superclass < Kiroshi::Filters
+
+        superclass.filter_for(filter_key_string)
+      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 filter key 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<String, Filter>] hash of {Filter} instances configured
+      #   for this filter class, keyed by filter key 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,78 +36,83 @@ 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.
-      #
-      # @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
-      #   @option options [String, Symbol, nil] :table (nil) the table name to qualify the attribute
-      #
-      # @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
-      #
-      # @example Filter with table qualification
-      #   class DocumentTagFilters < Kiroshi::Filters
-      #     filter_by :name, table: :tags
-      #   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(filter_key, **options)
+    #   @api public
+    #   @param filter_key [Symbol] the filter key name to identify this filter
+    #   @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 column
+    #     when dealing with joined tables that have conflicting column names
+    #   @option options [Symbol, nil] :column (nil) the column name to use in database queries,
+    #     defaults to filter_key if not specified
+    #
+    #   @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
+    #
+    #   @example Using custom column names
+    #     class UserFilters < Kiroshi::Filters
+    #       filter_by :full_name, column: :name, match: :like    # Filter key 'full_name' maps to 'name' column
+    #       filter_by :user_email, column: :email                # Filter key 'user_email' maps to 'email' column
+    #       filter_by :account_status, column: :status           # Filter key 'account_status' maps to 'status' column
+    #     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.3.0
 
     # Creates a new Filters instance
     #
     # @param filters [Hash] a hash containing the filter values to be applied.
-    #   Keys should correspond to attributes defined with {.filter_by}.
+    #   Keys should correspond to filter keys defined with {.filter_by}.
     #   Values will be used for filtering. Nil or blank values are ignored.
     #
     # @example Creating filters with values
@@ -125,7 +130,7 @@ module Kiroshi
     #
     # @since 0.1.0
     def initialize(filters = {})
-      @filters = filters || {}
+      @filters = filters
     end
 
     # Applies all configured filters to the given scope
@@ -160,10 +165,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 |filter_key, value|
+        filter = self.class.filter_for(filter_key)
+        next unless filter
+
+        scope = filter.apply(scope: scope, value: value)
       end
 
       scope
@@ -171,14 +179,17 @@ module Kiroshi
 
     private
 
-    attr_reader :filters
-
-    # @!method filters
-    #   @api private
-    #   @private
+    # Returns the hash of filter values to be applied
     #
-    #   Returns the hash of filter values to be applied
+    # Uses lazy initialization to ensure @filters is never nil,
+    # defaulting to an empty hash when no filters were provided.
     #
-    #   @return [Hash] the hash of filter values to be applied
+    # @return [Hash] the hash of filter values to be applied
+    #
+    # @api private
+    # @since 0.3.0
+    def filters
+      @filters ||= {}
+    end
   end
 end

data/lib/kiroshi/version.rb

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

data/lib/kiroshi.rb

@@ -9,9 +9,10 @@
 # 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 two main concepts:
+# The gem is designed around the main concept:
 # - {Filters}: A base class for creating reusable filter sets
-# - {Filter}: Individual filters that can be applied to scopes
+#
+# Individual filters are handled internally and don't require direct interaction.
 #
 # @example Basic filter class definition
 #   class DocumentFilters < Kiroshi::Filters
@@ -68,25 +69,6 @@
 #   filtered_users = filters.apply(User.includes(:department))
 #   # Generates: WHERE email LIKE '%admin%' AND role = 'moderator' AND active = true
 #
-# @example Individual filter usage
-#   # Create standalone filters
-#   name_filter = Kiroshi::Filter.new(:name, match: :like)
-#   status_filter = Kiroshi::Filter.new(:status)
-#
-#   # Apply filters step by step
-#   scope = Document.all
-#   scope = name_filter.apply(scope, { name: 'annual' })
-#   scope = status_filter.apply(scope, { status: 'published' })
-#
-# @example Filter matching types
-#   # Exact matching (default)
-#   Kiroshi::Filter.new(:status)
-#   # Generates: WHERE status = 'value'
-#
-#   # Partial matching with LIKE
-#   Kiroshi::Filter.new(:title, match: :like)
-#   # Generates: WHERE title LIKE '%value%'
-#
 # @example Empty value handling
 #   filters = DocumentFilters.new(name: '', status: 'published')
 #   result = filters.apply(Document.all)
@@ -148,9 +130,7 @@
 #   end
 #
 # @see Filters Base class for creating filter sets
-# @see Filter Individual filter implementation
 # @see https://github.com/darthjee/kiroshi GitHub repository
-# @see https://www.rubydoc.info/gems/kiroshi YARD documentation
 #
 # @since 0.1.0
 module Kiroshi