lotus-rethinkdb 0.1.1

data/lib/lotus/model/adapters/rethinkdb/query.rb

@@ -0,0 +1,364 @@
+require 'forwardable'
+require 'lotus/utils/kernel'
+require 'rethinkdb'
+
+module Lotus
+  module Model
+    module Adapters
+      module Rethinkdb
+        # Query the database with a powerful API.
+        #
+        # All the methods are chainable, it allows advanced composition of
+        # ReQL conditions.
+        #
+        # This works as a lazy filtering mechanism: the documents are fetched
+        # from the database only when needed.
+        #
+        # @example
+        #
+        #   query.where(language: 'ruby')
+        #        .and(framework: 'lotus')
+        #        .desc(:users_count).all
+        #
+        #   # the documents are fetched only when we invoke #all
+        #
+        # It implements Ruby's `Enumerable` and borrows some methods from
+        # `Array`. Expect a query to act like them.
+        #
+        # @since 0.1.0
+        class Query
+          include RethinkDB::Shortcuts
+          include Enumerable
+          extend Forwardable
+
+          def_delegators :all, :each, :to_s, :empty?
+
+          # @attr_reader conditions [Array] an accumulator for the called
+          #   methods
+          #
+          # @since 0.1.0
+          # @api private
+          attr_reader :conditions
+
+          # Initialize a query
+          #
+          # @param collection [Lotus::Model::Adapters::Rethinkdb::Collection]
+          #   the collection to query
+          #
+          # @param blk [Proc] an optional block that gets yielded in the
+          #   context of the current query
+          #
+          # @return [Lotus::Model::Adapters::Rethinkdb::Query]
+          def initialize(collection, context = nil, &blk)
+            @collection, @context = collection, context
+            @conditions = []
+
+            instance_eval(&blk) if block_given?
+          end
+
+          # Resolves the query by fetching documents from the database and
+          # translating them into entities.
+          #
+          # @return [Array] a collection of entities
+          #
+          # @since 0.1.0
+          def all
+            scoped.execute
+          end
+
+          # Adds a condition like SQL `WHERE` using r.filter().
+          #
+          # It accepts a `Hash` with only one pair.
+          # The key must be the name of the field expressed as a `Symbol`.
+          # The value is the one used by the ReQL query
+          #
+          # @param condition [Hash]
+          #
+          # @return self
+          #
+          # @since 0.1.0
+          #
+          # @example Fixed value
+          #
+          #   query.where(language: 'ruby')
+          #
+          #   # => r.filter(language: 'ruby')
+          #
+          # @example Multiple conditions
+          #
+          #   query.where(language: 'ruby')
+          #        .where(framework: 'lotus')
+          #
+          #   # => r.filter(language: 'ruby').filter('framework: 'lotus')
+          #
+          # @example Blocks
+          #
+          #   query.where { |doc| doc['age'] > 10 }
+          #
+          #   # => r.filter { |doc| doc.bracket('age').gt('10') }
+          def where(condition = nil, &blk)
+            condition = condition || blk ||
+                        fail(ArgumentError, 'You need to specify a condition.')
+            conditions.push([:filter, condition])
+            self
+          end
+
+          alias_method :and, :where
+
+          # Pluck only the specified fields. Documents without the fields are
+          # omitted.
+          #
+          # By default a query includes all the fields of a table.
+          #
+          # @param fields [Array<Symbol>]
+          #
+          # @return self
+          #
+          # @since 0.1.0
+          #
+          # @example Single field
+          #
+          #   query.pluck(:name)
+          #
+          #   # => r.pluck(:name)
+          #
+          # @example Multiple fields
+          #
+          #   query.pluck(:name, :year)
+          #
+          #   # => r.pluck(:name, :year)
+          def pluck(*fields)
+            conditions.push([:pluck, *fields])
+            self
+          end
+
+          # Limit the number of documents to return.
+          #
+          # This operation is performed at the database level with r.limit().
+          #
+          # @param number [Fixnum]
+          #
+          # @return self
+          #
+          # @since 0.1.0
+          #
+          # @example
+          #
+          #   query.limit(1)
+          #
+          #   # => r.limit(1)
+          def limit(number)
+            conditions.push([:limit, number])
+            self
+          end
+
+          # Specify the ascending order of the documents, sorted by the given
+          # fields or index. Identify an index using `{ index: :key }`.
+          #
+          # The last invokation of this method takes precidence. Previously
+          # called sorts will be overwritten by RethinkDB.
+          #
+          # @param fields [Array<Symbol, Hash>] the field names, optionally with
+          #   an index identifier
+          #
+          # @return self
+          #
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters::Rethinkdb::Query#desc
+          #
+          # @example Single field
+          #
+          #   query.order(:name)
+          #
+          #   # => r.order_by(:name)
+          #
+          # @example Multiple columns
+          #
+          #   query.order(:name, :year)
+          #
+          #   # => r.order_by(:name, :year)
+          #
+          # @example Single index
+          #
+          #   query.order(index: :date)
+          #
+          #   # => r.order_by(index: :date)
+          #
+          # @example Mixed fields and index
+          #
+          #   query.order(:name, :year, index: :date)
+          #
+          #   # => r.order_by(:name, :year, index: :date)
+          def order(*fields)
+            conditions.push([:order_by, *fields])
+            self
+          end
+
+          alias_method :asc, :order
+
+          # Specify the descending order of the documents, sorted by the given
+          # fields or index. Identify an index using `{ index: :key }`.
+          #
+          # The last invokation of this method takes precidence. Previously
+          # called sorts will be overwritten by RethinkDB.
+          #
+          # @return self
+          #
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters::Rethinkdb::Query#desc
+          #
+          # @example Single field
+          #
+          #   query.desc(:name)
+          #
+          #   # => r.order_by(r.desc(:name))
+          #
+          # @example Multiple columns
+          #
+          #   query.desc(:name, :year)
+          #
+          #   # => r.order_by(r.desc(:name), r.desc(:year))
+          #
+          # @example Single index
+          #
+          #   query.desc(index: :date)
+          #
+          #   # => r.order_by(index: r.desc(:date))
+          #
+          # @example Mixed fields and index
+          #
+          #   query.desc(r.desc(:name), r.desc(:year), index: r.desc(:date))
+          #
+          #   # => r.order_by(:name, :year, index: :date)
+          def desc(*fields)
+            conditions.push([:order_by, *_desc_wrapper(*fields)])
+            self
+          end
+
+          # Apply all the conditions and returns a filtered collection.
+          #
+          # This operation is idempotent, and the returned result didn't
+          # fetched the documents yet.
+          #
+          # @return [Lotus::Model::Adapters::Rethinkdb::Collection]
+          #
+          # @since 0.1.0
+          def scoped
+            scope = @collection
+
+            conditions.each do |(method, *args)|
+              scope = scope.public_send(method, *args)
+            end
+
+            scope
+          end
+
+          protected
+
+          # Handles missing methods for query combinations
+          #
+          # @api private
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters:Rethinkdb::Query#apply
+          def method_missing(m, *args, &blk)
+            if @context.respond_to?(m)
+              apply @context.public_send(m, *args, &blk)
+            else
+              super
+            end
+          end
+
+          private
+
+          # Returns a new query that is the result of the merge of the current
+          # conditions with the ones of the given query.
+          #
+          # This is used to combine queries together in a Repository.
+          #
+          # @param query [Lotus::Model::Adapters::Rethinkdb::Query] the query
+          #   to apply
+          #
+          # @return [Lotus::Model::Adapters::Rethinkdb::Query] a new query with
+          #   the merged conditions
+          #
+          # @api private
+          # @since 0.1.0
+          #
+          # @example
+          #   require 'lotus/model'
+          #
+          #   class ArticleRepository
+          #     include Lotus::Repository
+          #
+          #     def self.by_author(author)
+          #       query do
+          #         where(author_id: author.id)
+          #       end
+          #     end
+          #
+          #     def self.rank
+          #       query.desc(:comments_count)
+          #     end
+          #
+          #     def self.rank_by_author(author)
+          #       rank.by_author(author)
+          #     end
+          #   end
+          #
+          #   # The code above combines two queries: `rank` and `by_author`.
+          #   #
+          #   # The first class method `rank` returns a `Rethinkdb::Query`
+          #   # instance which doesn't respond to `by_author`. How to solve
+          #   # this problem?
+          #   #
+          #   # 1. When we use `query` to fabricate a `Rethinkdb::Query` we
+          #   # pass the current context (the repository itself) to the query
+          #   # initializer.
+          #   #
+          #   # 2. When that query receives the `by_author` message, it's
+          #   # captured by `method_missing` and dispatched to the repository.
+          #   #
+          #   # 3. The class method `by_author` returns a query too.
+          #   #
+          #   # 4. We just return a new query that is the result of the current
+          #   # query's conditions (`rank`) and of the conditions from
+          #   # `by_author`.
+          #   #
+          #   # You're welcome ;)
+          def apply(query)
+            dup.tap do |result|
+              result.conditions.push(*query.conditions)
+            end
+          end
+
+          # Wrap the given fields with a desc operator.
+          #
+          # @return [Array] the wrapped fields
+          #
+          # @api private
+          # @since 0.1.0
+          def _desc_wrapper(*fields)
+            Array(fields).map do |field|
+              if field.is_a?(Hash)
+                field.merge(field) { |_k, v| r.desc(v) }
+              else
+                r.desc(field)
+              end
+            end
+          end
+
+          # Run the enclosed block on the database.
+          #
+          # @api private
+          # @since 0.1.0
+          def _run
+            yield.run(@connection)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lotus/model/adapters/rethinkdb_adapter.rb

