hayfork 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4244a8852812afa0efbd85f9d0c70e0baac4567a50ef5a4b7b24cf6c447cd0f
+  data.tar.gz: 8911ea611f7a67d9b7573c9b64080bdd827e3e68b23c8788d870c74033f3acdb
+SHA512:
+  metadata.gz: 85bf188fc4e268f5ca08283071cc7c6137a5f360731a35bf82ac99c7e945be9efcca1cfa2199973cfa86d619de6ba24edac72f550c03d614bc855f9c6df1df99
+  data.tar.gz: d0457753638b6c4e13cd1a551dd0c8dbace0d901214dda978733133904a6a790b1195c41abddc3e06987e11efc040f3b83c6542952d45c21a11e9a67b154430b

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/Gemfile.lock
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.ruby-version

@@ -0,0 +1 @@
+2.5.3

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+
+rvm:
+  - 2.3.8
+  - 2.5.3
+  - 2.6.0
+
+sudo: required
+dist: xenial
+addons:
+  postgresql: 10
+
+services:
+  - postgresql
+
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in hayfork.gemspec
+gemspec
+
+gem "rails", "~> 5.2"
+
+gem "pry"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Bob Lail
+
+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,200 @@
+# Hayfork
+
+[![Gem Version](https://badge.fury.io/rb/hayfork.svg)](https://rubygems.org/gems/hayfork)
+[![Build Status](https://travis-ci.org/boblail/hayfork.svg)](https://travis-ci.org/boblail/hayfork)
+
+Full-Text search for ActiveRecord and Postgres.
+
+Hayfork generates triggers to maintain a **Haystack** of all searchable fields that Postgres can index easily and efficiently.
+
+
+
+<br/>
+
+## About
+
+#### How Hayfork works
+
+You define the tables and fields that are to be searchable. Hayfork defines triggers that watch those tables for INSERTs, UPDATEs, and DELETEs. In response, the triggers insert, update, or delete corresponding rows in the haystack: one row per searchable field.
+
+They Haystack has a column named `search_vector` that can be indexed, optimizing searches.
+
+A query against the Haystack returns a list of **hits** — one result may have more than one hit (as when a search string is found in both the text and title of a book).
+
+
+#### Why Hayfork?
+
+Hayfork is designed to:
+
+ - optimize searches by:
+    - executing one query to search any number of fields or tables
+    - writing `search_vector` when hits are inserted so that the column may be indexed
+ - rebuild the haystack at the database level so that it works with bulk-inserted records
+ - support extension so, by adding metadata to a hit, you can:
+    - provide additional context about a result in the UI
+    - search only within a particular field (e.g. enable users to search `author:Potok` to find books whether the author's name includes "Potok")
+    - scope searches by a user or tenant or feature
+
+
+<br/>
+
+## Setup
+
+Generate a haystack table and model for your application.
+
+    $ rails generate hayfork:haystack
+
+This will generate several files:
+
+ - `app/models/haystack.rb` and `db/migrate/000_create_haystack.rb` define the Haystack
+ - `app/models/query.rb` (and several models in the `Query` namespace) are responsible for parsing a query string and constructing the SQL to execute it.
+ - `lib/haystack_triggers.rb` is where you will define the tables and fields to be added to the Haystack.
+
+
+<br/>
+
+## lib/haystack_triggers.rb
+
+#### Basic Example
+
+This basic example allows you to search all your employees and projects with one search box:
+
+```ruby
+Hayfork.maintain(Haystack) do
+  foreach(Employee) do
+    insert(:full_name)
+  end
+  foreach(Project) do
+    insert(:title)
+  end
+end
+```
+
+<br/>
+
+#### Multiple Fields
+
+To allow finding employees by multiple traits (e.g by name, job title, or short biography), you can define multiple `insert` statements per employee:
+
+```ruby
+Hayfork.maintain(Haystack) do
+  foreach(Employee) do
+    insert(:full_name)
+    insert(:position)
+    insert(:short_bio)
+  end
+end
+```
+
+<br/>
+
+#### Scoping Searches
+
+Additional columns on `haystack` can also be useful for scoping searches. Suppose we're maintaining a database of employees for multiple companies. We would want to scope searches by company. If we've added `company_id` to our haystack, we can populate it like this:
+
+```ruby
+Hayfork.maintain(Haystack) do
+  foreach(Employee) do
+    set :company_id, row[:company_id]
+
+    insert(:full_name)
+    insert(:position)
+    insert(:short_bio)
+  end
+end
+```
+
+In this line,
+
+```ruby
+    set :company_id, row[:company_id]
+```
+
+1. `row` is an instance of `Arel::Table` that represents the row passed to the trigger; `row` is present in every `foreach` block.
+2. `set` assigns a value that will be inserted in the haystack for all following `insert` statements.
+
+<br/>
+
+#### belongs_to
+
+If a book `belongs_to :author`, you can find the book by _either_ its title or its author's name like this:
+
+```ruby
+Hayfork.maintain(Haystack) do
+  foreach(Book) do
+    insert(:title)
+    insert(author: :name)
+  end
+end
+```
+
+When a book is inserted, this will add an entry to the haystack for the book's title and another entry for its author's name. If `book.author_id` is changed, it'll replace the appropriate entry in the haystack; but what if `authors.name` is modified? We also need to watch the `authors` table for changes to modify the haystack:
+
+```ruby
+Hayfork.maintain(Haystack) do
+  foreach(Book) do
+    insert(:title)
+    insert(author: :name)
+  end
+  foreach(Author) do
+    joins :books
+    set :search_result_type, "Book"
+    set :search_result_id, Book.arel_table[:id]
+
+    insert(:name)
+  end
+end
+```
+
+In the examples seen before, we haven't set `search_result_type` and `search_result_id`. If these values aren't defined, Hayfork assumes that the model passed to `foreach` — the table being watched — is the search result; but for an associated record, we need to explicitly declare the result. In this case, an entry is added to the haystack for every book that belongs to an author.
+
+<br/>
+
+#### has_many
+
+`has_many` and `has_many :through` associations work much the same way. If an article `has_many :comments`, you can find an article by any of its comments like this:
+
+```ruby
+Hayfork.maintain(Haystack) do
+  foreach(Article) do
+    insert(comments: :text)
+  end
+  foreach(Comment) do
+    joins :article
+    set :search_result_type, "Article"
+    set :search_result_id, Article.arel_table[:id]
+
+    insert(:text)
+  end
+end
+```
+
+<br/>
+
+#### Rebuild Triggers
+
+After making changes to `lib/haystack_triggers.rb` or to the default scopes of any of the models being used by the Triggers File, you'll need to replace the triggers in your database and rebuild the Haystack. Hayfork generates a migration to do that:
+
+    $ rails generate hayfork:rebuild
+
+
+
+<br/>
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+<br/>
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/cph/hayfork.
+
+<br/>
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hayfork"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hayfork.gemspec

@@ -0,0 +1,33 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "hayfork/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "hayfork"
+  spec.version       = Hayfork::VERSION
+  spec.authors       = ["Bob Lail"]
+  spec.email         = ["bob.lailfamily@gmail.com"]
+
+  spec.summary       = %q{ Full-Text search for ActiveRecord and Postgres }
+  spec.description   = %q{ Hayfork generates triggers to maintain a Haystack of all searchable fields that Postgres can index easily and efficiently }
+  spec.homepage      = "https://github.com/cph/hayfork"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "railties", ">= 5.2.0", "< 6.0"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-reporters"
+  spec.add_development_dependency "minitest-reporters-turn_reporter"
+  spec.add_development_dependency "database_cleaner"
+  spec.add_development_dependency "pg"
+  spec.add_development_dependency "rr"
+  spec.add_development_dependency "shoulda-context"
+end

data/lib/generators/hayfork/haystack_generator.rb

@@ -0,0 +1,45 @@
+require "rails"
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Hayfork
+  module Generators
+    class HaystackGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # `argument :name` is defined in ::NamedBase,
+      # but we override it to provide a default value.
+      argument :name, type: :string, default: "haystack"
+
+      def copy_model
+        template "model.rb", "app/models/#{file_name}.rb"
+      end
+
+      def copy_migration
+        migration_template "migrations/create.rb", "#{db_migrate_path}/create_#{table_name}.rb", migration_version: migration_version
+      end
+
+      def copy_triggers
+        template "triggers.rb", "lib/#{file_name}_triggers.rb"
+      end
+
+      def copy_query_models
+        template "query.rb", "app/models/query.rb"
+        template "query/exact_phrase.rb", "app/models/query/exact_phrase.rb"
+        template "query/object.rb", "app/models/query/object.rb"
+        template "query/parser.rb", "app/models/query/parser.rb"
+      end
+
+      def table_name
+        return "haystack" if class_name == "Haystack"
+        super
+      end
+
+      def migration_version
+        return unless Rails::VERSION::MAJOR >= 5
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+    end
+  end
+end

data/lib/generators/hayfork/rebuild_generator.rb

@@ -0,0 +1,49 @@
+require "rails"
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Hayfork
+  module Generators
+    class CreateOrReplaceMigration < Rails::Generators::Actions::CreateMigration
+      def initialize(base, destination, data, config = {})
+        config[:force] = true
+        super
+      end
+
+      def identical?
+        false
+      end
+    end
+
+    module CreateOrReplaceMigrationConcern
+      def create_migration(destination, data, config = {}, &block)
+        action CreateOrReplaceMigration.new(self, destination, block || data.to_s, config)
+      end
+    end
+
+    class RebuildGenerator < ActiveRecord::Generators::Base
+      include CreateOrReplaceMigrationConcern
+
+      source_root File.expand_path("templates", __dir__)
+
+      # `argument :name` is defined in ::NamedBase,
+      # but we override it to provide a default value.
+      argument :name, type: :string, default: "haystack"
+
+      def copy_migration
+        migration_template "migrations/rebuild.rb", "#{db_migrate_path}/rebuild_#{table_name}.rb", migration_version: migration_version
+      end
+
+      def table_name
+        return "haystack" if class_name == "Haystack"
+        super
+      end
+
+      def migration_version
+        return unless Rails::VERSION::MAJOR >= 5
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+    end
+  end
+end