epiphy 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c60ab2f9d0a39156bab381f3217ad2c8fd210d8
-  data.tar.gz: 24fde7963aa8d74479e2a90030928b7fc8fc7d89
+  metadata.gz: 346e101f2179b4b096e7d9e38ef7c08879598e99
+  data.tar.gz: fc54f4cf44e3a1e25e79d10f5ecd2e85bd0bff0c
 SHA512:
-  metadata.gz: 1e18a93aef681e795efd164d3467f7136fe6f938bea9d08448cfe854b4a2a4a50dd4b5ea4bc46c54a18f0bd6996c902c747449dd9448a0f3fd83cf1694ab39e5
-  data.tar.gz: f3549f8a25a32cc5bc2f5a6c565e2a081dd029653d499be1aa28743e293fa975de93c7f8b1a12b0915bb3e9d1153d5e25cbc156ada19fa2fc8c656a9c70f5b8c
+  metadata.gz: a8823aac0ef0a54099141567fcc3155d3289ca71d08b39b506f14ed668bb073f78d99a622d3090a804997f69370ec36841d7c256b7ff98c507fc057c3e4e100e
+  data.tar.gz: e6fd39cb0525b115d1fb6bfb35d094ef3f1661902f4db8bfbb5924eef21f3b74281ed71db385a19ce00bcac225ad8398ba302f8e5d49d200d1a4baa1b842bc74

data/EXAMPLE.md

