pursuit 0.4.5 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3de94df3d5b52d4c91443ae748a3abb79e64a46aee742af05d81f38dc3c050b6
-  data.tar.gz: c41d2d0a0498b08fa938046973bd459856253e78159e7f71256f0d33ce6b0c61
+  metadata.gz: 48b4becb7e8e0e0d39335cd5172fd4870989a9e26033a882e082480431330285
+  data.tar.gz: 33265eafe36113d7e4f263a6f9a2dc9fd7d12cfda95073c29ea0866f627e4566
 SHA512:
-  metadata.gz: 488e5ac1cf2b9d4368608d179134f16945450de39560c07671909c3dbdf2c736afe528ec0b319d9b673ff4f990272b3d9678c22a1748f64f8f526b35a7ff554c
-  data.tar.gz: 78178098bb90e01510d2bb741a7bc5994ea307d5e79fb47e45cf1e476a91a2cd1dc6df2b70423530a4a7aca93e29f1c3e16b6c80a03c3538158043b5330ff32d
+  metadata.gz: 01fba1c0d143f914d3a040620f618538f8e77396e7e9fa17f503a06ef6b419c2b9eb0a55950e60b16608d944535eb9a3bf70888615709d08f525938d25850bf6
+  data.tar.gz: b2d0106bc8ceea194d87f62dd8831c3cb4477c831c951f638038d6d94384ee91c64039891203783ee50a3bedf76672245641ba5206191b5350f72d46e1e462f3

data/.github/workflows/rubygem.yaml

@@ -0,0 +1,46 @@
+name: RubyGem
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+      - name: Setup RubyGems
+        run: |
+          bundle install
+      - name: RuboCop
+        run: |
+          bundle exec rubocop --parallel --format progress --format html --out rubocop-report.html
+      - name: Upload Report
+        uses: actions/upload-artifact@v3
+        with:
+          name: RuboCop Report
+          path: rubocop-report.html
+
+  rspec:
+    name: RSpec
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+      - name: Setup RubyGems
+        run: |
+          bundle install
+      - name: RSpec
+        run: |
+          bundle exec rspec --format progress --format html --out rspec-report.html
+      - name: Upload Report
+        uses: actions/upload-artifact@v3
+        with:
+          name: RSpec Report
+          path: rspec-report.html

data/Gemfile

