kiroshi 0.0.1 → 0.1.1

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Kiroshi
+  # @api public
+  # Base class for implementing filter sets on ActiveRecord scopes
+  #
+  # This class provides a foundation for creating reusable filter collections
+  # that can be applied to ActiveRecord queries. It uses a class-level DSL
+  # to define filters and an instance-level interface to apply them.
+  #
+  # The class is designed to be inherited by specific filter implementations
+  # that define their own set of filters using the {.filter_by} method.
+  #
+  # @api public
+  # @author darthjee
+  #
+  # @example Basic usage with inheritance
+  #   class DocumentFilters < Kiroshi::Filters
+  #     filter_by :name, match: :like
+  #     filter_by :status
+  #     filter_by :created_at, match: :exact
+  #   end
+  #
+  #   filters = DocumentFilters.new(name: 'report', status: 'published')
+  #   filtered_documents = filters.apply(Document.all)
+  #
+  # @example Multiple filter types
+  #   class UserFilters < Kiroshi::Filters
+  #     filter_by :email, match: :like
+  #     filter_by :role
+  #     filter_by :active, match: :exact
+  #   end
+  #
+  #   filters = UserFilters.new(email: 'admin', role: 'moderator')
+  #   filtered_users = filters.apply(User.all)
+  #
+  # @since 0.1.0
+  class Filters
+    class << self
+      # Defines a filter for the current filter class
+      #
+      # This method is used at the class level to configure filters that will
+      # be applied when {#apply} is called. Each call creates a new {Filter}
+      # instance with the specified configuration.
+      #
+      # @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
+      #
+      # @example Defining exact match filters
+      #   class ProductFilters < Kiroshi::Filters
+      #     filter_by :category
+      #     filter_by :brand
+      #   end
+      #
+      # @example Defining partial match filters
+      #   class SearchFilters < Kiroshi::Filters
+      #     filter_by :title, match: :like
+      #     filter_by :description, match: :like
+      #   end
+      #
+      # @example Mixed filter types
+      #   class OrderFilters < Kiroshi::Filters
+      #     filter_by :customer_name, match: :like
+      #     filter_by :status, match: :exact
+      #     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|
+          filter_configs << filter
+        end
+      end
+
+      # Returns the list of configured filters for this class
+      #
+      # @return [Array<Filter>] array of {Filter} instances configured
+      #   for this filter class
+      #
+      # @example Accessing configured filters
+      #   class MyFilters < Kiroshi::Filters
+      #     filter_by :name
+      #     filter_by :status, match: :like
+      #   end
+      #
+      #   MyFilters.filter_configs.length # => 2
+      #   MyFilters.filter_configs.first.attribute # => :name
+      #
+      # @since 0.1.0
+      def filter_configs
+        @filter_configs ||= []
+      end
+    end
+
+    # 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}.
+    #   Values will be used for filtering. Nil or blank values are ignored.
+    #
+    # @example Creating filters with values
+    #   filters = DocumentFilters.new(
+    #     name: 'annual report',
+    #     status: 'published',
+    #     category: 'finance'
+    #   )
+    #
+    # @example Creating filters with partial values
+    #   filters = UserFilters.new(email: 'admin')  # Only email filter will be applied
+    #
+    # @example Creating empty filters
+    #   filters = ProductFilters.new({})  # No filters will be applied
+    #
+    # @since 0.1.0
+    def initialize(filters = {})
+      @filters = filters || {}
+    end
+
+    # Applies all configured filters to the given scope
+    #
+    # This method iterates through all filters defined via {.filter_by}
+    # and applies each one sequentially to the scope. Filters with no
+    # corresponding value in the filters hash or with blank values are
+    # automatically skipped.
+    #
+    # @param scope [ActiveRecord::Relation] the ActiveRecord scope to filter
+    #
+    # @return [ActiveRecord::Relation] the filtered scope with all
+    #   applicable filters applied
+    #
+    # @example Applying filters to a scope
+    #   class ArticleFilters < Kiroshi::Filters
+    #     filter_by :title, match: :like
+    #     filter_by :published, match: :exact
+    #   end
+    #
+    #   filters = ArticleFilters.new(title: 'Ruby', published: true)
+    #   filtered_articles = filters.apply(Article.all)
+    #   # Generates: WHERE title LIKE '%Ruby%' AND published = true
+    #
+    # @example With empty filters
+    #   filters = ArticleFilters.new({})
+    #   filtered_articles = filters.apply(Article.all)
+    #   # Returns the original scope unchanged
+    #
+    # @example With partial filters
+    #   filters = ArticleFilters.new(title: 'Ruby')  # published filter ignored
+    #   filtered_articles = filters.apply(Article.all)
+    #   # Generates: WHERE title LIKE '%Ruby%'
+    #
+    # @since 0.1.0
+    def apply(scope)
+      self.class.filter_configs.each do |filter|
+        scope = filter.apply(scope, filters)
+      end
+
+      scope
+    end
+
+    private
+
+    attr_reader :filters
+
+    # @!method filters
+    #   @api private
+    #   @private
+    #
+    #   Returns the hash of filter values to be applied
+    #
+    #   @return [Hash] the hash of filter values to be applied
+  end
+end

data/lib/kiroshi/version.rb

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

data/lib/kiroshi.rb

@@ -2,6 +2,162 @@
 
 # @api public
 # @author darthjee
