hanami-model 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29439a9ce3f9aa3cdd0600a6a04a0316209eb91d
-  data.tar.gz: fa6bb573a2e58f14cc3b09126168fdc4ed88f72a
+  metadata.gz: ac96a7e41555f5a379c12d3fd45c999ea4ce7e93
+  data.tar.gz: 59f4d8fe809cd3536bc47fff73830ba37304a6c7
 SHA512:
-  metadata.gz: 10a26d11cb59a13d93664a4e9fd29d35f8fa6ce788d95281b7b805ed04cf9a4ca390ace931c3a943ee65fc8a55b138f9931d5c351a50d09b19d8acf8b1845cae
-  data.tar.gz: 5d5ef5cf0bdee581b7d4d9272fd064c3c8973ea4a6da813fe318f49c24b00a285c6a4b2a410166b19560ddbc6a4a9a69f4a3221d79efc952f3d40e8234599a63
+  metadata.gz: f730a23b1a29d426405c1cb79ee2ea74ab73f9baaa73521c7136b3f39913a4a9dcc6cdeed2e45ce4ffd2b334fbb839e637b8ff60edbafa19777d47fb9e5c505d
+  data.tar.gz: 382a94c09b68ed787d67643b6128ce1d2f54b0d2c669bc2c0248ad45c8e54fbfe14bd613bb9e9268988d16dcc29f2dd05c30be08c7461ec1a30b11fe34f9f635

data/CHANGELOG.md

@@ -1,6 +1,50 @@
 # Hanami::Model
 A persistence layer for Hanami
 
+## v0.7.0 - 2016-11-15
+### Added
+- [Luca Guidi] `Hanami::Entity` defines an automatic schema for SQL databases
+– [Luca Guidi] `Hanami::Entity` attributes schema
+- [Luca Guidi] Experimental support for One-To-Many association (aka `has_many`)
+- [Luca Guidi] Native support for PostgreSQL types like UUID, Array, JSON(B) and Money
+- [Luca Guidi] Repositories instances can access all the relations (eg. `BookRepository` can access `users` relation via `#users`)
+- [Luca Guidi] Automapping for SQL databases
+- [Luca Guidi] Added `Hanami::Model::DatabaseError`
+
+### Changed
+- [Luca Guidi] Entities are immutable
+- [Luca Guidi] Removed support for Memory and File System adapters
+- [Luca Guidi] Removed support for _dirty tracking_
+- [Luca Guidi] `Hanami::Entity.attributes` method no longer accepts a list of attributes, but a block to optionally define typed attributes
+- [Luca Guidi] Removed `#fetch`, `#execute` and `#transaction` from repository
+- [Luca Guidi] Removed `mapping` block from `Hanami::Model.configure`
+- [Luca Guidi] Changed `adapter` signature in `Hanami::Model.configure` (use `adapter :sql, ENV['DATABASE_URL']`)
+- [Luca Guidi] Repositories must inherit from `Hanami::Repository` instead of including it
+- [Luca Guidi] Entities must inherit from `Hanami::Entity` instead of including it
+- [Pascal Betz] Repositories use instance level interface (eg. `BookRepository.new.find` instead of `BookRepository.find`)
+- [Luca Guidi] Repositories now accept hashes for CRUD operations
+- [Luca Guidi] `Hanami::Repository#create` now accepts: hash (or entity)
+- [Luca Guidi] `Hanami::Repository#update` now accepts two arguments: primary key (`id`) and data (or entity)
+- [Luca Guidi] `Hanami::Repository#delete` now accepts: primary key (`id`)
+- [Luca Guidi] Drop `Hanami::Model::NonPersistedEntityError`, `Hanami::Model::InvalidMappingError`, `Hanami::Model::InvalidCommandError`, `Hanami::Model::InvalidQueryError`
+- [Luca Guidi] Official support for Ruby 2.3 and JRuby 9.0.5.0
+- [Luca Guidi] Drop support for Ruby 2.0, 2.1, 2.2, and JRuby 9.0.0.0
+- [Luca Guidi] Drop support for `mysql` gem in favor of `mysql2`
+
+### Fixed
+- [Luca Guidi] Ensure booleans to be correctly dumped in database
+- [Luca Guidi] Ensure to respect default database schema values
+- [Luca Guidi] Ensure SQL UPDATE to not override non-default primary key
+- [James Hamilton] Print appropriate error message when trying to create a PostgreSQL database that is already existing
+
+## v0.6.2 - 2016-06-01
+### Changed
+- [Kjell-Magne Øierud] Ensure inherited entities to expose attributes from base class
+
+## v0.6.1 - 2016-02-05
+### Changed
+- [Hélio Costa e Silva & Pascal Betz] Mapping SQL Adapter's errors as `Hanami::Model` errors
+
 ## v0.6.1 - 2016-02-05
 ### Changed
 - [Hélio Costa e Silva & Pascal Betz] Mapping SQL Adapter's errors as `Hanami::Model` errors

data/README.md

@@ -7,11 +7,8 @@ The architecture eases keeping the business logic (entities) separated from deta
 
 It implements the following concepts:
 
