kiroshi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bbe023d89c78eca0371b05303b85c44da60ce794a1c39844b2ab719350cc665
-  data.tar.gz: aa64d92280278a488c7bb2c5385fc7fd5f28a04a5b7a22aa1cbd1681311bf316
+  metadata.gz: ff66735688ded970094d5a88a9bcd67ad4f9cac7679fc55ceb75534d9b16d9fc
+  data.tar.gz: d6da2da4ec294c0d134ceff028e19b30fa5e13ddab2fae2ad0582a5fdfc559aa
 SHA512:
-  metadata.gz: 588fb1ce51bb238a8536b08d123a6cd23b8393896eea4f66df436b8fb641e016f517e411a6936ea6277b76c9d34564d44e82b547517b27ec61762634dbaa1ca3
-  data.tar.gz: 7f90feb28c09bc3858110427fe2266ec16fcc699238689ceea3432ed56a6e839ad1d33d49818e7563998817b3d41fc839f175d5e64bbdb0d838f4375e0d5698a
+  metadata.gz: 15f142b43b0fcd7fc12f8cd2c1246031aabec104deaf1270030eca5afa56d5776d5c3fec301422c12baec0c531d5366f39832b4afe6ec3d1c83f40ce3e94aea5
+  data.tar.gz: af94b97459b7a157c6ea30f36c36b937e9a75c25b7081106cf6b6d104b3514687a7da4842e9ac847b7669954bab65f707e8a609d55e3666393f6da09cad6d9c4

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.0](https://www.rubydoc.info/gems/kiroshi/0.1.0)
+[https://www.rubydoc.info/gems/kiroshi/0.2.0](https://www.rubydoc.info/gems/kiroshi/0.2.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.0](https://github.com/darthjee/kiroshi/tree/0.1.0)
+Current Release: [0.2.0](https://github.com/darthjee/kiroshi/tree/0.2.0)
 
-[Next release](https://github.com/darthjee/kiroshi/compare/0.1.0...master)
+[Next release](https://github.com/darthjee/kiroshi/compare/0.2.0...master)
 
 ## Installation
 
@@ -100,6 +100,7 @@ products = filters.apply(Product.all)
 ##### Controller Integration
 
 ```ruby
+# URL: /documents?filter[name]=report&filter[status]=published&filter[author]=john
 class DocumentsController < ApplicationController
   def index
     @documents = document_filters.apply(Document.all)
@@ -113,7 +114,7 @@ class DocumentsController < ApplicationController
   end
 
   def filter_params
-    params.permit(:name, :status, :category, :author)
+    params[:filter]&.permit(:name, :status, :category, :author)
   end
 end
 
@@ -128,6 +129,7 @@ end
 ##### Nested Resource Filtering
 
 ```ruby
+# URL: /users/123/articles?filter[title]=ruby&filter[published]=true&filter[tag]=tutorial
 class ArticleFilters < Kiroshi::Filters
   filter_by :title, match: :like
   filter_by :published
@@ -141,54 +143,67 @@ def articles
 end
 
 def article_filters
-  ArticleFilters.new(params.permit(:title, :published, :tag))
+  ArticleFilters.new(params[:filter]&.permit(:title, :published, :tag))
 end
 ```
 
-### Kiroshi::Filter
+##### Joined Tables and Table Qualification
 
-[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.
-
-#### Standalone Usage
+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
-# 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' })
-```
+class DocumentFilters < Kiroshi::Filters
+  filter_by :name, match: :like                    # Filters by documents.name (default table)
+  filter_by :tag_name, match: :like, table: :tags  # Filters by tags.name
+  filter_by :status                                # Filters by documents.status
+  filter_by :category, table: :documents           # Explicitly filter by documents.category
+end
 
-#### Filter Options
+# Example with joined scope
+scope = Document.joins(:tags)
+filters = DocumentFilters.new(tag_name: 'ruby', status: 'published')
+filtered_documents = filters.apply(scope)
+# Generates: WHERE tags.name LIKE '%ruby%' AND documents.status = 'published'
+```
 
-- `match: :exact` - Performs exact matching (default)
-- `match: :like` - Performs partial matching using SQL LIKE
+###### Table Qualification Examples
 
 ```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%'
+# Filter documents by tag name and document status
+class DocumentTagFilters < Kiroshi::Filters
+  filter_by :tag_name, match: :like, table: :tags  # Search in tags.name
+  filter_by :status, table: :documents             # Search in documents.status
+  filter_by :title, match: :like                   # Search in documents.title (default table)
+end
+
+scope = Document.joins(:tags)
+filters = DocumentTagFilters.new(tag_name: 'programming', status: 'published', title: 'Ruby')
+result = filters.apply(scope)
+# Generates: WHERE tags.name LIKE '%programming%' AND documents.status = 'published' AND documents.title LIKE '%Ruby%'
+
+# Filter by both document and tag attributes with different field names
+class AdvancedDocumentFilters < Kiroshi::Filters
+  filter_by :title, match: :like, table: :documents
+  filter_by :tag_name, match: :like, table: :tags
+  filter_by :category, table: :documents
+  filter_by :tag_color, table: :tags
+end
+
+scope = Document.joins(:tags)
+filters = AdvancedDocumentFilters.new(
+  title: 'Ruby', 
+  tag_name: 'tutorial', 
+  category: 'programming',
+  tag_color: 'blue'
+)
+result = filters.apply(scope)
+# Generates: WHERE documents.title LIKE '%Ruby%' AND tags.name LIKE '%tutorial%' AND documents.category = 'programming' AND tags.color = 'blue'
 ```
 
-#### Empty Value Handling
+The `table` parameter accepts both symbols and strings, and helps resolve column name ambiguity in complex joined queries.
 
-Filters automatically ignore empty or nil values:
+## API Reference
 
-```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
-```
+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

@@ -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,18 +11,46 @@ 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
+
+    # @!method attribute
+    #   @api private
+    #
+    #   Returns the attribute name to filter by
+    #
+    #   @return [Symbol] the attribute name to filter by
+
+    # @!method match
+    #   @api private
+    #
+    #   Returns the matching type (+:exact+ or +:like+)
+    #
+    #   @return [Symbol] the matching type (+:exact+ or +:like+)
+
+    # @!method table_name
+    #   @api private
+    #
+    #   Returns the table name to qualify the attribute
+    #
+    #   @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 match [Symbol] the matching type, defaults to :exact
+    # @param table [String, Symbol, nil] the table name to qualify the attribute, defaults to nil
     # @option match [Symbol] :exact performs exact matching (default)
     # @option match [Symbol] :like performs partial matching using SQL LIKE
     #
@@ -31,69 +60,56 @@ module Kiroshi
     # @example Creating a partial match filter
     #   filter = Kiroshi::Filter.new(:name, match: :like)
     #
+    # @example Creating a filter with table qualification
+    #   filter = Kiroshi::Filter.new(:name, table: 'documents')
+    #
     # @since 0.1.0
-    def initialize(attribute, match: :exact)
+    def initialize(attribute, match: :exact, table: nil)
       @attribute = attribute
       @match = match
+      @table_name = table
     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(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(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)
-      filter_value = filters[attribute]
-      return scope unless filter_value.present?
-
-      case match
-      when :like
-        scope.where("#{attribute} LIKE ?", "%#{filter_value}%")
-      else # :exact (default)
-        scope.where(attribute => filter_value)
-      end
+    # @since 0.2.0
+    def apply(scope:, value: nil)
+      runner = FilterRunner.new(filter: self, scope: scope, value: value)
+      runner.apply
     end
-
-    private
-
-    attr_reader :attribute, :match
-
-    # @!method attribute
-    #   @api private
-    #   @private
-    #
-    #   Returns the attribute name to filter by
-    #
-    #   @return [Symbol] the attribute name to filter by
-
-    # @!method match
-    #   @api private
-    #   @private
-    #
-    #   Returns the matching type (+:exact+ or +:like+)
-    #
-    #   @return [Symbol] the matching type (+:exact+ or +:like+)
   end
 end

data/lib/kiroshi/filter_query/exact.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  class FilterQuery
+    # @api private
+    # @author darthjee
+    #
+    # Query strategy for exact matching
+    #
+    # This class implements the exact match query strategy, generating
+    # WHERE clauses with exact equality comparisons.
+    #
+    # @example Applying exact match query
+    #   query = Kiroshi::FilterQuery::Exact.new(filter_runner)
+    #   query.apply
+    #   # Generates: WHERE attribute = '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.
+      #
+      # @return [ActiveRecord::Relation] the filtered scope with exact match
+      #
+      # @example Applying exact match
+      #   query = Exact.new(filter_runner)
+      #   query.apply
+      #   # Generates: WHERE status = 'published'
+      #
+      # @since 0.1.1
+      def apply
+        scope.where(table_name => { attribute => value })
+      end
+    end
+  end
+end

data/lib/kiroshi/filter_query/like.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  class FilterQuery
+    # @api private
+    # @author darthjee
+    #
+    # Query strategy for LIKE matching
+    #
+    # This class implements the LIKE match query strategy, generating
+    # WHERE clauses with SQL LIKE operations for partial matching.
+    #
+    # @example Applying LIKE match query
+    #   query = Kiroshi::FilterQuery::Like.new(filter_runner)
+    #   query.apply
+    #   # Generates: WHERE table_name.attribute LIKE '%value%'
+    #
+    # @since 0.1.1
+    class Like < FilterQuery
+      # Applies LIKE match filtering to the scope
+      #
+      # This method generates a WHERE clause with SQL LIKE operation
+      # for partial matching, including table name prefix to avoid
+      # column ambiguity in complex queries.
+      #
+      # @return [ActiveRecord::Relation] the filtered scope with LIKE match
+      #
+      # @example Applying LIKE match
+      #   query = Like.new(filter_runner)
+      #   query.apply
+      #   # Generates: WHERE documents.name LIKE '%ruby%'
+      #
+      # @since 0.1.1
+      def apply
+        scope.where(
+          "#{table_name}.#{attribute} LIKE ?",
+          "%#{value}%"
+        )
+      end
+    end
+  end
+end

data/lib/kiroshi/filter_query.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  # @api private
+  # @author darthjee
+  #
+  # Factory class for creating filter query strategies
+  #
+  # This class implements the Strategy pattern for handling different types of
+  # database queries based on the filter match type. It provides a factory method
+  # to create the appropriate query strategy class.
+  #
+  # @example Getting an exact match query strategy
+  #   query = Kiroshi::FilterQuery.for(:exact).new(filter_runner)
+  #   query.apply
+  #
+  # @example Getting a LIKE match query strategy
+  #   query = Kiroshi::FilterQuery.for(:like).new(filter_runner)
+  #   query.apply
+  #
+  # @since 0.1.1
+  class FilterQuery
+    autoload :Exact, 'kiroshi/filter_query/exact'
+    autoload :Like, 'kiroshi/filter_query/like'
+
+    class << self
+      # Factory method to create the appropriate query strategy
+      #
+      # This method returns the correct query strategy class based on the
+      # match type provided. It serves as the main entry point for creating
+      # query strategies.
+      #
+      # @param match [Symbol] the type of matching to perform
+      #   - :exact for exact matching
+      #   - :like for partial matching using SQL LIKE
+      #
+      # @return [Class] the appropriate FilterQuery subclass
+      #
+      # @example Creating an exact match query
+      #   query_class = Kiroshi::FilterQuery.for(:exact)
+      #   # Returns Kiroshi::FilterQuery::Exact
+      #
+      # @example Creating a LIKE match query
+      #   query_class = Kiroshi::FilterQuery.for(:like)
+      #   # Returns Kiroshi::FilterQuery::Like
+      #
+      # @raise [ArgumentError] when an unsupported match type is provided
+      #
+      # @since 0.1.1
+      def for(match)
+        case match
+        when :exact
+          Exact
+        when :like
+          Like
+        else
+          raise ArgumentError, "Unsupported match type: #{match}"
+        end
+      end
+    end
+
+    # Creates a new FilterQuery instance
+    #
+    # @param filter_runner [Kiroshi::FilterRunner] the filter runner instance
+    #
+    # @since 0.1.1
+    def initialize(filter_runner)
+      @filter_runner = filter_runner
+    end
+
+    # Base implementation for applying a filter query
+    #
+    # This method should be overridden by subclasses to provide specific
+    # query logic for each match type.
+    #
+    # @return [ActiveRecord::Relation] the filtered scope
+    #
+    # @raise [NotImplementedError] when called on the base class
+    #
+    # @since 0.1.1
+    def apply
+      raise NotImplementedError, 'Subclasses must implement #apply method'
+    end
+
+    private
+
+    attr_reader :filter_runner
+
+    # @!method filter_runner
+    #   @api private
+    #   @private
+    #
+    #   Returns the filter runner instance
+    #
+    #   @return [Kiroshi::FilterRunner] the filter runner instance
+
+    delegate :scope, :attribute, :table_name, :value, to: :filter_runner
+
+    # @!method scope
+    #   @api private
+    #
+    #   Returns the current scope being filtered
+    #
+    #   @return [ActiveRecord::Relation] the scope
+
+    # @!method attribute
+    #   @api private
+    #
+    #   Returns the attribute name to filter by
+    #
+    #   @return [Symbol] the attribute name
+
+    # @!method table_name
+    #   @api private
+    #
+    #   Returns the table name for the filter
+    #
+    #   @return [String] the table name
+
+    # @!method value
+    #   @api private
+    #
+    #   Returns the filter value
+    #
+    #   @return [Object] the filter value
+  end
+end