@@ -0,0 +1,173 @@
+# Epiphy
+
+This is a guide that helps you to getting started with [**Epiphy**](https://github.com/kureikain/epiphy). This file is inspired by Lotus::Model
+
+## Gems
+
+First of all, we need to setup a `Gemfile`.
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'epiphy'
+```
+
+Then we can fetch the dependencies with `bundle install`.
+
+## Setup
+
+We need to feed `Epiphy` with an adapter. Adapter is a lighweight wrap
+contains a RethinkDB connection and its run option.
+
+```
+# Default connect to localhost, 28015, no auth key, use database 'test'
+# by default
+connection = Epiphy::Connection.create 
+adapter    = Epiphy::Adapter::RethinkDB.new connection, 'test'
+RethinkDB::Repository.configure do |r|
+  r.adapter = adapter 
+end
+
+# Or merge them all
+RethinkDB::Repository.configure do |r|
+  r.adapter = Epiphy::Adapter::RethinkDB.new(Epiphy::Connection.create)
+end
+
+# Or connect to a different host, use database `cms`
+RethinkDB::Repository.configure do |r|
+  r.adapter = Epiphy::Adapter::RethinkDB.new Epiphy::Connection.create({:host => '192.168.1.2'}, 'cms')
+end
+
+```
+
+## Entities
+
+We have two entities in our application: `Author` and `Article`.
+`Author` is a `Struct`, Epiphy 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 Epiphy::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 Epiphy::Repository
+end
+
+class ArticleRepository
+  include Epiphy::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
+```
+
+## 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 Epiphy',              author_id: author.id, comments_count: 123, published: true),
+  Article.new(title: 'Introducing Epiphy::Router',     author_id: author.id, comments_count: 63,  published: true),
+  Article.new(title: 'Introducing Epiphy::Controller', author_id: author.id, comments_count: 82,  published: true),
+  Article.new(title: 'Introducing Epiphy',      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/lib/epiphy/adapter/rethinkdb.rb

@@ -1,5 +1,5 @@
 require 'epiphy/adapter/error'
-#require 'epiphy/adapter/helper'
+
 module Epiphy
   module Adapter
     class Rethinkdb
@@ -102,6 +102,7 @@ module Epiphy
         raise ArgumentError, 'Missing query block' unless block_given? 
         if block_given?
           rql = get_table(table, database)
+          @current_rql = rql
           rql = yield(rql, r)
         end
         rql.run(@connection)
@@ -125,9 +126,15 @@ module Epiphy
       end
       
       # Insert a document.
+      #
+      # When the ID is already existed, we simply return the ID if insert
+      # succesful. Or, the generated ID will be returned.
+      #
       # @param collection [Symbol the target collection
       # @param entity [#id, #id=] the entity to create
       # @return [Object] the entity 
+      # 
+      # @raise 
       #
       # @api private
       # @since 0.0.1
@@ -136,12 +143,17 @@ module Epiphy
           result = query table: collection do |r|
             r.insert(entity)
           end
-        rescue 
-          return false
+        rescue RethinkDB::RqlRuntimeError => e
+          raise e
         end
         
         if result["inserted"]==1
-          result["generated_keys"].first
+          return entity["id"] if result["generated_keys"].nil?
+          result["generated_keys"].first 
+        else 
+          if result['first_error'].include? 'Duplicate primary key'
+            raise Epiphy::Model::EntityExisted, 'Duplicate primary key'
+          end
         end
       end
 
@@ -179,8 +191,31 @@ module Epiphy
           query table: collection do |r|
             r
           end
-        rescue
-          return false
+        rescue RethinkDB::RqlRuntimeError => e
+          raise Epiphy::Model::RuntimeError, e.message
+        rescue Exception =>e
+          raise Epiphy::Model::RuntimeError, e.message
+        end
+      end
+
+      # Count entity in table
+      #
+      # @param collection [Symbol] the target collection (it must be mapped).
+      #
+      # @return [Integer] How many record?
+      #
+      # @api private
+      # @since 0.2.0
+      def count(collection)
+        # TODO consider to make this lazy (aka remove #all)
+        begin 
+          query table: collection do |r|
+            r.count
+          end
+        rescue RethinkDB::RqlRuntimeError => e
+          raise Epiphy::Model::RuntimeError, e.message
+        rescue Exception =>e
+          raise Epiphy::Model::RuntimeError, e.message
         end
       end
 
@@ -243,8 +278,8 @@ module Epiphy
             return result['deleted']
           end
           return false
-        rescue 
-          return false 
+        rescue RethinkDB::RqlRuntimeError => e
+          raise Epiphy::Model::RuntimeError, e.message
         end
       end
 
@@ -256,10 +291,14 @@ module Epiphy
       #
       # @api private
       # @since 0.1.0
-      def first(collection)
-        _first(
-          query(collection).asc(_identity(collection))
-        )
+      def first(collection, order_by: nil)
+        begin
+          query table: collection do |q,r|
+            q.order_by(r.asc(order_by)).nth(0)
+          end
+        rescue RethinkDB::RqlRuntimeError => e
+          return nil
+        end
       end
 
       # Returns the last record in the given collection.
@@ -270,21 +309,18 @@ module Epiphy
       #
       # @api private
       # @since 0.1.0
-      def last(collection)
-        _first(
-          query(collection).desc(_identity(collection))
-        )
+      def last(collection, order_by: nil)
+        begin
+          query table: collection do |q, r|
+            q.order_by(r.desc(order_by)).nth(0)
+          end
+        rescue RethinkDB::RqlRuntimeError => e
+          return nil
+        end
+ 
       end
 
       private
-      def _collection(name)
-        raise NotImplementedError
-      end
-
-      def _mapped_collection(name)
-        @mapper.collection(name)
-      end
-
       def _find(collection, id)
         identity = _identity(collection)
         query(collection).where(identity => _id(collection, identity, id))

data/lib/epiphy/entity/timestamp.rb

@@ -0,0 +1,14 @@
+module Epiphy
+  module Entity
+    
+    # Add created_at and updated_at field to an entity.
+    #   
+    #
+    module Timestamp
+      def self.included(base)
+        base.send :attr_accessor, :_ts
+      end
+    end
+
+  end
+end

data/lib/epiphy/model.rb

@@ -9,6 +9,10 @@ module Epiphy
   #
   # @since 0.1.0
   module Model
+
+    class RuntimeError < RethinkDB::RqlRuntimeError
+
+    end
     # Error for not found entity
     #
     # @since 0.1.0
@@ -33,5 +37,9 @@ module Epiphy
     # @see epiphy::Repository.update
     class NonPersistedEntityError < ::StandardError
     end
+
+    class EntityExisted < ::StandardError
+
+    end
   end
 end

data/lib/epiphy/repository.rb

@@ -1,6 +1,7 @@
 require 'lotus/utils/class_attribute'
 require 'epiphy/repository/configuration'
 require 'epiphy/repository/cursor'
+require 'epiphy/repository/helper'
 
 module Epiphy
   # Mediates between the entities and the persistence layer, by offering an API
@@ -215,6 +216,7 @@ module Epiphy
     end
 
     module ClassMethods
+      include Epiphy::Repository::Helper
       # Assigns an adapter.
       #
       # Epiphy::Repository is shipped with an adapters:
@@ -289,7 +291,8 @@ module Epiphy
       # Creates a record in the database for the given entity.
       # It assigns the `id` attribute, in case of success.
       #
-      # If already persisted (`id` present) it does nothing.
+      # If already persisted (`id` present), it will try to insert use that id
+      # and will raise an error if the `id` is already exist
       #
       # @param entity [#id,#id=] the entity to create
       #
@@ -314,10 +317,16 @@ module Epiphy
       #
       #   ArticleRepository.create(article) # no-op
       def create(entity)
-        unless entity.id
+        #unless entity.id
+        begin
           result = @adapter.create(collection, to_document(entity))
           entity.id = result
+        rescue Epiphy::Model::EntityExisted => e
+          raise e
+        rescue RethinkDB::RqlRuntimeError => e
+          raise Epiphy::Model::RuntimeError, e.message
         end
+        #end
       end
 
       # Updates a record in the database corresponding to the given entity.
@@ -504,8 +513,13 @@ module Epiphy
       #   end
       #
       #   ArticleRepository.first # => nil
-      def first
-        @adapter.first(collection)
+      def first(order_by=:id)
+        result = @adapter.first(collection, order_by: order_by)
+        if result
+          to_entity result
+        else
+          result
+        end
       end
 
       # Returns the last entity in the database.
@@ -533,8 +547,12 @@ module Epiphy
       #   end
       #
       #   ArticleRepository.last # => nil
-      def last
-        @adapter.last(collection)
+      def last(order_by=:id)
+        if result = @adapter.last(collection, order_by: order_by)
+          to_entity result
+        else
+          nil
+        end
       end
 
       # Deletes all the records from the current collection.
@@ -553,22 +571,16 @@ module Epiphy
       #   ArticleRepository.clear # deletes all the records
       def clear
         @adapter.clear(collection)
-      end
+      end 
 
-      # Create a collection storage in database.
+      # Count the entity in this collection
       #
-      def create_collection
-        query do |r|
-          r.table_create(self.collection)
-        end
-      end
-
-      # Drop a collection storage in database
-      #
-      def drop_collection
-        query do |r|
-          r.table_drop(self.collection)
-        end
+      # @param void
+      # @return Interget 
+      # @api public
+      # @since 0.2.0
+      def count
+        @adapter.count(collection)
       end
 
       private
@@ -585,27 +597,34 @@ module Epiphy
       # The returned query SHOULD refer to the entire collection by default.
       #
       # Queries can be reused and combined together. See the example below.
-      # IMPORTANT: This feature works only with the Sql adapter.
       #
       # A repository is storage independent.
       # All the queries are delegated to the current adapter, which is
       # responsible to implement a querying API.
       #
-      # Epiphy::Model is shipped with two adapters:
+      # Epiphy::Model is shipped with adapter:
       #
-      #   * SqlAdapter, which yields a Epiphy::Model::Adapters::Sql::Query
-      #   * MemoryAdapter, which yields a Epiphy::Model::Adapters::Memory::Query
+      #   * RethinkDB: which yields a RethinkDB::ReQL class.
       #
-      # @param blk [Proc] a block of code that is executed in the context of a
-      #   query
+      # By default, all return items will be convert into its entity. The
+      # behavious can change by alter `to_entity` parameter 
       #
+      # @param to_entity [Boolean][Optional] to convert the result back to a
+      # entity class or not. 
+      #       
+      # @param blk [Proc] a block of code that is executed in the context of a
+      #   query.
+      #   The block will be passed two parameters. First parameter is the `reql`
+      #   which is building. the second parameter is th `r` top name space of
+      #   RethinkDB. By doing this, Repository doesn't have to include
+      #   RethinkDB::Shortcuts
+      # 
       # @return a query, the type depends on the current adapter
       #
       # @api public
       # @since 0.1.0
       #
-      # @see Epiphy::Model::Adapters::Sql::Query
-      # @see Epiphy::Model::Adapters::Memory::Query
+      # @see Epiphy::Adapters::Rethinkdb
       #
       # @example
       #   require 'epiphy/model'
@@ -646,9 +665,27 @@ module Epiphy
       #       query.average(:comments_count)
       #     end
       #   end
-      def query(&blk)
-        @adapter.query(collection, self, &blk)
+      def query(to_entity: true, &blk)
+        result = @adapter.query(table: collection, &blk)
+        require 'pp'
+        if result.is_a? RethinkDB::Cursor
+          return Epiphy::Repository::Cursor.new result do |item|
+            to_entity(item)
+          end
+        end
+
+        if result.is_a? Array
+          result.map! do |item|
+            to_entity(item)
+          end
+        end
+
+        if result.is_a? Hash
+          return to_entity(result)
+        end
+        result
       end
+      
 
       # Negates the filtering conditions of a given query with the logical
       # opposite operator.

data/lib/epiphy/repository/helper.rb

@@ -0,0 +1,28 @@
+module Epiphy
+  module Repository
+    module Helper
+
+      # Find the first record matching the 
+      #
+      # @param Keyword argument [field_name: value] 
+      # @return Entity [Object]
+      # @raise Epiphy::Model::EntityNotFound if not found
+      #
+      # @api public
+      # @since 0.2.0
+      def find_by(**option)
+        begin
+          query do |r|
+            r.filter(option).nth(0)
+          end
+        rescue RethinkDB::RqlRuntimeError => e
+          #raise RethinkDB::RqlRuntimeError
+          raise Epiphy::Model::EntityNotFound if e.message.include?("Index out of bounds")
+        end
+      end
+      
+      #private :where, :desc#, :exlude
+    end
+  end
+end
+

data/lib/epiphy/scheme.rb

@@ -0,0 +1,19 @@
+module Epiphy
+  module Schema
+    # Create a collection storage in database.
+    #
+    def create_collection
+      query do |r|
+        r.table_create(self.collection)
+      end
+    end
+
+    # Drop a collection storage in database
+    #
+    def drop_collection
+      query do |r|
+        r.table_drop(self.collection)
+      end
+    end
+  end
+end

data/lib/epiphy/version.rb

@@ -2,5 +2,5 @@ module Epiphy
   # Defines the version
   #
   # @since 0.0.1
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.1.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epiphy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Vinh
@@ -59,18 +59,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- EXAMPLE.md
 - README.md
 - lib/epiphy.rb
 - lib/epiphy/adapter/error.rb
-- lib/epiphy/adapter/helper.rb
-- lib/epiphy/adapter/model.rb
 - lib/epiphy/adapter/rethinkdb.rb
 - lib/epiphy/connection.rb
 - lib/epiphy/entity.rb
+- lib/epiphy/entity/timestamp.rb
 - lib/epiphy/model.rb
 - lib/epiphy/repository.rb
 - lib/epiphy/repository/configuration.rb
 - lib/epiphy/repository/cursor.rb
+- lib/epiphy/repository/helper.rb
+- lib/epiphy/scheme.rb
 - lib/epiphy/version.rb
 homepage: http://rubygems.org/gems/hola
 licenses:

data/lib/epiphy/adapter/helper.rb

@@ -1,114 +0,0 @@
-module Epiphy
-  module Adapter
-    class Rethinkdb
-      # RethinkDB method related. Should be in its helper
-      def insert_object
-        get_table.insert(
-          safe_params.merge(
-            id: params[:id],
-            created_at: Time.now,
-            updated_at: Time.now
-          ).merge(parents)
-        ).run(@connection)
-        :created
-      end
-
-      def update_object
-        get_table.update(
-          safe_params.merge(
-            id: params[:id],
-            updated_at: Time.now
-          )
-        ).run(@connection)
-        :ok
-      end
-
-      def replace_object
-        get_table.replace(
-          safe_params.merge(
-            id: params[:id],
-            created_at: Time.now,
-            updated_at: Time.now
-          ).merge(parents)
-        ).run(@connection)
-        :ok
-      end
-
-      def delete_object
-        get_table.get(params[:id]).delete(
-          :durability => "hard", :return_vals => false
-        ).run(@connection)
-        :no_content
-      end
-
-      def sort(qry)
-        ordering = params[:sort].split(",").map do |attr|
-          if attr[0] == "-"
-            r.desc(attr[1..-1].to_sym)
-          else
-            r.asc(attr.to_sym)
-          end
-        end
-
-        qry.order_by(*ordering)
-      end
-
-      def select(qry)
-        qry = qry.get_all(*params[:ids].split(",")) if params[:ids]
-        qry
-      end
-
-      def parents
-        params.select {|k,v| k.match(/\A[a-z0-9_]+_id\z/i) }.compact
-      end
-
-      def filter(qry)
-        parents.empty? ? qry : qry.filter(parents)
-      end
-
-      def attrs
-        [ :id ]
-      end
-
-      def get_range(qry)
-        begin
-          rhdr = request.headers[:HTTP_RANGE].split("=")
-
-          if rhdr[0] == collection
-            qry = qry[Range.new(*rhdr[1].split("-").map(&:to_i))]
-          end
-        rescue Exception => e
-          puts e.message
-          raise Exception.new(:bad_request)
-        end
-        qry
-      end
-
-      def get_records
-        qry = get_table
-        qry = sort(qry) if params[:sort]
-
-        fields = if params[:fields]
-                   params[:fields].split(",").map {|f| f.to_sym }.select do |field|
-                     attrs.include? field
-                   end
-                 else
-                   attrs
-                 end
-
-        qry = filter(select(qry)).pluck(fields)
-        qry = get_range(qry) if request.headers[:HTTP_RANGE]
-
-        qry.run(@connection).map do |record|
-          record.merge(href: some_url(record["id"]))
-        end
-      end
-
-      def get_object
-        get_table.filter(parents.merge({id: params[:id]})).pluck(attrs).run(@connection).first
-      end
-
-    end
-  end
-end
-

data/lib/epiphy/adapter/model.rb

@@ -1,99 +0,0 @@
-require 'errors'
-
-class Rethink
-  include RethinkDB::Shortcuts
-  include RethinkdbHelper
-  include Errors
-
-  def initialize
-    create_connect_if_need 
-    @r = @@r.table(self.class.name.downcase)
-  end
-
-  def all
-    self
-  end
-
-  # Get a single element by primary key
-  def single(id)
-    @r = @r.get(id)
-    self
-  end
-
-  # Return raw RethinkDB object
-  def raw_query
-    @r
-  end
-  
-  def reset
-    @r = @@r.table self.class.name.downcase
-  end
-
-  # Run a RQL
-  def get(r=nil)
-    if r.nil?
-      r = @r
-    end
-    r.run(@@rdb_connection)
-  end
-
-  [:update, "get_all", :limit, :order_by, :slice, :count, :filter].each do |name|
-    define_method(name) do |*arg, &block|
-      @r = @r.send(name, *arg, &block)
-      self
-    end
-  end 
-  
-  # Command work ona single object
-  #{:destroy => :delete}.each do |public_name, name| 
-    #define_method(public_name) do |*arg, &block|
-      #r = @@r.table self.class.name.downcase
-      #r.get(*arg)
-      #r.send(name, *arg, &block)
-      #r.run @@rdb_connection
-    #end
-  #end
-  
-  def destroy(id)
-    r = @@r.table self.class.name.downcase
-    r.get(id)
-      .delete()
-      .run(@@rdb_connection)
-  end
-
-  # Validation
-  def self.validate(args)
-    if args.has_key? :errors
-      raise ValidationError.new('Bad request', args[:errors])
-    end
-
-    args
-  end
-
-  def self.validate_present(args, *keys)
-    for k in keys
-      unless args.has_key?(k) and args[k].present?
-        args[:errors] ||= {}
-        args[:errors][k] ||= []
-        args[:errors][k] << "can't be blank."
-      end
-    end
-    args
-  end
-
-  def self.validate_email(args)
-    if args.has_key? :email
-      args[:email].downcase!
-
-      unless args[:email].present? and
-        args[:email].match EMAIL_REGEX
-
-        args[:errors] ||= {}
-        args[:errors][:email] ||= []
-        args[:errors][:email] << "is invalid."
-      end
-    end
-    args
-  end
-end
-