lotus-model 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f8aeb016a4308c564ac6a9da4d20dad73669e64
-  data.tar.gz: 8a63dbd06ddc13e1c78db5c9961e26a2ace6006b
+  metadata.gz: ae1042adba4d02f0e12ad69ccb025061603a3b24
+  data.tar.gz: 0c976c625163281c1d8e03409f1ff79db9838ba6
 SHA512:
-  metadata.gz: 16812c63f5ae325e6be21362f00a37aa9e926356119ffafbb6e76823f342db5f18b5a9d1a6a8d4d302045b6c2c72d64e5fa167fda344823664eb056b52efa2e5
-  data.tar.gz: dea5481126a0c5104d68335cfe294199c7183f2ba30209e173184d00d490c98bd567d9057f790c2e336cba4baf9da66648c13cd84310c9b9da433195ea28ef04
+  metadata.gz: 91017c7d534780cb9dd7004969835762c1185596845ac8b9a968d762af7913709ddfbd17d5b68daea1c6851152a3b45e6135d2b23b65f548619b77f22a5d8ec5
+  data.tar.gz: 5a40607f634bdea786e3d2f6005d14acc5f27160f01bb6cb0a0f028414a1163bb0612131ba8554cd1264bcfa7086be853054f7e246d55ff17d9797b7ebe83335

data/CHANGELOG.md

