hanami-model 0.0.0 → 0.6.0

data/lib/hanami/model/migrator/connection.rb

@@ -0,0 +1,133 @@
+module Hanami
+  module Model
+    module Migrator
+      # Sequel connection wrapper
+      #
+      # Normalize external adapters interfaces
+      #
+      # @since 0.5.0
+      # @api private
+      class Connection
+        attr_reader :adapter_connection
+
+        def initialize(adapter_connection)
+          @adapter_connection = adapter_connection
+        end
+
+        # Returns DB connection host
+        #
+        # Even when adapter doesn't provide it explicitly it tries to parse
+        #
+        # @since 0.5.0
+        # @api private
+        def host
+          @host ||= opts.fetch(:host, parsed_uri.host)
+        end
+
+        # Returns DB connection port
+        #
+        # Even when adapter doesn't provide it explicitly it tries to parse
+        #
+        # @since 0.5.0
+        # @api private
+        def port
+          @port ||= opts.fetch(:port, parsed_uri.port)
+        end
+
+        # Returns DB name from conenction
+        #
+        # Even when adapter doesn't provide it explicitly it tries to parse
+        #
+        # @since 0.5.0
+        # @api private
+        def database
+          @database ||= opts.fetch(:database, parsed_uri.path[1..-1])
+        end
+
+        # Returns DB type
+        #
+        # @example
+        #   connection.database_type
+        #   # => 'postgres'
+        #
+        # @since 0.5.0
+        # @api private
+        def database_type
+          adapter_connection.database_type
+        end
+
+        # Returns user from DB connection
+        #
+        # Even when adapter doesn't provide it explicitly it tries to parse
+        #
+        # @since 0.5.0
+        # @api private
+        def user
+          @user ||= opts.fetch(:user, parsed_opt('user'))
+        end
+
+        # Returns user from DB connection
+        #
+        # Even when adapter doesn't provide it explicitly it tries to parse
+        #
+        # @since 0.5.0
+        # @api private
+        def password
+          @password ||= opts.fetch(:password, parsed_opt('password'))
+        end
+
+        # Returns DB connection URI directly from adapter
+        #
+        # @since 0.5.0
+        # @api private
+        def uri
+          adapter_connection.uri
+        end
+
+        # Returns DB connection wihout specifying database name
+        #
+        # @since 0.5.0
+        # @api private
+        def global_uri
+          adapter_connection.uri.sub(parsed_uri.select(:path).first, '')
+        end
+
+        # Returns a boolean telling if a DB connection is from JDBC or not
+        #
+        # @since 0.5.0
+        # @api private
+        def jdbc?
+          !adapter_connection.uri.scan('jdbc:').empty?
+        end
+
+        # Returns database connection URI instance without JDBC namespace
+        #
+        # @since 0.5.0
+        # @api private
+        def parsed_uri
+          @uri ||= URI.parse(adapter_connection.uri.sub('jdbc:', ''))
+        end
+
+        private
+
+        # Returns a value of a given query string param
+        #
+        # @param option [String] which option from database connection will be extracted from URI
+        #
+        # @since 0.5.0
+        # @api private
+        def parsed_opt(option)
+          parsed_uri.to_s.match(/[\?|\&]#{ option }=(\w+)\&?/).to_a.last
+        end
+
+        # Fetch connection options from adapter
+        #
+        # @since 0.5.0
+        # @api private
+        def opts
+          adapter_connection.opts
+        end
+      end
+    end
+  end
+end

data/lib/hanami/model/migrator/mysql_adapter.rb

@@ -0,0 +1,72 @@
+module Hanami
+  module Model
+    module Migrator
+      # MySQL adapter
+      #
+      # @since 0.4.0
+      # @api private
+      class MySQLAdapter < Adapter
+        # @since 0.4.0
+        # @api private
+        def create
+          new_connection(global: true).run %(CREATE DATABASE #{ database };)
+        rescue Sequel::DatabaseError => e
+          message = if e.message.match(/database exists/)
+            "Database creation failed. There is 1 other session using the database"
+          else
+            e.message
+          end
+
+          raise MigrationError.new(message)
+        end
+
+        # @since 0.4.0
+        # @api private
+        def drop
+          new_connection(global: true).run %(DROP DATABASE #{ database };)
+        rescue Sequel::DatabaseError => e
+          message = if e.message.match(/doesn\'t exist/)
+            "Cannot find database: #{ database }"
+          else
+            e.message
+          end
+
+          raise MigrationError.new(message)
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump
+          dump_structure
+          dump_migrations_data
+        end
+
+        # @since 0.4.0
+        # @api private
+        def load
+          load_structure
+        end
+
+        private
+
+        # @since 0.4.0
+        # @api private
+        def dump_structure
+          system "mysqldump --user=#{ username } --password=#{ password } --no-data --skip-comments --ignore-table=#{ database }.#{ migrations_table } #{ database } > #{ schema }"
+        end
+
+        # @since 0.4.0
+        # @api private
+        def load_structure
+          system "mysql --user=#{ username } --password=#{ password } #{ database } < #{ escape(schema) }" if schema.exist?
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump_migrations_data
+          system "mysqldump --user=#{ username } --password=#{ password } --skip-comments #{ database } #{ migrations_table } >> #{ schema }"
+        end
+      end
+    end
+  end
+end

data/lib/hanami/model/migrator/postgres_adapter.rb

@@ -0,0 +1,119 @@
+module Hanami
+  module Model
+    module Migrator
+      # PostgreSQL adapter
+      #
+      # @since 0.4.0
+      # @api private
+      class PostgresAdapter < Adapter
+        # @since 0.4.0
+        # @api private
+        HOST     = 'PGHOST'.freeze
+
+        # @since 0.4.0
+        # @api private
+        PORT     = 'PGPORT'.freeze
+
+        # @since 0.4.0
+        # @api private
+        USER     = 'PGUSER'.freeze
+
+        # @since 0.4.0
+        # @api private
+        PASSWORD = 'PGPASSWORD'.freeze
+
+        # @since 0.4.0
+        # @api private
+        def create
+          set_environment_variables
+
+          call_db_command('createdb') do |error_message|
+            message = if error_message.match(/already exists/)
+              "createdb: database creation failed. There is 1 other session using the database."
+            else
+              error_message
+            end
+
+            raise MigrationError.new(message)
+          end
+        end
+
+        # @since 0.4.0
+        # @api private
+        def drop
+          set_environment_variables
+
+          call_db_command('dropdb') do |error_message|
+            message = if error_message.match(/does not exist/)
+              "Cannot find database: #{ database }"
+            else
+              error_message
+            end
+
+            raise MigrationError.new(message)
+          end
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump
+          set_environment_variables
+          dump_structure
+          dump_migrations_data
+        end
+
+        # @since 0.4.0
+        # @api private
+        def load
+          set_environment_variables
+          load_structure
+        end
+
+        private
+
+        # @since 0.4.0
+        # @api private
+        def set_environment_variables
+          ENV[HOST]     = host      unless host.nil?
+          ENV[PORT]     = port.to_s unless port.nil?
+          ENV[PASSWORD] = password  unless password.nil?
+          ENV[USER]     = username  unless username.nil?
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump_structure
+          system "pg_dump -i -s -x -O -T #{ migrations_table } -f #{ escape(schema) } #{ database }"
+        end
+
+        # @since 0.4.0
+        # @api private
+        def load_structure
+          system "psql -X -q -f #{ escape(schema) } #{ database }" if schema.exist?
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump_migrations_data
+          system "pg_dump -t #{ migrations_table } #{ database } >> #{ escape(schema) }"
+        end
+
+        # @since 0.5.1
+        # @api private
+        def call_db_command(command)
+          require 'open3'
+
+          begin
+            Open3.popen3(command, database) do |stdin, stdout, stderr, wait_thr|
+              unless wait_thr.value.success? # wait_thr.value is the exit status
+                yield stderr.read
+              end
+            end
+          rescue SystemCallError => e
+            yield e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami/model/migrator/sqlite_adapter.rb

@@ -0,0 +1,110 @@
+require 'pathname'
+
+module Hanami
+  module Model
+    module Migrator
+      # SQLite3 Migrator
+      #
+      # @since 0.4.0
+      # @api private
+      class SQLiteAdapter < Adapter
+        # No-op for in-memory databases
+        #
+        # @since 0.4.0
+        # @api private
+        module Memory
+          # @since 0.4.0
+          # @api private
+          def create
+          end
+
+          # @since 0.4.0
+          # @api private
+          def drop
+          end
+        end
+
+        # Initialize adapter
+        #
+        # @since 0.4.0
+        # @api private
+        def initialize(connection)
+          super
+          extend Memory if memory?
+        end
+
+        # @since 0.4.0
+        # @api private
+        def create
+          path.dirname.mkpath
+          FileUtils.touch(path)
+        rescue Errno::EACCES, Errno::EPERM
+          raise MigrationError.new("Permission denied: #{ path.sub(/\A\/\//, '') }")
+        end
+
+        # @since 0.4.0
+        # @api private
+        def drop
+          path.delete
+        rescue Errno::ENOENT
+          raise MigrationError.new("Cannot find database: #{ path.sub(/\A\/\//, '') }")
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump
+          dump_structure
+          dump_migrations_data
+        end
+
+        # @since 0.4.0
+        # @api private
+        def load
+          load_structure
+        end
+
+        private
+
+        # @since 0.4.0
+        # @api private
+        def path
+          root.join(
+            @connection.uri.sub(/(jdbc\:|)sqlite\:\/\//, '')
+          )
+        end
+
+        # @since 0.4.0
+        # @api private
+        def root
+          Hanami::Model.configuration.root
+        end
+
+        # @since 0.4.0
+        # @api private
+        def memory?
+          uri = path.to_s
+          uri.match(/sqlite\:\/\z/) ||
+            uri.match(/\:memory\:/)
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump_structure
+          system "sqlite3 #{ escape(path) } .schema > #{ escape(schema) }"
+        end
+
+        # @since 0.4.0
+        # @api private
+        def load_structure
+          system "sqlite3 #{ escape(path) } < #{ escape(schema) }" if schema.exist?
+        end
+
+        # @since 0.4.0
+        # @api private
+        def dump_migrations_data
+          system %(sqlite3 #{ escape(path) } .dump | grep '^INSERT INTO "#{ migrations_table }"' >> #{ escape(schema) })
+        end
+      end
+    end
+  end
+end

data/lib/hanami/model/version.rb

@@ -1,5 +1,8 @@
 module Hanami
   module Model
-    VERSION = "0.0.0"
+    # Defines the version
+    #
+    # @since 0.1.0
+    VERSION = '0.6.0'.freeze
   end
 end

data/lib/hanami/repository.rb

@@ -0,0 +1,872 @@
+require 'hanami/utils/class_attribute'
+require 'hanami/model/adapters/null_adapter'
+
+module Hanami
+  # Mediates between the entities and the persistence layer, by offering an API
+  # to query and execute commands on a database.
+  #
+  #
+  #
+  # By default, a repository is named after an entity, by appending the
+  # `Repository` suffix to the entity class name.
+  #
+  # @example
+  #   require 'hanami/model'
+  #
+  #   class Article
+  #     include Hanami::Entity
+  #   end
+  #
+  #   # valid
+  #   class ArticleRepository
+  #     include Hanami::Repository
+  #   end
+  #
+  #   # not valid for Article
+  #   class PostRepository
+  #     include Hanami::Repository
+  #   end
+  #
+  # Repository for an entity can be configured by setting # the `#repository`
+  # on the mapper.
+  #
+  # @example
+  #   # PostRepository is repository for Article
+  #   mapper = Hanami::Model::Mapper.new do
+  #     collection :articles do
+  #       entity Article
+  #       repository PostRepository
+  #     end
+  #   end
+  #
+  # A repository is storage independent.
+  # All the queries and commands are delegated to the current adapter.
+  #
+  # This architecture has several advantages:
+  #
+  #   * Applications depend on an abstract API, instead of low level details
+  #     (Dependency Inversion principle)
+  #
+  #   * Applications depend on a stable API, that doesn't change if the
+  #     storage changes
+  #
+  #   * Developers can postpone storage decisions
+  #
+  #   * Isolates the persistence logic at a low level
+  #
+  # Hanami::Model is shipped with two adapters:
+  #
+  #   * SqlAdapter
+  #   * MemoryAdapter
+  #
+  #
+  #
+  # All the queries and commands are private.
+  # This decision forces developers to define intention revealing API, instead
+  # leak storage API details outside of a repository.
+  #
+  # @example
+  #   require 'hanami/model'
+  #
+  #   # This is bad for several reasons:
+  #   #
+  #   #  * The caller has an intimate knowledge of the internal mechanisms
+  #   #      of the Repository.
+  #   #
+  #   #  * The caller works on several levels of abstraction.
+  #   #
+  #   #  * It doesn't express a clear intent, it's just a chain of methods.
+  #   #
+  #   #  * The caller can't be easily tested in isolation.
+  #   #
+  #   #  * If we change the storage, we are forced to change the code of the
+  #   #    caller(s).
+  #
+  #   ArticleRepository.where(author_id: 23).order(:published_at).limit(8)
+  #
+  #
+  #
+  #   # This is a huge improvement:
+  #   #
+  #   #  * The caller doesn't know how the repository fetches the entities.
+  #   #
+  #   #  * The caller works on a single level of abstraction.
+  #   #    It doesn't even know about records, only works with entities.
+  #   #
+  #   #  * It expresses a clear intent.
+  #   #
+  #   #  * The caller can be easily tested in isolation.
+  #   #    It's just a matter of stub this method.
+  #   #
+  #   #  * If we change the storage, the callers aren't affected.
+  #
+  #   ArticleRepository.most_recent_by_author(author)
+  #
+  #   class ArticleRepository
+  #     include Hanami::Repository
+  #
+  #     def self.most_recent_by_author(author, limit = 8)
+  #       query do
+  #         where(author_id: author.id).
+  #           order(:published_at)
+  #       end.limit(limit)
+  #     end
+  #   end
+  #
+  # @since 0.1.0
+  #
+  # @see Hanami::Entity
+  # @see http://martinfowler.com/eaaCatalog/repository.html
+  # @see http://en.wikipedia.org/wiki/Dependency_inversion_principle
+  module Repository
+    # Inject the public API into the hosting class.
+    #
+    # @since 0.1.0
+    #
+    # @example
+    #   require 'hanami/model'
+    #
+    #   class UserRepository
+    #     include Hanami::Repository
+    #   end
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        include Hanami::Utils::ClassAttribute
+
+        class_attribute :collection
+        self.adapter = Hanami::Model::Adapters::NullAdapter.new
+      end
+    end
+
+    module ClassMethods
+      # Assigns an adapter.
+      #
+      # Hanami::Model is shipped with two adapters:
+      #
+      #   * SqlAdapter
+      #   * MemoryAdapter
+      #
+      # @param adapter [Object] an object that implements
+      #   `Hanami::Model::Adapters::Abstract` interface
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Model::Adapters::SqlAdapter
+      # @see Hanami::Model::Adapters::MemoryAdapter
+      #
+      # @example Memory adapter
+      #   require 'hanami/model'
+      #   require 'hanami/model/adapters/memory_adapter'
+      #
+      #   mapper = Hanami::Model::Mapper.new do
+      #     # ...
+      #   end
+      #
+      #   adapter = Hanami::Model::Adapters::MemoryAdapter.new(mapper)
+      #
+      #   class UserRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   UserRepository.adapter = adapter
+      #
+      #
+      #
+      # @example SQL adapter with a Sqlite database
+      #   require 'sqlite3'
+      #   require 'hanami/model'
+      #   require 'hanami/model/adapters/sql_adapter'
+      #
+      #   mapper = Hanami::Model::Mapper.new do
+      #     # ...
+      #   end
+      #
+      #   adapter = Hanami::Model::Adapters::SqlAdapter.new(mapper, 'sqlite://path/to/database.db')
+      #
+      #   class UserRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   UserRepository.adapter = adapter
+      #
+      #
+      #
+      # @example SQL adapter with a Postgres database
+      #   require 'pg'
+      #   require 'hanami/model'
+      #   require 'hanami/model/adapters/sql_adapter'
+      #
+      #   mapper = Hanami::Model::Mapper.new do
+      #     # ...
+      #   end
+      #
+      #   adapter = Hanami::Model::Adapters::SqlAdapter.new(mapper, 'postgres://host:port/database')
+      #
+      #   class UserRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   UserRepository.adapter = adapter
+      def adapter=(adapter)
+        @adapter = adapter
+      end
+
+      # @since 0.5.0
+      # @api private
+      def adapter
+        @adapter
+      end
+
+      # Creates or updates a record in the database for the given entity.
+      #
+      # @param entity [#id, #id=] the entity to persist
+      #
+      # @return [Object] a copy of the entity with `id` assigned
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Repository#create
+      # @see Hanami::Repository#update
+      #
+      # @example With a non persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = Article.new(title: 'Introducing Hanami::Model')
+      #   article.id # => nil
+      #
+      #   persisted_article = ArticleRepository.persist(article) # creates a record
+      #   article.id # => nil
+      #   persisted_article.id # => 23
+      #
+      # @example With a persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = ArticleRepository.find(23)
+      #   article.id # => 23
+      #
+      #   article.title = 'Launching Hanami::Model'
+      #   ArticleRepository.persist(article) # updates the record
+      #
+      #   article = ArticleRepository.find(23)
+      #   article.title # => "Launching Hanami::Model"
+      def persist(entity)
+        _touch(entity)
+        @adapter.persist(collection, entity)
+      end
+
+      # Creates a record in the database for the given entity.
+      # It returns a copy of the entity with `id` assigned.
+      #
+      # If already persisted (`id` present) it does nothing.
+      #
+      # @param entity [#id,#id=] the entity to create
+      #
+      # @return [Object] a copy of the entity with `id` assigned
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Repository#persist
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = Article.new(title: 'Introducing Hanami::Model')
+      #   article.id # => nil
+      #
+      #   created_article = ArticleRepository.create(article) # creates a record
+      #   article.id # => nil
+      #   created_article.id # => 23
+      #
+      #   created_article = ArticleRepository.create(article)
+      #   created_article.id # => 24
+      #
+      #   created_article = ArticleRepository.create(existing_article) # => no-op
+      #   created_article # => nil
+      #
+      def create(entity)
+        unless _persisted?(entity)
+          _touch(entity)
+          @adapter.create(collection, entity)
+        end
+      end
+
+      # Updates a record in the database corresponding to the given entity.
+      #
+      # If not already persisted (`id` present) it raises an exception.
+      #
+      # @param entity [#id] the entity to update
+      #
+      # @return [Object] the entity
+      #
+      # @raise [Hanami::Model::NonPersistedEntityError] if the given entity
+      #   wasn't already persisted.
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Repository#persist
+      # @see Hanami::Model::NonPersistedEntityError
+      #
+      # @example With a persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = ArticleRepository.find(23)
+      #   article.id # => 23
+      #   article.title = 'Launching Hanami::Model'
+      #
+      #   ArticleRepository.update(article) # updates the record
+      #
+      #
+      #
+      # @example With a non persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = Article.new(title: 'Introducing Hanami::Model')
+      #   article.id # => nil
+      #
+      #   ArticleRepository.update(article) # raises Hanami::Model::NonPersistedEntityError
+      def update(entity)
+        if _persisted?(entity)
+          _touch(entity)
+          @adapter.update(collection, entity)
+        else
+          raise Hanami::Model::NonPersistedEntityError
+        end
+      end
+
+      # Deletes a record in the database corresponding to the given entity.
+      #
+      # If not already persisted (`id` present) it raises an exception.
+      #
+      # @param entity [#id] the entity to delete
+      #
+      # @return [Object] the entity
+      #
+      # @raise [Hanami::Model::NonPersistedEntityError] if the given entity
+      #   wasn't already persisted.
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Model::NonPersistedEntityError
+      #
+      # @example With a persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = ArticleRepository.find(23)
+      #   article.id # => 23
+      #
+      #   ArticleRepository.delete(article) # deletes the record
+      #
+      #
+      #
+      # @example With a non persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = Article.new(title: 'Introducing Hanami::Model')
+      #   article.id # => nil
+      #
+      #   ArticleRepository.delete(article) # raises Hanami::Model::NonPersistedEntityError
+      def delete(entity)
+        if _persisted?(entity)
+          @adapter.delete(collection, entity)
+        else
+          raise Hanami::Model::NonPersistedEntityError
+        end
+
+        entity
+      end
+
+      # Returns all the persisted entities.
+      #
+      # @return [Array<Object>] the result of the query
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.all # => [ #<Article:0x007f9b19a60098> ]
+      def all
+        @adapter.all(collection)
+      end
+
+      # Finds an entity by its identity.
+      #
+      # If used with a SQL database, it corresponds to the primary key.
+      #
+      # @param id [Object] the identity of the entity
+      #
+      # @return [Object,NilClass] the result of the query, if present
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.find(23)   # => #<Article:0x007f9b19a60098>
+      #   ArticleRepository.find(9999) # => nil
+      def find(id)
+        @adapter.find(collection, id)
+      end
+
+      # Returns the first entity in the database.
+      #
+      # @return [Object,nil] the result of the query
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Repository#last
+      #
+      # @example With at least one persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.first # => #<Article:0x007f8c71d98a28>
+      #
+      # @example With an empty collection
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.first # => nil
+      def first
+        @adapter.first(collection)
+      end
+
+      # Returns the last entity in the database.
+      #
+      # @return [Object,nil] the result of the query
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Repository#last
+      #
+      # @example With at least one persisted entity
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.last # => #<Article:0x007f8c71d98a28>
+      #
+      # @example With an empty collection
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.last # => nil
+      def last
+        @adapter.last(collection)
+      end
+
+      # Deletes all the records from the current collection.
+      #
+      # If used with a SQL database it executes a `DELETE FROM <table>`.
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   ArticleRepository.clear # deletes all the records
+      def clear
+        @adapter.clear(collection)
+      end
+
+      # Wraps the given block in a transaction.
+      #
+      # For performance reasons the block isn't in the signature of the method,
+      # but it's yielded at the lower level.
+      #
+      # Please note that it's only supported by some databases.
+      # For this reason, the accepted options may be different from adapter to
+      # adapter.
+      #
+      # For advanced scenarios, please check the documentation of each adapter.
+      #
+      # @param options [Hash] options for transaction
+      #
+      # @see Hanami::Model::Adapters::SqlAdapter#transaction
+      # @see Hanami::Model::Adapters::MemoryAdapter#transaction
+      #
+      # @since 0.2.3
+      #
+      # @example Basic usage with SQL adapter
+      #   require 'hanami/model'
+      #
+      #   class Article
+      #     include Hanami::Entity
+      #     attributes :title, :body
+      #   end
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #   end
+      #
+      #   article = Article.new(title: 'Introducing transactions',
+      #     body: 'lorem ipsum')
+      #
+      #   ArticleRepository.transaction do
+      #     ArticleRepository.dangerous_operation!(article) # => RuntimeError
+      #     # !!! ROLLBACK !!!
+      #   end
+      def transaction(options = {})
+        @adapter.transaction(options) do
+          yield
+        end
+      end
+
+      private
+
+      # Executes the given raw statement on the adapter.
+      #
+      # Please note that it's only supported by some databases,
+      # a `NotImplementedError` will be raised when the adapter does not
+      # responds to the `execute` method.
+      #
+      # For advanced scenarios, please check the documentation of each adapter.
+      #
+      # @param raw [String] the raw statement to execute on the connection
+      #
+      # @return [NilClass]
+      #
+      # @raise [NotImplementedError] if current Hanami::Model adapter doesn't
+      #   implement `execute`.
+      #
+      # @raise [Hanami::Model::InvalidCommandError] if the raw statement is invalid
+      #
+      # @see Hanami::Model::Adapters::Abstract#execute
+      # @see Hanami::Model::Adapters::SqlAdapter#execute
+      #
+      # @since 0.3.1
+      #
+      # @example Basic usage with SQL adapter
+      #   require 'hanami/model'
+      #
+      #   class Article
+      #     include Hanami::Entity
+      #     attributes :title, :body
+      #   end
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #
+      #     def self.reset_comments_count
+      #       execute "UPDATE articles SET comments_count = 0"
+      #     end
+      #   end
+      #
+      #   ArticleRepository.reset_comments_count
+      def execute(raw)
+        @adapter.execute(raw)
+      end
+
+      # Fetch raw result sets for the the given statement.
+      #
+      # PLEASE NOTE: The returned result set contains an array of hashes.
+      #              The columns are returned as they are from the database,
+      #              the mapper is bypassed here.
+      #
+      # @param raw [String] the raw statement used to fetch records
+      # @param blk [Proc] an optional block that is yielded for each record
+      #
+      # @return [Enumerable<Hash>,Array<Hash>] the collection of raw records
+      #
+      # @raise [NotImplementedError] if current Hanami::Model adapter doesn't
+      #   implement `fetch`.
+      #
+      # @raise [Hanami::Model::InvalidQueryError] if the raw statement is invalid
+      #
+      # @since 0.5.0
+      #
+      # @example Basic Usage
+      #   require 'hanami/model'
+      #
+      #   mapping do
+      #     collection :articles do
+      #       attribute :id,    Integer, as: :s_id
+      #       attribute :title, String,  as: :s_title
+      #     end
+      #   end
+      #
+      #   class Article
+      #     include Hanami::Entity
+      #     attributes :title, :body
+      #   end
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #
+      #     def self.all_raw
+      #       fetch("SELECT * FROM articles")
+      #     end
+      #   end
+      #
+      #   ArticleRepository.all_raw
+      #     # => [{:_id=>1, :user_id=>nil, :s_title=>"Art 1", :comments_count=>nil, :umapped_column=>nil}]
+      #
+      # @example Map A Value From Result Set
+      #   require 'hanami/model'
+      #
+      #   mapping do
+      #     collection :articles do
+      #       attribute :id,    Integer, as: :s_id
+      #       attribute :title, String,  as: :s_title
+      #     end
+      #   end
+      #
+      #   class Article
+      #     include Hanami::Entity
+      #     attributes :title, :body
+      #   end
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #
+      #     def self.titles
+      #       fetch("SELECT s_title FROM articles").map do |article|
+      #         article[:s_title]
+      #       end
+      #     end
+      #   end
+      #
+      #   ArticleRepository.titles # => ["Announcing Hanami v0.5.0"]
+      #
+      # @example Passing A Block
+      #   require 'hanami/model'
+      #
+      #   mapping do
+      #     collection :articles do
+      #       attribute :id,    Integer, as: :s_id
+      #       attribute :title, String,  as: :s_title
+      #     end
+      #   end
+      #
+      #   class Article
+      #     include Hanami::Entity
+      #     attributes :title, :body
+      #   end
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #
+      #     def self.titles
+      #       result = []
+      #
+      #       fetch("SELECT s_title FROM articles") do |article|
+      #         result << article[:s_title]
+      #       end
+      #
+      #       result
+      #     end
+      #   end
+      #
+      #   ArticleRepository.titles # => ["Announcing Hanami v0.5.0"]
+      def fetch(raw, &blk)
+        @adapter.fetch(raw, &blk)
+      end
+
+      # Fabricates a query and yields the given block to access the low level
+      # APIs exposed by the query itself.
+      #
+      # This is a Ruby private method, because we wanted to prevent outside
+      # objects to query directly the database. However, this is a public API
+      # method, and this is the only way to filter entities.
+      #
+      # The returned query SHOULD be lazy: the entities should be fetched by
+      # the database only when needed.
+      #
+      # The returned query SHOULD refer to the entire collection by default.
+      #
+      # Queries can be reused and combined together. See the example below.
+      # IMPORTANT: This feature works only with the Sql adapter.
+      #
+      # A repository is storage independent.
+      # All the queries are delegated to the current adapter, which is
+      # responsible to implement a querying API.
+      #
+      # Hanami::Model is shipped with two adapters:
+      #
+      #   * SqlAdapter, which yields a Hanami::Model::Adapters::Sql::Query
+      #   * MemoryAdapter, which yields a Hanami::Model::Adapters::Memory::Query
+      #
+      # @param blk [Proc] a block of code that is executed in the context of a
+      #   query
+      #
+      # @return a query, the type depends on the current adapter
+      #
+      # @api public
+      # @since 0.1.0
+      #
+      # @see Hanami::Model::Adapters::Sql::Query
+      # @see Hanami::Model::Adapters::Memory::Query
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class ArticleRepository
+      #     include Hanami::Repository
+      #
+      #     def self.most_recent_by_author(author, limit = 8)
+      #       query do
+      #         where(author_id: author.id).
+      #           desc(:published_at).
+      #           limit(limit)
+      #       end
+      #     end
+      #
+      #     def self.most_recent_published_by_author(author, limit = 8)
+      #       # combine .most_recent_published_by_author and .published queries
+      #       most_recent_by_author(author, limit).published
+      #     end
+      #
+      #     def self.published
+      #       query do
+      #         where(published: true)
+      #       end
+      #     end
+      #
+      #     def self.rank
+      #       # reuse .published, which returns a query that respond to #desc
+      #       published.desc(:comments_count)
+      #     end
+      #
+      #     def self.best_article_ever
+      #       # reuse .published, which returns a query that respond to #limit
+      #       rank.limit(1)
+      #     end
+      #
+      #     def self.comments_average
+      #       query.average(:comments_count)
+      #     end
+      #   end
+      def query(&blk)
+        @adapter.query(collection, self, &blk)
+      end
+
+      # Negates the filtering conditions of a given query with the logical
+      # opposite operator.
+      #
+      # This is only supported by the SqlAdapter.
+      #
+      # @param query [Object] a query
+      #
+      # @return a negated query, the type depends on the current adapter
+      #
+      # @api public
+      # @since 0.1.0
+      #
+      # @see Hanami::Model::Adapters::Sql::Query#negate!
+      #
+      # @example
+      #   require 'hanami/model'
+      #
+      #   class ProjectRepository
+      #     include Hanami::Repository
+      #
+      #     def self.cool
+      #       query do
+      #         where(language: 'ruby')
+      #       end
+      #     end
+      #
+      #     def self.not_cool
+      #       exclude cool
+      #     end
+      #   end
+      def exclude(query)
+        query.negate!
+        query
+      end
+
+      # This is a method to check entity persited or not
+      #
+      # @param entity
+      # @return a boolean value
+      # @since 0.3.1
+      def _persisted?(entity)
+        !!entity.id
+      end
+
+      # Update timestamps
+      #
+      # @param entity [Object, Hanami::Entity] the entity
+      #
+      # @api private
+      # @since 0.3.1
+      def _touch(entity)
+        now = Time.now.utc
+
+        if _has_timestamp?(entity, :created_at)
+          entity.created_at ||= now
+        end
+
+        if _has_timestamp?(entity, :updated_at)
+          entity.updated_at = now
+        end
+      end
+
+      # Check if the given entity has the given timestamp
+      #
+      # @param entity [Object, Hanami::Entity] the entity
+      # @param timestamp [Symbol] the timestamp name
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api private
+      # @since 0.3.1
+      def _has_timestamp?(entity, timestamp)
+        entity.respond_to?(timestamp) &&
+          entity.respond_to?("#{ timestamp }=")
+      end
+    end
+  end
+end