elasticsearch-model 0.0.1 → 0.1.0.rc1

data/lib/elasticsearch/model/naming.rb

@@ -0,0 +1,101 @@
+module Elasticsearch
+  module Model
+
+    # Provides methods for getting and setting index name and document type for the model
+    #
+    module Naming
+
+      module ClassMethods
+
+        # Get or set the name of the index
+        #
+        # @example Set the index name for the `Article` model
+        #
+        #     class Article
+        #       index_name "articles-#{Rails.env}"
+        #     end
+        #
+        # @example Directly set the index name for the `Article` model
+        #
+        #     Article.index_name "articles-#{Rails.env}"
+        #
+        # TODO: Dynamic names a la Tire -- `Article.index_name { "articles-#{Time.now.year}" }`
+        #
+        def index_name name=nil
+          @index_name = name || @index_name || self.model_name.collection.gsub(/\//, '-')
+        end
+
+        # Set the index name
+        #
+        # @see index_name
+        def index_name=(name)
+          @index_name = name
+        end
+
+        # Get or set the document type
+        #
+        # @example Set the document type for the `Article` model
+        #
+        #     class Article
+        #       document_type "my-article"
+        #     end
+        #
+        # @example Directly set the document type for the `Article` model
+        #
+        #     Article.document_type "my-article"
+        #
+        def document_type name=nil
+          @document_type = name || @document_type || self.model_name.element
+        end
+
+
+        # Set the document type
+        #
+        # @see document_type
+        #
+        def document_type=(name)
+          @document_type = name
+        end
+      end
+
+      module InstanceMethods
+
+        # Get or set the index name for the model instance
+        #
+        # @example Set the index name for an instance of the `Article` model
+        #
+        #     @article.index_name "articles-#{@article.user_id}"
+        #     @article.__elasticsearch__.update_document
+        #
+        def index_name name=nil
+          @index_name = name || @index_name || self.class.index_name
+        end
+
+        # Set the index name
+        #
+        # @see index_name
+        def index_name=(name)
+          @index_name = name
+        end
+
+        # @example Set the document type for an instance of the `Article` model
+        #
+        #     @article.document_type "my-article"
+        #     @article.__elasticsearch__.update_document
+        #
+        def document_type name=nil
+          @document_type = name || @document_type || self.class.document_type
+        end
+
+        # Set the document type
+        #
+        # @see document_type
+        #
+        def document_type=(name)
+          @document_type = name
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/model/proxy.rb

@@ -0,0 +1,127 @@
+module Elasticsearch
+  module Model
+
+    # This module provides a proxy interfacing between the including class and
+    # {Elasticsearch::Model}, preventing the pollution of the including class namespace.
+    #
+    # The only "gateway" between the model and Elasticsearch::Model is the
+    # `__elasticsearch__` class and instance method.
+    #
+    # The including class must be compatible with
+    # [ActiveModel](https://github.com/rails/rails/tree/master/activemodel).
+    #
+    # @example Include the {Elasticsearch::Model} module into an `Article` model
+    #
+    #     class Article < ActiveRecord::Base
+    #       include Elasticsearch::Model
+    #     end
+    #
+    #     Article.__elasticsearch__.respond_to?(:search)
+    #     # => true
+    #
+    #     article = Article.first
+    #
+    #     article.respond_to? :index_document
+    #     # => false
+    #
+    #     article.__elasticsearch__.respond_to?(:index_document)
+    #     # => true
+    #
+    module Proxy
+
+      # Define the `__elasticsearch__` class and instance methods in the including class
+      # and register a callback for intercepting changes in the model.
+      #
+      # @note The callback is triggered only when `Elasticsearch::Model` is included in the
+      #       module and the functionality is accessible via the proxy.
+      #
+      def self.included(base)
+        base.class_eval do
+          # {ClassMethodsProxy} instance, accessed as `MyModel.__elasticsearch__`
+          #
+          def self.__elasticsearch__ &block
+            @__elasticsearch__ ||= ClassMethodsProxy.new(self)
+            @__elasticsearch__.instance_eval(&block) if block_given?
+            @__elasticsearch__
+          end
+
+          # {InstanceMethodsProxy}, accessed as `@mymodel.__elasticsearch__`
+          #
+          def __elasticsearch__ &block
+            @__elasticsearch__ ||= InstanceMethodsProxy.new(self)
+            @__elasticsearch__.instance_eval(&block) if block_given?
+            @__elasticsearch__
+          end
+
+          # Register a callback for storing changed attributes for models which implement
+          # `before_save` and `changed_attributes` methods (when `Elasticsearch::Model` is included)
+          #
+          # @see http://api.rubyonrails.org/classes/ActiveModel/Dirty.html
+          #
+          before_save do |i|
+            i.__elasticsearch__.instance_variable_set(:@__changed_attributes,
+                                                      Hash[ i.changes.map { |key, value| [key, value.last] } ])
+          end if respond_to?(:before_save) && instance_methods.include?(:changed_attributes)
+        end
+      end
+
+      # Common module for the proxy classes
+      #
+      module Base
+        attr_reader :target
+
+        def initialize(target)
+          @target = target
+        end
+
+        # Delegate methods to `@target`
+        #
+        def method_missing(method_name, *arguments, &block)
+          target.respond_to?(method_name) ? target.__send__(method_name, *arguments, &block) : super
+        end
+
+        # Respond to methods from `@target`
+        #
+        def respond_to?(method_name, include_private = false)
+          target.respond_to?(method_name) || super
+        end
+
+        def inspect
+          "[PROXY] #{target.inspect}"
+        end
+      end
+
+      # A proxy interfacing between Elasticsearch::Model class methods and model class methods
+      #
+      # TODO: Inherit from BasicObject and make Pry's `ls` command behave?
+      #
+      class ClassMethodsProxy
+        include Base
+      end
+
+      # A proxy interfacing between Elasticsearch::Model instance methods and model instance methods
+      #
+      # TODO: Inherit from BasicObject and make Pry's `ls` command behave?
+      #
+      class InstanceMethodsProxy
+        include Base
+
+        def klass
+          target.class
+        end
+
+        def class
+          klass.__elasticsearch__
+        end
+
+        # Need to redefine `as_json` because we're not inheriting from `BasicObject`;
+        # see TODO note above.
+        #
+        def as_json(options={})
+          target.as_json(options)
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/model/response.rb

@@ -0,0 +1,70 @@
+module Elasticsearch
+  module Model
+
+    # Contains modules and classes for wrapping the response from Elasticsearch
+    #
+    module Response
+
+      # Encapsulate the response returned from the Elasticsearch client
+      #
+      # Implements Enumerable and forwards its methods to the {#results} object.
+      #
+      class Response
+        attr_reader :klass, :search, :response,
+                    :took, :timed_out, :shards
+
+        include Enumerable
+        extend  Support::Forwardable
+
+        forward :results, :each, :empty?, :size, :slice, :[], :to_ary
+
+        def initialize(klass, search, options={})
+          @klass     = klass
+          @search    = search
+        end
+
+        # Returns the Elasticsearch response
+        #
+        # @return [Hash]
+        #
+        def response
+          @response ||= search.execute!
+        end
+
+        # Returns the collection of "hits" from Elasticsearch
+        #
+        # @return [Results]
+        #
+        def results
+          @results ||= Results.new(klass, self)
+        end
+
+        # Returns the collection of records from the database
+        #
+        # @return [Records]
+        #
+        def records
+          @records ||= Records.new(klass, self)
+        end
+
+        # Returns the "took" time
+        #
+        def took
+          response['took']
+        end
+
+        # Returns whether the response timed out
+        #
+        def timed_out
+          response['timed_out']
+        end
+
+        # Returns the statistics on shards
+        #
+        def shards
+          Hashie::Mash.new(response['_shards'])
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/response/base.rb

@@ -0,0 +1,44 @@
+module Elasticsearch
+  module Model
+    module Response
+      # Common funtionality for classes in the {Elasticsearch::Model::Response} module
+      #
+      module Base
+        attr_reader :klass, :response
+
+        # @param klass    [Class] The name of the model class
+        # @param response [Hash]  The full response returned from Elasticsearch client
+        # @param options  [Hash]  Optional parameters
+        #
+        def initialize(klass, response, options={})
+          @klass     = klass
+          @response  = response
+        end
+
+        # @abstract Implement this method in specific class
+        #
+        def results
+          raise NotImplemented, "Implement this method in #{klass}"
+        end
+
+        # @abstract Implement this method in specific class
+        #
+        def records
+          raise NotImplemented, "Implement this method in #{klass}"
+        end
+
+        # Returns the total number of hits
+        #
+        def total
+          response.response['hits']['total']
+        end
+
+        # Returns the max_score
+        #
+        def max_score
+          response.response['hits']['max_score']
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/response/pagination.rb

@@ -0,0 +1,96 @@
+module Elasticsearch
+  module Model
+    module Response
+
+      # Pagination for search results/records
+      #
+      module Pagination
+        # Allow models to be paginated with the "kaminari" gem [https://github.com/amatsuda/kaminari]
+        #
+        module Kaminari
+          def self.included(base)
+            # Include the Kaminari configuration and paging method in response
+            #
+            base.__send__ :include, ::Kaminari::ConfigurationMethods::ClassMethods
+            base.__send__ :include, ::Kaminari::PageScopeMethods
+
+            # Include the Kaminari paging methods in results and records
+            #
+            Elasticsearch::Model::Response::Results.__send__ :include, ::Kaminari::ConfigurationMethods::ClassMethods
+            Elasticsearch::Model::Response::Results.__send__ :include, ::Kaminari::PageScopeMethods
+            Elasticsearch::Model::Response::Records.__send__ :include, ::Kaminari::PageScopeMethods
+
+            Elasticsearch::Model::Response::Results.__send__ :forward, :response, :limit_value, :offset_value, :total_count
+            Elasticsearch::Model::Response::Records.__send__ :forward, :response, :limit_value, :offset_value, :total_count
+
+            base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              # Define the `page` Kaminari method
+              #
+              def #{::Kaminari.config.page_method_name}(num=nil)
+                @results  = nil
+                @records  = nil
+                @response = nil
+                self.search.definition.update size: klass.default_per_page,
+                                              from: klass.default_per_page * ([num.to_i, 1].max - 1)
+                self
+              end
+            RUBY
+          end
+
+          # Returns the current "limit" (`size`) value
+          #
+          def limit_value
+            case
+              when search.definition[:body] && search.definition[:body][:size]
+                search.definition[:body][:size]
+              when search.definition[:size]
+                search.definition[:size]
+              else
+                0
+            end
+          end
+
+          # Returns the current "offset" (`from`) value
+          #
+          def offset_value
+            case
+              when search.definition[:body] && search.definition[:body][:from]
+                search.definition[:body][:from]
+              when search.definition[:from]
+                search.definition[:from]
+              else
+                0
+            end
+          end
+
+          # Set the "limit" (`size`) value
+          #
+          def limit(value)
+            @results  = nil
+            @records  = nil
+            @response = nil
+            search.definition.update :size => value
+            self
+          end
+
+          # Set the "offset" (`from`) value
+          #
+          def offset(value)
+            @results  = nil
+            @records  = nil
+            @response = nil
+            search.definition.update :from => value
+            self
+          end
+
+          # Returns the total number of results
+          #
+          def total_count
+            results.total
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/model/response/records.rb

@@ -0,0 +1,71 @@
+module Elasticsearch
+  module Model
+    module Response
+
+      # Encapsulates the collection of records returned from the database
+      #
+      # Implements Enumerable and forwards its methods to the {#records} object,
+      # which is provided by an {Elasticsearch::Model::Adapter::Adapter} implementation.
+      #
+      class Records
+        include Enumerable
+
+        extend  Support::Forwardable
+        forward :records, :each, :empty?, :size, :slice, :[], :to_a, :to_ary
+
+        include Base
+
+        # @see Base#initialize
+        #
+        def initialize(klass, response, options={})
+          super
+
+          # Include module provided by the adapter in the singleton class ("metaclass")
+          #
+          adapter = Adapter.from_class(klass)
+          metaclass = class << self; self; end
+          metaclass.__send__ :include, adapter.records_mixin
+
+          self
+        end
+
+        # Returns the hit IDs
+        #
+        def ids
+          response.response['hits']['hits'].map { |hit| hit['_id'] }
+        end
+
+        # Returns the {Results} collection
+        #
+        def results
+          response.results
+        end
+
+        # Yields [record, hit] pairs to the block
+        #
+        def each_with_hit(&block)
+          records.zip(results).each(&block)
+        end
+
+        # Yields [record, hit] pairs and returns the result
+        #
+        def map_with_hit(&block)
+          records.zip(results).map(&block)
+        end
+
+        # Delegate methods to `@records`
+        #
+        def method_missing(method_name, *arguments)
+          records.respond_to?(method_name) ? records.__send__(method_name, *arguments) : super
+        end
+
+        # Respond to methods from `@records`
+        #
+        def respond_to?(method_name, include_private = false)
+          records.respond_to?(method_name) || super
+        end
+
+      end
+    end
+  end
+end