kiroshi 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f215b5db38cfab5958a6d87cfbfffe94a6a4ca9f36b114d6539f064e918aaf3c
-  data.tar.gz: 11fd8327a643b27eab6feaa92eda2dd962ccbb573501a0dd06f0811ac840dbdc
+  metadata.gz: 3df16fe842c4fcd160633af8a5e4d91fa19cbb857dc135a31160c1f389a5f6c1
+  data.tar.gz: b3f98740895ae5c611d616c36472d77ce412a1086d9d6a9ffe4532a8b3fa2235
 SHA512:
-  metadata.gz: 60fbd8f3a711432be3ecfdd1c565d535657b6424ee46eae72b85d345fed4dd160606eeb7e4c13c83de291b72cce32d6c63bbbc8c31949c1e5c0a3155ddb02821
-  data.tar.gz: e57185d0789ef027ac87be751cc5054cdf52169beb7a7f9836aaa7e750b9776b4ae86751560c91b20dc20b93775a9f63f58d91948d7d85ec23a5012b1a151fdd
+  metadata.gz: 328641f23218cf3a3a3841af7027f42981dced635c03e47642e5f7bd3a9194d94e13e59a87f51f71adc51344642a682148606daff113ebf80f638e0cb0f5be19
+  data.tar.gz: e3cb7920836e0ad2d86d05875c74a57759c5b28d9309124539c61c902adaaaa3a9bf1d0f094e9b19500d23f4034563ac9de234b9fd6f36a21084054bfed09c13

data/.rubocop_todo.yml

@@ -1,21 +1,23 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-08-15 21:59:24 UTC using RuboCop version 1.79.2.
+# on 2025-08-17 15:11:59 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
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-# Configuration parameters: AllowComments, AllowEmptyLambdas.
-Lint/EmptyBlock:
-  Exclude:
-    - 'spec/**/*_spec.rb'
-    - 'spec/dummy/config/routes.rb'
-
 # Offense count: 1
 # Configuration parameters: AllowedPatterns.
 # AllowedPatterns: ^expect_, ^assert_
 RSpec/NoExpectationExample:
   Exclude:
     - 'spec/lib/kiroshi_spec.rb'
+
+# Offense count: 2
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/kiroshi/filter.rb'
+    - 'lib/kiroshi/filters.rb'

data/Gemfile

@@ -6,6 +6,7 @@ gemspec
 
 gem 'actionpack',                '7.2.2.1'
 gem 'activerecord',              '7.2.2.1'
+gem 'activesupport',             '7.2.2.1'
 gem 'bundler',                   '~> 2.3'
 gem 'factory_bot',               '6.2.1'
 gem 'minitest',                  '5.25.4'

data/README.md

