kiroshi 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3df16fe842c4fcd160633af8a5e4d91fa19cbb857dc135a31160c1f389a5f6c1
-  data.tar.gz: b3f98740895ae5c611d616c36472d77ce412a1086d9d6a9ffe4532a8b3fa2235
+  metadata.gz: 5748e560809cbfa28ea2b9d6ad06578ad1f4d0c67038bed6aca1a1978f27aa7c
+  data.tar.gz: b15225c3e02cbb634ec4fec69c240cf7bb623e8d89d9fa216c0c5521e98f08a1
 SHA512:
-  metadata.gz: 328641f23218cf3a3a3841af7027f42981dced635c03e47642e5f7bd3a9194d94e13e59a87f51f71adc51344642a682148606daff113ebf80f638e0cb0f5be19
-  data.tar.gz: e3cb7920836e0ad2d86d05875c74a57759c5b28d9309124539c61c902adaaaa3a9bf1d0f094e9b19500d23f4034563ac9de234b9fd6f36a21084054bfed09c13
+  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/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-08-17 15:11:59 UTC using RuboCop version 1.79.2.
+# on 2025-08-18 22:27:27 UTC using RuboCop version 1.79.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,11 +13,7 @@ RSpec/NoExpectationExample:
   Exclude:
     - 'spec/lib/kiroshi_spec.rb'
 
-# Offense count: 2
-# Configuration parameters: AllowedConstants.
-Style/Documentation:
+# Offense count: 1
+RSpec/PendingWithoutReason:
   Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'lib/kiroshi/filter.rb'
-    - 'lib/kiroshi/filters.rb'
+    - 'spec/lib/kiroshi/filters_spec.rb'

data/README.md

@@ -7,16 +7,16 @@
 
 ## Yard Documentation
 