@@ -1,168 +1,52 @@
-## v0.1.2
-### Jun 26, 2014
-
-27eef39 2014-06-26 **Luca Guidi** Bump version to 0.1.2
-
-afc33eb 2014-06-24 **Stanislav Spiridonov** Fix Coercions require
-
-f5778e4 2014-05-22 **Krzysztof Zalewski** Entity defines #id accessor by default
-
-## v0.1.1
-### Jun 23, 2014
-
-99ea094 2014-06-13 **Luca Guidi** Introduced Lotus::Model::Mapping::Coercions in order to decouple from Lotus::Utils::Kernel
-
-3fa2693 2014-05-10 **Luca Guidi** Support for Ruby 2.1.2
-
-3682552 2014-04-25 **Peter Suschlik** Iterate over each value using `each_value`
-
-cce7746 2014-04-24 **Peter Suschlik** Just extend the base class. No need to class_eval
-
-719e03c 2014-04-24 **Peter Suschlik** Pass list of attributes to `attr_accessor`
-
-## v0.1.0
-### Apr 23, 2014
-
-ec395d8 2014-04-22 **Luca Guidi** Added an accessor to introspect Mapper collections
-
-96d9d00 2014-04-18 **Luca Guidi** Allow queries to be composed
-
-a7d64c1 2014-04-18 **Damir Zekic**  Don't serialize identity column if it's nil
-
-8484941 2014-04-17 **Luca Guidi** Fixed Sql::Collection#select for Ruby 2.0.0
-
-bd9d679 2014-04-17 **Luca Guidi** Allow Sql#Query#order and #desc to accept multiple columns and/or multiple invokations.
-
-b6a7af8 2014-04-16 **Luca Guidi** Enforce Adapter interface with #command and #query
-
-3787f33 2014-04-16 **Luca Guidi** Allow Mapper to accept a custom coercer for the database
-
-893109a 2014-04-15 **Luca Guidi** Ensure that unmapped attributes doens't interfer with initialization of entities
-
-da37d7a 2014-04-15 **Luca Guidi** Implemented Memory::Query #to_s, #empty? and #any?
-
-94f0ecb 2014-04-15 **Luca Guidi** Implemented Repository#exclude
-
-6998328 2014-04-15 **Luca Guidi** Removed unused require
-
-7211935 2014-04-15 **Luca Guidi** Implemented Sql::Query #to_s, #empty? and #any?
-
-5e7e0c4 2014-04-15 **Luca Guidi** Implemented Sql::Query#negate!
-
-5df30c2 2014-04-15 **Luca Guidi** Define top level constant ::Boolean
-
-a9df2ec 2014-04-15 **Luca Guidi** Load Mapper when the framework is loaded
-
-de21101 2014-04-15 **Luca Guidi** Extracted Mapping::Collection::REPOSITORY_SUFFIX constant
-
-b4ed0fe 2014-04-15 **Luca Guidi** Expose Mapper#load! to make Lotus::Model thread safe
-
-0936848 2014-04-14 **Luca Guidi** Moved UnmappedCollectionError under a separated file
-
-b6e49ff 2014-04-14 **Luca Guidi** Removed serialization responsibility from Mapper
-
-9057fbd 2014-04-14 **Luca Guidi** Removed unnecessary conditional in test
-
-43c462f 2014-04-14 **Luca Guidi** Renamed Lotus::Model::Mapping::Collection#key into #identity
-
-af59039 2014-04-14 **Luca Guidi** Removed serialization responsibility from Sql::Command
-
-92101bb 2014-04-14 **Luca Guidi** Removed deserialization responsibility from Sql::Query
-
-04e9597 2014-04-14 **Luca Guidi** Rewritten Sql::Command, it now works on scoped queries
-
-eb49746 2014-04-14 **Luca Guidi** Coerce with the right type the primary key for Repository.find
-
-daf3e04 2014-04-14 **Luca Guidi** Implemented Command for mutation actions such as insert, update, delete. Removed serialization responsibility to the adapter. Removed unused code.
-
-5ae8b11 2014-04-13 **Luca Guidi** Sql and Memory adapter are now using Query to serve #all, #find, #first, #last
-
-b0a35c5 2014-04-13 **Luca Guidi** Implemented Query#asc and #desc
-
-ef2d1fa 2014-04-13 **Luca Guidi** Make querying thread safe for MemoryAdapter
-
-db7e699 2014-04-12 **Luca Guidi** Implemented Query#select
-
-2d83581 2014-04-12 **Luca Guidi** Implemented Query#exist?
-
-13cfde0 2014-04-12 **Luca Guidi** Implemented Query#exclude
-
-79596de 2014-04-12 **Luca Guidi** Implemented Query#range
-
-70df238 2014-04-12 **Luca Guidi** Implemented Query#interval
-
-a0cbb8c 2014-04-12 **Luca Guidi** Implemented Query#min
-
-41e3d69 2014-04-12 **Luca Guidi** Implemented Query#max
-
-5577283 2014-04-12 **Luca Guidi** Changed the semantic of Query#average: let return a float if needed, handle strings and nil values
-
-3e1bddc 2014-04-12 **Luca Guidi** Implemented Query#sum
-
-97d0fb9 2014-04-12 **Luca Guidi** Implemented Lotus::Model::Adapters::Memory::Query#average
-
-d7068b5 2014-04-12 **Luca Guidi** Implemented Lotus::Model::Adapters::Sql::Query#average
-
-21abc27 2014-04-10 **Luca Guidi** Introduced Sql::Query
-
-7b63b7f 2014-04-10 **Luca Guidi** Implemented Memory::Query#count
-
-517a89a 2014-04-10 **Luca Guidi** Make the results of Repository queries lazy
-
-e6a756c 2014-04-10 **Luca Guidi** Renamed adapters with the "Adapter" suffix, in order to keep namespaces free.
-
-8a076b9 2014-04-10 **Luca Guidi** Implemented Query#or, #limit and #offset
-
-388957d 2014-04-09 **Luca Guidi** Added tests for SQL adapter and implemented #where, #and and #order for all the adapters
-
-5a97c12 2014-04-09 **Luca Guidi** Initial design for quering the datasource
-
-6f804db 2014-04-08 **Luca Guidi** Use Lotus::Utils::Kernel conversions
-
-4ae6967 2014-04-07 **Luca Guidi** Allow the mapper to specify the primary key of a collection with Lotus::Model::Mapper::Collection#key.
-
-85def40 2014-04-07 **Luca Guidi** Extracted Lotus::Model::Adapters::Memory::Collection::PrimaryKey
-
-ff8d6d4 2014-04-07 **Luca Guidi** Lotus::Repository.collection is now configured by the framework internals.
-
-122e040 2014-04-02 **Luca Guidi** Introduced attributes mapping and (de)serializations policies based on it.
-
-f925ebc 2014-03-26 **Luca Guidi** Lotus::Entity#id is always the primary key
-
-0bf8bb5 2014-03-26 **Luca Guidi** Introduced Lotus::Model::Adapters::Sql
-
-cfbed99 2014-03-26 **Luca Guidi** Lotus::Model::Repository => Lotus::Repository
-
-3a72d68 2014-03-26 **Luca Guidi** Lotus::Model::Entity => Lotus::Entity
-
-ed29d2d 2014-03-26 **Luca Guidi** Preload Lotus::Model::Repository
-
-f1bda7f 2014-03-26 **Luca Guidi** Improved tests and better semantic for Lotus::Model::Repository
-
-65b8e1a 2014-03-26 **Luca Guidi** Tests and thready safety for Lotus::Model::Adapters::Memory
-
-63d9fc5 2014-03-26 **Luca Guidi** When generate Entity#initialize use class attribute 'attributes', instead of the homonym argument
-
-442987d 2014-02-17 **Luca Guidi** Lotus::Model::Repository.find raises a Lotus::Model::RecordNotFound exception if it can't find a record, associated with the given ID
-
-c2b94e0 2014-02-15 **Luca Guidi** Ensure memory adapted is able to find a record for a string id
-
-b258ea0 2014-02-07 **Luca Guidi** Make Repository to work with entities
-
-0371b41 2014-02-05 **Luca Guidi** Implemented Entity
-
-9d2bfe3 2014-02-05 **Luca Guidi** Renamed "object" in "entity" in method signatures. Repositories and adapters work on objects that are aware of the identity's concept.
-
-be0e4e0 2014-02-05 **Luca Guidi** Extracted Abstract adapter and made Memory to inherit from it
-
-3ca28af 2014-02-05 **Luca Guidi** Let Repository to delegate operations to the current adapter
-
-3318bd1 2014-02-05 **Luca Guidi** Made Repository methods to accept one object instead of a collection
-
-baf378a 2014-02-05 **Luca Guidi** Implemented Repository.delete
-
-1b8c0a0 2014-02-05 **Luca Guidi** Implemented Repository.persist, .create and .update
-
-c6bde87 2014-02-05 **Luca Guidi** Implemented Repository.find
-
-a45248f 2014-02-05 **Luca Guidi** Initial mess
+# Lotus::Model
+A persistence layer for Lotus
+
+## 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 `'lotus/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