-class Kiroshi
-  autoload :VERSION, 'kiroshi/version'
+#
+# Kiroshi - Flexible ActiveRecord Query Filtering
+#
+# Kiroshi provides a clean and extensible way to filter ActiveRecord queries
+# using a declarative DSL. It supports multiple matching strategies and can
+# be easily integrated into Rails controllers and other components.
+#
+# The gem is designed around two main concepts:
+# - {Filters}: A base class for creating reusable filter sets
+# - {Filter}: Individual filters that can be applied to scopes
+#
+# @example Basic filter class definition
+#   class DocumentFilters < Kiroshi::Filters
+#     filter_by :name, match: :like
+#     filter_by :status
+#     filter_by :category
+#   end
+#
+#   # Usage
+#   filters = DocumentFilters.new(name: 'report', status: 'published')
+#   filtered_documents = filters.apply(Document.all)
+#   # Generates: WHERE name LIKE '%report%' AND status = 'published'
+#
+# @example Controller integration
+#   # URL: /articles?filter[title]=ruby&filter[author]=john&filter[category]=tech
+#   class ArticlesController < ApplicationController
+#     def index
+#       @articles = article_filters.apply(Article.published)
+#       render json: @articles
+#     end
+#
+#     private
+#
+#     def article_filters
+#       ArticleFilters.new(filter_params)
+#     end
+#
+#     def filter_params
+#       params[:filter]&.permit(:title, :author, :category, :tag)
+#     end
+#   end
+#
+#   class ArticleFilters < Kiroshi::Filters
+#     filter_by :title, match: :like
+#     filter_by :author, match: :like
+#     filter_by :category
+#     filter_by :tag
+#   end
+#
+# @example Advanced filtering scenarios
+#   class UserFilters < Kiroshi::Filters
+#     filter_by :email, match: :like
+#     filter_by :role
+#     filter_by :active, match: :exact
+#     filter_by :department
+#   end
+#
+#   # Apply multiple filters
+#   filters = UserFilters.new(
+#     email: 'admin',
+#     role: 'moderator',
+#     active: true
+#   )
+#   filtered_users = filters.apply(User.includes(:department))
+#   # Generates: WHERE email LIKE '%admin%' AND role = 'moderator' AND active = true
+#
+# @example Individual filter usage
+#   # Create standalone filters
+#   name_filter = Kiroshi::Filter.new(:name, match: :like)
+#   status_filter = Kiroshi::Filter.new(:status)
+#
+#   # Apply filters step by step
+#   scope = Document.all
+#   scope = name_filter.apply(scope, { name: 'annual' })
+#   scope = status_filter.apply(scope, { status: 'published' })
+#
+# @example Filter matching types
+#   # Exact matching (default)
+#   Kiroshi::Filter.new(:status)
+#   # Generates: WHERE status = 'value'
+#
+#   # Partial matching with LIKE
+#   Kiroshi::Filter.new(:title, match: :like)
+#   # Generates: WHERE title LIKE '%value%'
+#
+# @example Empty value handling
+#   filters = DocumentFilters.new(name: '', status: 'published')
+#   result = filters.apply(Document.all)
+#   # Only status filter is applied, name is ignored due to empty value
+#
+# @example Chaining with existing scopes
+#   # URL: /orders?filter[status]=completed&filter[customer_name]=john
+#   class OrderFilters < Kiroshi::Filters
+#     filter_by :customer_name, match: :like
+#     filter_by :status
+#     filter_by :payment_method
+#   end
+#
+#   # Apply to pre-filtered scope
+#   recent_orders = Order.where('created_at > ?', 1.month.ago)
+#   filters = OrderFilters.new(status: 'completed', customer_name: 'john')
+#   filtered_orders = filters.apply(recent_orders)
+#
+# @example Complex controller with pagination
+#   # URL: /products?filter[name]=laptop&filter[category]=electronics&filter[in_stock]=true&page=2
+#   class ProductsController < ApplicationController
+#     def index
+#       @products = filtered_products.page(params[:page])
+#       render json: {
+#         products: @products,
+#         total: filtered_products.count,
+#         filters_applied: applied_filter_count
+#       }
+#     end
+#
+#     private
+#
+#     def filtered_products
+#       @filtered_products ||= product_filters.apply(base_scope)
+#     end
+#
+#     def base_scope
+#       Product.includes(:category, :brand).available
+#     end
+#
+#     def product_filters
+#       ProductFilters.new(filter_params)
+#     end
+#
+#     def filter_params
+#       params[:filter]&.permit(:name, :category, :brand, :price_range, :in_stock)
+#     end
+#
+#     def applied_filter_count
+#       filter_params.compact.count
+#     end
+#   end
+#
+#   class ProductFilters < Kiroshi::Filters
+#     filter_by :name, match: :like
+#     filter_by :category
+#     filter_by :brand
+#     filter_by :in_stock, match: :exact
+#   end
+#
+# @see Filters Base class for creating filter sets
+# @see Filter Individual filter implementation
+# @see https://github.com/darthjee/kiroshi GitHub repository
+# @see https://www.rubydoc.info/gems/kiroshi YARD documentation
+#
+# @since 0.1.0
+module Kiroshi
+  autoload :VERSION,      'kiroshi/version'
+
+  autoload :Filters,      'kiroshi/filters'
+  autoload :Filter,       'kiroshi/filter'
+  autoload :FilterRunner, 'kiroshi/filter_runner'
+  autoload :FilterQuery,  'kiroshi/filter_query'
 end