-[https://www.rubydoc.info/gems/kiroshi/0.1.1](https://www.rubydoc.info/gems/kiroshi/0.1.1)
+[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.1.1](https://github.com/darthjee/kiroshi/tree/0.1.1)
+Current Release: [0.3.0](https://github.com/darthjee/kiroshi/tree/0.3.0)
 
-[Next release](https://github.com/darthjee/kiroshi/compare/0.1.1...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,83 +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>
 
-### Kiroshi::Filter
+##### Custom Column Mapping
 
-[Filter](https://www.rubydoc.info/gems/kiroshi/Kiroshi/Filter)
-is the individual filter class that applies filtering logic to ActiveRecord scopes.
-It's automatically used by `Kiroshi::Filters`, but can also be used standalone.
+<details>
+<summary>Using different filter keys from database columns</summary>
 
-#### Standalone Usage
+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
-# Create individual filters
-name_filter = Kiroshi::Filter.new(:name, match: :like)
-status_filter = Kiroshi::Filter.new(:status, match: :exact)
-
-# Apply filters manually
-scope = Document.all
-scope = name_filter.apply(scope, { name: 'report' })
-scope = status_filter.apply(scope, { status: 'published' })
-```
-
-#### Filter Options
-
-- `match: :exact` - Performs exact matching (default)
-- `match: :like` - Performs partial matching using SQL LIKE
-- `table: :table_name` - Specifies which table to filter on (useful for joined queries)
+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
 
-```ruby
-# Exact match filter
-exact_filter = Kiroshi::Filter.new(:status)
-exact_filter.apply(Document.all, { status: 'published' })
-# Generates: WHERE status = 'published'
-
-# LIKE match filter
-like_filter = Kiroshi::Filter.new(:title, match: :like)
-like_filter.apply(Document.all, { title: 'Ruby' })
-# Generates: WHERE title LIKE '%Ruby%'
-
-# Table-qualified filter for joined queries
-tag_filter = Kiroshi::Filter.new(:name, match: :like, table: :tags)
-tag_filter.apply(Document.joins(:tags), { name: 'programming' })
-# Generates: WHERE tags.name LIKE '%programming%'
-
-# Document-specific filter in joined query
-doc_filter = Kiroshi::Filter.new(:title, match: :exact, table: :documents)
-doc_filter.apply(Document.joins(:tags), { title: 'Ruby Guide' })
-# Generates: WHERE documents.title = 'Ruby Guide'
+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
 
-#### Empty Value Handling
+<details>
+<summary>Combining column mapping with table qualification</summary>
 
-Filters automatically ignore empty or nil values:
+You can combine `column` and `table` parameters for complex scenarios:
 
 ```ruby
-filter = Kiroshi::Filter.new(:name)
-filter.apply(Document.all, { name: nil })        # Returns original scope
-filter.apply(Document.all, { name: '' })         # Returns original scope  
-filter.apply(Document.all, {})                   # Returns original scope
-filter.apply(Document.all, { name: 'value' })    # Applies filter
-```
+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
 
-#### Handling Column Name Ambiguity
+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%'
+```
 
-When working with joined tables that have columns with the same name, use the `table` parameter to specify which table's column to filter:
+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>
 
-```ruby
-# Without table specification - may cause ambiguity
-scope = Document.joins(:tags)  # Both documents and tags have 'name' column
-
-# Specify which table to filter on
-name_filter = Kiroshi::Filter.new(:name, match: :like, table: :tags)
-result = name_filter.apply(scope, { name: 'ruby' })
-# Generates: WHERE tags.name LIKE '%ruby%'
-
-# Or filter by document name specifically
-doc_name_filter = Kiroshi::Filter.new(:name, match: :like, table: :documents)
-result = doc_name_filter.apply(scope, { name: 'guide' })
-# Generates: WHERE documents.name LIKE '%guide%'
-```
+## API Reference
 
-**Priority**: When using `Kiroshi::Filters`, if a filter specifies a `table`, it takes priority over the scope's default table name.
+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.

data/lib/kiroshi/filter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Kiroshi
+  # @api private
   # @author darthjee
   #
   # A filter class that applies filtering logic to ActiveRecord scopes
@@ -10,22 +11,26 @@ module Kiroshi
   #
   # @example Creating and applying an exact filter
   #   filter = Kiroshi::Filter.new(:name)
-  #   filtered_scope = filter.apply(Document.all, { name: 'John' })
+  #   filtered_scope = filter.apply(scope: Document.all, value: 'John')
   #
   # @example Creating and applying a LIKE filter
   #   filter = Kiroshi::Filter.new(:title, match: :like)
-  #   filtered_scope = filter.apply(Article.all, { title: 'Ruby' })
+  #   filtered_scope = filter.apply(scope: Article.all, value: 'Ruby')
+  #
+  # @example Creating and applying a filter with specific value
+  #   filter = Kiroshi::Filter.new(:status)
+  #   filtered_scope = filter.apply(scope: Document.all, value: 'published')
   #
   # @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
@@ -37,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
     #
@@ -58,52 +64,68 @@ 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
     #
-    # This method examines the filters hash for a value corresponding to the
-    # filter's attribute and applies the appropriate WHERE clause to the scope.
-    # If no value is present or the value is blank, the original scope is returned unchanged.
+    # This method applies the appropriate WHERE clause to the scope using the
+    # provided value. If no value is present or the value is blank, the original
+    # scope is returned unchanged.
     #
     # @param scope [ActiveRecord::Relation] the ActiveRecord scope to filter
-    # @param filters [Hash] a hash containing filter values
+    # @param value [Object, nil] the value to use for filtering, defaults to nil
     #
     # @return [ActiveRecord::Relation] the filtered scope
     #
     # @example Applying an exact filter
     #   filter = Kiroshi::Filter.new(:status)
-    #   filter.apply(Document.all, { status: 'published' })
+    #   filter.apply(scope: Document.all, value: 'published')
     #   # Generates: WHERE status = 'published'
     #
     # @example Applying a LIKE filter
     #   filter = Kiroshi::Filter.new(:title, match: :like)
-    #   filter.apply(Article.all, { title: 'Ruby' })
+    #   filter.apply(scope: Article.all, value: 'Ruby')
     #   # Generates: WHERE title LIKE '%Ruby%'
     #
     # @example Applying a filter with table qualification
     #   filter = Kiroshi::Filter.new(:name, table: 'documents')
-    #   filter.apply(Document.joins(:tags), { name: 'report' })
+    #   filter.apply(scope: Document.joins(:tags), value: 'report')
     #   # Generates: WHERE documents.name = 'report'
     #
     # @example Applying a filter with table qualification for tags
     #   filter = Kiroshi::Filter.new(:name, table: 'tags')
-    #   filter.apply(Document.joins(:tags), { name: 'ruby' })
+    #   filter.apply(scope: Document.joins(:tags), value: 'ruby')
     #   # Generates: WHERE tags.name = 'ruby'
     #
     # @example With empty filter value
     #   filter = Kiroshi::Filter.new(:name)
-    #   filter.apply(User.all, { name: nil })
+    #   filter.apply(scope: User.all, value: nil)
     #   # Returns the original scope unchanged
     #
-    # @since 0.1.0
-    def apply(scope, filters)
-      runner = FilterRunner.new(filter: self, scope: scope, filters: filters)
+    # @since 0.2.0
+    def apply(scope:, value: nil)
+      runner = FilterRunner.new(filter: self, scope: scope, value: value)
       runner.apply
     end
   end

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 => filter_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 ?",
-          "%#{filter_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,38 +94,34 @@ module Kiroshi
     #
     #   @return [Kiroshi::FilterRunner] the filter runner instance
 
-    delegate :scope, :attribute, :table_name, :filter_value, to: :filter_runner
+    delegate :scope, :column, :table_name, :value, to: :filter_runner
 
     # @!method scope
     #   @api private
-    #   @private
     #
-    #   Returns the ActiveRecord scope being filtered
+    #   Returns the current scope being filtered
     #
-    #   @return [ActiveRecord::Relation] the scope being filtered
+    #   @return [ActiveRecord::Relation] the scope
 
-    # @!method attribute
+    # @!method column
     #   @api private
-    #   @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
 
     # @!method table_name
     #   @api private
-    #   @private
     #
-    #   Returns the table name from the scope
+    #   Returns the table name for the filter
     #
     #   @return [String] the table name
 
-    # @!method filter_value
+    # @!method value
     #   @api private
-    #   @private
     #
-    #   Returns the filter value for the current filter's attribute
+    #   Returns the filter value
     #
-    #   @return [Object, nil] the filter value or nil if not present
+    #   @return [Object] the filter value
   end
 end