hanami-model 0.0.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d93e87761cb8a7aac28af6df5cdfac35c112c635
-  data.tar.gz: f0b1f122133ba1fb283ab126da3784d81dafa8a1
+  metadata.gz: a99014d711cf7b1e4fd9469acdee5a7fefb69d9f
+  data.tar.gz: 71781d9d98ea8e5b5e75bd0df4527ed47f6e6b3a
 SHA512:
-  metadata.gz: 4e3f70305ca019849d22f0bd888396b51d0d154c468710a78d98800b9bcc9e1446771c84efcff51d7e56e4e10342e06d9d016e8dac55b368409faabfbaea382c
-  data.tar.gz: 23dbad87035fe552c51155609bc1ac789c8396d8d01b3931dc9f098125c8a10ac027829ea84ea83663636ceb6b6c46327b09e16c6137943bf3551536196011db
+  metadata.gz: 312c76418b3d0e8a8c7c41125c009f03bfdd03c4102de60ed87806df705c9584922ff1afc952b6ae383a86805b209333c1ba31dbfb4706810028bcba598e88f9
+  data.tar.gz: 5bba6c44f8cebef794b53c7b7a94d897f09098440feec568f293602fc46e0593c52ce090451cdcaee76e261fc0a908d731aa82ab552afb172b078f07e3be46ba

