pursuit 0.1.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d982a8b67d1a828b2e19e01e3477364bb607fa1fe51ef9d4ac1542a335e319
-  data.tar.gz: 6a552d6af9ca41bbdc6b4df6cfcfd3cdd3f06c6a4163e8879289cfcef6679fc5
+  metadata.gz: 5cf47bc77d2ccf93d20d66ee529c6554a995ee612e3135f90fd7d437f0fa5b08
+  data.tar.gz: 8ac3ace51a32566144c34cbe9ebb33d0c8327327f8ce1d2d8ae120c079a494f8
 SHA512:
-  metadata.gz: 9b56dd56e67e489faee6f2ba58acd4d68ae75e989cce1cad2a8e578ad830e93cf346168282400d57fc0936029fc93916115bc46dadece9ca1ee7e9c36981981c
-  data.tar.gz: cbd230e5840c4ed85041dc7463fbf8867bed55d1c114a78b6ca3d65c429350bc1bd3f52044fe7658bad26acc1f93f145f6a0c228ff82bb3d4d64f5d742871294
+  metadata.gz: 184fd8c2520cedd0c3ac45e83e4040295de141065419ee676ea159d8a419222a9bac51a950d6e0decb0e7106f8a3839d76f1a3144786647db528b9115d10bb9b
+  data.tar.gz: 65462af7fb13f713f4680845ba297bf659d230d9285b89b2b4c1de1bde2a64402a022c7929298d022f2a9b7a8fa1f4e0bbb7e569fb88cba99e39c01db17f244d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pursuit (0.1.1)
+    pursuit (0.3.2)
       activerecord (>= 5.2.0, < 6.2.0)
       activesupport (>= 5.2.0, < 6.2.0)
 

data/README.md

@@ -20,9 +20,28 @@ You can use the convenient DSL syntax to declare which attributes and relationsh
 
 ```ruby
 class Product < ActiveRecord::Base
-  has_search relationships: { variations: %i[title] },
-             keyed_attributes: %i[title description rating],
-             unkeyed_attributes: %i[title description]
+  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
 end
 ```
 

data/lib/pursuit/constants.rb

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

data/lib/pursuit/dsl.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pursuit
+  module DSL
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def searchable(&block)
+        if respond_to?(:search_options) || respond_to?(:search)
+          raise "#{self} already has #search and #search_options defined."
+        end
+
+        options = SearchOptions.new(self, &block)
+
+        define_singleton_method(:search_options) do
+          options
+        end
+
+        define_singleton_method(:search) do |query|
+          search = Pursuit::Search.new(options)
+          search.perform(query)
+        end
+      end
+    end
+  end
+end

data/lib/pursuit/railtie.rb

@@ -4,9 +4,9 @@ module Pursuit
   class Railtie < Rails::Railtie
     initializer 'pursuit.active_record.inject_dsl' do
       ActiveSupport.on_load(:active_record) do
-        require 'pursuit/active_record_dsl'
+        require 'pursuit/dsl'
 
-        ActiveRecord::Base.include(Pursuit::ActiveRecordDSL)
+        ActiveRecord::Base.include(Pursuit::DSL)
       end
     end
   end