@@ -1,6 +1,6 @@
 # Lotus::Model
 
-This is a guide that helps you to getting started with [**Lotus::Model**](https://github.com/lotus/model).
+This is a guide that helps you to get started with [**Lotus::Model**](https://github.com/lotus/model).
 You can find the full code source [here](https://gist.github.com/jodosha/11211048).
 
 ## Gems
@@ -18,8 +18,12 @@ Then we can fetch the dependencies with `bundle install`.
 
 ## Setup
 
-**Lotus::Model** doesn't have migrations, for this example we're gonna use [Sequel](http://sequel.jeremyevans.net).
-We create the database first, and then two tables: `authors` and `articles`.
+<a name="connection-url"></a>
+
+**Lotus::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'
@@ -60,7 +64,7 @@ end
 
 class Article
   include Lotus::Entity
-  self.attributes = :author_id, :title, :comments_count, :published # id is implicit
+  attributes :author_id, :title, :comments_count, :published # id is implicit
 
   def published?
     !!published
@@ -111,7 +115,7 @@ class ArticleRepository
   end
 
   def self.best_article_ever
-    rank.limit(1)
+    rank.limit(1).first
   end
 
   def self.comments_average
@@ -120,48 +124,38 @@ class ArticleRepository
 end
 ```
 
-## Mapper
-
-We create a correspondence between the database columns with the entities' attributes.
+## Loading
 
 ```ruby
-mapper = Lotus::Model::Mapper.new do
-  collection :authors do
-    entity Author
-
-    attribute :id,   Integer
-    attribute :name, String
-  end
+Lotus::Model.configure do
+  adapter type: :sql, uri: connection_uri
 
-  collection :articles do
-    entity Article
+  mapping do
+    collection :authors do
+      entity     Author
+      repository AuthorRepository
 
-    attribute :id,             Integer
-    attribute :author_id,      Integer
-    attribute :title,          String
-    attribute :comments_count, Integer
-    attribute :published,      Boolean
-  end
-end
-```
-
-## Loading
+      attribute :id,   Integer
+      attribute :name, String
+    end
 
-We create an adapter instance, passing `mapper` and the connection URI (see above).
-Please remember that the setup code is only required for the standalone usage of **Lotus::Model**.
-A **Lotus** application will handle that configurations for you.
+    collection :articles do
+      entity     Article
+      repository ArticleRepository
 
-```ruby
-adapter = Lotus::Model::Adapters::SqlAdapter.new(mapper, connection_uri)
-AuthorRepository.adapter  = adapter
-ArticleRepository.adapter = adapter
-
-mapper.load! # last operation
+      attribute :id,             Integer
+      attribute :author_id,      Integer
+      attribute :title,          String
+      attribute :comments_count, Integer
+      attribute :published,      Boolean
+    end
+  end
+end.load!
 ```
 
 ## Persist
 
-Let's instantiate and persist some objects for our example:
+We instantiate and persist an `Author` and a few `Articles` for our example:
 
 ```ruby
 author = Author.new(name: 'Luca')
@@ -181,7 +175,7 @@ end
 
 ## Query
 
-We can use repositories to query the database and return the entities we're looking for:
+We use the repositories to query the database and return the entities we're looking for:
 
 ```ruby
 ArticleRepository.first # => return the first article
@@ -200,10 +194,11 @@ ArticleRepository.most_recent_by_author(author) # => most recent articles by an
 ArticleRepository.most_recent_published_by_author(author) # => most recent published articles by an author
 ```
 
-## Business logic
+## Business Logic
 
 As we've seen above, `Article` implements an API for publishing.
-We're gonna use that logic to alter the state of an article (from draft to published) and then we use the repository to persist this new state.
+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

data/README.md

@@ -41,7 +41,9 @@ __Lotus::Model__ supports Ruby (MRI) 2+
 
 Add this line to your application's Gemfile:
 
-    gem 'lotus-model'
+```ruby
+gem 'lotus-model'
+```
 
 And then execute:
 
@@ -53,9 +55,52 @@ Or install it yourself as:
 
 ## Usage
 
+This class provides a DSL to configure adapter, mapping and collection.
+
+```ruby
+require 'lotus/model'
+
+class User
+  include Lotus::Entity
+  attributes :name, :age
+end
+
+class UserRepository
+  include Lotus::Repository
+end
+
+Lotus::Model.configure do
+  adapter type: :sql, uri: 'postgres://localhost/database'
+
+  mapping do
+    collection :users do
+      entity      User
+      respository UserRepository
+
+      attribute :id,   Integer
+      attribute :name, String
+      attribute :age,  Integer
+    end
+  end
+end
+
+Lotus::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.
@@ -72,17 +117,17 @@ require 'lotus/model'
 
 class Person
   include Lotus::Entity
-  self.attributes = :name, :age
+  attributes :name, :age
 end
 ```
 
-When a class includes `Lotus::Entity` it will receive the following interface:
+When a class includes `Lotus::Entity` it receives the following interface:
 
   * `#id`
   * `#id=`
   * `#initialize(attributes = {})`
 
-Also, the usage of `.attributes=` defines accessors for the given attribute names.
+`Lotus::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:
 
@@ -96,8 +141,32 @@ class Person
 end
 ```
 
-Indeed, **Lotus::Model** ships `Entity` only for developers's convenience, but the
-rest of the framework is able to accept any object that implements the interface above.
+**Lotus::Model** ships `Lotus::Entity` for developers's convenience.
+
+**Lotus::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 **Lotus::Model** framework.
+
+However, we suggest to implement this interface by including `Lotus::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 extend an entity class, it will also *inherit* its mother's attributes.
+
+```ruby
+require 'lotus/model'
+
+class Article
+  include Lotus::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
 
@@ -138,7 +207,7 @@ When a class includes `Lotus::Repository`, it will receive the following interfa
 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 leak storage API details outside of a repository.
+This decision forces developers to define intention revealing API, instead of leaking storage API details outside of a repository.
 
 Look at the following code:
 
@@ -229,6 +298,28 @@ class ArticleRepository
 end
 ```
 
+**Your models and repositories have to be in the same namespace.** Otherwise `Lotus::Model::Mapper#load!`
+will not initialize your repositories correctly.
+
+```ruby
+class MyLotusApp::Model::User
+  include Lotus::Entity
+  # your code here
+end
+
+# This repository will work...
+class MyLotusApp::Model::UserRepository
+  include Lotus::Repository
+  # your code here
+end
+
+# ...this will not!
+class MyLotusApp::Repository::UserRepository
+  include Lotus::Repository
+  # your code here
+end
+```
+
 ### Data Mapper
 
 A persistence mapper that keeps entities independent from database details.
@@ -250,19 +341,53 @@ mapper = Lotus::Model::Mapper.new do
 end
 ```
 
-For simplicity sake, imagine that the mapper above is used with a SQL database.
+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 `#attribute` call, is to associate the column with a Ruby type.
+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**
+
+Please be noted there are limitations with inherited entities:
+
+```ruby
+require 'lotus/model'
+
+class Article
+  include Lotus::Entity
+  attributes :name
+end
+
+class RareArticle < Article
+  attributes :price
+end
+
+mapper = Lotus::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 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.
-**Lotus::Model** is shipped with two adapters:
+**Lotus::Model** is shipped with three adapters:
 
   * SqlAdapter
   * MemoryAdapter
+  * FileSystemAdapter
 
 An adapter can be associated with one or multiple repositories.
 
@@ -286,7 +411,7 @@ In the example above, we reuse the adapter because the target tables (`people` a
 
 ### Query
 
-An object that implements an interface for quering the database.
+An object that implements an interface for querying the database.
 This interface may vary, according to the adapter's specifications.
 Think of an adapter for Redis, it will probably employ different strategies to filter records than an SQL query object.
 
@@ -294,6 +419,21 @@ Think of an adapter for Redis, it will probably employ different strategies to f
 
   * A repository must be named after an entity, by appending `"Repository"` to the entity class name (eg. `Article` => `ArticleRepository`).
 
+### Configurations
+
+  * Non-standard respository can be configured for an entity, by setting `repository` on the collection.
+
+  ```ruby
+  require 'lotus/model'
+
+  mapper = Lotus::Model::Mapper.new do
+    collection :users do
+      entity User
+      repository EmployeeRepository
+    end
+  end
+  ```
+
 ### Thread safety
 
 **Lotus::Model**'s is thread safe during the runtime, but it isn't during the loading process.
@@ -301,7 +441,7 @@ The mapper compiles some code internally, be sure to safely load it before your
 
 ```ruby
 Mutex.new.synchronize do
-  mapper.load!
+  Lotus::Model.load!
 end
 ```