@@ -0,0 +1,234 @@
+require 'lotus/model/adapters/abstract'
+require 'lotus/model/adapters/rethinkdb/collection'
+require 'lotus/model/adapters/rethinkdb/command'
+require 'lotus/model/adapters/rethinkdb/query'
+require 'rethinkdb'
+
+module Lotus
+  module Model
+    module Adapters
+      # Adapter for RethinkDB databases
+      #
+      # @see Lotus::Model::Adapters::Implementation
+      #
+      # @api private
+      # @since 0.1.0
+      class RethinkdbAdapter < Abstract
+        include ::RethinkDB::Shortcuts
+
+        # Initialize the adapter.
+        #
+        # Lotus::Model uses RethinkDB.
+        #
+        # @param mapper [Object] the database mapper
+        # @param connection [RethinkDB::Connection] the database connection
+        #
+        # @return [Lotus::Model::Adapters::RethinkdbAdapter]
+        #
+        # @see Lotus::Model::Mapper
+        # @see http://rethinkdb.com/api/ruby/
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(mapper, connection)
+          super(mapper)
+          @connection = connection
+        end
+
+        # Creates or updates a document in the database for the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id, #id=] the entity to persist
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def persist(collection, entity)
+          if entity.id
+            update(collection, entity)
+          else
+            create(collection, entity)
+          end
+        end
+
+        # Creates a document in the database for the given entity.
+        # It assigns the `id` attribute, in case of success.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id=] the entity to create
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def create(collection, entity)
+          entity.id = command(
+                        query(collection)
+                      ).create(entity)
+          entity
+        end
+
+        # Updates a document in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to update
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def update(collection, entity)
+          command(
+            _find(collection, entity.id)
+          ).update(entity)
+        end
+
+        # Deletes a document in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to delete
+        #
+        # @api private
+        # @since 0.1.0
+        def delete(collection, entity)
+          command(
+            _find(collection, entity.id)
+          ).delete
+        end
+
+        # Returns all the documents for the given collection
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Array] all the documents
+        #
+        # @api private
+        # @since 0.1.0
+        def all(collection)
+          query(collection).all
+        end
+
+        # Returns a unique document from the given collection, with the given
+        # id.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param id [Object] the identity of the object.
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.1.0
+        def find(collection, id)
+          _first(
+            _find(collection, id)
+          )
+        end
+
+        # This method is not implemented. RethinkDB does not have sequential
+        # primary keys.
+        #
+        # @param _collection [Symbol] the target collection (it must be mapped)
+        #
+        # @raise [NotImplementedError]
+        #
+        # @since 0.1.0
+        def first(_collection)
+          fail NotImplementedError
+        end
+
+        # This method is not implemented. RethinkDB does not have sequential
+        # primary keys.
+        #
+        # @param _collection [Symbol] the target collection (it must be mapped)
+        #
+        # @raise [NotImplementedError]
+        #
+        # @since 0.1.0
+        def last(_collection)
+          fail NotImplementedError
+        end
+
+        # Deletes all the documents from the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @api private
+        # @since 0.1.0
+        def clear(collection)
+          command(query(collection)).clear
+        end
+
+        # Fabricates a command for the given query.
+        #
+        # @param query [Lotus::Model::Adapters::Rethinkdb::Query] the query
+        # object to act on.
+        #
+        # @return [Lotus::Model::Adapters::Rethinkdb::Command]
+        #
+        # @see Lotus::Model::Adapters::Rethinkdb::Command
+        #
+        # @api private
+        # @since 0.1.0
+        def command(query)
+          Rethinkdb::Command.new(query)
+        end
+
+        # Fabricates a query
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param blk [Proc] a block of code to be executed in the context of
+        #   the query.
+        #
+        # @return [Lotus::Model::Adapters::Rethinkdb::Query]
+        #
+        # @see Lotus::Model::Adapters::Rethinkdb::Query
+        #
+        # @api private
+        # @since 0.1.0
+        def query(collection, context = nil, &blk)
+          Rethinkdb::Query.new(_collection(collection), context, &blk)
+        end
+
+        private
+
+        # Returns a collection from the given name.
+        #
+        # @param name [Symbol] a name of the collection (it must be mapped).
+        #
+        # @return [Lotus::Model::Adapters::Rethinkdb::Collection]
+        #
+        # @see Lotus::Model::Adapters::Rethinkdb::Collection
+        #
+        # @api private
+        # @since 0.1.0
+        def _collection(name)
+          Rethinkdb::Collection.new(
+            @connection, r.table(name), _mapped_collection(name)
+          )
+        end
+
+        def _mapped_collection(name)
+          @mapper.collection(name)
+        end
+
+        def _find(collection, id)
+          identity = _identity(collection)
+          query(collection).where(identity => _id(collection, identity, id))
+        end
+
+        def _first(query)
+          query.limit(1).first
+        end
+
+        def _identity(collection)
+          _mapped_collection(collection).identity
+        end
+
+        def _id(collection, column, value)
+          _mapped_collection(collection).deserialize_attribute(column, value)
+        end
+      end
+    end
+  end
+end

