pursuit 1.0.1 → 1.1.1

data/README.md

@@ -6,7 +6,9 @@ Search your ActiveRecord objects with ease!
 
 You can install **Pursuit** using the following command:
 
-  $ gem install pursuit
+```sh
+$ gem install pursuit
+```
 
 Or, by adding the following to your `Gemfile`:
 
@@ -28,10 +30,10 @@ Simple takes the entire query and generates a SQL `LIKE` (or `ILIKE` for *Postgr
 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 = Pursuit::SimpleSearch.new(default_table: Product.arel_table)
 search.search_attribute(:title)
 search.search_attribute(:subtitle)
-search.apply('Green Shirt')
+search.apply('Green Shirt', Product.all)
 ```
 
 Which results in the following SQL query:
@@ -50,25 +52,23 @@ The initializer method also accepts a block, which is evaluated within the insta
 when declaring the searchable attributes:
 
 ```ruby
-search = Pursuit::SimpleSearch.new(Product.all) do
+search = Pursuit::SimpleSearch.new(default_table: Product.arel_table) do
   search_attribute :title
   search_attribute :subtitle
 end
 
-search.apply('Green Shirt')
+search.apply('Green Shirt', Product.all)
 ```
 
 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 = Pursuit::SimpleSearch.new(default_table: Product.arel_table) do
   search_attribute :title
   search_attribute ProductVariation.arel_table[:title]
 end
 
-search.apply('Green Shirt')
+search.apply('Green Shirt', Product.left_outer_joins(:variations).group(:id))
 ```
 
 Which results in the following SQL query:
@@ -92,12 +92,12 @@ Term searches break a query into individual terms on spaces, while providing dou
 means to include spaces. Here's an example of using term searches on the same `Product` record from earlier:
 
 ```ruby
-search = Pursuit::TermSearch.new(Product.all) do
+search = Pursuit::TermSearch.new(default_table: Product.arel_table) do
   search_attribute :title
   search_attribute :subtitle
 end
 
-search.apply('Green "Luxury Shirt"')
+search.apply('Green "Luxury Shirt"', Product.all)
 ```
 
 Which results in a SQL query similar to the following:
@@ -128,9 +128,7 @@ 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
-search = Pursuit::PredicateSearch.new(
-  Product.left_outer_join(:category, :variations).group(:id)
-) do
+search = Pursuit::PredicateSearch.new(default_table: Product.arel_table) do
   # Product Attributes
   permit_attribute :title
 
@@ -143,7 +141,10 @@ search = Pursuit::PredicateSearch.new(
   permit_attribute :variation_amount, ProductVariation.arel_table[:amount]
 end
 
-search.apply('title = "Luxury Shirt" & (variation_amount = 0 | variation_amount > 1000)')
+search.apply(
+  'title = "Luxury Shirt" & (variation_amount = 0 | variation_amount > 1000)',
+  Product.left_outer_join(:category, :variations).group(:id)
+)
 ```
 
 This translates to "a product whose title is 'Luxury Shirt' and has at least one variation with either an amount of 0,
@@ -181,9 +182,7 @@ Predicate searches also support "aggregate modifiers" which enable the use of ag
 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
+search = Pursuit::PredicateSearch.new(default_table: Product.arel_table, permit_aggregate_modifiers: true) do
   # Product Attributes
   permit_attribute :title
 
@@ -198,7 +197,10 @@ search = Pursuit::PredicateSearch.new(
   permit_attribute :variation_amount, ProductVariation.arel_table[:amount]
 end
 
-search.apply('title = "Luxury Shirt" & #variation > 5')
+search.apply(
+  'title = "Luxury Shirt" & #variation > 5',
+  Product.left_outer_join(:category, :variations).group(:id)
+)
 ```
 
 And the resulting SQL from this query:

data/lib/pursuit/constants.rb

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

data/lib/pursuit/predicate_parser.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 module Pursuit
-  # Parser for predicate-based queries.
+  # Parser for predicate queries.
   #
-  # Predicate-based queries take an attribute to compare the value of, an operator (such as the equal sign), and the
-  # value to compare with.
+  # Predicate queries take an attribute, an operator (such as the equal sign), and a value to compare with.
   #
   # For example, to search for records where the `first_name` attribute is equal to "John" and the `last_name`
-  # attribute contains either "Doe" or "Smith", you would enter:
+  # attribute contains either "Doe" or "Smith", you might use:
+  #
   # => "first_name = John & (last_name ~ Doe | last_name ~ Smith)"
   #
   class PredicateParser < Parslet::Parser

data/lib/pursuit/predicate_search.rb

@@ -1,29 +1,33 @@
 # frozen_string_literal: true
 
 module Pursuit
-  # :nodoc:
+  # Provides an interface for declaring which attributes can be used in a predicate query, and a method for applying
+  # a predicate query to an `ActiveRecord::Relation` instance.
+  #
+  # @see Pursuit::PredicateParser
+  # @see Pursuit::PredicateTransform
   #
   class PredicateSearch
-    # @return [Boolean] `true` when aggregate modifiers can be used in queries, `false` otherwise.
+    # @return [Arel::Table] The default table to retrieve attributes from.
     #
-    attr_accessor :permit_aggregate_modifiers
+    attr_accessor :default_table
 
-    # @return [Hash<Symbol, Arel::Attributes::Attribute>] The attributes permitted for use in queries.
+    # @return [Boolean] `true` when aggregate modifiers can be used, `false` otherwise.
     #
-    attr_reader :permitted_attributes
+    attr_accessor :permit_aggregate_modifiers
 
-    # @return [ActiveRecord::Relation] The relation to which the predicate clauses are added.
+    # @return [Hash<Symbol, Arel::Attributes::Attribute>] The attributes permitted for use in queries.
     #
-    attr_reader :relation
+    attr_accessor :permitted_attributes
 
     # Creates a new predicate search instance.
     #
-    # @param relation                   [ActiveRecord::Relation] The relation to which the predicate clauses are added.
-    # @param permit_aggregate_modifiers [Boolean]                Whether aggregate modifiers can be used or not.
-    # @param block                      [Proc]                   The proc to invoke in the search instance (optional).
+    # @param default_table              [Arel::Table] The default table to retrieve attributes from.
+    # @param permit_aggregate_modifiers [Boolean]     `true` when aggregate modifiers can be used, `false` otherwise.
+    # @param block                      [Proc]        The proc to invoke in the search instance (optional).
     #
-    def initialize(relation, permit_aggregate_modifiers: false, &block)
-      @relation = relation
+    def initialize(default_table: nil, permit_aggregate_modifiers: false, &block)
+      @default_table = default_table
       @permit_aggregate_modifiers = permit_aggregate_modifiers
       @permitted_attributes = HashWithIndifferentAccess.new
 
@@ -49,8 +53,8 @@ module Pursuit
     # @return           [Arel::Attributes::Attribute]         The underlying attribute to query.
     #
     def permit_attribute(name, attribute = nil)
-      attribute = relation.klass.arel_table[attribute] if attribute.is_a?(Symbol)
-      permitted_attributes[name] = attribute || relation.klass.arel_table[name]
+      attribute = default_table[attribute] if attribute.is_a?(Symbol)
+      permitted_attributes[name] = attribute || default_table[name]
     end
 
     # Parse a predicate query into ARel nodes.
@@ -59,22 +63,21 @@ module Pursuit
     # @return       [Hash<Symbol, Arel::Nodes::Node>] The ARel nodes representing the predicate query.
     #
     def parse(query)
-      tree = parser.parse(query)
       transform.apply(
-        tree,
-        permitted_attributes: permitted_attributes,
-        permit_aggregate_modifiers: permit_aggregate_modifiers
+        parser.parse(query),
+        permit_aggregate_modifiers: permit_aggregate_modifiers,
+        permitted_attributes: permitted_attributes
       )
     end
 
-    # Returns #relation filtered by the predicate query.
+    # Applies the predicate clauses derived from `query` to `relation`.
     #
-    # @param  query [String]                 The predicate query.
-    # @return       [ActiveRecord::Relation] The updated relation with the predicate clauses added.
+    # @param  query    [String]                 The predicate query.
+    # @param  relation [ActiveRecord::Relation] The base relation to apply the predicate clauses to.
+    # @return          [ActiveRecord::Relation] The base relation with the predicate clauses applied.
     #
-    def apply(query)
+    def apply(query, relation)
       nodes = parse(query)
-      relation = self.relation
       relation = relation.where(nodes[:where]) if nodes[:where]
       relation = relation.having(nodes[:having]) if nodes[:having]
       relation

data/lib/pursuit/predicate_transform.rb

@@ -162,7 +162,7 @@ module Pursuit
         attribute_name = context[:attribute].to_sym
         attribute = context.dig(:permitted_attributes, attribute_name)
         raise AttributeNotFound, attribute_name if attribute.blank?
-        raise AggregateModifierRequired, attribute_name if attribute.name == Arel.star
+        raise AggregateModifierRequired, attribute_name if attribute.respond_to?(:name) && attribute.name == Arel.star
 
         attribute
       end

data/lib/pursuit/simple_search.rb

@@ -1,25 +1,26 @@
 # frozen_string_literal: true
 
 module Pursuit
-  # :nodoc:
+  # Provides an interface for declaring which attributes should be searched in a simple query, and a method for applying
+  # a simple query to an `ActiveRecord::Relation` instance.
   #
   class SimpleSearch
     # @return [Set<Arel::Attributes::Attribute>] The attributes to match against.
     #
-    attr_reader :attributes
+    attr_accessor :attributes
 
-    # @return [ActiveRecord::Relation] The relation to which the clauses are added.
+    # @return [Arel::Table] The default table to retrieve attributes from.
     #
-    attr_reader :relation
+    attr_accessor :default_table
 
     # Creates a new simple search instance.
     #
-    # @param relation [ActiveRecord::Relation] The relation to which the clauses are added.
-    # @param block    [Proc]                   The proc to invoke in the search instance (optional).
+    # @param default_table [Arel::Table] The default table to retrieve attributes from.
+    # @param block         [Proc]        The proc to invoke in the search instance (optional).
     #
-    def initialize(relation, &block)
+    def initialize(default_table: nil, &block)
       @attributes = Set.new
-      @relation = relation
+      @default_table = default_table
 
       instance_eval(&block) if block
     end
@@ -30,7 +31,7 @@ module Pursuit
     # @return           [Arel::Attributes::Attribute]         The underlying attribute to query.
     #
     def search_attribute(attribute)
-      attribute = relation.klass.arel_table[attribute] if attribute.is_a?(Symbol)
+      attribute = default_table[attribute] if attribute.is_a?(Symbol)
       attributes.add(attribute)
     end
 
@@ -51,12 +52,13 @@ module Pursuit
       end
     end
 
-    # Returns #relation filtered by the query.
+    # Applies the simple clauses derived from `query` to `relation`.
     #
-    # @param  query [String]                 The simple query.
-    # @return       [ActiveRecord::Relation] The updated relation with the clauses added.
+    # @param  query    [String]                 The simple query.
+    # @param  relation [ActiveRecord::Relation] The base relation to apply the simple clauses to.
+    # @return          [ActiveRecord::Relation] The base relation with the simple clauses applied.
     #
-    def apply(query)
+    def apply(query, relation)
       node = parse(query)
       node ? relation.where(node) : relation.none
     end

data/lib/pursuit/term_search.rb

@@ -1,25 +1,29 @@
 # frozen_string_literal: true
 
 module Pursuit
-  # :nodoc:
+  # Provides an interface for declaring which attributes should be searched in a term query, and a method for applying
+  # a term query to an `ActiveRecord::Relation` instance.
+  #
+  # @see Pursuit::TermParser
+  # @see Pursuit::TermTransform
   #
   class TermSearch
     # @return [Set<Arel::Attributes::Attribute>] The attributes to match against.
     #
-    attr_reader :attributes
+    attr_accessor :attributes
 
-    # @return [ActiveRecord::Relation] The relation to which the term clauses are added.
+    # @return [Arel::Table] The default table to retrieve attributes from.
     #
-    attr_reader :relation
+    attr_accessor :default_table
 
     # Creates a new term search instance.
     #
-    # @param relation [ActiveRecord::Relation] The relation to which the term clauses are added.
-    # @param block    [Proc]                   The proc to invoke in the search instance (optional).
+    # @param default_table [Arel::Table] The default table to retrieve attributes from.
+    # @param block         [Proc]        The proc to invoke in the search instance (optional).
     #
-    def initialize(relation, &block)
+    def initialize(default_table: nil, &block)
       @attributes = Set.new
-      @relation = relation
+      @default_table = default_table
 
       instance_eval(&block) if block
     end
@@ -42,7 +46,7 @@ module Pursuit
     # @return           [Arel::Attributes::Attribute]         The underlying attribute to query.
     #
     def search_attribute(attribute)
-      attribute = relation.klass.arel_table[attribute] if attribute.is_a?(Symbol)
+      attribute = default_table[attribute] if attribute.is_a?(Symbol)
       attributes.add(attribute)
     end
 
@@ -56,12 +60,13 @@ module Pursuit
       transform.apply(tree, attributes: attributes)
     end
 
-    # Returns #relation filtered by the term query.
+    # Applies the term clauses derived from `query` to `relation`.
     #
-    # @param  query [String]                 The term query.
-    # @return       [ActiveRecord::Relation] The updated relation with the term clauses added.
+    # @param  query    [String]                 The term query.
+    # @param  relation [ActiveRecord::Relation] The base relation to apply the term clauses to.
+    # @return          [ActiveRecord::Relation] The base relation with the term clauses applied.
     #
-    def apply(query)
+    def apply(query, relation)
       node = parse(query)
       node ? relation.where(node) : relation.none
     end

data/pursuit.gemspec

@@ -6,16 +6,16 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'pursuit/constants'
 
 Gem::Specification.new do |spec|
-  spec.name          = 'pursuit'
-  spec.version       = Pursuit::VERSION
-  spec.authors       = ['Nialto Services']
-  spec.email         = ['support@nialtoservices.co.uk']
+  spec.name = 'pursuit'
+  spec.version = Pursuit::VERSION
+  spec.authors = ['Nialto Services']
+  spec.email = ['support@nialtoservices.co.uk']
 
-  spec.summary       = 'Advanced key-based searching for ActiveRecord objects.'
-  spec.homepage      = 'https://github.com/NialtoServices/pursuit'
-  spec.license       = 'Apache-2.0'
+  spec.summary = 'Advanced key-based searching for ActiveRecord objects.'
+  spec.homepage = 'https://github.com/NialtoServices/pursuit'
+  spec.license = 'Apache-2.0'
 
-  spec.files         = `git ls-files -z`.split("\x0")
+  spec.files = `git ls-files -z`.split("\x0")
   spec.require_paths = ['lib']
 
   spec.required_ruby_version = '>= 2.6.0'
@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.metadata['rubygems_mfa_required'] = 'true'
   spec.metadata['yard.run'] = 'yri'
 
-  spec.add_runtime_dependency 'activerecord',  '>= 5.2.0', '<= 8.0.0'
-  spec.add_runtime_dependency 'activesupport', '>= 5.2.0', '<= 8.0.0'
-  spec.add_runtime_dependency 'parslet',       '~> 2.0'
+  spec.add_dependency 'activerecord', '>= 5.2.0', '<= 8.0.0'
+  spec.add_dependency 'activesupport', '>= 5.2.0', '<= 8.0.0'
+  spec.add_dependency 'parslet', '~> 2.0'
 end

data/spec/internal/app/models/product.rb

@@ -1,38 +1,11 @@
 # frozen_string_literal: true
 
 class Product < ApplicationRecord
+  include ProductSearch
+
   belongs_to :category, class_name: 'ProductCategory', inverse_of: :products, optional: true
 
   has_many :variations, class_name: 'ProductVariation', inverse_of: :product
 
   validates :title, presence: true
-
-  def self.predicate_search
-    @predicate_search ||= Pursuit::PredicateSearch.new(
-      left_outer_joins(:category, :variations).group(:id).order(:title)
-    ) do
-      permit_attribute :title
-      permit_attribute :category, ProductCategory.arel_table[:id]
-      permit_attribute :category_name, ProductCategory.arel_table[:name]
-      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
-  end
-
-  def self.term_search
-    @term_search ||= Pursuit::TermSearch.new(
-      left_outer_joins(:category).group(:id).order(:title)
-    ) do
-      search_attribute :title
-      search_attribute ProductCategory.arel_table[:name]
-    end
-  end
-
-  def self.search(query)
-    predicate_search.apply(query)
-  rescue Parslet::ParseFailed
-    term_search.apply(query)
-  end
 end

data/spec/internal/app/models/product_category.rb

@@ -1,29 +1,9 @@
 # frozen_string_literal: true
 
 class ProductCategory < ApplicationRecord
+  include ProductCategorySearch
+
   has_many :products, class_name: 'Product', foreign_key: :category_id, inverse_of: :category, dependent: :nullify
 
   validates :name, presence: true
-
-  def self.predicate_search
-    @predicate_search ||= Pursuit::PredicateSearch.new(
-      left_outer_joins(:products).group(:id)
-    ) do
-      permit_attribute :name
-      permit_attribute :product, Product.arel_table[:id]
-      permit_attribute :product_title, Product.arel_table[:title]
-    end
-  end
-
-  def self.term_search
-    @term_search ||= Pursuit::TermSearch.new(all) do
-      search_attribute :name
-    end
-  end
-
-  def self.search(query)
-    predicate_search.apply(query)
-  rescue Parslet::ParseFailed
-    term_search.apply(query)
-  end
 end

data/spec/internal/app/models/product_variation.rb

@@ -1,37 +1,18 @@
 # frozen_string_literal: true
 
 class ProductVariation < ApplicationRecord
+  include ProductVariationSearch
+
   belongs_to :product
 
-  enum stock_status: { in_stock: 1, low_stock: 2, out_of_stock: 3 }
+  if Gem::Version.new(Rails.version) >= Gem::Version.new('7.0.0')
+    enum :stock_status, { in_stock: 1, low_stock: 2, out_of_stock: 3 }
+  else
+    enum stock_status: { in_stock: 1, low_stock: 2, out_of_stock: 3 }
+  end
 
   validates :title, presence: true
 
   validates :currency, presence: true
   validates :amount, presence: true, numericality: true
-
-  def self.predicate_search
-    @predicate_search ||= Pursuit::PredicateSearch.new(
-      left_outer_joins(:product).group(:id)
-    ) do
-      permit_attribute :title
-      permit_attribute :stock_status
-      permit_attribute :currency
-      permit_attribute :amount
-      permit_attribute :product, Product.arel_table[:id]
-      permit_attribute :product_title, Product.arel_table[:title]
-    end
-  end
-
-  def self.term_search
-    @term_search ||= Pursuit::TermSearch.new(all) do
-      search_attribute :title
-    end
-  end
-
-  def self.search(query)
-    predicate_search.apply(query)
-  rescue Parslet::ParseFailed
-    term_search.apply(query)
-  end
 end

data/spec/internal/app/searches/product_category_search.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ProductCategorySearch
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Search for records matching the specified predicate.
+    #
+    # @param  query [String]                 The query with a predicate.
+    # @return       [ActiveRecord::Relation] The current relation filtered by the predicate.
+    #
+    def predicate_search(query)
+      @predicate_search ||= Pursuit::PredicateSearch.new(default_table: arel_table) do
+        permit_attribute :name
+        permit_attribute :product, Product.arel_table[:id]
+        permit_attribute :product_title, Product.arel_table[:title]
+      end
+
+      @predicate_search.apply(query, left_outer_joins(:products).group(:id))
+    end
+
+    # Search for records matching the specified terms.
+    #
+    # @param  query [String]                 The query with one or more terms.
+    # @return       [ActiveRecord::Relation] The current relation filtered by the terms.
+    #
+    def term_search(query)
+      @term_search ||= Pursuit::TermSearch.new(default_table: arel_table) do
+        search_attribute :name
+      end
+
+      # Note that we're using `all` here, but this still works when used in a chain:
+      # => ProductVariation.where(stock_status: :in_stock).search('Green')
+      @term_search.apply(query, all)
+    end
+
+    # Search for records matching the specified query.
+    #
+    # @param  query [String]                 The query.
+    # @return       [ActiveRecord::Relation] The current relation filtered by the query.
+    #
+    def search(query)
+      return none if query.blank?
+
+      predicate_search(query)
+    rescue Parslet::ParseFailed
+      term_search(query)
+    end
+  end
+end

data/spec/internal/app/searches/product_search.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ProductSearch
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Search for records matching the specified predicate.
+    #
+    # @param  query [String]                 The query with a predicate.
+    # @return       [ActiveRecord::Relation] The current relation filtered by the predicate.
+    #
+    def predicate_search(query)
+      @predicate_search ||= Pursuit::PredicateSearch.new(default_table: arel_table) do
+        permit_attribute :title
+        permit_attribute :category, ProductCategory.arel_table[:id]
+        permit_attribute :category_name, ProductCategory.arel_table[:name]
+        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
+
+      @predicate_search.apply(query, left_outer_joins(:category, :variations).group(:id).order(:title))
+    end
+
+    # Search for records matching the specified terms.
+    #
+    # @param  query [String]                 The query with one or more terms.
+    # @return       [ActiveRecord::Relation] The current relation filtered by the terms.
+    #
+    def term_search(query)
+      @term_search ||= Pursuit::TermSearch.new(default_table: arel_table) do
+        search_attribute :title
+        search_attribute ProductCategory.arel_table[:name]
+      end
+
+      @term_search.apply(query, left_outer_joins(:category).group(:id).order(:title))
+    end
+
+    # Search for records matching the specified query.
+    #
+    # @param  query [String]                 The query.
+    # @return       [ActiveRecord::Relation] The current relation filtered by the query.
+    #
+    def search(query)
+      return none if query.blank?
+
+      predicate_search(query)
+    rescue Parslet::ParseFailed
+      term_search(query)
+    end
+  end
+end