lotus-model 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa3a89ff8d50e481fffb8cbd68c8cc38bb97e52a
-  data.tar.gz: c1205c925a3cadac434c381d8f80dd5a15846544
+  metadata.gz: b91d99745af6c3080d3e83ff84b369517df2dd77
+  data.tar.gz: cda6f8e7128dbb6db125054d0092a6f4fc83b413
 SHA512:
-  metadata.gz: 573a4b357ec946e3945e819279fe646f72b22144da46e3d8a1f7adf140d6845e9811fad860bd33cd97afcc5587bac93a470489c73ae7e5355be7e463c453d5cd
-  data.tar.gz: 2d380bd41f0f1d3f934d1d4b74e036126f34f5fc0207a3066549c0ab9f31fd5c930f06ffea5baa081734b9dd02de19a34028e3a51cc3094ba99f1e1e9a260f46
+  metadata.gz: 1ad445fbbf969ebd9dccc1997bd92a10ccc3e4bd3f679d8691b94f9c66940d72afda02d3fcad063001a1905fcae862b5eeb2b0768bc0d85016f10fc3e5e1ef5e
+  data.tar.gz: ed8fafcd2491178a6b9646e1a28c07110208c7d8d1dfa15420aeca8482fccc38952058b95d3f86c28e0bc8066a1a9503c11b487348853b442a2bd491e9cf8314

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Lotus::Model
 A persistence layer for Lotus
 
+## 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

data/README.md

@@ -150,7 +150,7 @@ However, we suggest to implement this interface by including `Lotus::Entity`, in
 
 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.
+When a class extends a `Lotus::Entity` class, it will also *inherit* its mother's attributes.
 
 ```ruby
 require 'lotus/model'
@@ -349,7 +349,7 @@ 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:
+Note there are limitations with inherited entities:
 
 ```ruby
 require 'lotus/model'
@@ -374,7 +374,7 @@ mapper = Lotus::Model::Mapper.new do
 end
 ```
 
-In the example above, there are few problems:
+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)`,
@@ -447,6 +447,108 @@ end
 
 **This is not necessary, when Lotus::Model is used within a Lotus 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 'lotus/model'
