algoliasearch-rails 1.19.1 → 2.2.2

data/LICENSE

@@ -1,7 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2013 Algolia
-http://www.algolia.com/
+Copyright (c) 2013-Present Algolia
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -10,13 +9,13 @@ 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 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.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,35 +1,50 @@
-# Algolia Search API Client for Rails
-
-[Algolia Search](https://www.algolia.com) is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.
-
-[![Build Status](https://travis-ci.org/algolia/algoliasearch-rails.svg?branch=master)](https://travis-ci.org/algolia/algoliasearch-rails) [![Gem Version](https://badge.fury.io/rb/algoliasearch-rails.svg)](http://badge.fury.io/rb/algoliasearch-rails) [![Code Climate](https://codeclimate.com/github/algolia/algoliasearch-rails.svg)](https://codeclimate.com/github/algolia/algoliasearch-rails) ![ActiveRecord](https://img.shields.io/badge/ActiveRecord-yes-blue.svg?style=flat-square) ![Mongoid](https://img.shields.io/badge/Mongoid-yes-blue.svg?style=flat-square) ![Sequel](https://img.shields.io/badge/Sequel-yes-blue.svg?style=flat-square)
+<p align="center">
+  <a href="https://www.algolia.com">
+    <img alt="Algolia for Rails" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/rails.png"/>
+  </a>
+</p>
+
+<h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your Rails project</h4>
+
+<p align="center">
+  <a href="https://circleci.com/gh/algolia/algoliasearch-rails"><img src="https://circleci.com/gh/algolia/algoliasearch-rails.svg?style=shield" alt="CircleCI" /></a>
+  <a href="http://badge.fury.io/rb/algoliasearch-rails"><img src="https://badge.fury.io/rb/algoliasearch-rails.svg" alt="Gem Version"/></a>
+  <a href="https://codeclimate.com/github/algolia/algoliasearch-rails"><img src="https://codeclimate.com/github/algolia/algoliasearch-rails.svg" alt="Code Climate"/></a>
+  <img src="https://img.shields.io/badge/ActiveRecord-yes-blue.svg?style=flat-square" alt="ActiveRecord"/>
+  <img src="https://img.shields.io/badge/Mongoid-yes-blue.svg?style=flat-square" alt="Mongoid"/>
+  <img src="https://img.shields.io/badge/Sequel-yes-blue.svg?style=flat-square" alt="Sequel"/>
+</p>
+
+<p align="center">
+  <a href="https://www.algolia.com/doc/framework-integration/rails/getting-started/setup/?language=ruby" target="_blank">Documentation</a>  •
+  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
+  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
+  <a href="https://github.com/algolia/algoliasearch-rails/issues" target="_blank">Report a bug</a>  •
+  <a href="https://www.algolia.com/doc/framework-integration/rails/troubleshooting/faq/" target="_blank">FAQ</a>  •
+  <a href="https://www.algolia.com/support" target="_blank">Support</a>
+</p>
 
 
 This gem let you easily integrate the Algolia Search API to your favorite ORM. It's based on the [algoliasearch-client-ruby](https://github.com/algolia/algoliasearch-client-ruby) gem.
-Rails 3.x, 4.x and 5.x are all supported.
-
-You might be interested in the sample Ruby on Rails application providing a `autocomplete.js`-based auto-completion and `instantsearch.js`-based instant search results page: [algoliasearch-rails-example](https://github.com/algolia/algoliasearch-rails-example/).
+Rails 5.x and 6.x are supported.
 
+You might be interested in the sample Ruby on Rails application providing a `autocomplete.js`-based auto-completion and `InstantSearch.js`-based instant search results page: [algoliasearch-rails-example](https://github.com/algolia/algoliasearch-rails-example/).
 
 
 
 ## API Documentation
 
-You can find the full reference on [Algolia's website](https://www.algolia.com/doc/api-client/rails/).
+You can find the full reference on [Algolia's website](https://www.algolia.com/doc/framework-integration/rails/).
 
 
-## Table of Contents
-
 
 1. **[Setup](#setup)**
-
     * [Install](#install)
     * [Configuration](#configuration)
     * [Timeouts](#timeouts)
     * [Notes](#notes)
 
 1. **[Usage](#usage)**
-
     * [Index Schema](#index-schema)
     * [Relevancy](#relevancy)
     * [Indexing](#indexing)
@@ -43,13 +58,12 @@ You can find the full reference on [Algolia's website](https://www.algolia.com/d
     * [Geo-Search](#geo-search)
 
 1. **[Options](#options)**
-
     * [Auto-indexing &amp; asynchronism](#auto-indexing--asynchronism)
     * [Custom index name](#custom-index-name)
     * [Per-environment indices](#per-environment-indices)
     * [Custom attribute definition](#custom-attribute-definition)
     * [Nested objects/relations](#nested-objectsrelations)
-    * [Custom `objectID`](#custom-objectid)
+    * [Custom <code>objectID</code>](#custom-objectid)
     * [Restrict indexing to a subset of your data](#restrict-indexing-to-a-subset-of-your-data)
     * [Sanitizer](#sanitizer)
     * [UTF-8 Encoding](#utf-8-encoding)
@@ -57,7 +71,6 @@ You can find the full reference on [Algolia's website](https://www.algolia.com/d
     * [Configuration example](#configuration-example)
 
 1. **[Indices](#indices)**
-
     * [Manual indexing](#manual-indexing)
     * [Manual removal](#manual-removal)
     * [Reindexing](#reindexing)
@@ -68,9 +81,10 @@ You can find the full reference on [Algolia's website](https://www.algolia.com/d
     * [Target multiple indices](#target-multiple-indices)
 
 1. **[Testing](#testing)**
-
     * [Notes](#notes)
 
+1. **[Troubleshooting](#troubleshooting)**
+    * [Frequently asked questions](#frequently-asked-questions)
 
 
 
@@ -113,7 +127,7 @@ You can configure a various timeout thresholds by setting the following options
 ```ruby
 AlgoliaSearch.configuration = {
   application_id: 'YourApplicationID',
-  api_key: 'YourAPIKey'
+  api_key: 'YourAPIKey',
   connect_timeout: 2,
   receive_timeout: 30,
   send_timeout: 30,
@@ -124,7 +138,7 @@ AlgoliaSearch.configuration = {
 
 ## Notes
 
-This gem makes intensive use of Rails' callbacks to trigger the indexing tasks. If you're using methods bypassing `after_validation`, `before_save` or `after_commit` callbacks, it will not index your changes. For example: `update_attribute` doesn't perform validations checks, to perform validations when updating use `update_attributes`.
+This gem makes extensive use of Rails' callbacks to trigger the indexing tasks. If you're using methods bypassing `after_validation`, `before_save` or `after_commit` callbacks, it will not index your changes. For example: `update_attribute` doesn't perform validations checks, to perform validations when updating use `update_attributes`.
 
 All methods injected by the `AlgoliaSearch` module are prefixed by `algolia_` and aliased to the associated short names if they aren't already defined.
 
@@ -135,6 +149,7 @@ Contact.algolia_search("jon doe") # <=> Contact.search("jon doe")
 ```
 
 
+
 # Usage
 
 
@@ -148,7 +163,7 @@ class Contact < ActiveRecord::Base
   include AlgoliaSearch
 
   algoliasearch do
-    attribute :first_name, :last_name, :email
+    attributes :first_name, :last_name, :email
   end
 end
 ```
@@ -291,8 +306,8 @@ class Contact < ActiveRecord::Base
     attribute :first_name, :last_name, :email
 
     # default search parameters stored in the index settings
-    minWordSizeForApprox1 4
-    minWordSizeForApprox2 8
+    minWordSizefor1Typo 4
+    minWordSizefor2Typos 8
     hitsPerPage 42
   end
 end
@@ -300,7 +315,7 @@ end
 
 ```ruby
 # dynamical search parameters
-p Contact.raw_search("jon doe", { :hitsPerPage => 5, :page => 2 })
+p Contact.raw_search('jon doe', { hitsPerPage: 5, page: 2 })
 ```
 
 ## Backend Pagination
@@ -375,7 +390,7 @@ end
 ```
 
 ```ruby
-hits = Contact.search("jon doe", { :facets => '*' })
+hits = Contact.search('jon doe', { facets: '*' })
 p hits                    # ORM-compliant array of objects
 p hits.facets             # extra method added to retrieve facets
 p hits.facets['company']  # facet values+count of facet 'company'
@@ -383,7 +398,7 @@ p hits.facets['zip_code'] # facet values+count of facet 'zip_code'
 ```
 
 ```ruby
-raw_json = Contact.raw_search("jon doe", { :facets => '*' })
+raw_json = Contact.raw_search('jon doe', { facets: '*' })
 p raw_json['facets']
 ```
 
@@ -409,7 +424,7 @@ Product.search_for_facet_values('category', 'phone', {
 ## Group by
 
 More info on distinct for grouping can be found
-[here](https://www.algolia.com/doc/guides/search/distinct#distinct-for-grouping).
+[here](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/).
 
 ```ruby
 class Contact < ActiveRecord::Base
@@ -442,13 +457,14 @@ end
 At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
 
 
+
 # Options
 
 
 
 ## Auto-indexing & asynchronism
 
-Each time a record is saved; it will be - asynchronously - indexed. On the other hand, each time a record is destroyed, it will be - asynchronously - removed from the index. That means that a network call with the ADD/DELETE operation is sent **synchronously** to the Algolia API but then the engine will **asynchronously** process the operation (so if you do a search just after, the results may not reflect it yet).
+Each time a record is saved, it will be *asynchronously* indexed. On the other hand, each time a record is destroyed, it will be - asynchronously - removed from the index. That means that a network call with the ADD/DELETE operation is sent **synchronously** to the Algolia API but then the engine will **asynchronously** process the operation (so if you do a search just after, the results may not reflect it yet).
 
 You can disable auto-indexing and auto-removing setting the following options:
 
@@ -501,7 +517,7 @@ class MySidekiqWorker
     if remove
       # the record has likely already been removed from your database so we cannot
       # use ActiveRecord#find to load it
-      index = Algolia::Index.new("index_name")
+      index = AlgoliaSearch.client.init_index("index_name")
       index.delete_object(id)
     else
       # the record should be present
@@ -531,8 +547,16 @@ end
 
 class MySidekiqWorker
   def perform(id, remove)
-    c = Contact.find(id)
-    remove ? c.remove_from_index! : c.index!
+    if remove
+      # the record has likely already been removed from your database so we cannot
+      # use ActiveRecord#find to load it
+      index = AlgoliaSearch.client.init_index("index_name")
+      index.delete_object(id)
+    else
+      # the record should be present
+      c = Contact.find(id)
+      c.index!
+    end
   end
 end
 ```
@@ -645,6 +669,8 @@ end
 
 ## Nested objects/relations
 
+### Defining the relationship
+
 You can easily embed nested objects defining an extra attribute returning any JSON-compliant object (an array or a hash or a combination of both).
 
 ```ruby
@@ -670,6 +696,82 @@ class Profile < ActiveRecord::Base
 end
 ```
 
+### Propagating the change from a nested child
+
+#### With ActiveRecord
+
+With ActiveRecord, we'll be using `touch` and `after_touch` to achieve this.
+
+```ruby
+# app/models/app.rb
+class App < ApplicationRecord
+  include AlgoliaSearch
+
+  belongs_to :author, class_name: :User
+  after_touch :index!
+
+  algoliasearch do
+    attribute :title
+    attribute :author do
+      author.as_json
+    end
+  end
+end
+
+# app/models/user.rb
+class User < ApplicationRecord
+  # If your association uses belongs_to
+  # - use `touch: true`
+  # - do not define an `after_save` hook
+  has_many :apps, foreign_key: :author_id
+
+  after_save { apps.each(&:touch) }
+end
+```
+
+#### With Sequel
+
+With Sequel, you can use the `touch` plugin to propagate the changes:
+
+```ruby
+# app/models/app.rb
+class App < Sequel::Model
+  include AlgoliaSearch
+
+  many_to_one :author, class: :User
+
+  plugin :timestamps
+  plugin :touch
+
+  algoliasearch do
+    attribute :title
+    attribute :author do
+      author.to_hash
+    end
+  end
+end
+
+# app/models/user.rb
+class User < Sequel::Model
+  one_to_many :apps, key: :author_id
+
+  plugin :timestamps
+  # Can't use the associations since it won't trigger the after_save
+  plugin :touch
+
+  # Define the associations that need to be touched here
+  # Less performant, but allows for the after_save hook to trigger
+  def touch_associations
+    apps.map(&:touch)
+  end
+
+  def touch
+    super
+    touch_associations
+  end
+end
+```
+
 ## Custom `objectID`
 
 By default, the `objectID` is based on your record's `id`. You can change this behavior specifying the `:id` option (be sure to use a uniq field).
@@ -849,6 +951,7 @@ end
 ```
 
 
+
 # Indices
 
 
@@ -885,6 +988,8 @@ Contact.reindex
 
 **Notes**: if you're using an index-specific API key, ensure you're allowing both `<INDEX_NAME>` and `<INDEX_NAME>.tmp`.
 
+**Warning:** You should not use such an atomic reindexing operation while scoping/filtering the model because this operation **replaces the entire index**, keeping the filtered objects only. ie: Don't do `MyModel.where(...).reindex` but do `MyModel.where(...).reindex!` (with the trailing `!`)!!!
+
 ### Regular reindexing
 
 To reindex all your objects in place (without temporary index and therefore without deleting removed objects), use the `reindex!` class method:
@@ -1028,13 +1133,14 @@ Book.search 'foo bar', index: 'Book_by_editor'
 ```
 
 
+
 # Testing
 
 
 
 ## Notes
 
-To run the specs, please set the <code>ALGOLIA_APPLICATION_ID</code> and <code>ALGOLIA_API_KEY</code> environment variables. Since the tests are creating and removing indexes, DO NOT use your production account.
+To run the specs, please set the <code>ALGOLIA_APPLICATION_ID</code> and <code>ALGOLIA_API_KEY</code> environment variables. Since the tests are creating and removing indices, DO NOT use your production account.
 
 You may want to disable all indexing (add, update & delete operations) API calls, you can set the `disable_indexing` option:
 
@@ -1042,40 +1148,24 @@ You may want to disable all indexing (add, update & delete operations) API calls
 class User < ActiveRecord::Base
   include AlgoliaSearch
 
-  algoliasearch :per_environment => true, :disable_indexing => Rails.env.test? do
+  algoliasearch per_environment: true, disable_indexing: Rails.env.test? do
   end
 end
 
 class User < ActiveRecord::Base
   include AlgoliaSearch
 
-  algoliasearch :per_environment => true, :disable_indexing => Proc.new { Rails.env.test? || more_complex_condition } do
+  algoliasearch per_environment: true, disable_indexing: Proc.new { Rails.env.test? || more_complex_condition } do
   end
 end
 ```
 
-Or you may want to mock Algolia's API calls. We provide a [WebMock](https://github.com/bblimke/webmock) sample configuration that you can use including `algolia/webmock`:
-
-```ruby
-require 'algolia/webmock'
 
-describe 'With a mocked client' do
+## ❓ Troubleshooting
 
-  before(:each) do
-    WebMock.enable!
-  end
-
-  it "shouldn't perform any API calls here" do
-    User.create(name: 'My Indexed User')  # mocked, no API call performed
-    User.search('').should == {}          # mocked, no API call performed
-  end
-
-  after(:each) do
-    WebMock.disable!
-  end
-
-end
-```
+Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/ruby/) where you will find answers for the most common issues and gotchas with the client.
 
+## Use the Dockerfile
 
+If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our [dedicated guide](DOCKER_README.MD) to learn more.
 

data/algoliasearch-rails.gemspec

@@ -1,10 +1,12 @@
 # -*- encoding: utf-8 -*-
 
-VERSION = File.read(File.join(File.dirname(__FILE__), 'VERSION')).strip
+require File.join(File.dirname(__FILE__), 'lib', 'algoliasearch', 'version')
+
+require 'date'
 
 Gem::Specification.new do |s|
   s.name = "algoliasearch-rails"
-  s.version = VERSION
+  s.version = AlgoliaSearch::VERSION
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Algolia"]
@@ -12,21 +14,19 @@ Gem::Specification.new do |s|
   s.description = "AlgoliaSearch integration to your favorite ORM"
   s.email = "contact@algolia.com"
   s.extra_rdoc_files = [
-    "ChangeLog",
+    "CHANGELOG.MD",
     "LICENSE",
     "README.md"
   ]
   s.files = [
     ".document",
     ".rspec",
-    ".travis.yml",
-    "ChangeLog",
+    "CHANGELOG.MD",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE",
     "README.md",
     "Rakefile",
-    "VERSION",
     "algoliasearch-rails.gemspec",
     "lib/algoliasearch-rails.rb",
     "lib/algoliasearch/algolia_job.rb",
@@ -37,6 +37,7 @@ Gem::Specification.new do |s|
     "lib/algoliasearch/railtie.rb",
     "lib/algoliasearch/tasks/algoliasearch.rake",
     "lib/algoliasearch/utilities.rb",
+    "lib/algoliasearch/version.rb",
     "spec/spec_helper.rb",
     "spec/utilities_spec.rb",
     "vendor/assets/javascripts/algolia/algoliasearch.angular.js",
@@ -77,19 +78,18 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<json>, [">= 1.5.1"])
-      s.add_runtime_dependency(%q<algoliasearch>, ["~> 1.12.4"])
+      s.add_runtime_dependency(%q<algolia>, ["< 3.0.0"])
       s.add_development_dependency(%q<will_paginate>, [">= 2.3.15"])
       s.add_development_dependency(%q<kaminari>, [">= 0"])
-      s.add_development_dependency "travis"
       s.add_development_dependency "rake"
       s.add_development_dependency "rdoc"
     else
       s.add_dependency(%q<json>, [">= 1.5.1"])
-      s.add_dependency(%q<algoliasearch>, ["~> 1.12.1"])
+      s.add_dependency(%q<algolia>, ["< 3.0.0"])
     end
   else
     s.add_dependency(%q<json>, [">= 1.5.1"])
-    s.add_dependency(%q<algoliasearch>, ["~> 1.12.1"])
+    s.add_dependency(%q<algolia>, ["< 3.0.0"])
   end
 end
 

data/lib/algoliasearch/configuration.rb

@@ -1,12 +1,38 @@
 module AlgoliaSearch
   module Configuration
+    def initialize
+      @client = nil
+    end
+
     def configuration
       @@configuration || raise(NotConfigured, "Please configure AlgoliaSearch. Set AlgoliaSearch.configuration = {application_id: 'YOUR_APPLICATION_ID', api_key: 'YOUR_API_KEY'}")
     end
 
     def configuration=(configuration)
-      @@configuration = configuration
-      Algolia.init @@configuration
+      @@configuration = configuration.merge(
+        :user_agent => "Algolia for Rails (#{AlgoliaSearch::VERSION}); Rails (#{Rails::VERSION::STRING})",
+        :symbolize_keys => false
+      )
+    end
+
+    def client_opts
+      @@opts ||= {}
+    end
+
+    def client_opts=(opts)
+      @@opts = opts
+    end
+
+    def client
+      if @client.nil?
+        setup_client
+      end
+
+      @client
+    end
+
+    def setup_client
+      @client = Algolia::Search::Client.new(Algolia::Search::Config.new(@@configuration), client_opts)
     end
   end
 end

data/lib/algoliasearch/pagination/kaminari.rb

@@ -9,7 +9,7 @@ module AlgoliaSearch
     class Kaminari < ::Kaminari::PaginatableArray
 
       def initialize(array, options)
-        super(array, options)
+        super(array, **options)
       end
 
       def limit(num)

data/lib/algoliasearch/tasks/algoliasearch.rake

@@ -1,9 +1,14 @@
 namespace :algoliasearch do
- 
+
   desc "Reindex all models"
   task :reindex => :environment do
     AlgoliaSearch::Utilities.reindex_all_models
   end
+
+  desc "Set settings to all indexes"
+  task :set_all_settings => :environment do
+    AlgoliaSearch::Utilities.set_settings_all_models
+  end
   
   desc "Clear all indexes"
   task :clear_indexes => :environment do

data/lib/algoliasearch/utilities.rb

@@ -2,7 +2,11 @@ module AlgoliaSearch
   module Utilities
     class << self
       def get_model_classes
-        Rails.application.eager_load! if Rails.application # Ensure all models are loaded (not necessary in production when cache_classes is true).
+        if Rails.application && defined?(Rails.autoloaders) && Rails.autoloaders.zeitwerk_enabled?
+          Zeitwerk::Loader.eager_load_all
+        elsif Rails.application
+          Rails.application.eager_load!
+        end
         AlgoliaSearch.instance_variable_get :@included_in
       end
 
@@ -20,11 +24,22 @@ module AlgoliaSearch
         puts ''
 
         klasses.each do |klass|
-          say "#{klass}:"
+          puts klass
+          puts "Reindexing #{klass.count} records..."
+          klass.algolia_reindex
+        end
+      end
+
+      def set_settings_all_models
+        klasses = get_model_classes
 
-          say "Reindexing #{klass.count} records...", true
+        puts ''
+        puts "Pushing settings for #{klasses.count} models: #{klasses.to_sentence}."
+        puts ''
 
-          klass.algolia_reindex
+        klasses.each do |klass|
+          puts "Pushing #{klass} settings..."
+          klass.algolia_set_settings
         end
       end
     end

data/lib/algoliasearch/version.rb

@@ -0,0 +1,3 @@
+module AlgoliaSearch
+  VERSION = '2.2.2'
+end