-  * [Entity](#entities) - An object defined by its identity.
+  * [Entity](#entities) - A model domain 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.
 
@@ -35,7 +32,7 @@ Like all the other Hanami components, it can be used as a standalone framework o
 
 ## Rubies
 
-__Hanami::Model__ supports Ruby (MRI) 2.2+ and JRuby 9000+
+__Hanami::Model__ supports Ruby (MRI) 2.3+ and JRuby 9.1.5.0+
 
 ## Installation
 
@@ -55,51 +52,40 @@ Or install it yourself as:
 
 ## Usage
 
-This class provides a DSL to configure adapter, mapping and collection.
+This class provides a DSL to configure the connection.
 
 ```ruby
 require 'hanami/model'
 
-class User
-  include Hanami::Entity
-  attributes :name, :age
+class User < Hanami::Entity
 end
 
-class UserRepository
-  include Hanami::Repository
+class UserRepository < Hanami::Repository
 end
 
 Hanami::Model.configure do
-  adapter type: :sql, uri: 'postgres://localhost/database'
+  adapter :sql, 'postgres://username:password@localhost/bookshelf'
+end.load!
 
-  mapping do
-    collection :users do
-      entity      User
-      repository UserRepository
-
-      attribute :id,   Integer
-      attribute :name, String
-      attribute :age,  Integer
-    end
-  end
-end
+repository = UserRepository.new
+user       = repository.create(name: 'Luca')
 
-Hanami::Model.load!
+puts user.id # => 1
 
-user = User.new(name: 'Luca', age: 32)
-user = UserRepository.create(user)
+found = repository.find(user.id)
+found == user # => true
 
-puts user.id # => 1
+updated = repository.update(user.id, age: 34)
+updated.age # => 34
 
-u = UserRepository.find(user.id)
-u == user # => true
+repository.delete(user.id)
 ```
 
 ## Concepts
 
 ### Entities
 
-An object that is defined by its identity.
+A model domain 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.
@@ -115,59 +101,10 @@ message passing if you will, which is the quintessence of Object Oriented Progra
 ```ruby
 require 'hanami/model'
 
-class Person
-  include Hanami::Entity
-  attributes :name, :age
+class Person < Hanami::Entity
 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
-```
-
-That is, `RareArticle`'s attributes carry over `:name` attribute from `Article`,
-thus is `:id, :name, :price`.
-
 ### Repositories
 
 An object that mediates between entities and the persistence layer.
@@ -192,18 +129,16 @@ This architecture has several advantages:
 
 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.**
+  * `#create(data)`     – Create a record for the given data (or entity)
+  * `#update(id, data)` – Update the record corresponding to the given id by setting the given data (or entity)
+  * `#delete(id)`       – Delete the record corresponding to the given id
+  * `#all`              - Fetch all the entities from the relation
+  * `#find`             - Fetch an entity from the relation by primary key
+  * `#first`            - Fetch the first entity from the relation
+  * `#last`             - Fetch the last entity from the relation
+  * `#clear`            - Delete all the records from the relation
+
+**A relation 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**.
@@ -212,7 +147,7 @@ This decision forces developers to define intention revealing API, instead of le
 Look at the following code:
 
 ```ruby
-ArticleRepository.where(author_id: 23).order(:published_at).limit(8)
+ArticleRepository.new.where(author_id: 23).order(:published_at).limit(8)
 ```
 
 This is **bad** for a variety of reasons:
@@ -232,14 +167,11 @@ 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)
+class ArticleRepository < Hanami::Repository
+  def most_recent_by_author(author, limit: 8)
+    articles.where(author_id: author.id).
+      order(:published_at).
+      limit(limit)
   end
 end
 ```
@@ -256,253 +188,31 @@ This is a **huge improvement**, because:
 
   * 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
+### Mapping
 
-  def self.best_article_ever
-    rank.limit(1)
-  end
+Hanami::Model can **_automap_** columns from relations and entities attributes.
 
-  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
-
-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.
+However, there are cases where columns and attribute names do not match (mainly **legacy databases**).
 
 ```ruby
 require 'hanami/model'
 
-mapper = Hanami::Model::Mapper.new do
-  collection :users do
-    entity User
+class UserRepository < Hanami::Repository
+  self.relation = :t_user_archive
 
-    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
+  mapping do
+    attribute :id,   from: :i_user_id
+    attribute :name, from: :s_name
+    attribute :age,  from: :i_age
   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.
-
-### Model Error Coercions
-
-All adapters' errors are encapsulated into Hanami error classes.
-
-Hanami Model may raise the following exceptions:
-
-  * `Hanami::Model::UniqueConstraintViolationError`
-  * `Hanami::Model::ForeignKeyConstraintViolationError`
-  * `Hanami::Model::NotNullConstraintViolationError`
-  * `Hanami::Model::CheckConstraintViolationError`
-
-For any other adapter's errors, Hanami will raise the `Hanami::Model::InvalidCommandError` object.
-All errors contains the root cause and the full error message thrown by sql adapter.
+**NOTE:** This feature should be used only when **_automapping_** fails because the naming mismatch.
 
 ### 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.
@@ -525,105 +235,29 @@ If an entity has the following accessors: `:created_at` and `:updated_at`, they
 ```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
+class User < Hanami::Entity
 end
 
-class UserRepository
-  include Hanami::Repository
+class UserRepository < 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
+  adapter :sql, uri: 'postgresql://localhost/bookshelf'
 end.load!
 
-user = User.new(name: 'L')
-user.changed? # => false
-
-user.age = 33
-user.changed?           # => true
-user.changed_attributes # => {:age=>33}
+repository = UserRepository.new
 
-user = UserRepository.create(user)
-user.changed? # => false
+user = repository.create(name: 'Luca')
 
-user.update(name: 'Luca')
-user.changed?           # => true
-user.changed_attributes # => {:name=>"Luca"}
+puts user.created_at.to_s # => "2016-09-19 13:40:13 UTC"
+puts user.updated_at.to_s # => "2016-09-19 13:40:13 UTC"
 
-user = UserRepository.update(user)
-user.changed? # => false
-
-result = UserRepository.find(user.id)
-result.changed? # => false
+sleep 3
+user = repository.update(user.id, age: 34)
+puts user.created_at.to_s # => "2016-09-19 13:40:13 UTC"
+puts user.updated_at.to_s # => "2016-09-19 13:40:16 UTC"
 ```
 
-## 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)