+
+class User
+  include Lotus::Entity
+  attributes :name, :created_at, :updated_at
+end
+
+class UserRepository
+  include Lotus::Repository
+end
+
+Lotus::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 `Lotus::Entity::DirtyTracking` is included.
+
+```ruby
+require 'lotus/model'
+
+class User
+  include Lotus::Entity
+  include Lotus::Entity::DirtyTracking
+  attributes :name, :age
+end
+
+class UserRepository
+  include Lotus::Repository
+end
+
+Lotus::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/lotus/model/blob/master/EXAMPLE.md).

data/lib/lotus/entity.rb

@@ -138,24 +138,35 @@ module Lotus
       #
       #   User.attributes => #<Set: {:id, :name}>
       #   DeletedUser.attributes => #<Set: {:id, :name, :deleted_at}>
+      #
       def attributes(*attrs)
         if attrs.any?
           attrs = Lotus::Utils::Kernel.Array(attrs)
           self.attributes.merge attrs
 
           attrs.each do |attr|
-            attr_accessor(attr) if define_attribute?(attr)
+            define_attr_accessor(attr) if defined_attribute?(attr)
           end
         else
           @attributes ||= Set.new
         end
       end
 
+      # Define setter/getter methods for attributes.
+      #
+      # @params attr [Symbol] an attribute name
+      #
+      # @since 0.3.1
+      # @api private
+      def define_attr_accessor(attr)
+        attr_accessor(attr)
+      end
+
       # Check if attr_reader define the given attribute
       #
-      # @since 0.2.1
+      # @since 0.3.1
       # @api private
-      def define_attribute?(name)
+      def defined_attribute?(name)
         name == :id ||
           !instance_methods.include?(name)
       end
@@ -237,4 +248,3 @@ module Lotus
 
   end
 end
-

data/lib/lotus/entity/dirty_tracking.rb

@@ -0,0 +1,126 @@
+module Lotus
+  module Entity
+    # Dirty tracking for entities
+    #
+    # @since 0.3.1
+    module DirtyTracking
+      # Override setters for attributes to support dirty tracking
+      #
+      # @since 0.3.1
+      #
+      # @example Dirty tracking
+      #   require 'lotus/model'
+      #
+      #   class User
+      #     include Lotus::Entity
+      #     include Lotus::Entity::DirtyTracking
+      #
+      #     attributes :name
+      #   end
+      #
+      #   article = Article.new(title: 'Generation P')
+      #   article.changed? # => false
+      #
+      #   article.title = 'Master and Margarita'
+      #   article.changed? # => true
+      #
+      #   article.changed_attributes # => {:title => "Generation P"}
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        # Override attribute accessors function.
+        # Create setter methods with attribute values checking.
+        # If the new value or a changed, added to @changed_attributes.
+        #
+        # @params attr [Symbol] an attribute name
+        #
+        # @since 0.3.1
+        # @api private
+        #
+        # @see Lotus::Entity::ClassMethods#define_attr_accessor
+        def define_attr_accessor(attr)
+          attr_reader(attr)
+
+          class_eval %{
+            def #{ attr }=(value)
+              _attribute_changed(:#{ attr }, @#{ attr }, value)
+              @#{ attr } = value
+            end
+          }
+        end
+      end
+
+      # Override initialize process.
+      #
+      # @param attributes [Hash] a set of attribute names and values
+      #
+      # @since 0.3.1
+      #
+      # @see Lotus::Entity#initialize
+      def initialize(attributes = {})
+        _clear_changes_information
+        super
+        _clear_changes_information
+      end
+
+      # Getter for hash of changed attributes.
+      # Return empty hash, if there is no changes
+      # Getter for hash of changed attributes. Value in it is the previous one.
+      #
+      # @return [::Hash] the changed attributes
+      #
+      # @since 0.3.1
+      #
+      # @example
+      #   require 'lotus/model'
+      #
+      #   class User
+      #     include Lotus::Entity
+      #     include Lotus::Entity::DirtyTracking
+      #
+      #     attributes :title
+      #   end
+      #
+      #   article = Article.new(title: 'The crime and punishment')
+      #   article.changed_attributes # => {}
+      #
+      #   article.title = 'Master and Margarita'
+      #   article.changed_attributes # => {:title => "The crime and punishment"}
+      def changed_attributes
+        @changed_attributes.dup
+      end
+
+      # Checks if the attributes were changed
+      #
+      # @return [TrueClass, FalseClass] the result of the check
+      #
+      # @since 0.3.1
+      def changed?
+        @changed_attributes.size > 0
+      end
+
+      private
+
+      # Set changed attributes in Hash with their old values.
+      #
+      # @params attrs [Symbol] an attribute name
+      #
+      # @since 0.3.1
+      # @api private
+      def _attribute_changed(attr, current_value, new_value)
+        @changed_attributes[attr] = new_value if current_value != new_value
+      end
+
+      # Clear all information about dirty data
+      #
+      # @since 0.3.1
+      def _clear_changes_information
+        @changed_attributes = {}
+      end
+    end
+  end
+end

data/lib/lotus/model.rb

@@ -1,5 +1,6 @@
 require 'lotus/model/version'
 require 'lotus/entity'
+require 'lotus/entity/dirty_tracking'
 require 'lotus/repository'
 require 'lotus/model/mapper'
 require 'lotus/model/configuration'
@@ -27,6 +28,16 @@ module Lotus
     class InvalidMappingError < ::StandardError
     end
 
+    # Error for invalid query
+    # It's raised when a query is malformed
+    #
+    # @since 0.3.1
+    class InvalidQueryError < ::StandardError
+      def initialize(message = "Invalid query")
+        super
+      end
+    end
+
     include Utils::ClassAttribute
 
     # Framework configuration

data/lib/lotus/model/adapters/abstract.rb

@@ -201,6 +201,16 @@ module Lotus
         def connection_string
           raise NotSupportedError
         end
+
+        # Executes a raw statement directly on the connection
+        #
+        # @param raw [String] the raw statement to execute on the connection
+        # @return [Object]
+        #
+        # @since 0.3.1
+        def execute(raw)
+          raise NotImplementedError
+        end
       end
     end
   end

data/lib/lotus/model/adapters/memory/query.rb

@@ -1,4 +1,5 @@
 require 'forwardable'
+require 'ostruct'
 require 'lotus/utils/kernel'
 
 module Lotus
@@ -17,7 +18,7 @@ module Lotus
         #
         #   query.where(language: 'ruby')
         #        .and(framework: 'lotus')
-        #        .desc(:users_count).all
+        #        .reverse_order(:users_count).all
         #
         #   # the records are fetched only when we invoke #all
         #
@@ -94,13 +95,42 @@ module Lotus
           #
           #   query.where(year: 1900..1982)
           #
+          # @example Using block
+          #
+          #   query.where { age > 31 }
+          #
           # @example Multiple conditions
           #
           #   query.where(language: 'ruby')
           #        .where(framework: 'lotus')
-          def where(condition)
-            column, value = _expand_condition(condition)
-            conditions.push([:where, Proc.new{ find_all{|r| r.fetch(column, nil) == value} }])
+          #
+          # @example Multiple conditions with blocks
+          #
+          #   query.where { language == 'ruby' }
+          #        .where { framework == 'lotus' }
+          #
+          # @example Mixed hash and block conditions
+          #
+          #   query.where(language: 'ruby')
+          #        .where { framework == 'lotus' }
+          def where(condition = nil, &blk)
+            if blk
+              _push_evaluated_block_condition(:where, blk, :find_all)
+            elsif condition
+              _push_to_expanded_condition(:where, condition) do |column, value|
+                Proc.new {
+                  find_all { |r|
+                    case value
+                    when Array,Set,Range
+                      value.include?(r.fetch(column, nil))
+                    else
+                      r.fetch(column, nil) == value
+                    end
+                  }
+                }
+              end
+            end
+
             self
           end
 
@@ -131,9 +161,24 @@ module Lotus
           # @example Range
           #
           #   query.where(country: 'italy').or(year: 1900..1982)
-          def or(condition=nil, &blk)
-            column, value = _expand_condition(condition)
-            conditions.push([:or, Proc.new{ find_all{|r| r.fetch(column) == value} }])
+          #
+          # @example Using block
+          #
+          #   query.where { age == 31 }.or { age == 32 }
+          #
+          # @example Mixed hash and block conditions
+          #
+          #   query.where(language: 'ruby')
+          #        .or { framework == 'lotus' }
+          def or(condition = nil, &blk)
+            if blk
+              _push_evaluated_block_condition(:or, blk, :find_all)
+            elsif condition
+              _push_to_expanded_condition(:or, condition) do |column, value|
+                Proc.new { find_all { |r| r.fetch(column) == value} }
+              end
+            end
+
             self
           end
 
@@ -165,9 +210,29 @@ module Lotus
           #
           #   query.exclude(language: 'java')
           #        .exclude(company: 'enterprise')
-          def exclude(condition)
-            column, value = _expand_condition(condition)
-            conditions.push([:where, Proc.new{ reject {|r| r.fetch(column) == value} }])
+          #
+          # @example Using block
+          #
+          #   query.exclude { age > 31 }
+          #
+          # @example Multiple conditions with blocks
+          #
+          #   query.exclude { language == 'java' }
+          #        .exclude { framework == 'spring' }
+          #
+          # @example Mixed hash and block conditions
+          #
+          #   query.exclude(language: 'java')
+          #        .exclude { framework == 'spring' }
+          def exclude(condition = nil, &blk)
+            if blk
+              _push_evaluated_block_condition(:where, blk, :reject)
+            elsif condition
+              _push_to_expanded_condition(:where, condition) do |column, value|
+                Proc.new { reject { |r| r.fetch(column) == value} }
+              end
+            end
+
             self
           end
 
@@ -204,7 +269,7 @@ module Lotus
           #
           # @since 0.1.0
           #
-          # @see Lotus::Model::Adapters::Sql::Query#desc
+          # @see Lotus::Model::Adapters::Memory::Query#reverse_order
           #
           # @example Single column
           #
@@ -225,6 +290,23 @@ module Lotus
             self
           end
 
+          # Alias for order
+          #
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters::Memory::Query#order
+          #
+          # @example Single column
+          #
+          #   query.asc(:name)
+          #
+          # @example Multiple columns
+          #
+          #   query.asc(:name, :year)
+          #
+          # @example Multiple invokations
+          #
+          #   query.asc(:name).asc(:year)
           alias_method :asc, :order
 
           # Specify the descending order of the records, sorted by the given
@@ -234,22 +316,22 @@ module Lotus
           #
           # @return self
           #
-          # @since 0.1.0
+          # @since 0.3.1
           #
-          # @see Lotus::Model::Adapters::Sql::Query#order
+          # @see Lotus::Model::Adapters::Memory::Query#order
           #
           # @example Single column
           #
-          #   query.desc(:name)
+          #   query.reverse_order(:name)
           #
           # @example Multiple columns
           #
-          #   query.desc(:name, :year)
+          #   query.reverse_order(:name, :year)
           #
           # @example Multiple invokations
           #
-          #   query.desc(:name).desc(:year)
-          def desc(*columns)
+          #   query.reverse_order(:name).reverse_order(:year)
+          def reverse_order(*columns)
             Lotus::Utils::Kernel.Array(columns).each do |column|
               modifiers.push(Proc.new{ sort_by!{|r| r.fetch(column)}.reverse! })
             end
@@ -257,6 +339,25 @@ module Lotus
             self
           end
 
+          # Alias for reverse_order
+          #
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters::Memory::Query#reverse_order
+          #
+          # @example Single column
+          #
+          #   query.desc(:name)
+          #
+          # @example Multiple columns
+          #
+          #   query.desc(:name, :year)
+          #
+          # @example Multiple invokations
+          #
+          #   query.desc(:name).desc(:year)
+          alias_method :desc, :reverse_order
+
           # Limit the number of records to return.
           #
           # @param number [Fixnum]
@@ -486,8 +587,51 @@ module Lotus
             all.map {|record| record.public_send(column) }.compact
           end
 
-          def _expand_condition(condition)
-            Array(condition).flatten
+          # Expands and yields keys and values of a query hash condition and
+          # stores the result and condition type in the conditions array.
+          #
+          # It yields condition's keys and values to allow the caller to create a proc
+          # object to be stored and executed later performing the actual query.
+          #
+          # @param condition_type [Symbol] the condition type. (eg. `:where`, `:or`)
+          # @param condition [Hash] the query condition to be expanded.
+          #
+          # @return [Array<Array>] the conditions array itself.
+          #
+          # @api private
+          # @since 0.3.1
+          def _push_to_expanded_condition(condition_type, condition)
+            proc = yield Array(condition).flatten(1)
+            conditions.push([condition_type, proc])
+          end
+
+          # Evaluates a block condition of a specified type and stores it in the
+          # conditions array.
+          #
+          # @param condition_type [Symbol] the condition type. (eg. `:where`, `:or`)
+          # @param condition [Proc] the query condition to be evaluated and stored.
+          # @param strategy [Symbol] the iterator method to be executed.
+          #   (eg. `:find_all`, `:reject`)
+          #
+          # @return [Array<Array>] the conditions array itself.
+          #
+          # @raise [Lotus::Model::InvalidQueryError] if block raises error when
+          # evaluated.
+          #
+          # @api private
+          # @since 0.3.1
+          def _push_evaluated_block_condition(condition_type, condition, strategy)
+            conditions.push([condition_type, Proc.new {
+              send(strategy) { |r|
+                begin
+                  OpenStruct.new(r).instance_eval(&condition)
+                rescue NoMethodError
+                  # TODO improve the error message, informing which
+                  # attributes are invalid
+                  raise Lotus::Model::InvalidQueryError.new
+                end
+              }
+            }])
           end
         end
       end

data/lib/lotus/model/adapters/sql/query.rb

@@ -17,7 +17,7 @@ module Lotus
         #
         #   query.where(language: 'ruby')
         #        .and(framework: 'lotus')
-        #        .desc(:users_count).all
+        #        .reverse_order(:users_count).all
         #
         #   # the records are fetched only when we invoke #all
         #
@@ -70,9 +70,14 @@ module Lotus
           #
           # @return [Array] a collection of entities
           #
+          # @raise [Lotus::Model::InvalidQueryError] if there is some issue when
+          # hitting the database for fetching records
+          #
           # @since 0.1.0
           def all
             Lotus::Utils::Kernel.Array(run)
+          rescue Sequel::DatabaseError => e
+            raise Lotus::Model::InvalidQueryError.new(e.message)
           end
 
           # Adds a SQL `WHERE` condition.
@@ -117,9 +122,8 @@ module Lotus
           #   query.where{ age > 10 }
           #
           #   # => SELECT * FROM `users` WHERE (`age` > 31)
-          def where(condition=nil, &blk)
-            condition = (condition or blk or raise ArgumentError.new('You need to specify a condition.'))
-            conditions.push([:where, condition])
+          def where(condition = nil, &blk)
+            _push_to_conditions(:where, condition || blk)
             self
           end
 
@@ -162,9 +166,8 @@ module Lotus
           #   query.where(name: 'John').or{ age > 31 }
           #
           #   # => SELECT * FROM `users` WHERE ((`name` = 'John') OR (`age` < 32))
-          def or(condition=nil, &blk)
-            condition = (condition or blk or raise ArgumentError.new('You need to specify a condition.'))
-            conditions.push([:or, condition])
+          def or(condition = nil, &blk)
+            _push_to_conditions(:or, condition || blk)
             self
           end
 
@@ -209,9 +212,8 @@ module Lotus
           #   query.exclude{ age > 31 }
           #
           #   # => SELECT * FROM `users` WHERE (`age` <= 31)
-          def exclude(condition=nil, &blk)
-            condition = (condition or blk or raise ArgumentError.new('You need to specify a condition.'))
-            conditions.push([:exclude, condition])
+          def exclude(condition = nil, &blk)
+            _push_to_conditions(:exclude, condition || blk).inspect
             self
           end
 
@@ -294,7 +296,7 @@ module Lotus
           #
           # @since 0.1.0
           #
-          # @see Lotus::Model::Adapters::Sql::Query#desc
+          # @see Lotus::Model::Adapters::Sql::Query#reverse_order
           #
           # @example Single column
           #
@@ -318,6 +320,29 @@ module Lotus
             self
           end
 
+          # Alias for order
+          #
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters::Sql::Query#order
+          #
+          # @example Single column
+          #
+          #   query.asc(:name)
+          #
+          #   # => SELECT * FROM `people` ORDER BY (`name`)
+          #
+          # @example Multiple columns
+          #
+          #   query.asc(:name, :year)
+          #
+          #   # => SELECT * FROM `people` ORDER BY `name`, `year`
+          #
+          # @example Multiple invokations
+          #
+          #   query.asc(:name).asc(:year)
+          #
+          #   # => SELECT * FROM `people` ORDER BY `name`, `year`
           alias_method :asc, :order
 
           # Specify the descending order of the records, sorted by the given
@@ -327,28 +352,28 @@ module Lotus
           #
           # @return self
           #
-          # @since 0.1.0
+          # @since 0.3.1
           #
           # @see Lotus::Model::Adapters::Sql::Query#order
           #
           # @example Single column
           #
-          #   query.desc(:name)
+          #   query.reverse_order(:name)
           #
           #   # => SELECT * FROM `people` ORDER BY (`name`) DESC
           #
           # @example Multiple columns
           #
-          #   query.desc(:name, :year)
+          #   query.reverse_order(:name, :year)
           #
           #   # => SELECT * FROM `people` ORDER BY `name`, `year` DESC
           #
           # @example Multiple invokations
           #
-          #   query.desc(:name).desc(:year)
+          #   query.reverse_order(:name).reverse_order(:year)
           #
           #   # => SELECT * FROM `people` ORDER BY `name`, `year` DESC
-          def desc(*columns)
+          def reverse_order(*columns)
             Array(columns).each do |column|
               conditions.push([_order_operator, Sequel.desc(column)])
             end
@@ -356,6 +381,25 @@ module Lotus
             self
           end
 
+          # Alias for reverse_order
+          #
+          # @since 0.1.0
+          #
+          # @see Lotus::Model::Adapters::Sql::Query#reverse_order
+          #
+          # @example Single column
+          #
+          #   query.desc(:name)
+          #
+          # @example Multiple columns
+          #
+          #   query.desc(:name, :year)
+          #
+          # @example Multiple invokations
+          #
+          #   query.desc(:name).desc(:year)
+          alias_method :desc, :reverse_order
+
           # Returns the sum of the values for the given column.
           #
           # @param column [Symbol] the column name
@@ -590,7 +634,7 @@ module Lotus
           #     end
           #
           #     def self.rank
-          #       query.desc(:comments_count)
+          #       query.reverse_order(:comments_count)
           #     end
           #
           #     def self.rank_by_author(author)
@@ -621,6 +665,22 @@ module Lotus
             end
           end
 
+          # Stores a query condition of a specified type in the conditions array.
+          #
+          # @param condition_type [Symbol] the condition type. (eg. `:where`, `:or`)
+          # @param condition [Hash, Proc] the query condition to be stored.
+          #
+          # @return [Array<Array>] the conditions array itself.
+          #
+          # @raise [ArgumentError] if condition is not specified.
+          #
+          # @api private
+          # @since 0.3.1
+          def _push_to_conditions(condition_type, condition)
+            raise ArgumentError.new('You need to specify a condition.') if condition.nil?
+            conditions.push([condition_type, condition])
+          end
+
           def _order_operator
             if conditions.any? {|c, _| c == :order }
               :order_more

data/lib/lotus/model/adapters/sql_adapter.rb

@@ -227,6 +227,20 @@ module Lotus
           Sql::Console.new(@uri).connection_string
         end
 
+        # Executes raw sql directly on the connection
+        #
+        # @param raw [String] the raw sql statement to execute on the connection
+        # @return [Object]
+        #
+        # @since 0.3.1
+        def execute(raw)
+          begin
+            @connection.execute(raw)
+          rescue Sequel::DatabaseError => e
+            raise Lotus::Model::InvalidQueryError.new(e.message)
+          end
+        end
+
         private
 
         # Returns a collection from the given name.

data/lib/lotus/model/mapping/coercions.rb

@@ -17,9 +17,9 @@ module Lotus
         #
         # @since 0.1.1
         #
-        # @see http://rdoc.info/gems/lotus-utils/Lotus/Utils/Kernel#Array-class_method
+        # @see http://ruby-doc.org/core/Kernel.html#method-i-Array
         def self.Array(arg)
-          Utils::Kernel.Array(arg) unless arg.nil?
+          ::Kernel.Array(arg) unless arg.nil?
         end
 
         # Coerce into a Boolean, unless the argument is nil

data/lib/lotus/model/mapping/collection.rb

@@ -236,6 +236,7 @@ module Lotus
         #   * Float
         #   * Hash
         #   * Integer
+        #   * BigDecimal
         #   * Set
         #   * String
         #   * Symbol

data/lib/lotus/model/version.rb

@@ -3,6 +3,6 @@ module Lotus
     # Defines the version
     #
     # @since 0.1.0
-    VERSION = '0.3.0'.freeze
+    VERSION = '0.3.1'.freeze
   end
 end

data/lib/lotus/repository.rb

@@ -252,6 +252,7 @@ module Lotus
       #   article = ArticleRepository.find(23)
       #   article.title # => "Launching Lotus::Model"
       def persist(entity)
+        _touch(entity)
         @adapter.persist(collection, entity)
       end
 
@@ -283,7 +284,8 @@ module Lotus
       #
       #   ArticleRepository.create(article) # no-op
       def create(entity)
-        unless entity.id
+        unless _persisted?(entity)
+          _touch(entity)
           @adapter.create(collection, entity)
         end
       end
@@ -331,7 +333,8 @@ module Lotus
       #
       #   ArticleRepository.update(article) # raises Lotus::Model::NonPersistedEntityError
       def update(entity)
-        if entity.id
+        if _persisted?(entity)
+          _touch(entity)
           @adapter.update(collection, entity)
         else
           raise Lotus::Model::NonPersistedEntityError
@@ -379,7 +382,7 @@ module Lotus
       #
       #   ArticleRepository.delete(article) # raises Lotus::Model::NonPersistedEntityError
       def delete(entity)
-        if entity.id
+        if _persisted?(entity)
           @adapter.delete(collection, entity)
         else
           raise Lotus::Model::NonPersistedEntityError
@@ -548,6 +551,50 @@ module Lotus
         end
       end
 
+      # Executes the given raw statement on the adapter.
+      #
+      # Please note that it's only supported by some databases,
+      # a `NotImplementedError` will be raised when the adapter does not
+      # responds to the `execute` method.
+      #
+      # For advanced scenarios, please check the documentation of each adapter.
+      #
+      # @param raw [String] the raw statement to execute on the connection
+      # @return [Object] the raw result set from SQL adapter
+      #
+      # @raise [NotImplementedError] if current Lotus::Model adapter doesn't
+      #   implement `execute`.
+      #
+      # @see Lotus::Model::Adapters::Abstract#execute
+      # @see Lotus::Model::Adapters::SqlAdapter#execute
+      #
+      # @since 0.3.1
+      #
+      # @example Basic usage with SQL adapter
+      #   require 'lotus/model'
+      #
+      #   class Article
+      #     include Lotus::Entity
+      #     attributes :title, :body
+      #   end
+      #
+      #   class ArticleRepository
+      #     include Lotus::Repository
+      #   end
+      #
+      #   article = Article.new(title: 'Introducing transactions',
+      #     body: 'lorem ipsum')
+      #
+      #   result_set = ArticleRepository.execute("SELECT * FROM articles")
+      #   result_set.each_hash do |result|
+      #     result # -> { id: 123, title: "Introducing transactions", body: "lorem ipsum"}
+      #   end
+      #
+      #   puts result_set.class # => SQLite3::ResultSet
+      def execute(raw)
+        @adapter.execute(raw)
+      end
+
       private
       # Fabricates a query and yields the given block to access the low level
       # APIs exposed by the query itself.
@@ -661,6 +708,47 @@ module Lotus
         query.negate!
         query
       end
+
+      # This is a method to check entity persited or not
+      #
+      # @param entity
+      # @return a boolean value
+      # @since 0.3.1
+      def _persisted?(entity)
+        !!entity.id
+      end
+
+      # Update timestamps
+      #
+      # @param entity [Object, Lotus::Entity] the entity
+      #
+      # @api private
+      # @since 0.3.1
+      def _touch(entity)
+        now = Time.now.utc
+
+        if _has_timestamp?(entity, :created_at)
+          entity.created_at ||= now
+        end
+
+        if _has_timestamp?(entity, :updated_at)
+          entity.updated_at = now
+        end
+      end
+
+      # Check if the given entity has the given timestamp
+      #
+      # @param entity [Object, Lotus::Entity] the entity
+      # @param timestamp [Symbol] the timestamp name
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api private
+      # @since 0.3.1
+      def _has_timestamp?(entity, timestamp)
+        entity.respond_to?(timestamp) &&
+          entity.respond_to?("#{ timestamp }=")
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lotus-model
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Luca Guidi
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-23 00:00:00.000000000 Z
+date: 2015-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lotus-utils
@@ -96,6 +96,7 @@ files:
 - README.md
 - lib/lotus-model.rb
 - lib/lotus/entity.rb
+- lib/lotus/entity/dirty_tracking.rb
 - lib/lotus/model.rb
 - lib/lotus/model/adapters/abstract.rb
 - lib/lotus/model/adapters/file_system_adapter.rb