lupa 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 83dad7fde61871e8d0333b609958b6eadaccc23c
-  data.tar.gz: 1a1eb1e14ede2f72d5f7eb029c38b2511e9182f6
+SHA256:
+  metadata.gz: d6c3063e519871ee2848d6202a6388482747e7e2668f04122036e3a5ae8dd1fa
+  data.tar.gz: 7cb6850bb59992671ac66d19ef3179bb7c400dae6d39faaa7cbe5bfbdb837643
 SHA512:
-  metadata.gz: e6f6127f879df5ec3bcee9e4c0c479df20aa53c17389fedf7a10d1403900da7920372a6bf2dab44ddad82843465c71834fe3343e515f506d63f331b4feec23b3
-  data.tar.gz: 84e3f845e779bdb383410f32509b99b4f7ae5fcda658dbb5e3dd49e8110b735c66b47c49ff583a2942822df800fc656fe8315c2f52bdb3b6807e476a5c7b06e0
+  metadata.gz: 4b41e376873605d430296381df17225bf5d168b885857be7a5b395d206b4a7ab4f388473928898003539df96bbb64e6d4fc02c130914c5245b6adf0d3c2034ca
+  data.tar.gz: 3003501628ef7c228bf4762bdbaf9f81cb00b2b6e436f75940adfa710e1a2ffd30224b6a3155a828c1fa942a1ca1589ae7e9fbf4056c83dede6b0622381a423e

data/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version:
+          - '2.2'
+          - '2.3'
+          - '2.4'
+          - '2.5'
+          - '2.6'
+          - '2.7'
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+
+    - name: Run tests
+      run: bundle exec rake test
+
+    - name: Upload coverage to Coveralls
+      if: ${{ matrix.ruby-version >= '2.5' }}
+      uses: coverallsapp/github-action@v2
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        flag-name: ruby-${{ matrix.ruby-version }}
+        parallel: true
+
+  coveralls-finish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+    - name: Coveralls Finished
+      uses: coverallsapp/github-action@v2
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        parallel-finished: true
+

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.1

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+## 1.0.2
+
+* documentation
+    * Add comprehensive RDoc documentation for all classes and methods
+    * Include detailed examples and usage patterns in RDoc
+    * Document all error classes with practical examples
+    * Fix multiple typos in README.md
+    * Update Table of Contents links in README.md
+    * Add benchmarks section comparing Lupa with HasScope and Searchlight
+    * Improve code examples and usage patterns in README.md
+
+* ci
+    * Migrate from Travis CI to GitHub Actions
+    * Add support for Ruby 2.2 through 3.3
+    * Configure Coveralls for Ruby 2.5+ (conditional loading for compatibility)
+
+* dependencies
+    * Update minitest development dependency from ~> 5.5.1 to ~> 5.5
+    * Update bundler development dependency from ~> 1.6 to >= 1.6
+    * Add rake development dependency >= 10.0
+
+## 1.0.1
+
+* enhancements
+    * A **Lupa::DefaultSearchAttributesError** exception will be raised if `default_search_attributes` does not return a hash.

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in lupa.gemspec
 gemspec
+
+gem 'coveralls', require: false

data/README.md

@@ -2,53 +2,66 @@
 
 Lupa means *Magnifier* in spanish.
 