data/lib/pursuit/search.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Pursuit
+  class Search
+    # @return [SearchOptions] The options to use when building the search query.
+    #
+    attr_reader :options
+
+    # Create a new instance to search a specific ActiveRecord record class.
+    #
+    # @param options [SearchOptions]
+    #
+    def initialize(options)
+      @options = options
+    end
+
+    # Perform a search for the specified query.
+    #
+    # @param  query [String]                 The query to transform into a SQL search.
+    # @return       [ActiveRecord::Relation] The search results.
+    #
+    def perform(query)
+      options.record_class.where(build_arel(query))
+    end
+
+    private
+
+    def build_arel(query)
+      parser = SearchTermParser.new(query, keys: options.keys)
+      unkeyed_arel = build_arel_for_unkeyed_term(parser.unkeyed_term)
+      keyed_arel = build_arel_for_keyed_terms(parser.keyed_terms)
+
+      if unkeyed_arel && keyed_arel
+        unkeyed_arel.and(keyed_arel)
+      else
+        unkeyed_arel || keyed_arel
+      end
+    end
+
+    def build_arel_for_unkeyed_term(value)
+      return nil if value.blank?
+
+      sanitized_value = "%#{ActiveRecord::Base.sanitize_sql_like(value)}%"
+      options.unkeyed_attributes.reduce(nil) do |chain, (attribute_name, node_builder)|
+        node = node_builder.call.matches(sanitized_value)
+        chain ? chain.or(node) : node
+      end
+    end
+
+    def build_arel_for_keyed_terms(terms)
+      return nil if terms.blank?
+
+      terms.reduce(nil) do |chain, term|
+        attribute_name = term.key.to_sym
+        reflection = options.relations.key?(attribute_name) ? options.record_class.reflections[term.key] : nil
+        node = if reflection.present?
+                 attribute_names = options.relations[attribute_name]
+                 build_arel_for_reflection(reflection, attribute_names, term.operator, term.value)
+               else
+                 node_builder = options.keyed_attributes[attribute_name]
+                 build_arel_for_node(node_builder.call, term.operator, term.value)
+               end
+
+        chain ? chain.and(node) : node
+      end
+    end
+
+    def build_arel_for_node(node, operator, value)
+      sanitized_value = ActiveRecord::Base.sanitize_sql_like(value)
+      sanitized_value = sanitized_value.to_i if sanitized_value =~ /^[0-9]+$/
+
+      case operator
+      when '>'   then node.gt(sanitized_value)
+      when '>='  then node.gteq(sanitized_value)
+      when '<'   then node.lt(sanitized_value)
+      when '<='  then node.lteq(sanitized_value)
+      when '*='  then node.matches("%#{sanitized_value}%")
+      when '!*=' then node.does_not_match("%#{sanitized_value}%")
+      when '!='  then node.not_eq(sanitized_value)
+      when '=='
+        if value.present?
+          node.eq(sanitized_value)
+        else
+          node.eq(nil).or(node.eq(''))
+        end
+      else
+        raise "The operator '#{operator}' is not supported."
+      end
+    end
+
+    def build_arel_for_reflection(reflection, attribute_names, operator, value)
+      nodes = build_arel_for_reflection_join(reflection)
+      count_nodes = build_arel_for_relation_count(nodes, operator, value)
+      return count_nodes if count_nodes.present?
+
+      match_nodes = attribute_names.reduce(nil) do |chain, attribute_name|
+        node = build_arel_for_node(reflection.klass.arel_table[attribute_name], operator, value)
+        chain ? chain.or(node) : node
+      end
+
+      return nil if match_nodes.blank?
+
+      nodes.where(match_nodes).project(1).exists
+    end
+
+    def build_arel_for_reflection_join(reflection)
+      reflection_table = reflection.klass.arel_table
+      reflection_through = reflection.through_reflection
+
+      if reflection_through.present?
+        # :has_one through / :has_many through
+        reflection_through_table = reflection_through.klass.arel_table
+        reflection_table.join(reflection_through_table).on(
+          reflection_through_table[reflection.foreign_key].eq(reflection_table[reflection.klass.primary_key])
+        ).where(
+          reflection_through_table[reflection_through.foreign_key].eq(
+            options.record_class.arel_table[options.record_class.primary_key]
+          )
+        )
+      else
+        # :has_one / :has_many
+        reflection_table.where(
+          reflection_table[reflection.foreign_key].eq(
+            options.record_class.arel_table[options.record_class.primary_key]
+          )
+        )
+      end
+    end
+
+    def build_arel_for_relation_count(nodes, operator, value)
+      node_builder = proc do |klass|
+        count = ActiveRecord::Base.sanitize_sql_like(value).to_i
+        klass.new(nodes.project(Arel.star.count), count)
+      end
+
+      case operator
+      when '>'  then node_builder.call(Arel::Nodes::GreaterThan)
+      when '>=' then node_builder.call(Arel::Nodes::GreaterThanOrEqual)
+      when '<'  then node_builder.call(Arel::Nodes::LessThan)
+      when '<=' then node_builder.call(Arel::Nodes::LessThanOrEqual)
+      else
+        return nil unless value =~ /^([0-9]+)$/
+
+        case operator
+        when '=='  then node_builder.call(Arel::Nodes::Equality)
+        when '!='  then node_builder.call(Arel::Nodes::NotEqual)
+        when '*='  then node_builder.call(Arel::Nodes::Matches)
+        when '!*=' then node_builder.call(Arel::Nodes::DoesNotMatch)
+        end
+      end
+    end
+  end
+end