data/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Hanami::Model
+A persistence layer for Hanami
+
+## v0.6.0 - 2016-01-22
+### Changed
+- [Luca Guidi] Renamed the project
+
+## v0.5.2 - 2016-01-19
+### Changed
+- [Sean Collins] Improved error message for `Lotus::Model::Adapters::NoAdapterError`
+
+### Fixed
+- [Kyle Chong & Trung Lê] Catch Sequel exceptions and re-raise as `Lotus::Model::Error`
+
+## v0.5.1 - 2016-01-12
+### Added
+- [Taylor Finnell] Let `Lotus::Model::Configuration#adapter` to accept arbitrary options (eg. `adapter type: :sql, uri: 'jdbc:...', after_connect: Proc.new { |connection| connection.auto_commit(true) }`)
+
+### Changed
+- [Andrey Deryabin] Improved `Entity#inspect`
+- [Karim Tarek] Introduced `Lotus::Model::Error` and let all the framework exceptions to inherit from it.
+
+### Fixed
+- [Luca Guidi] Improved error message when trying to use a repository without mapping the corresponding collections
+- [Sean Collins] Improved error message when trying to create database, but it fails (eg. missing `createdb` executable)
+- [Andrey Deryabin] Improved error message when trying to drop database, but a client is still connected (useful for PostgreSQL)
+- [Hiếu Nguyễn] Improved error message when trying to "prepare" database, but it fails
+
+## v0.5.0 - 2015-09-30
+### Added
+- [Brenno Costa] Official support for JRuby 9k+
+- [Luca Guidi] Command/Query separation via `Repository.execute` and `Repository.fetch`
+- [Luca Guidi] Custom attribute coercers for data mapper
+- [Alfonso Uceda] Added `#join` and `#left_join` and `#group` to SQL adapter
+
+### Changed
+- [Luca Guidi] `Repository.execute` no longer returns a result from the database.
+
+### Fixed
+- [Manuel Corrales] Use `dropdb` to drop PostgreSQL database.
+- [Luca Guidi & Bohdan V.] Ignore dotfiles while running migrations.
+
+## v0.4.1 - 2015-07-10
+### Fixed
+- [Nick Coyne] Fixed database creation for PostgreSQL (now it uses `createdb`).
+
+## v0.4.0 - 2015-06-23
+### Added
+- [Luca Guidi] Database migrations
+
+### Changed
+- [Matthew Bellantoni] Made `Repository.execute` not callable from the outside (private Ruby method, public API).
+
+## v0.3.2 - 2015-05-22
+### Added
+- [Dmitry Tymchuk & Luca Guidi] Fix for dirty tracking of attributes changed in place (eg. `book.tags << 'non-fiction'`)
+
+## v0.3.1 - 2015-05-15
+### Added
+- [Dmitry Tymchuk] Dirty tracking for entities (via `Lotus::Entity::DirtyTracking` module to include)
+- [My Mai] Automatic update of timestamps when an entity is persisted.
+- [Peter Berkenbosch] Introduced `Lotus::Repository#execute`, to execute raw query/commands against database (eg. `BookRepository.execute "SELECT * FROM users"` or `BookRepository.execute "UPDATE users SET admin = 'f'"`)
+- [Guilherme Franco] Memory and File System adapters now accept a block for `where`, `or`, `and` conditions (eg `where { age > 33 }`).
+
+### Fixed
+- [Luca Guidi] Ensure Array coercion to preserve original data structure
+
+## v0.3.0 - 2015-03-23
+### Added
+- [Linus Pettersson] Database console
+
+### Fixed
+- [Alfonso Uceda Pompa] Don't send unwanted null values to the database, while coercing entities
+- [Jan Lelis] Do not define top-level `Boolean`, because it is already defined by `hanami-utils`
+- [Vsevolod Romashov] Fix entity class resolving in `Coercer#from_record`
+- [Jason Harrelson] Add file and line to `instance_eval` in `Coercer` to make backtrace more usable
+
+## v0.2.4 - 2015-02-20
+### Fixed
+- [Luca Guidi] When duplicate the framework don't copy over the original `Lotus::Model` configuration
+
+## v0.2.3 - 2015-02-13
+### Added
+- [Alfonso Uceda Pompa] Added support for database transactions in repositories
+
+### Fixed
+- [Luca Guidi] Ensure file system adapter old data is read when a new process is started
+
+## v0.2.2 - 2015-01-18
+### Added
+- [Luca Guidi] Coerce entities when persisted
+
+## v0.2.1 - 2015-01-12
+### Added
+- [Luca Guidi] Compatibility between Lotus::Entity and Lotus::Validations
+
+## v0.2.0 - 2014-12-23
+### Added
+- [Luca Guidi] Introduced file system adapter
+– [Benny Klotz & Trung Lê] Introduced `Entity` inheritance of attributes
+- [Trung Lê] Introduced `Entity#update` for bulk update of attributes
+- [Luca Guidi] Improved error when try to use a repository which wasn't configured or when the framework wasn't loaded yet
+- [Trung Lê] Introduced `Entity#to_h`
+- [Trung Lê] Introduced `Lotus::Model.duplicate`
+- [Trung Lê] Made `Lotus::Mapper` lazy
+- [Trung Lê] Introduced thread safe autoloading for adapters
+- [Felipe Sere] Add support for `Symbol` coercion
+- [Celso Fernandes] Add support for `BigDecimal` coercion
+- [Trung Lê] Introduced `Lotus::Model.load!` as entry point for loading
+- [Trung Lê] Introduced `Mapper#repository` as DSL to associate a repository to a collection
+- [Trung Lê & Tao Guo] Introduced `Configuration#mapping` as DSL to configure the mapping
+- [Coen Wessels] Allow `where`, `exclude` and `or` to accept blocks
+- [Trung Lê & Tao Guo] Introduced `Configuration#adapter` as DSL to configure the adapter
+- [Trung Lê] Introduced `Lotus::Model::Configuration`
+
+### Changed
+- [Trung Lê] Changed `Entity.attributes=` to `Entity.attributes`
+- [Trung Lê] In case of missing entity, let `Repository#find` returns `nil` instead of raise an exception
+
+### Fixed
+- [Rik Tonnard] Ensure correct behavior of `#offset` in memory adapter
+- [Benny Klotz] Ensure `Entity` to set the attributes even when the given Hash uses strings as keys
+- [Ben Askins] Always return the entity from `Repository#persist`
+- [Jeremy Stephens] Made `Memory::Query#where` and `#or` behave more like the SQL counter-part
+
+## v0.1.2 - 2014-06-26
+### Fixed
+- [Stanislav Spiridonov] Ensure to require `'hanami/model/mapping/coercions'`
+- [Krzysztof Zalewski] `Entity` defines `#id` accessor by default
+
+
+## v0.1.1 - 2014-06-23
+### Added
+- [Luca Guidi] Introduced `Lotus::Model::Mapping::Coercions` in order to decouple from `Lotus::Utils::Kernel`
+- [Luca Guidi] Official support for Ruby 2.1
+
+## v0.1.0 - 2014-04-23
+### Added
+- [Luca Guidi] Allow to inject coercer into mapper
+- [Luca Guidi] Introduced database mapping
+- [Luca Guidi] Introduced `Lotus::Entity`
+- [Luca Guidi] Introduced SQL adapter
+- [Luca Guidi] Introduced memory adapter
+– [Luca Guidi] Introduced adapters for repositories
+- [Luca Guidi] Introduced `Lotus::Repository`