data/lib/lotus/rethinkdb/version.rb

@@ -0,0 +1,16 @@
+module Lotus
+  module Model
+    module Adapters
+      # Adapter for RethinkDB databases
+      #
+      # @api private
+      # @since 0.1.0
+      module Rethinkdb
+        # Defines the version
+        #
+        # @since 0.1.0
+        VERSION = '0.1.1'
+      end
+    end
+  end
+end

data/lib/lotus-rethinkdb.rb

@@ -0,0 +1,2 @@
+require 'lotus/model' # rubocop:disable Style/FileName
+require 'lotus/model/adapters/rethinkdb_adapter'

data/lotus-rethinkdb.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lotus/rethinkdb/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lotus-rethinkdb'
+  spec.version       = Lotus::Model::Adapters::Rethinkdb::VERSION
+  spec.authors       = ['Angelo Ashmore']
+  spec.email         = ['angeloashmore@gmail.com']
+  spec.summary       = 'RethinkDB adapter for Lotus::Model'
+  spec.description   = 'RethinkDB adapter for Lotus::Model'
+  spec.homepage      = 'https://github.com/angeloashmore/lotus-rethinkdb'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split("\n")
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'lotus-model',   '~> 0.2'
+  spec.add_runtime_dependency 'rethinkdb',     '~> 1.15'
+  spec.add_runtime_dependency 'activesupport', '~> 4.2'
+
+  spec.add_development_dependency 'bundler',       '~> 1.7'
+  spec.add_development_dependency 'minitest',      '~> 5.5'
+  spec.add_development_dependency 'minitest-line', '~> 0.6.2'
+  spec.add_development_dependency 'rake',          '~> 10.0'
+end