data/lib/pursuit/search_options.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Pursuit
+  class SearchOptions
+    # @return [Struct] The structure which holds the search options for a single attribute.
+    #
+    AttributeOptions = Struct.new(:keyed, :unkeyed, :block)
+
+    # @return [Class<ActiveRecord::Base>] The `ActiveRecord::Base` child class to search.
+    #
+    attr_reader :record_class
+
+    # @return [Hash<Symbol, Array<Symbol>>] The attribute names of the record's relatives which can be searched.
+    #
+    attr_reader :relations
+
+    # @return [Hash<Symbol, AttributeOptions>] The attributes which can be searched.
+    #
+    attr_reader :attributes
+
+    # Create a new `SearchOptions` and call the passed block to setup the options.
+    #
+    # @params record_class [Class<ActiveRecord::Base>]
+    # @params block        [Proc]
+    #
+    def initialize(record_class, &block)
+      @record_class = record_class
+      @relations = {}
+      @attributes = {}
+
+      block.call(self) if block
+    end
+
+    # @return [Hash<Symbol, Proc>] The attributes which can be queried using a keyed term.
+    #
+    def keyed_attributes
+      attributes.each_with_object({}) do |(name, options), keyed_attributes|
+        keyed_attributes[name] = options.block if options.keyed
+      end
+    end
+
+    # @return [Hash<Symbol, Proc>] The attributes which can be queried using an unkeyed term.
+    #
+    def unkeyed_attributes
+      attributes.each_with_object({}) do |(name, options), unkeyed_attributes|
+        unkeyed_attributes[name] = options.block if options.unkeyed
+      end
+    end
+
+    # @return [Array<String>] The collection of all possible attributes which can be used as a keyed term.
+    #
+    def keys
+      keys = relations.keys + attributes.select { |_, a| a.keyed }.keys
+      keys.map(&:to_s).uniq
+    end
+
+    # Add a relation to search.
+    #
+    # @param name            [Symbol] The name of the relationship attribute.
+    # @param attribute_names [Splat]  The name of the attributes within the relationship to search.
+    #
+    def relation(name, *attribute_names)
+      relations[name] = attribute_names
+      nil
+    end
+
+    # Add an attribute to search.
+    #
+    # @param term_name      [Symbol]  The keyed search term (can be an existing attribute, or a custom value when
+    #                                 passing either the `attribute_name` or a block returning an Arel node).
+    # @param attribute_name [Symbol]  The attribute name to search (defaults to the keyword, when left blank and no
+    #                                 block is passed).
+    # @param keyed          [Boolean] `true` when the attribute should be searchable using a keyed term,
+    #                                 `false` otherwise.
+    # @param unkeyed        [Boolean] `true` when the attribute should be searchable using an unkeyed term,
+    #                                 `false` otherwise.
+    # @param block          [Proc]    A block which returns the Arel node to query against. When left blank, the
+    #                                 matching attribute from `.arel_table` is queried instead.
+    #
+    def attribute(term_name, attribute_name = nil, keyed: true, unkeyed: true, &block)
+      block ||= -> { record_class.arel_table[attribute_name || term_name] }
+      attributes[term_name] = AttributeOptions.new(keyed, unkeyed, block)
+      nil
+    end
+  end
+end

data/lib/pursuit/{term_parser.rb → search_term_parser.rb}

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Pursuit
-  class TermParser
+  class SearchTermParser
     # @return [Struct] Represents a single keyed term extracted from a query.
     #
     KeyedTerm = Struct.new(:key, :operator, :value)
 
-    # @return [Array<Pursuit::TermParser::KeyedTerm>] The keys which are permitted for use as keyed terms.
+    # @return [Array<Pursuit::SearchTermParser::KeyedTerm>] The keys which are permitted for use as keyed terms.
     #
     attr_reader :keyed_terms
 
@@ -14,14 +14,12 @@ module Pursuit
     #
     attr_reader :unkeyed_term
 
-    # Create a new `TermParser` by parsing the specified query into an 'unkeyed term' and 'keyed terms'.
+    # Create a new search term parser by parsing the specified query into an 'unkeyed term' and 'keyed terms'.
     #
     # @param query [String]        The query to parse.
-    # @param keys  [Array<Symbol>] The keys which are permitted for use as keyed terms.
+    # @param keys  [Array<String>] The keys which are permitted for use as keyed terms.
     #
     def initialize(query, keys: [])
-      keys = keys.map(&:to_s)
-
       @keyed_terms = []
       @unkeyed_term = query.gsub(/(\s+)?(\w+)(==|\*=|!=|!\*=|<=|>=|<|>)("([^"]+)?"|'([^']+)?'|[^\s]+)(\s+)?/) do |term|
         key = Regexp.last_match(2)

data/lib/pursuit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'pursuit/constants'
-require 'pursuit/term_parser'
-require 'pursuit/active_record_search'
+require 'pursuit/search_options'
+require 'pursuit/search_term_parser'
+require 'pursuit/search'
 require 'pursuit/railtie' if defined?(Rails::Railtie)

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

@@ -1,11 +1,24 @@
 # frozen_string_literal: true
 
 class Product < ActiveRecord::Base
-  has_many :variations, class_name: 'ProductVariation', inverse_of: :product
+  belongs_to :category, class_name: 'ProductCategory', inverse_of: :products, optional: true
 
