kiroshi 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bbe023d89c78eca0371b05303b85c44da60ce794a1c39844b2ab719350cc665
-  data.tar.gz: aa64d92280278a488c7bb2c5385fc7fd5f28a04a5b7a22aa1cbd1681311bf316
+  metadata.gz: 3df16fe842c4fcd160633af8a5e4d91fa19cbb857dc135a31160c1f389a5f6c1
+  data.tar.gz: b3f98740895ae5c611d616c36472d77ce412a1086d9d6a9ffe4532a8b3fa2235
 SHA512:
-  metadata.gz: 588fb1ce51bb238a8536b08d123a6cd23b8393896eea4f66df436b8fb641e016f517e411a6936ea6277b76c9d34564d44e82b547517b27ec61762634dbaa1ca3
-  data.tar.gz: 7f90feb28c09bc3858110427fe2266ec16fcc699238689ceea3432ed56a6e839ad1d33d49818e7563998817b3d41fc839f175d5e64bbdb0d838f4375e0d5698a
+  metadata.gz: 328641f23218cf3a3a3841af7027f42981dced635c03e47642e5f7bd3a9194d94e13e59a87f51f71adc51344642a682148606daff113ebf80f638e0cb0f5be19
+  data.tar.gz: e3cb7920836e0ad2d86d05875c74a57759c5b28d9309124539c61c902adaaaa3a9bf1d0f094e9b19500d23f4034563ac9de234b9fd6f36a21084054bfed09c13

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.1.1](https://www.rubydoc.info/gems/kiroshi/0.1.1)
 
 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.1.1](https://github.com/darthjee/kiroshi/tree/0.1.1)
 
-[Next release](https://github.com/darthjee/kiroshi/compare/0.1.0...master)
+[Next release](https://github.com/darthjee/kiroshi/compare/0.1.1...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,10 +143,65 @@ def articles
 end
 
 def article_filters
-  ArticleFilters.new(params.permit(:title, :published, :tag))
+  ArticleFilters.new(params[:filter]&.permit(:title, :published, :tag))
 end
 ```
 
+##### Joined Tables and Table Qualification
+
+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
+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
+
+# 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'
+```
+
+###### Table Qualification Examples
+
+```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'
+```
+
+The `table` parameter accepts both symbols and strings, and helps resolve column name ambiguity in complex joined queries.
+
 ### Kiroshi::Filter
 
 [Filter](https://www.rubydoc.info/gems/kiroshi/Kiroshi/Filter)
@@ -168,6 +225,7 @@ scope = status_filter.apply(scope, { status: 'published' })
 
 - `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)
 
 ```ruby
 # Exact match filter
@@ -179,6 +237,16 @@ exact_filter.apply(Document.all, { status: 'published' })
 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'
 ```
 
 #### Empty Value Handling
@@ -192,3 +260,24 @@ filter.apply(Document.all, { name: '' })         # Returns original scope
 filter.apply(Document.all, {})                   # Returns original scope
 filter.apply(Document.all, { name: 'value' })    # Applies filter
 ```
+
+#### Handling Column Name Ambiguity
+
+When working with joined tables that have columns with the same name, use the `table` parameter to specify which table's column to filter:
+
+```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%'
+```
+
+**Priority**: When using `Kiroshi::Filters`, if a filter specifies a `table`, it takes priority over the scope's default table name.

data/lib/kiroshi/filter.rb

@@ -18,10 +18,34 @@ module Kiroshi
   #
   # @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,10 +55,14 @@ 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
@@ -58,6 +86,16 @@ module Kiroshi
     #   filter.apply(Article.all, { title: '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' })
+    #   # 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' })
+    #   # Generates: WHERE tags.name = 'ruby'
+    #
     # @example With empty filter value
     #   filter = Kiroshi::Filter.new(:name)
     #   filter.apply(User.all, { name: nil })
@@ -65,35 +103,8 @@ module Kiroshi
     #
     # @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
+      runner = FilterRunner.new(filter: self, scope: scope, filters: filters)
+      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 => filter_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 ?",
+          "%#{filter_value}%"
+        )
+      end
+    end
+  end
+end

data/lib/kiroshi/filter_query.rb

@@ -0,0 +1,131 @@
+# 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, :filter_value, to: :filter_runner
+
+    # @!method scope
+    #   @api private
+    #   @private
+    #
+    #   Returns the ActiveRecord scope being filtered
+    #
+    #   @return [ActiveRecord::Relation] the scope being filtered
+
+    # @!method attribute
+    #   @api private
+    #   @private
+    #
+    #   Returns the attribute name to filter by
+    #
+    #   @return [Symbol] the attribute name to filter by
+
+    # @!method table_name
+    #   @api private
+    #   @private
+    #
+    #   Returns the table name from the scope
+    #
+    #   @return [String] the table name
+
+    # @!method filter_value
+    #   @api private
+    #   @private
+    #
+    #   Returns the filter value for the current filter's attribute
+    #
+    #   @return [Object, nil] the filter value or nil if not present
+  end
+end

data/lib/kiroshi/filter_runner.rb

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

data/lib/kiroshi/filters.rb

@@ -43,11 +43,13 @@ module Kiroshi
       # be applied when {#apply} is called. Each call creates a new {Filter}
       # instance with the specified configuration.
       #
-      # @param attribute [Symbol] the attribute name to filter by
-      # @param options [Hash] additional options passed to {Filter#initialize}
-      # @option options [Symbol] :match (:exact) the matching type
-      #   - +:exact+ for exact matching (default)
-      #   - +:like+ for partial matching using SQL LIKE
+      # @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
       #
@@ -70,6 +72,11 @@ module Kiroshi
       #     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|

data/lib/kiroshi/version.rb

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