data/EXAMPLE.md

@@ -0,0 +1,212 @@
+# Hanami::Model
+
+This is a guide that helps you to get started with [**Hanami::Model**](https://github.com/hanami/model).
+You can find the full code source [here](https://gist.github.com/jodosha/11211048).
+
+## Gems
+
+First of all, we need to setup a `Gemfile`.
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'sqlite3'
+gem 'hanami-model'
+```
+
+Then we can fetch the dependencies with `bundle install`.
+
+## Setup
+
+<a name="connection-url"></a>
+
+**Hanami::Model** doesn't have migrations.
+For this example we will use [Sequel](http://sequel.jeremyevans.net).
+We create the database first.
+Then we create two tables: `authors` and `articles`.
+
+```ruby
+require 'bundler/setup'
+require 'sqlite3'
+require 'hanami/model'
+require 'hanami/model/adapters/sql_adapter'
+
+connection_uri = "sqlite://#{ __dir__ }/test.db"
+
+database = Sequel.connect(connection_uri)
+
+database.create_table! :authors do
+  primary_key :id
+  String  :name
+end
+
+database.create_table! :articles do
+  primary_key :id
+  Integer :author_id,      null: false
+  String  :title
+  Integer :comments_count, default: 0
+  Boolean :published,      default: false
+end
+```
+
+## Entities
+
+We have two entities in our application: `Author` and `Article`.
+`Author` is a `Struct`, Hanami::Model can persist it.
+`Article` has a small API concerning its publishing process.
+
+```ruby
+Author = Struct.new(:id, :name) do
+  def initialize(attributes = {})
+    @id, @name = attributes.values_at(:id, :name)
+  end
+end
+
+class Article
+  include Hanami::Entity
+  attributes :author_id, :title, :comments_count, :published # id is implicit
+
+  def published?
+    !!published
+  end
+
+  def publish!
+    @published = true
+  end
+end
+```
+
+## Repositories
+
+In order to persist and query the entities above, we define two corresponding repositories:
+
+```ruby
+class AuthorRepository
+  include Hanami::Repository
+end
+
+class ArticleRepository
+  include Hanami::Repository
+
+  def self.most_recent_by_author(author, limit = 8)
+    query do
+      where(author_id: author.id).
+        desc(:id).
+        limit(limit)
+    end
+  end
+
+  def self.most_recent_published_by_author(author, limit = 8)
+    most_recent_by_author(author, limit).published
+  end
+
+  def self.published
+    query do
+      where(published: true)
+    end
+  end
+
+  def self.drafts
+    exclude published
+  end
+
+  def self.rank
+    published.desc(:comments_count)
+  end
+
+  def self.best_article_ever
+    rank.limit(1).first
+  end
+
+  def self.comments_average
+    query.average(:comments_count)
+  end
+end
+```
+
+## Loading
+
+```ruby
+Hanami::Model.configure do
+  adapter type: :sql, uri: connection_uri
+
+  mapping do
+    collection :authors do
+      entity     Author
+      repository AuthorRepository
+
+      attribute :id,   Integer
+      attribute :name, String
+    end
+
+    collection :articles do
+      entity     Article
+      repository ArticleRepository
+
+      attribute :id,             Integer
+      attribute :author_id,      Integer
+      attribute :title,          String
+      attribute :comments_count, Integer
+      attribute :published,      Boolean
+    end
+  end
+end.load!
+```
+
+## Persist
+
+We instantiate and persist an `Author` and a few `Articles` for our example:
+
+```ruby
+author = Author.new(name: 'Luca')
+AuthorRepository.create(author)
+
+articles = [
+  Article.new(title: 'Announcing Hanami',              author_id: author.id, comments_count: 123, published: true),
+  Article.new(title: 'Introducing Hanami::Router',     author_id: author.id, comments_count: 63,  published: true),
+  Article.new(title: 'Introducing Hanami::Controller', author_id: author.id, comments_count: 82,  published: true),
+  Article.new(title: 'Introducing Hanami::Model',      author_id: author.id)
+]
+
+articles.each do |article|
+  ArticleRepository.create(article)
+end
+```
+
+## Query
+
+We use the repositories to query the database and return the entities we're looking for:
+
+```ruby
+ArticleRepository.first # => return the first article
+ArticleRepository.last  # => return the last article
+
+ArticleRepository.published # => return all the published articles
+ArticleRepository.drafts    # => return all the drafts
+
+ArticleRepository.rank      # => all the published articles, sorted by popularity
+
+ArticleRepository.best_article_ever # => the most commented article
+
+ArticleRepository.comments_average # => calculates the average of comments across all the published articles.
+
+ArticleRepository.most_recent_by_author(author) # => most recent articles by an author (drafts and published).
+ArticleRepository.most_recent_published_by_author(author) # => most recent published articles by an author
+```
+
+## Business Logic
+
+As we've seen above, `Article` implements an API for publishing.
+We use that logic to alter the state of an article (from draft to published).
+We then use the repository to persist this new state.
+
+```ruby
+article = ArticleRepository.drafts.first
+
+article.published? # => false
+article.publish!
+
+article.published? # => true
+
+ArticleRepository.update(article)
+```

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright © 2014-2016 Luca Guidi
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights 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 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.

data/README.md

@@ -1,8 +1,41 @@
 # Hanami::Model
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hanami/model`. To experiment with that code, run `bin/console` for an interactive prompt.
+A persistence framework for [Hanami](http://hanamirb.org).
 
-TODO: Delete this and the text above, and describe your gem
+It delivers a convenient public API to execute queries and commands against a database.
+The architecture eases keeping the business logic (entities) separated from details such as persistence or validations.
+
+It implements the following concepts:
+
+  * [Entity](#entities) - An object defined by its identity.
+  * [Repository](#repositories) - An object that mediates between the entities and the persistence layer.
+  * [Data Mapper](#data-mapper) - A persistence mapper that keep entities independent from database details.
+  * [Adapter](#adapter) – A database adapter.
+  * [Query](#query) - An object that represents a database query.
+
+Like all the other Hanami components, it can be used as a standalone framework or within a full Hanami application.
+
+## Status
+
+[![Gem Version](https://badge.fury.io/rb/hanami-model.svg)](http://badge.fury.io/rb/hanami-model)
+[![Build Status](https://secure.travis-ci.org/hanami/model.svg?branch=master)](http://travis-ci.org/hanami/model?branch=master)
+[![Coverage](https://img.shields.io/coveralls/hanami/model/master.svg)](https://coveralls.io/r/hanami/model)
+[![Code Climate](https://img.shields.io/codeclimate/github/hanami/model.svg)](https://codeclimate.com/github/hanami/model)
+[![Dependencies](https://gemnasium.com/hanami/model.svg)](https://gemnasium.com/hanami/model)
+[![Inline docs](http://inch-ci.org/github/hanami/model.png)](http://inch-ci.org/github/hanami/model)
+
+## Contact
+
+* Home page: http://hanamirb.org
+* Mailing List: http://hanamirb.org/mailing-list
+* API Doc: http://rdoc.info/gems/hanami-model
+* Bugs/Issues: https://github.com/hanami/model/issues
+* Support: http://stackoverflow.com/questions/tagged/hanami
+* Chat: https://chat.hanamirb.org
+
+## Rubies
+
+__Hanami::Model__ supports Ruby (MRI) 2.2+ and JRuby 9000+
 
 ## Installation
 
@@ -22,15 +55,575 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+This class provides a DSL to configure adapter, mapping and collection.
+
+```ruby
+require 'hanami/model'
+
+class User
+  include Hanami::Entity
+  attributes :name, :age
+end
+
+class UserRepository
+  include Hanami::Repository
+end
+
+Hanami::Model.configure do
+  adapter type: :sql, uri: 'postgres://localhost/database'
+
+  mapping do
+    collection :users do
+      entity      User
+      repository UserRepository
+
+      attribute :id,   Integer
+      attribute :name, String
+      attribute :age,  Integer
+    end
+  end
+end
+
+Hanami::Model.load!
+
+user = User.new(name: 'Luca', age: 32)
+user = UserRepository.create(user)
+
+puts user.id # => 1
+
+u = UserRepository.find(user.id)
+u == user # => true
+```
+
+## Concepts
+
+### Entities
+
+An object that is defined by its identity.
+See "Domain Driven Design" by Eric Evans.
+
+An entity is the core of an application, where the part of the domain logic is implemented.
+It's a small, cohesive object that expresses coherent and meaningful behaviors.
+
+It deals with one and only one responsibility that is pertinent to the
+domain of the application, without caring about details such as persistence
+or validations.
+
+This simplicity of design allows developers to focus on behaviors, or
+message passing if you will, which is the quintessence of Object Oriented Programming.
+
+```ruby
+require 'hanami/model'
+
+class Person
+  include Hanami::Entity
+  attributes :name, :age
+end
+```
+
+When a class includes `Hanami::Entity` it receives the following interface:
+
+  * `#id`
+  * `#id=`
+  * `#initialize(attributes = {})`
+
+`Hanami::Entity` also provides the `.attributes` for defining attribute accessors for the given names.
+
+If we expand the code above in **pure Ruby**, it would be:
+
+```ruby
+class Person
+  attr_accessor :id, :name, :age
+
+  def initialize(attributes = {})
+    @id, @name, @age = attributes.values_at(:id, :name, :age)
+  end
+end
+```
+
+**Hanami::Model** ships `Hanami::Entity` for developers's convenience.
+
+**Hanami::Model** depends on a narrow and well-defined interface for an Entity - `#id`, `#id=`, `#initialize(attributes={})`.
+If your object implements that interface then that object can be used as an Entity in the **Hanami::Model** framework.
+
+However, we suggest to implement this interface by including `Hanami::Entity`, in case that future versions of the framework will expand it.
+
+See [Dependency Inversion Principle](http://en.wikipedia.org/wiki/Dependency_inversion_principle) for more on interfaces.
+
+When a class extends a `Hanami::Entity` class, it will also *inherit* its mother's attributes.
+
+```ruby
+require 'hanami/model'
+
+class Article
+  include Hanami::Entity
+  attributes :name
+end
+
+class RareArticle < Article
+  attributes :price
+end
+```
 
-## Development
+That is, `RareArticle`'s attributes carry over `:name` attribute from `Article`,
+thus is `:id, :name, :price`.
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Repositories
+
+An object that mediates between entities and the persistence layer.
+It offers a standardized API to query and execute commands on a database.
+
+A repository is **storage independent**, all the queries and commands are
+delegated to the current adapter.
+
+This architecture has several advantages:
+
+  * Applications depend on a standard 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
+
+  * Confines persistence logic at a low level
+
+  * Multiple data sources can easily coexist in an application
+
+When a class includes `Hanami::Repository`, it will receive the following interface:
+
+  * `.persist(entity)` – Create or update an entity
+  * `.create(entity)`  – Create a record for the given entity
+  * `.update(entity)`  – Update the record corresponding to the given entity
+  * `.delete(entity)`  – Delete the record corresponding to the given entity
+  * `.all`   - Fetch all the entities from the collection
+  * `.find`  - Fetch an entity from the collection by its ID
+  * `.first` - Fetch the first entity from the collection
+  * `.last`  - Fetch the last entity from the collection
+  * `.clear` - Delete all the records from the collection
+  * `.query` - Fabricates a query object
+
+**A collection is a homogenous set of records.**
+It corresponds to a table for a SQL database or to a MongoDB collection.
+
+**All the queries are private**.
+This decision forces developers to define intention revealing API, instead of leaking storage API details outside of a repository.
+
+Look at the following code:
+
+```ruby
+ArticleRepository.where(author_id: 23).order(:published_at).limit(8)
+```
+
+This is **bad** for a variety of 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).
+
+There is a better way:
+
+```ruby
+require 'hanami/model'
+
+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
+```
+
+This is a **huge improvement**, because:
+
+  * 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 stubbing this method.
+
+  * If we change the storage, the callers aren't affected.
+
+Here is an extended example of a repository that uses the SQL adapter.
+
+```ruby
+class ArticleRepository
+  include Hanami::Repository
+
+  def self.most_recent_by_author(author, limit = 8)
+    query do
+      where(author_id: author.id).
+        desc(:id).
+        limit(limit)
+    end
+  end
+
+  def self.most_recent_published_by_author(author, limit = 8)
+    most_recent_by_author(author, limit).published
+  end
+
+  def self.published
+    query do
+      where(published: true)
+    end
+  end
+
+  def self.drafts
+    exclude published
+  end
+
+  def self.rank
+    published.desc(:comments_count)
+  end
+
+  def self.best_article_ever
+    rank.limit(1)
+  end
+
+  def self.comments_average
+    query.average(:comments_count)
+  end
+end
+```
+
+You can also extract the common logic from your repository into a module to reuse it in other repositories. Here is a pagination example:
+
+```ruby
+module RepositoryHelpers
+  module Pagination
+    def paginate(limit: 10, offset: 0)
+      query do
+        limit(limit).offset(offset)
+      end
+    end
+  end
+end
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+class ArticleRepository
+  include Hanami::Repository
+  extend RepositoryHelpers::Pagination
+
+  def self.published
+    query do
+      where(published: true)
+    end
+  end
+
+  # other repository-specific methods here
+end
+```
+
+That will allow `.paginate` usage on `ArticleRepository`, for example:
+`ArticleRepository.published.paginate(15, 0)`
+
+**Your models and repositories have to be in the same namespace.** Otherwise `Hanami::Model::Mapper#load!`
+will not initialize your repositories correctly.
+
+```ruby
+class MyHanamiApp::Model::User
+  include Hanami::Entity
+  # your code here
+end
+
+# This repository will work...
+class MyHanamiApp::Model::UserRepository
+  include Hanami::Repository
+  # your code here
+end
+
+# ...this will not!
+class MyHanamiApp::Repository::UserRepository
+  include Hanami::Repository
+  # your code here
+end
+```
+
+### Data Mapper
+
+A persistence mapper that keeps entities independent from database details.
+It is database independent, it can work with SQL, document, and even with key/value stores.
+
+The role of a data mapper is to translate database columns into the corresponding attribute of an entity.
+
+```ruby
+require 'hanami/model'
+
+mapper = Hanami::Model::Mapper.new do
+  collection :users do
+    entity User
+
+    attribute :id,   Integer
+    attribute :name, String
+    attribute :age,  Integer
+  end
+end
+```
+
+For simplicity's sake, imagine that the mapper above is used with a SQL database.
+We use `#collection` to indicate the name of the table that we want to map, `#entity` to indicate the class that we want to associate.
+In the end, each call to `#attribute` associates the specified column with a corresponding Ruby type.
+
+For advanced mapping and legacy databases, please have a look at the API doc.
+
+**Known limitations**
+
+Note there are limitations with inherited entities:
+
+```ruby
+require 'hanami/model'
+
+class Article
+  include Hanami::Entity
+  attributes :name
+end
+
+class RareArticle < Article
+  attributes :price
+end
+
+mapper = Hanami::Model::Mapper.new do
+  collection :articles do
+    entity Article
+
+    attribute :id,    Integer
+    attribute :name,  String
+    attribute :price, Integer
+  end
+end
+```
+
+In the example above, there are a few problems:
+
+* `Article` could not be fetched because mapping could not map `price`.
+* Finding a persisted `RareArticle` record, for eg. `ArticleRepository.find(123)`,
+the result is an `Article` not `RareArticle`.
+
+### Adapter
+
+An adapter is a concrete implementation of persistence logic for a specific database.
+**Hanami::Model** is shipped with three adapters:
+
+  * SqlAdapter
+  * MemoryAdapter
+  * FileSystemAdapter
+
+An adapter can be associated with one or multiple repositories.
+
+```ruby
+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')
+
+PersonRepository.adapter  = adapter
+ArticleRepository.adapter = adapter
+```
+
+In the example above, we reuse the adapter because the target tables (`people` and `articles`) are defined in the same database.
+**As rule of thumb, one adapter instance per database.**
+
+### Query
+
+An object that implements an interface for querying the database.
+This interface may vary, according to the adapter's specifications.
+
+Here is common interface for existing class:
+
+  * `.all` - Resolves the query by fetching records from the database and translating them into entities
+  * `.where`, `.and` - Adds a condition that behaves like SQL `WHERE`
+  * `.or` - Adds a condition that behaves like SQL `OR`
+  * `.exclude`, `.not` - Logical negation of a #where condition
+  * `.select` - Selects only the specified columns
+  * `.order`, `.asc` - Specify the ascending order of the records, sorted by the given columns
+  * `.reverse_order`, `.desc` - Specify the descending order of the records, sorted by the given columns
+  * `.limit` - Limit the number of records to return
+  * `.offset` - Specify an `OFFSET` clause. Due to SQL syntax restriction, offset MUST be used with `#limit`
+  * `.sum` - Returns the sum of the values for the given column
+  * `.average`, `.avg` - Returns the average of the values for the given column
+  * `.max` - Returns the maximum value for the given column
+  * `.min` - Returns the minimum value for the given column
+  * `.interval` - Returns the difference between the MAX and MIN for the given column
+  * `.range` - Returns a range of values between the MAX and the MIN for the given column
+  * `.exist?` - Checks if at least one record exists for the current conditions
+  * `.count` - Returns a count of the records for the current conditions
+  * `.join` - Adds an inner join with a table (only SQL)
+  * `.left_join` - Adds a left join with a table (only SQL)
+
+If you need more information regarding those methods, you can use comments from [memory](https://github.com/hanami/model/blob/master/lib/hanami/model/adapters/memory/query.rb#L29) or [sql](https://github.com/hanami/model/blob/master/lib/hanami/model/adapters/sql/query.rb#L28) adapters interface.
+
+Think of an adapter for Redis, it will probably employ different strategies to filter records than an SQL query object.
+
+### Conventions
+
+  * A repository must be named after an entity, by appending `"Repository"` to the entity class name (eg. `Article` => `ArticleRepository`).
+
+### Configurations
+
+  * Non-standard repository can be configured for an entity, by setting `repository` on the collection.
+
+  ```ruby
+  require 'hanami/model'
+
+  mapper = Hanami::Model::Mapper.new do
+    collection :users do
+      entity User
+      repository EmployeeRepository
+    end
+  end
+  ```
+
+### Thread safety
+
+**Hanami::Model**'s is thread safe during the runtime, but it isn't during the loading process.
+The mapper compiles some code internally, be sure to safely load it before your application starts.
+
+```ruby
+Mutex.new.synchronize do
+  Hanami::Model.load!
+end
+```
+
+**This is not necessary, when Hanami::Model is used within a Hanami application.**
+
+## Features
+
+### Timestamps
+
+If an entity has the following accessors: `:created_at` and `:updated_at`, they will be automatically updated when the entity is persisted.
+
+```ruby
+require 'hanami/model'
+
+class User
+  include Hanami::Entity
+  attributes :name, :created_at, :updated_at
+end
+
+class UserRepository
+  include Hanami::Repository
+end
+
+Hanami::Model.configure do
+  adapter type: :memory, uri: 'memory://localhost/timestamps'
+
+  mapping do
+    collection :users do
+      entity     User
+      repository UserRepository
+
+      attribute :id,         Integer
+      attribute :name,       String
+      attribute :created_at, DateTime
+      attribute :updated_at, DateTime
+    end
+  end
+end.load!
+
+user = User.new(name: 'L')
+puts user.created_at # => nil
+puts user.updated_at # => nil
+
+user = UserRepository.create(user)
+puts user.created_at.to_s # => "2015-05-15T10:12:20+00:00"
+puts user.updated_at.to_s # => "2015-05-15T10:12:20+00:00"
+
+sleep 3
+user.name = "Luca"
+user      = UserRepository.update(user)
+puts user.created_at.to_s # => "2015-05-15T10:12:20+00:00"
+puts user.updated_at.to_s # => "2015-05-15T10:12:23+00:00"
+```
+
+### Dirty Tracking
+
+Entities are able to track changes of their data, if `Hanami::Entity::DirtyTracking` is included.
+
+```ruby
+require 'hanami/model'
+
+class User
+  include Hanami::Entity
+  include Hanami::Entity::DirtyTracking
+  attributes :name, :age
+end
+
+class UserRepository
+  include Hanami::Repository
+end
+
+Hanami::Model.configure do
+  adapter type: :memory, uri: 'memory://localhost/dirty_tracking'
+
+  mapping do
+    collection :users do
+      entity     User
+      repository UserRepository
+
+      attribute :id,   Integer
+      attribute :name, String
+      attribute :age,  String
+    end
+  end
+end.load!
+
+user = User.new(name: 'L')
+user.changed? # => false
+
+user.age = 33
+user.changed?           # => true
+user.changed_attributes # => {:age=>33}
+
+user = UserRepository.create(user)
+user.changed? # => false
+
+user.update(name: 'Luca')
+user.changed?           # => true
+user.changed_attributes # => {:name=>"Luca"}
+
+user = UserRepository.update(user)
+user.changed? # => false
+
+result = UserRepository.find(user.id)
+result.changed? # => false
+```
+
+## Example
+
+For a full working example, have a look at [EXAMPLE.md](https://github.com/hanami/model/blob/master/EXAMPLE.md).
+Please remember that the setup code is only required for the standalone usage of **Hanami::Model**.
+A **Hanami** application will handle that configurations for you.
+
+## Versioning
+
+__Hanami::Model__ uses [Semantic Versioning 2.0.0](http://semver.org)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hanami-model.
+1. Fork it ( https://github.com/hanami/model/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Copyright
+
+Copyright © 2014-2016 Luca Guidi – Released under MIT License
 
+This project was formerly known as Lotus (`lotus-model`).