-  has_search relationships: { variations: %i[title stock_status] },
-             keyed_attributes: %i[title description rating],
-             unkeyed_attributes: %i[title description]
+  has_many :variations, class_name: 'ProductVariation', inverse_of: :product
 
   validates :title, presence: true
+
+  searchable do |o|
+    o.relation :variations, :title, :stock_status
+
+    o.attribute :title
+    o.attribute :description
+    o.attribute :rating, unkeyed: false
+    o.attribute :title_length, unkeyed: false do
+      Arel::Nodes::NamedFunction.new('LENGTH', [
+        arel_table[:title]
+      ])
+    end
+
+    o.attribute :category, :category_id
+  end
 end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class ProductCategory < ActiveRecord::Base
+  has_many :products, class_name: 'Product', foreign_key: :category_id, inverse_of: :category, dependent: :nullify
+
+  validates :name, presence: true
+end

data/spec/internal/db/schema.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 ActiveRecord::Schema.define do
+  create_table :product_categories, id: :string, force: true do |t|
+    t.string :name, null: false
+
+    t.timestamps null: false
+  end
+
   create_table :products, force: true do |t|
+    t.belongs_to :category, type: :string, foreign_key: { to_table: 'product_categories' }
+
     t.string :title, null: false
 
     t.text :description

data/spec/pursuit/dsl_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+RSpec.describe Pursuit::DSL do
+  subject(:record) { Product.new }
+
+  describe '.search_options' do
+    subject(:search_options) { record.class.search_options }
+
+    it { is_expected.to be_a(Pursuit::SearchOptions) }
+  end
+
+  describe '.search' do
+    subject(:search) { record.class.search('funky') }
+
+    let(:product_a) { Product.create!(title: 'Plain Shirt') }
+    let(:product_b) { Product.create!(title: 'Funky Shirt') }
+
+    it 'is expected to return the matching records' do
+      expect(search).to contain_exactly(product_b)
+    end
+  end
+end

data/spec/pursuit/search_options_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+RSpec.describe Pursuit::SearchOptions do
+  subject(:search_options) { described_class.new(Product) }
+
+  let(:title_length_node_builder) do
+    proc do
+      Arel::Nodes::NamedFunction.new('LENGTH', [
+        Product.arel_table[:title]
+      ])
+    end
+  end
+
+  describe '#record_class' do
+    subject(:record_class) { search_options.record_class }
+
+    it 'is expected to eq the class passed during initialization' do
+      expect(record_class).to eq(Product)
+    end
+  end
+
+  describe '#relations' do
+    subject(:relations) { search_options.relations }
+
+    before do
+      search_options.relation :variations, :title, :stock_status
+    end
+
+    it 'is expected to contain the correct relations' do
+      expect(relations).to eq(variations: %i[title stock_status])
+    end
+  end
+
+  describe '#keyed_attributes' do
+    subject(:keyed_attributes) { search_options.keyed_attributes }
+
+    before do
+      search_options.attribute :title, keyed: false
+      search_options.attribute :title_length, &title_length_node_builder
+      search_options.attribute :description
+      search_options.attribute :rating, unkeyed: false
+    end
+
+    it 'is expected to contain the correct keyed attributes' do
+      expect(keyed_attributes.keys).to contain_exactly(:title_length, :description, :rating)
+    end
+
+    it 'is expected to set a default node builder for attributes declared without a block' do
+      expect(keyed_attributes[:description].call).to eq(Product.arel_table[:description])
+    end
+
+    it 'is expected to set a custom node builder for attributes declared with a block' do
+      expect(keyed_attributes[:title_length]).to eq(title_length_node_builder)
+    end
+  end
+
+  describe '#unkeyed_attributes' do
+    subject(:unkeyed_attributes) { search_options.unkeyed_attributes }
+
+    before do
+      search_options.attribute :title, keyed: false
+      search_options.attribute :title_length, &title_length_node_builder
+      search_options.attribute :description
+      search_options.attribute :rating, unkeyed: false
+    end
+
+    it 'is expected to contain the correct unkeyed attributes' do
+      expect(unkeyed_attributes.keys).to contain_exactly(:title, :title_length, :description)
+    end
+
+    it 'is expected to set a default node builder for attributes declared without a block' do
+      expect(unkeyed_attributes[:title].call).to eq(Product.arel_table[:title])
+    end
+
+    it 'is expected to set a custom node builder for attributes declared with a block' do
+      expect(unkeyed_attributes[:title_length]).to eq(title_length_node_builder)
+    end
+  end
+
+  describe '#relation' do
+    subject(:relation) { search_options.relation(:variations, :title, :stock_status) }
+
+    it 'is expected to add the relation to #relations' do
+      expect { relation }.to change(search_options, :relations).from({}).to(variations: %i[title stock_status])
+    end
+  end
+
+  describe '#attribute' do
+    subject(:attribute) { search_options.attribute(:description) }
+
+    it { is_expected.to eq(nil) }
+
+    it 'is expected to add the attribute to #attributes' do
+      expect { attribute }.to change(search_options.attributes, :keys).from([]).to(%i[description])
+    end
+
+    it 'is expected to allow keyed searching by default' do
+      attribute
+      expect(search_options.attributes[:description].keyed).to eq(true)
+    end
+
+    it 'is expected to allow unkeyed searching by default' do
+      attribute
+      expect(search_options.attributes[:description].unkeyed).to eq(true)
+    end
+
+    it 'is expected to query the #term_name attribute' do
+      attribute
+      expect(search_options.attributes[:description].block.call).to eq(Product.arel_table[:description])
+    end
+
+    context 'when passing the attribute name to search' do
+      subject(:attribute) { search_options.attribute(:desc, :description) }
+
+      it 'is expected to query the #attribute_name attribute' do
+        attribute
+        expect(search_options.attributes[:desc].block.call).to eq(Product.arel_table[:description])
+      end
+    end
+
+    context 'when passing :keyed eq false' do
+      subject(:attribute) { search_options.attribute(:description, keyed: false) }
+
+      it 'is expected to disallow keyed searching' do
+        attribute
+        expect(search_options.attributes[:description].keyed).to eq(false)
+      end
+    end
+
+    context 'when passing :unkeyed eq false' do
+      subject(:attribute) { search_options.attribute(:description, unkeyed: false) }
+
+      it 'is expected to disallow unkeyed searching' do
+        attribute
+        expect(search_options.attributes[:description].unkeyed).to eq(false)
+      end
+    end
+
+    context 'when passing a block' do
+      subject(:attribute) { search_options.attribute(:description, &title_length_node_builder) }
+
+      it 'is expected to query the result of the passed block' do
+        attribute
+        expect(search_options.attributes[:description].block).to eq(title_length_node_builder)
+      end
+    end
+  end
+end

