lotus-model 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 45eafad8cbc67eedd9b93f6c4febf4a70666e698
-  data.tar.gz: ef28d6829b48fe1e0a6615fbe436e3a2d296d7a9
+  metadata.gz: 49e959406b3eb918c7a4bd905a12ba1c10262710
+  data.tar.gz: d94acfc3ddd8cf6b68acda3df7b6316532c3da3c
 SHA512:
-  metadata.gz: b931608e74e698873231ec83a8bb52ec8139e806734b2c8bc72a441d3f18afc82c790a46df99715fb2f6e73a2f37247e0240d48ef2be3c38f3aa6e6ef458aae4
-  data.tar.gz: d45a1c327e775c321d70c214e760a9d67e92f71323e855e8519519d190858d216dc3a2c2c5bb019380f7e35ca6f9dca0aee35257c8d0f7c1c674c222795d8f75
+  metadata.gz: 5fbddd4ce436384d0c76cdb23fe97c836bcb86f68bc43ce18a6c128be5effe992454e0e542d08113e8e0f920498257d06efe8633b9c07256a73c5f9cac24f7fd
+  data.tar.gz: 61a389ebd9c46d67fb19bd5af588c1c5681253f3470eea10b2975c32d246741c66bf53ed888261c07d33f81d99fd7f641ff7b2932f1ac8afc367f84cb2346917

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.greenbar

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+script: 'bundle exec rake test:coverage'
+rvm:
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1

data/.yardopts

@@ -0,0 +1,5 @@
+--protected
+--private
+-
+LICENSE.txt
+lib/**/*.rb

data/EXAMPLE.md

