hanami-rethinkdb 0.2.3

data/lib/hanami/model/adapters/rethinkdb/command.rb

@@ -0,0 +1,66 @@
+module Hanami
+  module Model
+    module Adapters
+      module Rethinkdb
+        # Execute a command for the given query.
+        #
+        # @see Hanami::Model::Adapters::Rethinkdb::Query
+        #
+        # @api private
+        # @since 0.1.0
+        class Command
+          # Initialize a command
+          #
+          # @param query [Hanami::Model::Adapters::Rethinkdb::Query]
+          #
+          # @api private
+          # @since 0.1.0
+          def initialize(query)
+            @collection = query.scoped
+          end
+
+          # Creates a document for the given entity.
+          #
+          # @param entity [Object] the entity to persist
+          #
+          # @see Hanami::Model::Adapters::Rethinkdb::Collection#insert
+          #
+          # @return the primary key of the just created document.
+          #
+          # @api private
+          # @since 0.1.0
+          def create(entity)
+            @collection.insert(entity)
+          end
+
+          # Updates the corresponding document for the given entity.
+          #
+          # @param entity [Object] the entity to persist
+          #
+          # @see Hanami::Model::Adapters::Rethinkdb::Collection#update
+          #
+          # @api private
+          # @since 0.1.0
+          def update(entity)
+            @collection.update(entity)
+          end
+
+          # Deletes all the documents for the current query.
+          #
+          # It's used to delete a single document or an entire database table.
+          #
+          # @see Hanami::Model::Adapters::RethinkdbAdapter#delete
+          # @see Hanami::Model::Adapters::RethinkdbAdapter#clear
+          #
+          # @api private
+          # @since 0.1.0
+          def delete
+            @collection.delete
+          end
+
+          alias_method :clear, :delete
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,486 @@
+require 'forwardable'
+require 'hanami/utils/kernel'
+require 'rethinkdb'
+
+module Hanami
+  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: 'hanami')
+        #        .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 [Hanami::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 [Hanami::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: 'hanami')
+          #
+          #   # => r.filter(language: 'ruby').filter('framework: 'hanami')
+          #
+          # @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
+
+          # Only include documents with the given fields.
+          #
+          # @param fields [Array<Symbol>]
+          #
+          # @return self
+          #
+          # @since 0.1.0
+          #
+          # @example Single column
+          #
+          #   query.has_fields(:name)
+          #
+          #   # => r.has_fields(:name)
+          #
+          # @example Multiple columns
+          #
+          #   query.has_fields(:name, :year)
+          #
+          #   # => r.has_fields(:name, :year)
+          def has_fields(*fields) # rubocop:disable Style/PredicateName
+            conditions.push([:has_fields, *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 Hanami::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 Hanami::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(:name, :year, { index: r.desc(:date) })
+          #
+          #   # => r.order_by(r.desc(:name), r.desc(:year), { index:
+          #                   r.desc(:date) })
+          def desc(*fields)
+            conditions.push([:order_by, *_desc_wrapper(*fields)])
+            self
+          end
+
+          # Returns the sum of the values for the given field.
+          #
+          # @param field [Symbol] the field name
+          #
+          # @return [Numeric]
+          #
+          # @since 0.1.0
+          #
+          # @example
+          #
+          #    query.sum(:comments_count)
+          #
+          #    # => r.sum(:comments_count)
+          def sum(field)
+            scoped.sum(field)
+          end
+
+          # Returns the average of the values for the given field.
+          #
+          # @param field [Symbol] the column name
+          #
+          # @return [Numeric]
+          #
+          # @since 0.1.0
+          #
+          # @example
+          #
+          #    query.average(:comments_count)
+          #
+          #    # => r.avg(:comments_count)
+          def average(field)
+            scoped.avg(field)
+          end
+
+          alias_method :avg, :average
+
+          # Returns the maximum value for the given field.
+          #
+          # @param field [Symbol] the field name
+          #
+          # @return result
+          #
+          # @since 0.1.0
+          #
+          # @example With numeric type
+          #
+          #    query.max(:comments_count)
+          #
+          #    # r.max(:comments_count)
+          #
+          # @example With string type
+          #
+          #    query.max(:title)
+          #
+          #    # => r.max(:title)
+          def max(field)
+            has_fields(field)
+            scoped.max(field)
+          end
+
+          # Returns the minimum value for the given field.
+          #
+          # @param field [Symbol] the field name
+          #
+          # @return result
+          #
+          # @since 0.1.0
+          #
+          # @example With numeric type
+          #
+          #    query.min(:comments_count)
+          #
+          #    # => r.min(:comments_count)
+          #
+          # @example With string type
+          #
+          #    query.min(:title)
+          #
+          #    # => r.min(:title)
+          def min(field)
+            has_fields(field)
+            scoped.min(field)
+          end
+
+          # Returns a count of the records for the current conditions.
+          #
+          # @return [Fixnum]
+          #
+          # @since 0.1.0
+          #
+          # @example
+          #
+          #    query.where(author_id: 23).count # => 5
+          def count
+            scoped.count
+          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 [Hanami::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 Hanami::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 [Hanami::Model::Adapters::Rethinkdb::Query] the query
+          #   to apply
+          #
+          # @return [Hanami::Model::Adapters::Rethinkdb::Query] a new query with
+          #   the merged conditions
+          #
+          # @api private
+          # @since 0.1.0
+          #
+          # @example
+          #   require 'hanami/model'
+          #
+          #   class ArticleRepository
+          #     include Hanami::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