data/spec/pursuit/{active_record_search_spec.rb → search_spec.rb}

@@ -1,17 +1,27 @@
 # frozen_string_literal: true
 
-RSpec.describe Pursuit::ActiveRecordSearch do
-  subject(:active_record_search) do
-    described_class.new(
-      Product,
-      relationships: { variations: %i[title stock_status] },
-      keyed_attributes: %i[title description rating],
-      unkeyed_attributes: %i[title description]
-    )
+RSpec.describe Pursuit::Search do
+  subject(:search) { described_class.new(search_options) }
+
+  let(:search_options) do
+    Pursuit::SearchOptions.new(Product) do |o|
+      o.relation :variations, :title, :stock_status
+
+      o.attribute :title
+      o.attribute :description
+      o.attribute :rating, unkeyed: false
+      o.attribute :title_length, unkeyed: false do
+        Arel::Nodes::NamedFunction.new('LENGTH', [
+          Product.arel_table[:title]
+        ])
+      end
+
+      o.attribute :category, :category_id
+    end
   end
 
-  describe '#search' do
-    subject(:search) { active_record_search.search(query) }
+  describe '#perform' do
+    subject(:perform) { search.perform(query) }
 
     context 'when passed a blank query' do
       let(:query) { '' }
@@ -25,7 +35,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain all records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -43,7 +53,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -61,7 +71,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_b)
+        expect(perform).to contain_exactly(product_b)
       end
     end
 
@@ -79,7 +89,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_c)
+        expect(perform).to contain_exactly(product_a, product_c)
       end
     end
 
@@ -97,7 +107,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -115,7 +125,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -133,7 +143,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_b, product_c)
+        expect(perform).to contain_exactly(product_b, product_c)
       end
     end
 
@@ -151,7 +161,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_b, product_c)
+        expect(perform).to contain_exactly(product_b, product_c)
       end
     end
 
@@ -169,7 +179,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_b, product_c)
+        expect(perform).to contain_exactly(product_b, product_c)
       end
     end
 
@@ -187,7 +197,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -205,7 +215,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -223,7 +233,23 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_b)
+        expect(perform).to contain_exactly(product_b)
+      end
+    end
+
+    context 'when passed a virtual keyed attribute query' do
+      let(:query) { 'title_length==5' }
+
+      let(:product_a) { Product.create!(title: 'Plain Shirt') }
+      let(:product_b) { Product.create!(title: 'Socks') }
+
+      before do
+        product_a
+        product_b
+      end
+
+      it 'is expected to contain the matching records' do
+        expect(perform).to contain_exactly(product_b)
       end
     end
 
@@ -247,7 +273,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_b)
+        expect(perform).to contain_exactly(product_b)
       end
     end
 