@@ -4,16 +4,17 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'bundler', '~> 2.4'
-gem 'combustion', '~> 1.3'
-gem 'guard', '~> 2.18'
-gem 'guard-rspec', '~> 4.7'
-gem 'pry', '~> 0.14'
-gem 'rake', '~> 13.0'
-gem 'rspec', '~> 3.12'
-gem 'rspec-rails', '~> 6.0'
-gem 'rubocop', '~> 1.57'
-gem 'rubocop-rake', '~> 0.6'
-gem 'rubocop-rspec', '~> 2.25'
-gem 'sqlite3', '~> 1.6'
-gem 'yard', '~> 0.9'
+group :development do
+  gem 'combustion', '~> 1.3'
+  gem 'guard', '~> 2.18'
+  gem 'guard-rspec', '~> 4.7'
+  gem 'pry', '~> 0.14'
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.12'
+  gem 'rspec-rails', '~> 6.0'
+  gem 'rubocop', '~> 1.57'
+  gem 'rubocop-rake', '~> 0.6'
+  gem 'rubocop-rspec', '~> 2.25'
+  gem 'sqlite3', '~> 1.6'
+  gem 'yard', '~> 0.9'
+end

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    pursuit (0.4.5)
-      activerecord (>= 5.2.0, < 7.2.0)
-      activesupport (>= 5.2.0, < 7.2.0)
+    pursuit (1.0.1)
+      activerecord (>= 5.2.0, <= 8.0.0)
+      activesupport (>= 5.2.0, <= 8.0.0)
+      parslet (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -90,7 +91,7 @@ GEM
     minitest (5.20.0)
     mutex_m (0.1.2)
     nenv (0.3.0)
-    nokogiri (1.15.4-aarch64-linux)
+    nokogiri (1.15.4-arm-linux)
       racc (~> 1.4)
     nokogiri (1.15.4-arm64-darwin)
       racc (~> 1.4)
@@ -105,12 +106,13 @@ GEM
     parser (3.2.2.4)
       ast (~> 2.4.1)
       racc
+    parslet (2.0.0)
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
     psych (5.1.1.1)
       stringio
-    racc (1.7.1)
+    racc (1.7.2)
     rack (3.0.8)
     rack-session (2.0.0)
       rack (>= 3.0.0)
@@ -135,7 +137,7 @@ GEM
       thor (~> 1.0, >= 1.2.2)
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
-    rake (13.0.6)
+    rake (13.1.0)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
@@ -192,10 +194,10 @@ GEM
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
     shellany (0.0.1)
-    sqlite3 (1.6.7-aarch64-linux)
-    sqlite3 (1.6.7-arm64-darwin)
-    sqlite3 (1.6.7-x86_64-darwin)
-    sqlite3 (1.6.7-x86_64-linux)
+    sqlite3 (1.6.8-arm-linux)
+    sqlite3 (1.6.8-arm64-darwin)
+    sqlite3 (1.6.8-x86_64-darwin)
+    sqlite3 (1.6.8-x86_64-linux)
     stringio (3.0.8)
     thor (1.3.0)
     timeout (0.4.0)
@@ -207,13 +209,12 @@ GEM
     zeitwerk (2.6.12)
 
 PLATFORMS
-  aarch64-linux
   arm64-darwin-22
-  x86_64-darwin-21
+  arm64-linux
+  x86_64-darwin-22
   x86_64-linux
 
 DEPENDENCIES
-  bundler (~> 2.4)
   combustion (~> 1.3)
   guard (~> 2.18)
   guard-rspec (~> 4.7)

data/README.md

@@ -1,6 +1,6 @@
 # Pursuit
 
-Advanced key-based searching for ActiveRecord objects.
+Search your ActiveRecord objects with ease!
 
 ## Installation
 
@@ -16,41 +16,224 @@ gem 'pursuit'
 
 ### Usage
 
-You can use the convenient DSL syntax to declare which attributes and relationships are searchable:
+Pursuit comes with three different strategies for interpreting queries:
+
+- Simple
+- Term
+- Predicate
+
+### Simple Search
+
+Simple takes the entire query and generates a SQL `LIKE` (or `ILIKE` for *PostgreSQL*) statement for each attribute
+added to the search instance. Here's an example of how you might use simple to search a hypothetical `Product` record:
+
+```ruby
+search = Pursuit::SimpleSearch.new(Product.all)
+search.search_attribute(:title)
+search.search_attribute(:subtitle)
+search.apply('Green Shirt')
+```
+
+Which results in the following SQL query:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+WHERE
+  "products"."title" LIKE '%Green Shirt%'
+  OR "products"."subtitle" LIKE '%Green Shirt%'
+```
+
+The initializer method also accepts a block, which is evaluated within the instance's context. This can make it cleaner
+when declaring the searchable attributes:
+
+```ruby
+search = Pursuit::SimpleSearch.new(Product.all) do
+  search_attribute :title
+  search_attribute :subtitle
+end
+
+search.apply('Green Shirt')
+```
+
+You can also pass custom `Arel::Attribute::Attribute` objects, which are especially useful when using joins:
+
+```ruby
+search = Pursuit::SimpleSearch.new(
+  Product.left_outer_joins(:variations).group(:id)
+) do
+  search_attribute :title
+  search_attribute ProductVariation.arel_table[:title]
+end
+
+search.apply('Green Shirt')
+```
+
+Which results in the following SQL query:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+  LEFT OUTER JOIN "product_variations" ON "product_variations"."product_id" = "products"."id"
+WHERE
+  "products"."title" LIKE '%Green Shirt%'
+  OR "product_variations"."title" LIKE '%Green Shirt%'
+GROUP BY
+  "products"."id"
+```
+
+### Term Search
+
+Term searches break a query into individual terms on spaces, while providing double and single quoted strings as a
+means to include spaces. Here's an example of using term searches on the same `Product` record from earlier:
 
 ```ruby
-class Product < ActiveRecord::Base
-  searchable do |o|
-    o.relation :variations, :title, :stock_status
-
-    # Attributes can be used for both keyed and unkeyed searching by default, but you can pass either `keyed: false` or
-    # `unkeyed: false` to restrict when the attribute is searched.
-    o.attribute :title
-    o.attribute :description
-    o.attribute :rating, unkeyed: false
-
-    # You can shorten the search keyword by passing the desired search term first, and then the real attribute name
-    # as the second argument.
-    #  => "category*=shirts"
-    o.attribute :category, :category_id
-
-    # It's also possible to query entirely custom Arel nodes by passing a block which returns the Arel node to query.
-    # You could use this to query a person's full name by concatenating their first and last name columns, for example.
-    o.attribute :title_length, unkeyed: false do
-      Arel::Nodes::NamedFunction.new('LENGTH', [
-        arel_table[:title]
-      ])
-    end
-  end
+search = Pursuit::TermSearch.new(Product.all) do
+  search_attribute :title
+  search_attribute :subtitle
 end
+
+search.apply('Green "Luxury Shirt"')
+```
+
+Which results in a SQL query similar to the following:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+WHERE
+  (
+    "products"."title" LIKE '%Green%'
+    OR "products"."subtitle" LIKE '%Green%'
+  ) AND (
+    "products"."title" LIKE '%Luxury Shirt%'
+    OR "products"."subtitle" LIKE '%Luxury Shirt%'
+  )
 ```
 
-This creates a ```.search``` method on your record class which accepts a single query argument:
+### Predicate Search
+
+Predicate searches use a parser (implemented with the `parslet` gem) to provide a minimal query language.
+This syntax is similar to the `WHERE` and `HAVING` clauses in SQL, but uses only symbols for operators and joins.
+
+Attributes can only be used in predicate searches when they have been added to the list of permitted attributes.
+You can also rename attributes, and add attributes for joined records.
+
+Here's a more complex example of using predicate-based searches with joins on the `Product` record from earlier:
 
 ```ruby
-Product.search('plain shirt rating>=3')
+search = Pursuit::PredicateSearch.new(
+  Product.left_outer_join(:category, :variations).group(:id)
+) do
+  # Product Attributes
+  permit_attribute :title
+
+  # Product Category Attributes
+  permit_attribute :category_name, ProductCategory.arel_table[:name]
+
+  # Product Variation Attributes
+  permit_attribute :variation_title, ProductVariation.arel_table[:title]
+  permit_attribute :variation_currency, ProductVariation.arel_table[:currency]
+  permit_attribute :variation_amount, ProductVariation.arel_table[:amount]
+end
+
+search.apply('title = "Luxury Shirt" & (variation_amount = 0 | variation_amount > 1000)')
+```
+
+This translates to "a product whose title is 'Luxury Shirt' and has at least one variation with either an amount of 0,
+or an amount greater than 1000", which could be expressed in SQL as:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+  LEFT OUTER JOIN "product_categories" ON "product_categories"."id" = "products"."category_id"
+  LEFT OUTER JOIN "product_variations" ON "product_variations"."product_id" = "products"."id"
+WHERE
+  "products"."title" = 'Luxury Shirt'
+  AND (
+    "product_variations"."amount" = 0
+    OR "product_variations"."amount" > 1000
+  )
+GROUP BY
+  "products"."id"
 ```
 
+You can use any of the following operators in comparisons:
+
+- `=` checks if the attribute is equal to the value.
+- `!=` checks if the attributes is not equal to the value.
+- `>` checks if the attribute is greater than the value.
+- `<` checks if the attribute is less than the value.
+- `>=` checks if the attribute is greater than or equal to the value.
+- `<=` checks if the attribute is less than or equal to the value.
+- `~` checks if the attribute matches the value (using `LIKE` or `ILIKE`).
+- `!~` checks if the attribute does not match the value (using `LIKE` or `ILIKE`).
+
+Predicate searches also support "aggregate modifiers" which enable the use of aggregate functions, however this feature
+must be explicitly enabled and requires you to use a `GROUP BY` clause:
+
+```ruby
+search = Pursuit::PredicateSearch.new(
+  Product.left_outer_join(:category, :variations).group(:id)
+) do
+  # Product Attributes
+  permit_attribute :title
+
+  # Product Category Attributes
+  permit_attribute :category, ProductCategory.arel_table[:id]
+  permit_attribute :category_name, ProductCategory.arel_table[:name]
+
+  # Product Variation Attributes
+  permit_attribute :variation, ProductVariation.arel_table[:id]
+  permit_attribute :variation_title, ProductVariation.arel_table[:title]
+  permit_attribute :variation_currency, ProductVariation.arel_table[:currency]
+  permit_attribute :variation_amount, ProductVariation.arel_table[:amount]
+end
+
+search.apply('title = "Luxury Shirt" & #variation > 5')
+```
+
+And the resulting SQL from this query:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+  LEFT OUTER JOIN "product_categories" ON "product_categories"."id" = "products"."category_id"
+  LEFT OUTER JOIN "product_variations" ON "product_variations"."product_id" = "products"."id"
+WHERE
+  "products"."title" = 'Luxury Shirt'
+GROUP BY
+  "products"."id"
+HAVING
+  COUNT("product_variations"."id") > 5
+```
+
+There's no distinction between the `WHERE` and `HAVING` clause in the predicate syntax, as it's intended to be easy to
+use, but this does come with a caveat.
+
+The query must have all aggregate-modified comparisons before or after non-aggregate-modified comparisons, you can't
+mix both.
+
+For example, this query would result in a parsing error: `title ~ Shirt & #variation > 5 & category_name = Shirts`
+
+You can preceed any attribute with one of these aggregate modifier symbols:
+
+- `#` uses the `COUNT` aggregate function
+- `+` uses the `MAX` aggregate function
+- `-` uses the `MIN` aggregate function
+- `*` uses the `SUM` aggregate function
+- `~` uses the `AVG` aggregate function
+
 ## Development
 
 After checking out the repo, run `bundle exec rake spec` to run the tests.

data/bin/console

@@ -1,7 +1,17 @@
 #!/usr/bin/env ruby
 
+# frozen_string_literal: true
+
 require 'bundler/setup'
 require 'pursuit'
 require 'pry'
 
+if ENV['AR'] == 'true'
+  require 'combustion'
+  Combustion.initialize!(:active_record)
+
+  require 'bundler'
+  Bundler.require(:default, :development)
+end
+
 Pry.start

data/lib/pursuit/aggregate_modifier_not_found.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an aggregate modifier cannot be found.
+  #
+  class AggregateModifierNotFound < QueryError
+    # @return [String] The aggregate modifier which does not map to an aggregate function.
+    #
+    attr_reader :aggregate_modifier
+
+    # Creates a new error instance.
+    #
+    # @param aggregate_modifier [Symbol] The aggregate modifier which does not map to an aggregate function.
+    #
+    def initialize(aggregate_modifier)
+      @aggregate_modifier = aggregate_modifier
+      super("#{aggregate_modifier} is not a valid aggregate modifier")
+    end
+  end
+end

data/lib/pursuit/aggregate_modifier_required.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an attribute that must be used with an aggregate modifier is used without one.
+  #
+  class AggregateModifierRequired < QueryError
+    # @return [Symbol] The name of the attribute which must be used with an aggregate modifier.
+    #
+    attr_reader :attribute
+
+    # Creates a new error instance.
+    #
+    # @param attribute [Symbol] The name of the attribute which must be used with an aggregate modifier.
+    #
+    def initialize(attribute)
+      @attribute = attribute
+      super("'#{attribute}' must be used with an aggregate modifier")
+    end
+  end
+end

data/lib/pursuit/aggregate_modifiers_not_available.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an aggregate modifier is used in a query, but aggregate modifiers are not available.
+  #
+  class AggregateModifiersNotAvailable < QueryError
+    # Creates a new error instance.
+    #
+    def initialize
+      super('Aggregate modifiers cannot be used in this query')
+    end
+  end
+end

data/lib/pursuit/attribute_not_found.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an attribute cannot be found.
+  #
+  class AttributeNotFound < QueryError
+    # @return [Symbol] The name of the attribute which could not be found.
+    #
+    attr_reader :attribute
+
+    # Creates a new error instance.
+    #
+    # @param attribute [Symbol] The name of the attribute which could not be found.
+    #
+    def initialize(attribute)
+      @attribute = attribute
+      super("'#{attribute}' is not a valid attribute")
+    end
+  end
+end

data/lib/pursuit/constants.rb

@@ -3,5 +3,5 @@
 module Pursuit
   # @return [String] The gem's semantic version number.
   #
-  VERSION = '0.4.5'
+  VERSION = '1.0.1'
 end

data/lib/pursuit/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Base error class for all pursuit errors.
+  #
+  class Error < StandardError; end
+end