lupa 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 46daf9ac53354ecc21016d968c78de4d322a1bb5
-  data.tar.gz: 62c8cde8889723041b1d622ed2bc1bec5f784ff6
+SHA256:
+  metadata.gz: d6c3063e519871ee2848d6202a6388482747e7e2668f04122036e3a5ae8dd1fa
+  data.tar.gz: 7cb6850bb59992671ac66d19ef3179bb7c400dae6d39faaa7cbe5bfbdb837643
 SHA512:
-  metadata.gz: 010ba896da1a30da488d2726646616ca4e1c7091dd5907ae20150756af248b8173266e4b68f501470c35cbf12d933f0f6f530b8943920b2b0f874bff9a782599
-  data.tar.gz: 36a3ac1ee305f13318d990f250a40b97ab5f6cb90661c1e546ca4f0b0218e746a05d321d7069944ba100c484e8343125ccb2a8123cc2b15b46e9539e918168e1
+  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/CHANGELOG.md

@@ -1,4 +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.
+    * A **Lupa::DefaultSearchAttributesError** exception will be raised if `default_search_attributes` does not return a hash.

data/README.md

@@ -2,28 +2,31 @@
 
 Lupa means *Magnifier* in spanish.
 
-[![Build Status](https://travis-ci.org/edelpero/lupa.svg?branch=master)](https://travis-ci.org/edelpero/lupa) [![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)
+[![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)
 
 Lupa lets you create simple, robust and scaleable search filters with ease using regular Ruby classes and object oriented design patterns.
 
-Lupa it's Framework and ORM agnostic. It will work with any ORM or Object that can build a query using **chained method calls**, like ActiveRecord: `
+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)`.
 
 **Table of Contents:**
 
-* [Search Class](https://github.com/edelpero/lupa#search-class)
-    * [Overview](https://github.com/edelpero/lupa#overview)
-    * [Definition](https://github.com/edelpero/lupa#definition)
-    * [Public Methods](https://github.com/edelpero/lupa#public-methods)
-    * [Default Search Scope](https://github.com/edelpero/lupa#default-search-scope)
-    * [Default Search Attributes](https://github.com/edelpero/lupa#default-search-attributes)
-    * [Combining Search Classes](https://github.com/edelpero/lupa#combining-search-classes)
-* [Usage with Rails](https://github.com/edelpero/lupa#usage-with-rails)
-* [Testing](https://github.com/edelpero/lupa#testing)
-    * [Testing Default Scope](https://github.com/edelpero/lupa#testing-default-scope)
-    * [Testing Default Search Attributes](https://github.com/edelpero/lupa#testing-default-search-attributes)
-    * [Testing Each Scope Method Individually](https://github.com/edelpero/lupa#testing-each-scope-method-individually)
-* [Installation](https://github.com/edelpero/lupa#installation)
+* [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)
 
 
 ## Search Class
@@ -49,9 +52,7 @@ class ProductSearch < Lupa::Search
 
     # Search method
     def name
-      if search_attributes[:name].present?
-        scope.where('name iLIKE ?', "%#{search_attributes[:name]}%")
-      end
+      scope.where('name iLIKE ?', "%#{search_attributes[:name]}%")
     end
 
     # Search method
@@ -90,16 +91,7 @@ class ProductSearch < Lupa::Search
 
     # 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
@@ -107,16 +99,6 @@ class ProductSearch < Lupa::Search
       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
 ```
@@ -179,7 +161,7 @@ class ProductSearch < Lupa::Search
   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
@@ -209,17 +191,25 @@ class ProductSearch < Lupa::Search
 
   # 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
@@ -250,12 +240,16 @@ class CreatedAtSearch < Lupa::Search
 
     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
@@ -273,11 +267,13 @@ class ProductSearch < Lupa::Search
       ...
     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
@@ -287,6 +283,7 @@ class ProductSearch < Lupa::Search
   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
 
@@ -323,7 +320,9 @@ class ProductsController < ApplicationController
     end
 end
 ```
-- Loop through the search results on your view.
+### Views
+
+Loop through the search results on your view.
 
 ```haml
 # app/views/products/index.html.haml
@@ -460,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/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