@@ -275,7 +301,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_c)
+        expect(perform).to contain_exactly(product_c)
       end
     end
 
@@ -307,7 +333,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -339,7 +365,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_b)
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
 
@@ -371,7 +397,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_c)
+        expect(perform).to contain_exactly(product_a, product_c)
       end
     end
 
@@ -403,7 +429,7 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a, product_c)
+        expect(perform).to contain_exactly(product_a, product_c)
       end
     end
 
@@ -435,7 +461,28 @@ RSpec.describe Pursuit::ActiveRecordSearch do
       end
 
       it 'is expected to contain the matching records' do
-        expect(search).to contain_exactly(product_a)
+        expect(perform).to contain_exactly(product_a)
+      end
+    end
+
+    context 'when querying a custom attribute whose name matches a reflection' do
+      let(:query) { 'category==shirts' }
+
+      let(:shirts_category) { ProductCategory.create!(id: 'shirts', name: 'The Shirt Collection') }
+      let(:socks_category)  { ProductCategory.create!(id: 'socks', name: 'The Sock Collection') }
+
+      let(:product_a) { Product.create!(title: 'Plain Shirt', category: shirts_category) }
+      let(:product_b) { Product.create!(title: 'Funky Shirt', category: shirts_category) }
+      let(:product_c) { Product.create!(title: 'Socks - Pack of 4', category: socks_category) }
+
+      before do
+        product_a
+        product_b
+        product_c
+      end
+
+      it 'is expected to contain the matching records' do
+        expect(perform).to contain_exactly(product_a, product_b)
       end
     end
   end

data/spec/pursuit/search_term_parser_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+RSpec.describe Pursuit::SearchTermParser do
+  subject(:parser) { described_class.new(query, keys: keys) }
+
+  let(:keys) { %w[title description rating stock_status] }
+  let(:query) do
+    "plain title!='Socks' description*=\"green\" stock_status==in_stock shirt rating>=2 other*=thing rating<5"
+  end
+
+  describe '#unkeyed_term' do
+    subject(:unkeyed_term) { parser.unkeyed_term }
+
+    it 'is expected to eq the correct unkeyed term' do
+      expect(unkeyed_term).to eq('plain shirt other*=thing')
+    end
+  end
+
+  describe '#keyed_terms' do
+    subject(:keyed_terms) { parser.keyed_terms }
+
+    it 'is expected to eq the correct keyed terms' do
+      expect(keyed_terms).to eq([
+        Pursuit::SearchTermParser::KeyedTerm.new('title', '!=', 'Socks'),
+        Pursuit::SearchTermParser::KeyedTerm.new('description', '*=', 'green'),
+        Pursuit::SearchTermParser::KeyedTerm.new('stock_status', '==', 'in_stock'),
+        Pursuit::SearchTermParser::KeyedTerm.new('rating', '>=', '2'),
+        Pursuit::SearchTermParser::KeyedTerm.new('rating', '<', '5')
+      ])
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pursuit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Nialto Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-18 00:00:00.000000000 Z
+date: 2021-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -199,21 +199,24 @@ files:
 - bin/setup
 - config.ru
 - lib/pursuit.rb
-- lib/pursuit/active_record_dsl.rb
-- lib/pursuit/active_record_search.rb
 - lib/pursuit/constants.rb
+- lib/pursuit/dsl.rb
 - lib/pursuit/railtie.rb
-- lib/pursuit/term_parser.rb
+- lib/pursuit/search.rb
+- lib/pursuit/search_options.rb
+- lib/pursuit/search_term_parser.rb
 - pursuit.gemspec
 - spec/internal/app/models/product.rb
+- spec/internal/app/models/product_category.rb
 - spec/internal/app/models/product_variation.rb
 - spec/internal/config/database.yml
 - spec/internal/db/schema.rb
 - spec/internal/log/.keep
-- spec/pursuit/active_record_dsl_spec.rb
-- spec/pursuit/active_record_search_spec.rb
 - spec/pursuit/constants_spec.rb
-- spec/pursuit/term_parser_spec.rb
+- spec/pursuit/dsl_spec.rb
+- spec/pursuit/search_options_spec.rb
+- spec/pursuit/search_spec.rb
+- spec/pursuit/search_term_parser_spec.rb
 - spec/spec_helper.rb
 - travis/gemfiles/5.2.gemfile
 - travis/gemfiles/6.0.gemfile
@@ -244,12 +247,14 @@ specification_version: 4
 summary: Advanced key-based searching for ActiveRecord objects.
 test_files:
 - spec/internal/app/models/product.rb
+- spec/internal/app/models/product_category.rb
 - spec/internal/app/models/product_variation.rb
 - spec/internal/config/database.yml
 - spec/internal/db/schema.rb
 - spec/internal/log/.keep
