pursuit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e63f3c017580251d11f1db0994e4e771f9689e63ed2ae8f4c1c98e14ba27e0b
+  data.tar.gz: 7956f93f4eea40de80878022796d823b57cbe95da8472a1784ab864fb6b17165
+SHA512:
+  metadata.gz: 7cfd6c4114d8e02181a8e74a8865f862cfbc904b56a64819b6993a788bf83f847b0859037baf7f43fa3425acb5b33e937875dfffbb0e57abe7dcb094c78e8dde
+  data.tar.gz: ca46b2fd3b10167df8b74419bd1e41ee200a943b3d73ce5842b52429f89b69fd111ab884b6941d5a84a402ecebab5831941838b10eee0454cb8df8d27c4caca0

data/.gitignore

@@ -0,0 +1,26 @@
+# OS Files
+.DS_Store
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Bundler
+/.bundle
+/vendor/bundle
+
+# RSpec
+/spec/examples.txt
+
+# SQLite Database
+/spec/internal/db/*.sqlite3
+/spec/internal/db/*.sqlite3-journal
+
+# Log & Temporary Files
+/spec/internal/log/*
+/spec/internal/tmp/*
+!/spec/internal/log/.keep
+!/spec/internal/tmp/.keep
+
+# Environment Files
+.env
+.env.*

data/.rbenv-gemsets

@@ -0,0 +1 @@
+pursuit

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+AllCops:
+  Exclude:
+    - 'bin/**/*'
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.0.2

data/.travis.yml

@@ -0,0 +1,24 @@
+language: ruby
+rvm:
+  - 3.0.2
+gemfile:
+  - travis/gemfiles/5.2.gemfile
+  - travis/gemfiles/6.0.gemfile
+  - travis/gemfiles/6.1.gemfile
+services:
+  - postgresql
+before_install:
+  - gem update --system
+  - gem install bundler
+before_script:
+  - psql -c 'CREATE DATABASE pursuit_test;' -U postgres
+addons:
+  postgresql: 14
+  apt:
+    packages:
+      - postgresql-14
+      - postgresql-client-14
+env:
+  global:
+    - DATABASE_URL="postgresql://127.0.0.1:5432/pursuit_test"
+    - RSPEC_DEFAULT_FORMATTER=doc

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,161 @@
+PATH
+  remote: .
+  specs:
+    pursuit (0.1.0)
+      activerecord (>= 5.2.0, < 6.1.0)
+      activesupport (>= 5.2.0, < 6.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (6.0.4.1)
+      actionview (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (6.0.4.1)
+      activesupport (= 6.0.4.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activemodel (6.0.4.1)
+      activesupport (= 6.0.4.1)
+    activerecord (6.0.4.1)
+      activemodel (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
+    activesupport (6.0.4.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    ast (2.4.2)
+    builder (3.2.4)
+    coderay (1.1.3)
+    combustion (1.3.3)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
+      thor (>= 0.14.6)
+    concurrent-ruby (1.1.9)
+    crass (1.0.6)
+    diff-lcs (1.4.4)
+    erubi (1.10.0)
+    ffi (1.15.4)
+    formatador (0.3.0)
+    guard (2.18.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.13.0)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    i18n (1.8.11)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    listen (3.7.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    loofah (2.12.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    lumberjack (1.2.8)
+    method_source (1.0.0)
+    minitest (5.14.4)
+    nenv (0.3.0)
+    nokogiri (1.12.5-x86_64-darwin)
+      racc (~> 1.4)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.21.0)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.6.0)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.2)
+      loofah (~> 2.3)
+    railties (6.0.4.1)
+      actionpack (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    rb-fsevent (0.11.0)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.3)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-rails (3.9.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.4)
+    rubocop (0.77.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.11.0)
+    shellany (0.0.1)
+    sqlite3 (1.4.2)
+    thor (1.1.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.9)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.6.1)
+    yard (0.9.26)
+    zeitwerk (2.5.1)
+
+PLATFORMS
+  x86_64-darwin-21
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  combustion (~> 1.1)
+  guard-rspec (~> 4.7)
+  pursuit!
+  rake (~> 13.0)
+  rspec (~> 3.8)
+  rspec-rails (~> 3.8)
+  rubocop (~> 0.77.0)
+  sqlite3 (~> 1.4)
+  yard (~> 0.9.20)
+
+BUNDLED WITH
+   2.2.22

data/Guardfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Nialto Services
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+# Pursuit
+
+Advanced key-based searching for ActiveRecord objects.
+
+## Installation
+
+You can install **Pursuit** using the following command:
+
+  $ gem install pursuit
+
+Or, by adding the following to your `Gemfile`:
+
+```ruby
+gem 'pursuit'
+```
+
+### Usage
+
+You can use the convenient DSL syntax to declare which attributes and relationships are searchable:
+
+```ruby
+class Product < ActiveRecord::Base
+  has_search relationships: { variations: %i[title] },
+             keyed_attributes: %i[title description rating],
+             unkeyed_attributes: %i[title description]
+end
+```
+
+This creates a ```.search``` method on your record class which accepts a single query argument:
+
+```ruby
+Product.search('plain shirt rating>=3')
+```
+
+## Development
+
+After checking out the repo, run `bundle exec rake spec` to run the tests.
+
+To install this gem onto your machine, run `bundle exec rake install`.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'pursuit'
+require 'pry'
+
+Pry.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/config.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize! :all
+run Combustion::Application

data/lib/pursuit/active_record_dsl.rb

@@ -0,0 +1,32 @@
+# 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

@@ -0,0 +1,165 @@
+# 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/lib/pursuit/constants.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # @return [String] The gem's semantic version number.
+  #
+  VERSION = '0.1.0'
+end

data/lib/pursuit/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pursuit
+  class Railtie < Rails::Railtie
+    initializer 'pursuit.active_record.inject_dsl' do
+      ActiveSupport.on_load(:active_record) do
+        require 'pursuit/active_record_dsl'
+
+        ActiveRecord::Base.include(Pursuit::ActiveRecordDSL)
+      end
+    end
+  end
+end

data/lib/pursuit/term_parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pursuit
+  class TermParser
+    # @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.
+    #
+    attr_reader :keyed_terms
+
+    # @return [String] The unkeyed term.
+    #
+    attr_reader :unkeyed_term
+
+    # Create a new `TermParser` 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.
+    #
+    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)
+        next term unless keys.include?(key)
+
+        operator = Regexp.last_match(3)
+        value = Regexp.last_match(4)
+        value = value[1..-2] if value =~ /^(".*"|'.*')$/
+
+        @keyed_terms << KeyedTerm.new(key, operator, value)
+
+        # Both the starting and ending spaces surrounding the keyed term can be removed, so in this case we'll need to
+        # replace with a single space to ensure the unkeyed term's words are separated correctly.
+        if term =~ /^\s.*\s$/
+          ' '
+        else
+          ''
+        end
+      end
+
+      @unkeyed_term = @unkeyed_term.strip
+    end
+  end
+end

data/lib/pursuit.rb

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