@@ -1,16 +1,24 @@
-Kiroshi
-====
+# Kiroshi
 [![Build Status](https://circleci.com/gh/darthjee/kiroshi.svg?style=shield)](https://circleci.com/gh/darthjee/kiroshi)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/35480a5e82e74ff7a0186697b3f61a4b)](https://app.codacy.com/gh/darthjee/kiroshi/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 
 ![kiroshi](https://raw.githubusercontent.com/darthjee/kiroshi/master/kiroshi.jpg)
 
-Yard Documentation
--------------------
-[https://www.rubydoc.info/gems/kiroshi/0.0.1](https://www.rubydoc.info/gems/kiroshi/0.0.1)
 
-Installation
----------------
+## Yard Documentation
+
+[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.1](https://github.com/darthjee/kiroshi/tree/0.1.1)
+
+[Next release](https://github.com/darthjee/kiroshi/compare/0.1.1...master)
+
+## Installation
 
 - Install it
 
@@ -27,3 +35,249 @@ Installation
 ```bash
   bundle install kiroshi
 ```
+
+## Usage
+
+### Kiroshi::Filters
+
+[Filters](https://www.rubydoc.info/gems/kiroshi/Kiroshi/Filters)
+is a base class for implementing filter sets on ActiveRecord scopes.
+It uses a class-level DSL to define filters and an instance-level interface to apply them.
+
+#### Basic Usage
+
+```ruby
+# Define a filter class
+class DocumentFilters < Kiroshi::Filters
+  filter_by :name, match: :like
+  filter_by :status
+  filter_by :category
+end
+
+# Apply filters to a scope
+filters = DocumentFilters.new(name: 'report', status: 'published')
+filtered_documents = filters.apply(Document.all)
+# Generates: WHERE name LIKE '%report%' AND status = 'published'
+```
+
+#### Filter Types
+
+Kiroshi supports two types of matching:
+
+- `:exact` - Exact match (default)
+- `:like` - Partial match using SQL LIKE
+
+```ruby
+class UserFilters < Kiroshi::Filters
+  filter_by :email, match: :like      # Partial matching
+  filter_by :role                     # Exact matching (default)
+  filter_by :active, match: :exact    # Explicit exact matching
+end
+
+filters = UserFilters.new(email: 'admin', role: 'moderator')
+filtered_users = filters.apply(User.all)
+# Generates: WHERE email LIKE '%admin%' AND role = 'moderator'
+```
+
+#### Advanced Examples
+
+##### Multiple Filter Types
+
+```ruby
+class ProductFilters < Kiroshi::Filters
+  filter_by :name, match: :like
+  filter_by :category
+  filter_by :price, match: :exact
+  filter_by :brand
+end
+
+# Apply only some filters
+filters = ProductFilters.new(name: 'laptop', category: 'electronics')
+products = filters.apply(Product.all)
+# Only name and category filters are applied, price and brand are ignored
+```
+
+##### 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)
+    render json: @documents
+  end
+
+  private
+
+  def document_filters
+    DocumentFilters.new(filter_params)
+  end
+
+  def filter_params
+    params[:filter]&.permit(:name, :status, :category, :author)
+  end
+end
+
+class DocumentFilters < Kiroshi::Filters
+  filter_by :name, match: :like
+  filter_by :status
+  filter_by :category
+  filter_by :author, match: :like
+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
+  filter_by :tag, match: :like
+end
+
+# In your controller
+def articles
+  base_scope = current_user.articles
+  article_filters.apply(base_scope)
+end
+
+def article_filters
+  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)
+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
+
+```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)
+
+```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'
+```
+
+#### Empty Value Handling
+
+Filters automatically ignore empty or nil values:
+
+```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
+```
+
+#### 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/config/yardstick.yml

@@ -1,4 +1,4 @@
-threshold: 100
+threshold: 100.0
 require_exact_threshold: false
 rules:
   ApiTag::Presence:

data/lib/kiroshi/filter.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  # @author darthjee
+  #
+  # A filter class that applies filtering logic to ActiveRecord scopes
+  #
+  # This class provides a flexible way to apply filters to database queries,
+  # supporting both exact matches and partial matches using SQL LIKE operations.
+  #
+  # @example Creating and applying an exact filter
+  #   filter = Kiroshi::Filter.new(:name)
+  #   filtered_scope = filter.apply(Document.all, { name: 'John' })
+  #
+  # @example Creating and applying a LIKE filter
+  #   filter = Kiroshi::Filter.new(:title, match: :like)
+  #   filtered_scope = filter.apply(Article.all, { title: 'Ruby' })
+  #
+  # @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
+    #
+    # @example Creating an exact match filter
+    #   filter = Kiroshi::Filter.new(:status)
+    #
+    # @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, 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.
+    #
+    # @param scope [ActiveRecord::Relation] the ActiveRecord scope to filter
+    # @param filters [Hash] a hash containing filter values
+    #
+    # @return [ActiveRecord::Relation] the filtered scope
+    #
+    # @example Applying an exact filter
+    #   filter = Kiroshi::Filter.new(:status)
+    #   filter.apply(Document.all, { status: 'published' })
+    #   # Generates: WHERE status = 'published'
+    #
+    # @example Applying a LIKE filter
+    #   filter = Kiroshi::Filter.new(:title, match: :like)
+    #   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 })
+    #   # Returns the original scope unchanged
+    #
+    # @since 0.1.0
+    def apply(scope, filters)
+      runner = FilterRunner.new(filter: self, scope: scope, filters: filters)
+      runner.apply
+    end
+  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