-- spec/pursuit/active_record_dsl_spec.rb
-- spec/pursuit/active_record_search_spec.rb
 - spec/pursuit/constants_spec.rb
-- spec/pursuit/term_parser_spec.rb
+- spec/pursuit/dsl_spec.rb
+- spec/pursuit/search_options_spec.rb
+- spec/pursuit/search_spec.rb
+- spec/pursuit/search_term_parser_spec.rb
 - spec/spec_helper.rb

data/lib/pursuit/active_record_dsl.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Pursuit
-  # Provides a DSL for the `ActiveRecord::Base` class.
-  #
-  module ActiveRecordDSL
-    def self.included(base)
-      base.extend ClassMethods
-    end
-
-    module ClassMethods
-      def has_search(relationships: {}, keyed_attributes: [], unkeyed_attributes: [])
-        raise 'The #search method has already been defined.' if respond_to?(:search)
-
-        # The value of `self` is a constant for the current `ActiveRecord::Base` subclass. We'll need to capture this
-        # in a custom variable to make it accessible from within the #define_method block.
-        klass = self
-
-        define_method(:search) do |query|
-          search = Pursuit::ActiveRecordSearch.new(
-            klass,
-            relationships: relationships,
-            keyed_attributes: keyed_attributes,
-            unkeyed_attributes: unkeyed_attributes
-          )
-
-          search.search(query)
-        end
-      end
-    end
-  end
-end

data/lib/pursuit/active_record_search.rb

@@ -1,165 +0,0 @@
-# frozen_string_literal: true
-
-module Pursuit
-  class ActiveRecordSearch
-    # @return [Class<ActiveRecord::Base>] The `ActiveRecord::Base` child class being searched.
-    #
-    attr_reader :klass
-
-    # @return [Hash<Symbol, Array<Symbol>>] The attribute names for relationships which can be queried with a keyed
-    #                                       term and the attributes in the relative's table which should be searched.
-    #
-    attr_accessor :relationships
-
-    # @return [Array<Symbol>] The attribute names which can be queried with a keyed term (e.g. 'last_name:*herb').
-    #
-    attr_accessor :keyed_attributes
-
-    # @return [Array<Symbol>] The attribute names which can be queried with an unkeyed term (e.g. 'herb').
-    #
-    attr_accessor :unkeyed_attributes
-
-    # Create a new instance to search a specific ActiveRecord record class.
-    #
-    # @param klass              [Class<ActiveRecord::Base>]
-    # @param relationships      [Hash<Symbol, Array<Symbol>>]
-    # @param keyed_attributes   [Array<Symbol>]
-    # @param unkeyed_attributes [Array<Symbol>]
-    #
-    def initialize(klass, relationships: {}, keyed_attributes: [], unkeyed_attributes: [])
-      @klass = klass
-      @relationships = relationships
-      @keyed_attributes = keyed_attributes
-      @unkeyed_attributes = unkeyed_attributes
-    end
-
-    # Search the record with the specified query.
-    #
-    # @param  query [String]                 The query to transform into a SQL search.
-    # @return       [ActiveRecord::Relation] The search results.
-    #
-    def search(query)
-      klass.where(build_arel(query))
-    end
-
-    private
-
-    def build_arel(query)
-      parser = TermParser.new(query, keys: relationships.keys + keyed_attributes)
-      unkeyed_arel = build_arel_for_unkeyed_term(parser.unkeyed_term)
-      keyed_arel = build_arel_for_keyed_terms(parser.keyed_terms)
-
-      if unkeyed_arel && keyed_arel
-        unkeyed_arel.and(keyed_arel)
-      else
-        unkeyed_arel || keyed_arel
-      end
-    end
-
-    def build_arel_for_unkeyed_term(value)
-      return nil if value.blank?
-
-      sanitized_value = "%#{klass.sanitize_sql_like(value)}%"
-      unkeyed_attributes.reduce(nil) do |chain, attribute_name|
-        node = klass.arel_table[attribute_name].matches(sanitized_value)
-        chain ? chain.or(node) : node
-      end
-    end
-
-    def build_arel_for_keyed_terms(terms)
-      return nil if terms.blank?
-
-      terms.reduce(nil) do |chain, term|
-        reflection = klass.reflections[term.key]
-        node = if reflection.present?
-                 keys = relationships[term.key.to_sym].presence || []
-                 build_arel_for_reflection(reflection, keys, term.operator, term.value)
-               else
-                 build_arel_for_attribute(klass.arel_table[term.key], term.operator, term.value)
-               end
-
-        chain ? chain.and(node) : node
-      end
-    end
-
-    def build_arel_for_attribute(attribute, operator, value)
-      sanitized_value = ActiveRecord::Base.sanitize_sql_like(value)
-
-      case operator
-      when '>'   then attribute.gt(sanitized_value)
-      when '>='  then attribute.gteq(sanitized_value)
-      when '<'   then attribute.lt(sanitized_value)
-      when '<='  then attribute.lteq(sanitized_value)
-      when '*='  then attribute.matches("%#{sanitized_value}%")
-      when '!*=' then attribute.does_not_match("%#{sanitized_value}%")
-      when '!='  then attribute.not_eq(sanitized_value)
-      when '=='
-        if value.present?
-          attribute.eq(sanitized_value)
-        else
-          attribute.eq(nil).or(attribute.eq(''))
-        end
-      else
-        raise "The operator '#{operator}' is not supported."
-      end
-    end
-
-    def build_arel_for_reflection(reflection, relation_attributes, operator, value)
-      nodes = build_arel_for_reflection_join(reflection)
-      count_nodes = build_arel_for_relation_count(nodes, operator, value)
-      return count_nodes if count_nodes.present?
-
-      match_nodes = relation_attributes.reduce(nil) do |chain, attribute_name|
-        node = build_arel_for_attribute(reflection.klass.arel_table[attribute_name], operator, value)
-        chain ? chain.or(node) : node
-      end
-
-      return nil if match_nodes.blank?
-
-      nodes.where(match_nodes).project(1).exists
-    end
-
-    def build_arel_for_reflection_join(reflection)
-      reflection_table = reflection.klass.arel_table
-      reflection_through = reflection.through_reflection
-
-      if reflection_through.present?
-        # :has_one through / :has_many through
-        reflection_through_table = reflection_through.klass.arel_table
-        reflection_table.join(reflection_through_table).on(
-          reflection_through_table[reflection.foreign_key].eq(reflection_table[reflection.klass.primary_key])
-        ).where(
-          reflection_through_table[reflection_through.foreign_key].eq(klass.arel_table[klass.primary_key])
-        )
-      else
-        # :has_one / :has_many
-        reflection_table.where(
-          reflection_table[reflection.foreign_key].eq(klass.arel_table[klass.primary_key])
-        )
-      end
-    end
-
-    def build_arel_for_relation_count(nodes, operator, value)
-      build = proc do |klass|
-        count = ActiveRecord::Base.sanitize_sql_like(value).to_i
-        klass.new(nodes.project(Arel.star.count), count)
-      end
-
-      case operator
-      when '>'  then build.call(Arel::Nodes::GreaterThan)
-      when '>=' then build.call(Arel::Nodes::GreaterThanOrEqual)
-      when '<'  then build.call(Arel::Nodes::LessThan)
-      when '<=' then build.call(Arel::Nodes::LessThanOrEqual)
-      else
-        return nil unless value =~ /^([0-9]+)$/
-
-        case operator
-        when '=='  then build.call(Arel::Nodes::Equality)
-        when '!='  then build.call(Arel::Nodes::NotEqual)
-        when '*='  then build.call(Arel::Nodes::Matches)
-        when '!*=' then build.call(Arel::Nodes::DoesNotMatch)
-        end
-      end
-    end
-  end
-end