-Lupa lets you create simple, robust and scaleable search filters with ease using regular Ruby classes and object oriented design patterns. It's Framework and ORM agnostic.
+[![CI](https://github.com/edelpero/lupa/actions/workflows/ci.yml/badge.svg)](https://github.com/edelpero/lupa/actions/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/edelpero/lupa/badge.svg?branch=master)](https://coveralls.io/r/edelpero/lupa?branch=master) [![Code Climate](https://codeclimate.com/github/edelpero/lupa/badges/gpa.svg)](https://codeclimate.com/github/edelpero/lupa) [![Inline docs](http://inch-ci.org/github/edelpero/lupa.svg?branch=master)](http://inch-ci.org/github/edelpero/lupa)
 
-## Search Class
+Lupa lets you create simple, robust and scaleable search filters with ease using regular Ruby classes and object oriented design patterns.
 
-### Usage
+Lupa is Framework and ORM agnostic. It will work with any ORM or Object that can build a query using **chained method calls**, like ActiveRecord: `
+Product.where(name: 'Digital').where(category: '23').limit(2)`.
 
-The example will explain how to use the class on a Rails application:
+**Table of Contents:**
 
-- Define a custom form:
+* [Search Class](#search-class)
+    * [Overview](#overview)
+    * [Definition](#definition)
+    * [Public Methods](#public-methods)
+    * [Default Search Scope](#default-search-scope)
+    * [Default Search Attributes](#default-search-attributes)
+    * [Combining Search Classes](#combining-search-classes)
+* [Usage with Rails](#usage-with-rails)
+* [Testing](#testing)
+    * [Testing Default Scope](#testing-default-scope)
+    * [Testing Default Search Attributes](#testing-default-search-attributes)
+    * [Testing Each Scope Method Individually](#testing-each-scope-method-individually)
+* [Benchmarks](#benchmarks)
+    * [Lupa vs HasScope](#lupa-vs-hasscope)
+    * [Lupa vs Searchlight](#lupa-vs-searchlight)
+* [Installation](#installation)
 
-```haml
-# app/views/products/_search.html.haml
 
-= form_tag products_path, method: :get do
-  = text_field_tag 'name'
-  = select_tag 'category', options_from_collection_for_select(@categories, 'id', 'name')
-  = date_field_tag 'created_between[start_date]'
-  = date_field_tag 'created_between[end_date]'
-  = submit_tag :search
-```
-- Create a new instance of your search class and pass a collection to which all search conditions will be applied and specify the search params you want to apply:
+## Search Class
+
+### Overview
 
 ```ruby
-# app/controllers/products_controller.rb
+products = ProductSearch.new(current_user.products).search(name: 'digital', category: '23')
 
-class ProductsController < ApplicationController
-  def index
-    @products = ProductSearch.new(current_user.products).search(search_params)
-  end
-  
-  protected
-    def search_params
-      params.permit(:name, :category, created_between: [:start_date, :end_date])
-    end
+# Iterate over the search results
+products.each do |product|
+  # Your logic goes here
 end
 ```
-- Loop through the search results on your view.
+Calling **.each** on the instance will build a search by chaining calls to **name** and **category** methods defined in our **ProductSearch::Scope** class.
 
-```haml
-# app/views/products/index.html.haml
+```ruby
+# app/searches/product_search.rb
 
-%h1 Products
+class ProductSearch < Lupa::Search
+  # Scope class holds all your search methods.
+  class Scope
 
-%ul
-  - @products.each do |product|
-    %li
-      = "#{product.name} - #{product.price} - #{product.category}"
+    # Search method
+    def name
+      scope.where('name iLIKE ?', "%#{search_attributes[:name]}%")
+    end
+
+    # Search method
+    def category
+      scope.where(category_id: search_attributes[:category])
+    end
+
+  end
+end
 ```
 
 ### Definition
@@ -65,7 +78,7 @@ end
 Inside your **Scope** class you must define your scope methods. You'll also be able to access to the following methods inside your scope class: **scope** and **search_attributes**.
 
 * **`scope:`** returns the current scope when the scope method is called.
-* **`search_attributes:`** returns a hash containing the all search attributes specified.
+* **`search_attributes:`** returns a hash containing the all search attributes specified including the default ones.
 
 <u>**Note:**</u> All keys of **`search_attributes`** are symbolized.
 
@@ -75,36 +88,17 @@ Inside your **Scope** class you must define your scope methods. You'll also be a
 class ProductSearch < Lupa::Search
   # Scope class holds all your search methods.
   class Scope
-  
+
     # Search method
     def name
-      if search_attributes[:name].present?
-        scope.where('name LIKE ?', "%#{search_attributes[:name]}%")
-      end
-    end
-    
-    # Search method
-    def created_between
-      if created_start_date && created_end_date
-        scope.where(created_at: created_start_date..created_end_date)
-      end
+      scope.where('name LIKE ?', "%#{search_attributes[:name]}%")
     end
-    
+
     # Search method
     def category
-      scope.where(category_id: search_attributes[:category])    
+      scope.where(category_id: search_attributes[:category])
     end
-    
-    private
-      # Parses search_attributes[:created_between][:start_date]
-      def created_start_date
-        search_attributes[:created_between] && search_attributes[:created_between][:start_date].try(:to_date)
-      end
-      
-      # Parses search_attributes[:created_between][:end_date]
-      def created_end_date
-        search_attributes[:created_between] && search_attributes[:created_between][:end_date].try(:to_date)
-      end
+
   end
 end
 ```
@@ -154,7 +148,7 @@ search.unexisting_method
 # => Lupa::ResultMethodNotImplementedError: The resulting scope does not respond to unexisting_method method.
 ```
 
-## Default Search Scope
+### Default Search Scope
 
 You can define a default search scope if you want to use a search class with an specific resource by overriding the initialize method as follows:
 
@@ -165,9 +159,9 @@ class ProductSearch < Lupa::Search
   class Scope
     ...
   end
-  
+
   # Be careful not to change the scope variable name,
-  # otherwise you will experiment some issues.
+  # otherwise you will experience issues.
   def initialize(scope = Product.all)
     @scope = scope
   end
@@ -183,7 +177,7 @@ search.first
 # => #<Product id: 1, name: 'Eames Chair', category_id: 23, created_at: "2015-04-06 18:54:13", updated_at: "2015-04-06 18:54:13" >
 ```
 
-## Default Search Attributes
+### Default Search Attributes
 
 Defining default search attributes will cause the scope method to be invoked always.
 
@@ -194,23 +188,31 @@ class ProductSearch < Lupa::Search
   class Scope
     ...
   end
-  
+
   # This should always return a hash
   def default_search_attributes
-    { category: 23 }
+    { category: '23' }
   end
 end
 ```
+
+```ruby
+search = ProductSearch.new(current_user.products).search(name: 'chair')
+
+search.search_attributes
+# => { name: 'chair', category: '23' }
+```
+
 **<u>Note:</u>** You can override default search attributes by passing it to the search params.
 
 ``` ruby
 search = ProductSearch.new(current_user.products).search(name: 'chair', category: '42')
 
 search.search_attributes
-# => { name: 'chair', category: 42 }
+# => { name: 'chair', category: '42' }
 ```
 
-## Combining Search Classes
+### Combining Search Classes
 
 You can reuse your search class in order to keep them DRY.
 
@@ -221,29 +223,33 @@ A common example is searching records created between two dates. So lets create
 
 class CreatedAtSearch < Lupa::Search
   class Scope
-  
+
     def created_before
       ...
     end
-    
+
     def created_after
       ...
     end
- 
+
     def created_between
       if created_start_date && created_end_date
         scope.where(created_at: created_start_date..created_end_date)
       end
     end
-  
+
     private
 
+      # Parses search_attributes[:created_between][:start_date]
       def created_start_date
-        search_attributes[:created_between] && search_attributes[:created_between][:start_date].try(:to_date)
+        search_attributes[:created_between] &&
+        search_attributes[:created_between][:start_date].try(:to_date)
       end
-      
+
+      # Parses search_attributes[:created_between][:end_date]
       def created_end_date
-        search_attributes[:created_between] && search_attributes[:created_between][:end_date].try(:to_date)
+        search_attributes[:created_between] &&
+        search_attributes[:created_between][:end_date].try(:to_date)
       end
   end
 end
@@ -256,25 +262,78 @@ Now we can use it in our **ProductSearch** class:
 
 class ProductSearch < Lupa::Search
   class Scope
-  
+
     def name
       ...
     end
-    
-    # We use CreatedAtSearch class to perform the search
+
+    # We use CreatedAtSearch class to perform the search.
+    # Be sure to always call `results` method on your composed
+    # search class.
     def created_between
-      if search_attributes[:created_between]
-        CreadtedAtSearch.new(scope).search(created_between: search_attributes[:created_between])
-      end
+      CreatedAtSearch.new(scope).
+        search(created_between: search_attributes[:created_between]).
+        results
     end
-    
+
     def category
       ...
     end
-    
+
   end
 end
 ```
+**Note:** If you are combining search classes. Be sure to always call **results** method on the search classes composing your main search class.
+
+## Usage with Rails
+
+### Forms
+
+Define a custom form:
+
+```haml
+# app/views/products/_search.html.haml
+
+= form_tag products_path, method: :get do
+  = text_field_tag 'name'
+  = select_tag 'category', options_from_collection_for_select(@categories, 'id', 'name')
+  = date_field_tag 'created_between[start_date]'
+  = date_field_tag 'created_between[end_date]'
+  = submit_tag :search
+```
+
+### Controllers
+
+Create a new instance of your search class and pass a collection to which all search conditions will be applied and specify the search params you want to apply:
+
+```ruby
+# app/controllers/products_controller.rb
+
+class ProductsController < ApplicationController
+  def index
+    @products = ProductSearch.new(current_user.products).search(search_params)
+  end
+
+  protected
+    def search_params
+      params.permit(:name, :category, created_between: [:start_date, :end_date])
+    end
+end
+```
+### Views
+
+Loop through the search results on your view.
+
+```haml
+# app/views/products/index.html.haml
+
+%h1 Products
+
+%ul
+  - @products.each do |product|
+    %li
+      = "#{product.name} - #{product.price} - #{product.category}"
+```
 
 ## Testing
 
@@ -400,6 +459,42 @@ describe ProductSearch do
 end
 ```
 
+## Benchmarks
+
+I used [benchmark-ips](https://github.com/evanphx/benchmark-ips).
+
+### Lupa vs. [HasScope](https://github.com/plataformatec/has_scope)
+
+```
+Calculating -------------------------------------
+                lupa   265.000  i/100ms
+           has_scope   254.000  i/100ms
+-------------------------------------------------
+                lupa      3.526k (±24.7%) i/s -     67.045k
+           has_scope      3.252k (±24.8%) i/s -     61.976k
+
+Comparison:
+                lupa:     3525.8 i/s
+           has_scope:     3252.0 i/s - 1.08x slower
+```
+
+### Lupa vs. [Searchlight](https://github.com/nathanl/searchlight)
+
+```
+Calculating -------------------------------------
+                lupa   480.000  i/100ms
+         searchlight   232.000  i/100ms
+-------------------------------------------------
+                lupa      7.273k (±25.1%) i/s -    689.280k
+         searchlight      2.665k (±14.1%) i/s -    260.072k
+
+Comparison:
+                lupa:     7273.5 i/s
+         searchlight:     2665.4 i/s - 2.73x slower
+```
+
+*If you know about another gem that was not included on the benchmark, feel free to run the benchmarks and send a Pull Request.*
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/Rakefile

@@ -8,4 +8,4 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-
+task :default => :test

data/lib/lupa/scope_methods.rb

@@ -1,13 +1,90 @@
 module Lupa
+  # Internal module that provides common functionality to Scope classes.
+  # This module is automatically included in the Scope class defined within
+  # your search class.
+  #
+  # It provides access to two key attributes:
+  # - `scope`: The current scope being searched
+  # - `search_attributes`: The hash of search parameters
+  #
+  # @example Accessing scope and search_attributes in a Scope class
+  #   class ProductSearch < Lupa::Search
+  #     class Scope
+  #       # scope and search_attributes are available here
+  #       def name
+  #         # scope is the current ActiveRecord relation (or any chainable object)
+  #         scope.where('name LIKE ?', "%#{search_attributes[:name]}%")
+  #       end
+  #
+  #       def price_range
+  #         # search_attributes contains all search parameters
+  #         if search_attributes[:price_range]
+  #           scope.where(price: search_attributes[:price_range])
+  #         else
+  #           scope
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # @note This module is included automatically by Lupa and should not be
+  #   included manually in your code.
+  #
+  # @api private
+  # @since 0.1.0
   module ScopeMethods
-
+    # @!attribute [rw] scope
+    #   The current scope object that search methods will operate on.
+    #   This is typically an ActiveRecord::Relation or similar chainable object.
+    #   The scope is updated after each search method is called.
+    #
+    #   @return [Object] the current scope object
+    #
+    #   @example Accessing the scope in a search method
+    #     def category
+    #       # scope is the current state of the query chain
+    #       scope.where(category_id: search_attributes[:category])
+    #     end
     attr_accessor :scope
-    attr_reader   :search_attributes
 
+    # @!attribute [r] search_attributes
+    #   A hash containing all search attributes, including default search attributes.
+    #   All keys are symbolized automatically by Lupa.
+    #
+    #   @return [Hash] the search attributes hash with symbolized keys
+    #
+    #   @example Accessing search attributes in a scope method
+    #     def search_by_name
+    #       name = search_attributes[:name]
+    #       scope.where('name LIKE ?', "%#{name}%") if name.present?
+    #     end
+    #
+    #   @example With nested hash attributes
+    #     def created_between
+    #       start_date = search_attributes[:created_between][:start_date]
+    #       end_date = search_attributes[:created_between][:end_date]
+    #       scope.where(created_at: start_date..end_date)
+    #     end
+    attr_reader :search_attributes
+
+    # Initializes a new Scope instance with the given scope and search attributes.
+    # This method is called automatically by Lupa::Search and should not be called directly.
+    #
+    # @param scope [Object] the initial scope object to search on (e.g., ActiveRecord::Relation)
+    # @param search_attributes [Hash] the hash of search parameters with symbolized keys
+    #
+    # @return [ScopeMethods] the initialized scope instance
+    #
+    # @example Internal usage (automatically called by Lupa)
+    #   # This happens internally when you call:
+    #   ProductSearch.new(Product.all).search(name: 'chair')
+    #   # Lupa automatically calls:
+    #   ProductSearch::Scope.new(Product.all, { name: 'chair' })
+    #
+    # @api private
     def initialize(scope, search_attributes)
       @scope             = scope
       @search_attributes = search_attributes
     end
-
   end
 end