kiroshi 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff66735688ded970094d5a88a9bcd67ad4f9cac7679fc55ceb75534d9b16d9fc
-  data.tar.gz: d6da2da4ec294c0d134ceff028e19b30fa5e13ddab2fae2ad0582a5fdfc559aa
+  metadata.gz: 5748e560809cbfa28ea2b9d6ad06578ad1f4d0c67038bed6aca1a1978f27aa7c
+  data.tar.gz: b15225c3e02cbb634ec4fec69c240cf7bb623e8d89d9fa216c0c5521e98f08a1
 SHA512:
-  metadata.gz: 15f142b43b0fcd7fc12f8cd2c1246031aabec104deaf1270030eca5afa56d5776d5c3fec301422c12baec0c531d5366f39832b4afe6ec3d1c83f40ce3e94aea5
-  data.tar.gz: af94b97459b7a157c6ea30f36c36b937e9a75c25b7081106cf6b6d104b3514687a7da4842e9ac847b7669954bab65f707e8a609d55e3666393f6da09cad6d9c4
+  metadata.gz: e7ad5fe225a10041b672270a6f4407985c4be7b9761f9ae2ad5bfcebd45318c3caa03633dc066faf845e5b818fc36e8408e5991abf125d394b29b8af96ade5a3
+  data.tar.gz: b7ba3b33bda40558ebc76e9a1cf4c9fd803fb4881e28eac16f38e64f5562ca6748bbdb206a12a416ab19376f619be26d52986339bedd9b929dc33b65fa68a36a

data/.codacy.yml

@@ -0,0 +1,13 @@
+---
+engines:
+  markdownlint:
+    enabled: true
+    exclude_paths:
+      - 'spec/**/*'
+      - 'coverage/**/*'
+    configurations:
+      MD033:
+        allowed_elements:
+          - details
+          - summary
+      MD041: false  # Allow HTML in headers

data/.markdownlint.json

@@ -0,0 +1,6 @@
+{
+  "MD033": {
+    "allowed_elements": ["details", "summary"]
+  },
+  "MD041": false
+}

data/README.md

@@ -7,16 +7,16 @@
 
 ## Yard Documentation
 