data/spec/pursuit/active_record_dsl_spec.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-RSpec.describe Pursuit::ActiveRecordDSL do
-  subject(:product) { Product.new }
-
-  it { is_expected.to respond_to(:search) }
-end

data/spec/pursuit/term_parser_spec.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-RSpec.describe Pursuit::TermParser do
-  subject(:term_parser) { described_class.new(query, keys: keys) }
-
-  let(:keys)  { %i[title description rating stock_status] }
-  let(:query) do
-    "plain title!='Socks' description*=\"green\" stock_status==in_stock shirt rating>=2 other*=thing rating<5"
-  end
-
-  describe '#unkeyed_term' do
-    subject(:unkeyed_term) { term_parser.unkeyed_term }
-
-    it 'is expected to eq the correct unkeyed term' do
-      expect(unkeyed_term).to eq('plain shirt other*=thing')
-    end
-  end
-
-  describe '#keyed_terms' do
-    subject(:keyed_terms) { term_parser.keyed_terms }
-
-    it 'is expected to eq the correct keyed terms' do
-      expect(keyed_terms).to eq([
-        Pursuit::TermParser::KeyedTerm.new('title', '!=', 'Socks'),
-        Pursuit::TermParser::KeyedTerm.new('description', '*=', 'green'),
-        Pursuit::TermParser::KeyedTerm.new('stock_status', '==', 'in_stock'),
-        Pursuit::TermParser::KeyedTerm.new('rating', '>=', '2'),
-        Pursuit::TermParser::KeyedTerm.new('rating', '<', '5')
-      ])
-    end
-  end
-end