@@ -0,0 +1,217 @@
+# Lotus::Model
+
+This is a guide that helps you to getting started with [**Lotus::Model**](https://github.com/lotus/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 'lotus-model'
+```
+
+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`.
+
+```ruby
+require 'bundler/setup'
+require 'sqlite3'
+require 'lotus/model'
+require 'lotus/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`, Lotus::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 Lotus::Entity
+  self.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 Lotus::Repository
+end
+
+class ArticleRepository
+  include Lotus::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
+```
+
+## Mapper
+
+We create a correspondence between the database columns with the entities' attributes.
+
+```ruby
+mapper = Lotus::Model::Mapper.new do
+  collection :authors do
+    entity Author
+
+    attribute :id,   Integer
+    attribute :name, String
+  end
+
+  collection :articles do
+    entity Article
+
+    attribute :id,             Integer
+    attribute :author_id,      Integer
+    attribute :title,          String
+    attribute :comments_count, Integer
+    attribute :published,      Boolean
+  end
+end
+```
+
+## Loading
+
+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.
+
+```ruby
+adapter = Lotus::Model::Adapters::SqlAdapter.new(mapper, connection_uri)
+AuthorRepository.adapter  = adapter
+ArticleRepository.adapter = adapter
+
+mapper.load! # last operation
+```
+
+## Persist
+
+Let's instantiate and persist some objects for our example:
+
+```ruby
+author = Author.new(name: 'Luca')
+AuthorRepository.create(author)
+
+articles = [
+  Article.new(title: 'Announcing Lotus',              author_id: author.id, comments_count: 123, published: true),
+  Article.new(title: 'Introducing Lotus::Router',     author_id: author.id, comments_count: 63,  published: true),
+  Article.new(title: 'Introducing Lotus::Controller', author_id: author.id, comments_count: 82,  published: true),
+  Article.new(title: 'Introducing Lotus::Model',      author_id: author.id)
+]
+
+articles.each do |article|
+  ArticleRepository.create(article)
+end
+```
+
+## Query
+
+We can use 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'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.
+
+```ruby
+article = ArticleRepository.drafts.first
+
+article.published? # => false
+article.publish!
+
+article.published? # => true
+
+ArticleRepository.update(article)
+```

data/Gemfile

@@ -1,4 +1,16 @@
 source 'https://rubygems.org'
-
-# Specify your gem's dependencies in lotus-model.gemspec
 gemspec
+
+if !ENV['TRAVIS']
+  gem 'byebug',      require: false, platforms: :ruby if RUBY_VERSION == '2.1.1'
+  gem 'yard',        require: false
+  # gem 'lotus-utils', require: false, github: 'lotus/utils'
+else
+  # gem 'lotus-utils', '~> 0.1', '> 0.1.0'
+end
+
+gem 'lotus-utils', require: false, github: 'lotus/utils'
+
+gem 'sqlite3',   require: false
+gem 'simplecov', require: false
+gem 'coveralls', require: false

data/README.md

@@ -1,6 +1,41 @@
 # Lotus::Model
 
-TODO: Write a gem description
+A persistence framework for [Lotus](http://lotusrb.org).
+
+It delivers a convenient public API to execute queries and commands against a database.
+The architecture allows to keep 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](#datamapper) - A persistence mapper that keep entities independent from database details.
+  * [Adapter](#adapters) – A database adapter.
+  * [Query](#queries) - An object that represents a database query.
+
+Like all the other Lotus compontents, it can be used as a standalone framework or within a full Lotus application.
+
+## Status
+
+[![Gem Version](https://badge.fury.io/rb/lotus-model.png)](http://badge.fury.io/rb/lotus-model)
+[![Build Status](https://secure.travis-ci.org/lotus/model.png?branch=master)](http://travis-ci.org/lotus/model?branch=master)
+[![Coverage](https://coveralls.io/repos/lotus/model/badge.png?branch=master)](https://coveralls.io/r/lotus/model)
+[![Code Climate](https://codeclimate.com/github/lotus/model.png)](https://codeclimate.com/github/lotus/model)
+[![Dependencies](https://gemnasium.com/lotus/model.png)](https://gemnasium.com/lotus/model)
+[![Inline docs](http://inch-pages.github.io/github/lotus/model.png)](http://inch-pages.github.io/github/lotus/model)
+
+## Contact
+
+* Home page: http://lotusrb.org
+* Mailing List: http://lotusrb.org/mailing-list
+* API Doc: http://rdoc.info/gems/lotus-model
+* Bugs/Issues: https://github.com/lotus/model/issues
+* Support: http://stackoverflow.com/questions/tagged/lotus-ruby
+* Chat: https://gitter.im/lotus/chat
+
+## Rubies
+
+__Lotus::View__ supports Ruby (MRI) 2+
 
 ## Installation
 
@@ -18,12 +53,277 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Entities
+
+An object that is defined by its identity.
+
+An entity is the core of an application, where the part of the domain logic is implemented.
+It's a small, cohesive object that express coherent and meagniful 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 'lotus/model'
+
+class Person
+  include Lotus::Entity
+  self.attributes = :name, :age
+end
+```
+
+When a class includes `Lotus::Entity` it will receive the following interface:
+
+  * `#id`
+  * `#id=`
+  * `#initialize(attributes = {})`
+
+Also, the usage of `.attributes=` defines accessors for the given attribute 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
+```
+
+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.
+
+### Repositories
+
+A object that mediates between entites and the persistence layer.
+It offers a standardized API to query and execute commands on a database.
+
+A repository is **storage idenpendent**, all the queries and commands are
+delegated to the current adapter.
+
+This architecture has several advantages:
+
+  * Applications depends on an standard API, instead of low level details
+    (Dependency Inversion principle)
+
+  * Applications depends 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 `Lotus::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 correspoding to the given entity
+  * `.delete(entity)`  – Delete the record correspoding to the given entity
+  * `.all`   - Fetch all the entities from the collection
+  * `.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 leak 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 'lotus/model'
+
+class ArticleRepository
+  include Lotus::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 stub this method.
+
+  * If we change the storage, the callers aren't affected.
+
+Here an extended example of a repository that uses the SQL adapter.
+
+```ruby
+class ArticleRepository
+  include Lotus::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
+```
+
+### Data Mapper
+
+A persistence mapper that keep entities independent from database details.
+It's 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 'lotus/model'
+
+mapper = Lotus::Model::Mapper.new do
+  collection :users do
+    entity User
+
+    attribute :id,   Integer
+    attribute :name, String
+    attribute :age,  Integer
+  end
+end
+```
+
+For simplicity sake, imagine that the mapper above is used with a SQL database.
+We use `#collection` to indicate 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.
+
+For advanced mapping and legacy databases, please have a look at the API doc.
+
+### Adapter
+
+An adapter is a concrete implementation of persistence logic for a specific database.
+**Lotus::Model** is shipped with two adapters:
+
+  * SqlAdapter
+  * MemoryAdapter
+
+An adapter can be associated to one or multiple repositories.
+
+```ruby
+require 'pg'
+require 'lotus/model'
+require 'lotus/model/adapters/sql_adapter'
+
+mapper = Lotus::Model::Mapper.new do
+  # ...
+end
+
+adapter = Lotus::Model::Adapters::SqlAdapter.new(mapper, 'postgres://host:port/database')
+
+PersonRepository.adapter  = adapter
+ArticleRepository.adapter = adapter
+```
+
+In the example above, we reuse the adpter 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 quering 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 from an SQL query object.
+
+### Conventions
+
+  * A repository must be named after an entity, by appeding `"Repository"` to the entity class name (eg. `Article` => `ArticleRepository`).
+
+### Thread safety
+
+**Lotus::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
+  mapper.load!
+end
+```
+
+**This is not necessary, when Lotus::Model is used within a Lotus application.**
+
+## Example
+
+For a full working example, have a look at [EXAMPLE.md](https://github.com/lotus/model/blob/master/EXAMPLE.md).
+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.
+
+## Versioning
+
+__Lotus::Model__ uses [Semantic Versioning 2.0.0](http://semver.org)
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/lotus-model/fork )
+1. Fork it ( https://github.com/lotus/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 Luca Guidi – Released under MIT License