-[https://www.rubydoc.info/gems/kiroshi/0.2.0](https://www.rubydoc.info/gems/kiroshi/0.2.0)
+[https://www.rubydoc.info/gems/kiroshi/0.3.0](https://www.rubydoc.info/gems/kiroshi/0.3.0)
 
 Kiroshi has been designed to make filtering ActiveRecord queries easier
 by providing a flexible and reusable filtering system. It allows you to
 define filter sets that can be applied to any ActiveRecord scope,
 supporting both exact matches and partial matching using SQL LIKE operations.
 
-Current Release: [0.2.0](https://github.com/darthjee/kiroshi/tree/0.2.0)
+Current Release: [0.3.0](https://github.com/darthjee/kiroshi/tree/0.3.0)
 
-[Next release](https://github.com/darthjee/kiroshi/compare/0.2.0...master)
+[Next release](https://github.com/darthjee/kiroshi/compare/0.3.0...master)
 
 ## Installation
 
@@ -67,6 +67,9 @@ Kiroshi supports two types of matching:
 - `:exact` - Exact match (default)
 - `:like` - Partial match using SQL LIKE
 
+<details>
+<summary>Specifying filter types</summary>
+
 ```ruby
 class UserFilters < Kiroshi::Filters
   filter_by :email, match: :like      # Partial matching
@@ -78,11 +81,15 @@ filters = UserFilters.new(email: 'admin', role: 'moderator')
 filtered_users = filters.apply(User.all)
 # Generates: WHERE email LIKE '%admin%' AND role = 'moderator'
 ```
+</details>
 
 #### Advanced Examples
 
 ##### Multiple Filter Types
 
+<details>
+<summary>Applying only some filters</summary>
+
 ```ruby
 class ProductFilters < Kiroshi::Filters
   filter_by :name, match: :like
@@ -96,9 +103,13 @@ filters = ProductFilters.new(name: 'laptop', category: 'electronics')
 products = filters.apply(Product.all)
 # Only name and category filters are applied, price and brand are ignored
 ```
+</details>
 
 ##### Controller Integration
 
+<details>
+<summary>Using filters in Rails controllers</summary>
+
 ```ruby
 # URL: /documents?filter[name]=report&filter[status]=published&filter[author]=john
 class DocumentsController < ApplicationController
@@ -125,9 +136,13 @@ class DocumentFilters < Kiroshi::Filters
   filter_by :author, match: :like
 end
 ```
+</details>
 
 ##### Nested Resource Filtering
 
+<details>
+<summary>Filtering nested resources</summary>
+
 ```ruby
 # URL: /users/123/articles?filter[title]=ruby&filter[published]=true&filter[tag]=tutorial
 class ArticleFilters < Kiroshi::Filters
@@ -146,9 +161,13 @@ def article_filters
   ArticleFilters.new(params[:filter]&.permit(:title, :published, :tag))
 end
 ```
+</details>
 
 ##### Joined Tables and Table Qualification
 
+<details>
+<summary>Working with joined tables</summary>
+
 When working with joined tables that have columns with the same name, you can specify which table to filter on using the `table` parameter:
 
 ```ruby
@@ -165,9 +184,13 @@ filters = DocumentFilters.new(tag_name: 'ruby', status: 'published')
 filtered_documents = filters.apply(scope)
 # Generates: WHERE tags.name LIKE '%ruby%' AND documents.status = 'published'
 ```
+</details>
 
 ###### Table Qualification Examples
 
+<details>
+<summary>Advanced table qualification scenarios</summary>
+
 ```ruby
 # Filter documents by tag name and document status
 class DocumentTagFilters < Kiroshi::Filters
@@ -201,9 +224,54 @@ result = filters.apply(scope)
 ```
 
 The `table` parameter accepts both symbols and strings, and helps resolve column name ambiguity in complex joined queries.
+</details>
+
+##### Custom Column Mapping
+
+<details>
+<summary>Using different filter keys from database columns</summary>
+
+Sometimes you may want to use a different filter key name from the database column name. The `column` parameter allows you to specify which database column to query while keeping a descriptive filter key:
+
+```ruby
+class UserFilters < Kiroshi::Filters
+  filter_by :full_name, column: :name, match: :like      # Filter key 'full_name' queries 'name' column
+  filter_by :user_email, column: :email, match: :like    # Filter key 'user_email' queries 'email' column  
+  filter_by :account_status, column: :status             # Filter key 'account_status' queries 'status' column
+end
+
+filters = UserFilters.new(full_name: 'John', user_email: 'admin', account_status: 'active')
+result = filters.apply(User.all)
+# Generates: WHERE name LIKE '%John%' AND email LIKE '%admin%' AND status = 'active'
+```
+</details>
+
+###### Column Mapping with Table Qualification
+
+<details>
+<summary>Combining column mapping with table qualification</summary>
+
+You can combine `column` and `table` parameters for complex scenarios:
+
+```ruby
+class DocumentFilters < Kiroshi::Filters
+  filter_by :author_name, column: :name, table: :users, match: :like  # Filter key 'author_name' queries 'users.name'
+  filter_by :doc_title, column: :title, table: :documents, match: :like  # Filter key 'doc_title' queries 'documents.title'
+  filter_by :tag_label, column: :name, table: :tags, match: :like     # Filter key 'tag_label' queries 'tags.name'
+end
+
+scope = Document.joins(:user, :tags)
+filters = DocumentFilters.new(author_name: 'John', doc_title: 'Ruby', tag_label: 'tutorial')
+result = filters.apply(scope)
+# Generates: WHERE users.name LIKE '%John%' AND documents.title LIKE '%Ruby%' AND tags.name LIKE '%tutorial%'
+```
+
+This feature is particularly useful when:
+- Creating more descriptive filter parameter names for APIs
+- Avoiding naming conflicts between filter keys and existing method names
+- Building user-friendly filter interfaces with intuitive parameter names
+</details>
 
 ## API Reference
 
 Kiroshi provides a simple, clean API focused on the `Kiroshi::Filters` class. Individual filters are handled internally and don't require direct interaction in most use cases.
-
-For detailed API documentation, see the [YARD documentation](https://www.rubydoc.info/gems/kiroshi/0.2.0).

data/lib/kiroshi/filter.rb

@@ -23,14 +23,14 @@ module Kiroshi
   #
   # @since 0.1.0
   class Filter
-    attr_reader :attribute, :match, :table_name
+    attr_reader :filter_key, :match, :table_name
 
-    # @!method attribute
+    # @!method filter_key
     #   @api private
     #
-    #   Returns the attribute name to filter by
+    #   Returns the filter key name to identify this filter
     #
-    #   @return [Symbol] the attribute name to filter by
+    #   @return [Symbol] the filter key name to identify this filter
 
     # @!method match
     #   @api private
@@ -42,15 +42,16 @@ module Kiroshi
     # @!method table_name
     #   @api private
     #
-    #   Returns the table name to qualify the attribute
+    #   Returns the table name to qualify the column
     #
     #   @return [String, String, nil] the table name or nil if not specified
 
     # Creates a new Filter instance
     #
-    # @param attribute [Symbol] the attribute name to filter by
+    # @param filter_key [Symbol] the filter key name to identify this filter
     # @param match [Symbol] the matching type, defaults to :exact
-    # @param table [String, Symbol, nil] the table name to qualify the attribute, defaults to nil
+    # @param table [String, Symbol, nil] the table name to qualify the column, defaults to nil
+    # @param column [Symbol] the column name to use in database queries, defaults to filter_key
     # @option match [Symbol] :exact performs exact matching (default)
     # @option match [Symbol] :like performs partial matching using SQL LIKE
     #
@@ -63,11 +64,27 @@ module Kiroshi
     # @example Creating a filter with table qualification
     #   filter = Kiroshi::Filter.new(:name, table: 'documents')
     #
-    # @since 0.1.0
-    def initialize(attribute, match: :exact, table: nil)
-      @attribute = attribute
+    # @example Creating a filter with custom column name
+    #   filter = Kiroshi::Filter.new(:user_name, column: :full_name)
+    #
+    # @since 0.3.0
+    def initialize(filter_key, match: :exact, table: nil, column: nil)
+      @filter_key = filter_key
       @match = match
       @table_name = table
+      @column = column
+    end
+
+    # Returns the column name to use in database queries
+    #
+    # Uses lazy initialization - defaults to filter_key if no column was specified.
+    # This allows for flexible column mapping while maintaining backward compatibility.
+    #
+    # @return [Symbol] the column name to use in database queries
+    #
+    # @since 0.3.0
+    def column
+      @column ||= filter_key
     end
 
     # Applies the filter to the given scope

data/lib/kiroshi/filter_query/exact.rb

@@ -13,14 +13,14 @@ module Kiroshi
     # @example Applying exact match query
     #   query = Kiroshi::FilterQuery::Exact.new(filter_runner)
     #   query.apply
-    #   # Generates: WHERE attribute = 'value'
+    #   # Generates: WHERE table_name.column = value
     #
     # @since 0.1.1
     class Exact < FilterQuery
       # Applies exact match filtering to the scope
       #
       # This method generates a WHERE clause with exact equality matching
-      # for the filter's attribute and value.
+      # for the filter's column and value.
       #
       # @return [ActiveRecord::Relation] the filtered scope with exact match
       #
@@ -31,7 +31,7 @@ module Kiroshi
       #
       # @since 0.1.1
       def apply
-        scope.where(table_name => { attribute => value })
+        scope.where(table_name => { column => value })
       end
     end
   end

data/lib/kiroshi/filter_query/like.rb

@@ -13,7 +13,7 @@ module Kiroshi
     # @example Applying LIKE match query
     #   query = Kiroshi::FilterQuery::Like.new(filter_runner)
     #   query.apply
-    #   # Generates: WHERE table_name.attribute LIKE '%value%'
+    #   # Generates: WHERE "table_name"."column" LIKE '%value%'
     #
     # @since 0.1.1
     class Like < FilterQuery
@@ -28,14 +28,38 @@ module Kiroshi
       # @example Applying LIKE match
       #   query = Like.new(filter_runner)
       #   query.apply
-      #   # Generates: WHERE documents.name LIKE '%ruby%'
+      #   # Generates: WHERE "documents"."name" LIKE '%ruby%'
       #
       # @since 0.1.1
       def apply
-        scope.where(
-          "#{table_name}.#{attribute} LIKE ?",
-          "%#{value}%"
-        )
+        scope.where(sql_query, "%#{value}%")
+      end
+
+      private
+
+      # @api private
+      # @private
+      #
+      # Builds the SQL query string for LIKE matching
+      #
+      # This method constructs the SQL fragment with proper table and column
+      # qualification using double quotes to avoid conflicts with reserved words.
+      #
+      # @return [String] the SQL query fragment for LIKE matching
+      #
+      # @example Generated SQL fragment
+      #   sql_query # => '    # Constructs the parameterized SQL query string for column matching
+      #
+      # @return [String] The SQL query string with placeholders
+      # @example
+      #   sql_query
+      #   # Returns: '"table_name"."column" LIKE ?''
+      #
+      # @since 0.3.0
+      def sql_query
+        <<~SQL.squish
+          "#{table_name}"."#{column}" LIKE ?
+        SQL
       end
     end
   end

data/lib/kiroshi/filter_query.rb

@@ -94,7 +94,7 @@ module Kiroshi
     #
     #   @return [Kiroshi::FilterRunner] the filter runner instance
 
-    delegate :scope, :attribute, :table_name, :value, to: :filter_runner
+    delegate :scope, :column, :table_name, :value, to: :filter_runner
 
     # @!method scope
     #   @api private
@@ -103,12 +103,12 @@ module Kiroshi
     #
     #   @return [ActiveRecord::Relation] the scope
 
-    # @!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
+    #   @return [Symbol] the column name
 
     # @!method table_name
     #   @api private

data/lib/kiroshi/filter_runner.rb

@@ -136,16 +136,16 @@ module Kiroshi
     #
     #   @return [Kiroshi::Filter] the filter configuration
 
-    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

@@ -21,8 +21,8 @@ module Kiroshi
     #   end
     #
     # @example Accessing filter configurations
-    #   DocumentFilters.filter_configs.keys # => [:name, :status, :category]
-    #   DocumentFilters.filter_configs[:name].match # => :like
+    #   DocumentFilters.filter_configs.keys # => ["name", "status", "category"]
+    #   DocumentFilters.filter_configs["name"].match # => :like
     #
     # @since 0.2.0
     # @author darthjee
@@ -38,37 +38,39 @@ module Kiroshi
       # 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
+      # @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 attribute
+      #   @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(attribute, **)
-        Filter.new(attribute, **).tap do |filter|
-          filter_configs[attribute] = filter
+      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 attribute
+      # Returns the filter configuration for a specific filter key
       #
       # This method provides a convenient way to retrieve a specific filter
-      # by its attribute name. It's a shorthand for accessing the filter_configs
+      # 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 attribute [Symbol] the attribute name to look up
+      # @param filter_key [Symbol, String] the filter key name to look up
       #
-      # @return [Filter, nil] the filter instance for the given attribute,
-      #   or nil if no filter is configured for that attribute
+      # @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
@@ -76,16 +78,17 @@ module Kiroshi
       #     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(: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.2.0
-      def filter_for(attribute)
-        filter_configs[attribute] || inherited_filter_for(attribute)
+      # @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
@@ -96,17 +99,17 @@ module Kiroshi
       # 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
+      # for the given filter key. 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
+      # @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.2.0
-      def inherited_filter_for(attribute)
+      # @since 0.3.0
+      def inherited_filter_for(filter_key_string)
         return nil unless superclass < Kiroshi::Filters
 
-        superclass.filter_for(attribute)
+        superclass.filter_for(filter_key_string)
       end
 
       # @api private
@@ -116,7 +119,7 @@ module Kiroshi
       #
       # 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
+      # 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
@@ -124,8 +127,8 @@ module Kiroshi
       # 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
+      # @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
@@ -135,17 +138,17 @@ module Kiroshi
       #   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
+      #   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)
+      #       expect(described_class.filter_configs).to have_key("name")
+      #       expect(described_class.filter_configs["name"].match).to eq(:like)
       #     end
       #   end
       #

data/lib/kiroshi/filters.rb

@@ -40,15 +40,17 @@ module Kiroshi
 
     extend ClassMethods
 
-    # @method self.filter_by(attribute, **options)
+    # @method self.filter_by(filter_key, **options)
     #   @api public
-    #   @param attribute [Symbol] the attribute name to filter by
+    #   @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 attribute
+    #   @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
     #
@@ -91,6 +93,13 @@ module Kiroshi
     #       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.
@@ -98,12 +107,12 @@ module Kiroshi
     #   @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
+    #   @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
@@ -121,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
@@ -158,8 +167,8 @@ module Kiroshi
     #
     # @since 0.2.0
     def apply(scope)
-      filters.compact.each do |attribute, value|
-        filter = self.class.filter_for(attribute)
+      filters.compact.each do |filter_key, value|
+        filter = self.class.filter_for(filter_key)
         next unless filter
 
         scope = filter.apply(scope: scope, value: value)
@@ -170,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.2.0'
+  VERSION = '0.3.0'
 end

data/lib/kiroshi.rb

@@ -131,7 +131,6 @@
 #
 # @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

data/spec/lib/kiroshi/filter_query/exact_spec.rb

@@ -270,5 +270,45 @@ RSpec.describe Kiroshi::FilterQuery::Exact, type: :model do
         end
       end
     end
+
+    context 'when Filter#column is different from filter_key' do
+      let(:filter) { Kiroshi::Filter.new(:user_name, match: :exact, column: :full_name) }
+      let(:filter_value) { 'John Doe' }
+
+      let!(:matching_document) { create(:document, full_name: 'John Doe') }
+      let!(:non_matching_document) { create(:document, full_name: 'Jane Smith') }
+
+      let(:expected_sql) do
+        <<~SQL.squish
+          SELECT "documents".* FROM "documents" WHERE "documents"."full_name" = 'John Doe'
+        SQL
+      end
+
+      it 'uses the column name instead of filter_key in SQL' do
+        expect(query.apply.to_sql).to eq(expected_sql)
+      end
+
+      it 'returns records that match the column value' do
+        expect(query.apply).to include(matching_document)
+      end
+
+      it 'does not return records that do not match the column value' do
+        expect(query.apply).not_to include(non_matching_document)
+      end
+
+      context 'with table qualification' do
+        let(:filter) { Kiroshi::Filter.new(:user_name, match: :exact, table: :documents, column: :full_name) }
+
+        let(:expected_sql) do
+          <<~SQL.squish
+            SELECT "documents".* FROM "documents" WHERE "documents"."full_name" = 'John Doe'
+          SQL
+        end
+
+        it 'generates SQL with proper table and column qualification' do
+          expect(query.apply.to_sql).to eq(expected_sql)
+        end
+      end
+    end
   end
 end

data/spec/lib/kiroshi/filter_query/like_spec.rb

@@ -17,7 +17,7 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
     let(:expected_sql) do
       <<~SQL.squish
-        SELECT "documents".* FROM "documents" WHERE (documents.name LIKE '%test%')
+        SELECT "documents".* FROM "documents" WHERE ("documents"."name" LIKE '%test%')
       SQL
     end
 
@@ -47,7 +47,7 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
       let(:expected_sql) do
         <<~SQL.squish
-          SELECT "documents".* FROM "documents" WHERE (documents.status LIKE '%pub%')
+          SELECT "documents".* FROM "documents" WHERE ("documents"."status" LIKE '%pub%')
         SQL
       end
 
@@ -78,7 +78,7 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
       let(:expected_sql) do
         <<~SQL.squish
-          SELECT "documents".* FROM "documents" WHERE (documents.version LIKE '%1.2%')
+          SELECT "documents".* FROM "documents" WHERE ("documents"."version" LIKE '%1.2%')
         SQL
       end
 
@@ -104,7 +104,7 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
       let(:expected_sql) do
         <<~SQL.squish
-          SELECT "documents".* FROM "documents" WHERE (documents.name LIKE '%nonexistent%')
+          SELECT "documents".* FROM "documents" WHERE ("documents"."name" LIKE '%nonexistent%')
         SQL
       end
 
@@ -218,7 +218,7 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
         it 'generates SQL with tags table qualification' do
           result_sql = query.apply.to_sql
-          expect(result_sql).to include('tags.name LIKE')
+          expect(result_sql).to include('"tags"."name" LIKE')
         end
 
         it 'generates SQL with correct LIKE pattern for tag name' do
@@ -245,7 +245,7 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
         it 'generates SQL with documents table qualification' do
           result_sql = query.apply.to_sql
-          expect(result_sql).to include('documents.name LIKE')
+          expect(result_sql).to include('"documents"."name" LIKE')
         end
 
         it 'generates SQL with correct LIKE pattern for document name' do
@@ -263,7 +263,52 @@ RSpec.describe Kiroshi::FilterQuery::Like, type: :model do
 
         it 'generates SQL with string table qualification' do
           result_sql = query.apply.to_sql
-          expect(result_sql).to include('tags.name LIKE')
+          expect(result_sql).to include('"tags"."name" LIKE')
+        end
+      end
+    end
+
+    context 'when Filter#column is different from filter_key' do
+      let(:filter)       { Kiroshi::Filter.new(:user_name, match: :like, column: :full_name) }
+      let(:filter_value) { 'John' }
+
+      let!(:matching_document) { create(:document, full_name: 'John Doe') }
+      let!(:another_match)         { create(:document, full_name: 'Johnny Smith') }
+      let!(:non_matching_document) { create(:document, full_name: 'Jane Wilson') }
+
+      let(:expected_sql) do
+        <<~SQL.squish
+          SELECT "documents".* FROM "documents" WHERE ("documents"."full_name" LIKE '%John%')
+        SQL
+      end
+
+      it 'uses the column name instead of filter_key in SQL' do
+        expect(query.apply.to_sql).to eq(expected_sql)
+      end
+
+      it 'returns records that partially match the column value' do
+        expect(query.apply).to include(matching_document)
+      end
+
+      it 'returns multiple records that contain the column value' do
+        expect(query.apply).to include(another_match)
+      end
+
+      it 'does not return records that do not contain the column value' do
+        expect(query.apply).not_to include(non_matching_document)
+      end
+
+      context 'with table qualification' do
+        let(:filter) { Kiroshi::Filter.new(:user_name, match: :like, table: :documents, column: :full_name) }
+
+        let(:expected_sql) do
+          <<~SQL.squish
+            SELECT "documents".* FROM "documents" WHERE ("documents"."full_name" LIKE '%John%')
+          SQL
+        end
+
+        it 'generates SQL with proper table and column qualification' do
+          expect(query.apply.to_sql).to eq(expected_sql)
         end
       end
     end

data/spec/lib/kiroshi/filter_runner_spec.rb

@@ -39,7 +39,7 @@ RSpec.describe Kiroshi::FilterRunner, type: :model do
       end
 
       it 'generates correct SQL with table name prefix' do
-        expected_sql = "SELECT \"documents\".* FROM \"documents\" WHERE (documents.name LIKE '%test%')"
+        expected_sql = "SELECT \"documents\".* FROM \"documents\" WHERE (\"documents\".\"name\" LIKE '%test%')"
         expect(runner.apply.to_sql).to eq(expected_sql)
       end
     end
@@ -90,5 +90,46 @@ RSpec.describe Kiroshi::FilterRunner, type: :model do
         expect(runner.apply).not_to include(non_matching_document)
       end
     end
+
+    context 'when Filter#column is different from filter_key' do
+      let(:filter) { Kiroshi::Filter.new(:user_name, match: :exact, column: :full_name) }
+      let(:filter_value) { 'John Doe' }
+
+      let!(:matching_document) { create(:document, full_name: 'John Doe') }
+      let!(:non_matching_document) { create(:document, full_name: 'Jane Smith') }
+
+      it 'filters using the column name instead of filter_key' do
+        expect(runner.apply).to include(matching_document)
+      end
+
+      it 'does not return non-matching records' do
+        expect(runner.apply).not_to include(non_matching_document)
+      end
+
+      it 'generates correct SQL using the column name' do
+        expected_sql = "SELECT \"documents\".* FROM \"documents\" WHERE \"documents\".\"full_name\" = 'John Doe'"
+        expect(runner.apply.to_sql).to eq(expected_sql)
+      end
+
+      context 'with LIKE match' do
+        let(:filter) { Kiroshi::Filter.new(:user_name, match: :like, column: :full_name) }
+        let(:filter_value) { 'John' }
+
+        let!(:partial_match) { create(:document, full_name: 'Johnny Smith') }
+
+        it 'performs LIKE filtering using the column name' do
+          expect(runner.apply).to include(matching_document)
+        end
+
+        it 'includes partial matches using the column name' do
+          expect(runner.apply).to include(partial_match)
+        end
+
+        it 'generates correct LIKE SQL using the column name' do
+          expected_sql = "SELECT \"documents\".* FROM \"documents\" WHERE (\"documents\".\"full_name\" LIKE '%John%')"
+          expect(runner.apply.to_sql).to eq(expected_sql)
+        end
+      end
+    end
   end
 end

data/spec/lib/kiroshi/filters/class_methods_spec.rb

@@ -52,7 +52,51 @@ RSpec.describe Kiroshi::Filters::ClassMethods, type: :model do
       it do
         expect { filters_class.filter_by :name, match: :like, table: :documents }
           .to change { filter_instance.apply(scope) }
-          .from(scope).to(scope.where('documents.name LIKE ?', '%test%'))
+          .from(scope).to(scope.where('"documents"."name" LIKE ?', '%test%'))
+      end
+    end
+
+    context 'when column is different from filter_key' do
+      let(:filters) { { user_name: 'John Doe' } }
+
+      context 'with exact match' do
+        it do
+          expect { filters_class.filter_by :user_name, column: :full_name }
+            .to change { filter_instance.apply(scope) }
+            .from(scope).to(scope.where(full_name: 'John Doe'))
+        end
+      end
+
+      context 'with like match' do
+        let(:filters) { { user_name: 'John' } }
+
+        it do
+          expect { filters_class.filter_by :user_name, match: :like, column: :full_name }
+            .to change { filter_instance.apply(scope) }
+            .from(scope).to(scope.where('"documents"."full_name" LIKE ?', '%John%'))
+        end
+      end
+
+      context 'with table qualification and different column' do
+        let(:scope) { Document.joins(:tags) }
+        let(:filters) { { tag_identifier: 'ruby' } }
+
+        it do
+          expect { filters_class.filter_by :tag_identifier, table: :tags, column: :name }
+            .to change { filter_instance.apply(scope) }
+            .from(scope).to(scope.where(tags: { name: 'ruby' }))
+        end
+      end
+
+      context 'with like match, table qualification and different column' do
+        let(:scope) { Document.joins(:tags) }
+        let(:filters) { { tag_identifier: 'rub' } }
+
+        it do
+          expect { filters_class.filter_by :tag_identifier, match: :like, table: :tags, column: :name }
+            .to change { filter_instance.apply(scope) }
+            .from(scope).to(scope.where('"tags"."name" LIKE ?', '%rub%'))
+        end
       end
     end
   end

data/spec/lib/kiroshi/filters_spec.rb

@@ -91,6 +91,142 @@ RSpec.describe Kiroshi::Filters, type: :model do
       end
     end
 
+    context 'when filters have string keys' do
+      before do
+        filters_class.filter_by :name, match: :like
+        filters_class.filter_by :status
+      end
+
+      context 'with single string key filter' do
+        let(:filters) { { 'name' => 'test' } }
+
+        it 'returns documents matching the string key filter' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'does not return documents not matching the string key filter' do
+          expect(filter_instance.apply(scope)).not_to include(other_document)
+        end
+
+        it 'generates SQL with LIKE operation for string key' do
+          expect(filter_instance.apply(scope).to_sql).to include('LIKE')
+        end
+      end
+
+      context 'with multiple string key filters' do
+        let(:filters) { { 'name' => 'test', 'status' => 'finished' } }
+
+        it 'returns documents matching all string key filters' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'does not return documents not matching all string key filters' do
+          expect(filter_instance.apply(scope)).not_to include(other_document)
+        end
+      end
+
+      context 'with mixed string and symbol keys' do
+        let(:filters) { { 'name' => 'test', status: 'finished' } }
+
+        it 'returns documents matching both string and symbol key filters' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'does not return documents not matching all mixed key filters' do
+          expect(filter_instance.apply(scope)).not_to include(other_document)
+        end
+
+        it 'treats string and symbol keys equivalently' do
+          string_result = filters_class.new({ 'name' => 'test', 'status' => 'finished' }).apply(scope)
+          symbol_result = filters_class.new({ name: 'test', status: 'finished' }).apply(scope)
+
+          expect(string_result.to_sql).to eq(symbol_result.to_sql)
+        end
+      end
+    end
+
+    context 'when filters is an instance of ActionController::Parameters' do
+      before do
+        filters_class.filter_by :name, match: :like
+        filters_class.filter_by :status
+      end
+
+      context 'with permitted parameters' do
+        let(:filters) do
+          ActionController::Parameters.new(
+            name: 'test',
+            status: 'finished',
+            unauthorized_param: 'ignored'
+          )
+        end
+
+        it 'returns documents matching the permitted parameters' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'does not return documents not matching the permitted parameters' do
+          expect(filter_instance.apply(scope)).not_to include(other_document)
+        end
+
+        it 'generates SQL with LIKE operation for ActionController::Parameters' do
+          expect(filter_instance.apply(scope).to_sql).to include('LIKE')
+        end
+
+        it 'generates SQL with exact match for status parameter' do
+          expect(filter_instance.apply(scope).to_sql).to include("'finished'")
+        end
+      end
+
+      context 'with unpermitted parameters' do
+        let(:filters) do
+          ActionController::Parameters.new(
+            name: 'test',
+            status: 'finished'
+          )
+        end
+
+        it 'works with unpermitted parameters' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'does not return documents not matching the parameters' do
+          expect(filter_instance.apply(scope)).not_to include(other_document)
+        end
+      end
+
+      context 'with string keys in ActionController::Parameters' do
+        let(:filters) do
+          ActionController::Parameters.new(
+            'name' => 'test',
+            'status' => 'finished'
+          )
+        end
+
+        it 'returns documents matching the string key parameters' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'does not return documents not matching the string key parameters' do
+          expect(filter_instance.apply(scope)).not_to include(other_document)
+        end
+
+        it 'treats ActionController::Parameters with string keys same as regular hash' do
+          ac_params_result = filter_instance.apply(scope)
+          hash_result = filters_class.new({ 'name' => 'test', 'status' => 'finished' }).apply(scope)
+
+          expect(ac_params_result.to_sql).to eq(hash_result.to_sql)
+        end
+      end
+
+      context 'with empty ActionController::Parameters' do
+        let(:filters) { ActionController::Parameters.new({}) }
+
+        it 'returns the original scope unchanged' do
+          expect(filter_instance.apply(scope)).to eq(scope)
+        end
+      end
+    end
+
     context 'when scope has joined tables with clashing fields' do
       let(:scope)   { Document.joins(:tags) }
       let(:filters) { { name: 'test_name' } }
@@ -143,7 +279,7 @@ RSpec.describe Kiroshi::Filters, type: :model do
 
         it 'generates SQL with table-qualified LIKE operation' do
           result = filter_instance.apply(scope)
-          expect(result.to_sql).to include('documents.name LIKE')
+          expect(result.to_sql).to include('"documents"."name" LIKE')
         end
 
         it 'generates SQL with correct LIKE pattern' do
@@ -153,6 +289,80 @@ RSpec.describe Kiroshi::Filters, type: :model do
       end
     end
 
+    context 'when specifying a different column' do
+      let(:scope)   { Document.joins(:tags) }
+      let(:filters) { { tag_name: 'ruby' } }
+
+      let!(:ruby_tag) { Tag.find_or_create_by(name: 'ruby') }
+      let!(:js_tag)   { Tag.find_or_create_by(name: 'javascript') }
+
+      before do
+        filters_class.filter_by :tag_name, table: :tags, column: :name
+
+        document.tags << [ruby_tag]
+        other_document.tags << [js_tag]
+      end
+
+      it 'filters by the specified column name instead of filter key' do
+        expect(filter_instance.apply(scope)).to include(document)
+      end
+
+      it 'does not return documents not matching the column filter' do
+        expect(filter_instance.apply(scope)).not_to include(other_document)
+      end
+
+      it 'generates SQL that filters by tags.name using the column parameter' do
+        expect(filter_instance.apply(scope).to_sql).to include('"tags"."name"')
+      end
+
+      it 'generates SQL that includes the filter value' do
+        expect(filter_instance.apply(scope).to_sql).to include("'ruby'")
+      end
+
+      it 'does not use the filter key name in the SQL' do
+        # The filter key is :tag_name but column is :name, so SQL should use 'name' not 'tag_name'
+        expect(filter_instance.apply(scope).to_sql).not_to include('tag_name')
+      end
+
+      context 'with LIKE matching' do
+        let(:filters) { { tag_name: 'rub' } }
+
+        before do
+          filters_class.filter_by :tag_name, table: :tags, column: :name, match: :like
+        end
+
+        it 'applies LIKE matching to the specified column' do
+          expect(filter_instance.apply(scope)).to include(document)
+        end
+
+        it 'generates SQL with LIKE operation on the specified column' do
+          expect(filter_instance.apply(scope).to_sql).to include('"tags"."name" LIKE')
+        end
+
+        it 'generates SQL with correct LIKE pattern' do
+          expect(filter_instance.apply(scope).to_sql).to include("'%rub%'")
+        end
+      end
+
+      context 'with different filter key and column names' do
+        let(:filters) { { user_full_name: 'test' } }
+
+        before do
+          filters_class.filter_by :user_full_name, column: :name, match: :like
+        end
+
+        it 'uses the column name in database queries' do
+          result = filter_instance.apply(Document.all)
+          expect(result.to_sql).to include('"documents"."name"')
+        end
+
+        it 'does not use the filter key in SQL' do
+          result = filter_instance.apply(Document.all)
+          expect(result.to_sql).not_to include('user_full_name')
+        end
+      end
+    end
+
     context 'when filter was defined in the superclass' do
       subject(:filters_class) { Class.new(parent_class) }
 

data/spec/spec_helper.rb

@@ -11,6 +11,7 @@ SimpleCov.start 'gem'
 require 'kiroshi'
 require 'pry-nav'
 require 'active_support/all'
+require 'action_controller/metal/strong_parameters'
 require 'factory_bot'
 
 require 'active_record'

data/spec/support/db/schema.rb

@@ -5,6 +5,7 @@ ActiveRecord::Schema.define do
 
   create_table :documents, force: true do |t|
     t.string   :name
+    t.string   :full_name
     t.string   :status
     t.boolean  :active
     t.integer  :priority

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiroshi
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Darthjee
@@ -46,7 +46,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
+- ".codacy.yml"
 - ".gitignore"
+- ".markdownlint.json"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"