datamappify 0.30.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: afcba7b889daac95e25ea353220e7f418082515d
-  data.tar.gz: d0cd4d8e8a01595ffe831c204ad52cccdafef85f
+  metadata.gz: 425218c5431f6668819ee6dee7cec37c8aa9e23f
+  data.tar.gz: a928d202dd9750197c297721fcb7142279a52d42
 SHA512:
-  metadata.gz: d95340abf96122fc88f136f028d31b0bf5b15915bbab6bc72e8a9180202ac8220e723c0b39f55b24b223640231580cbf8ae17636c118b86530bd9c81c0fceb40
-  data.tar.gz: e90bcfb79e7f232bcab801f73326d3088891454aa93db4cf6060590fc2fafc3f5bbf0bb8cd172aa3b017ab8677442db95a369c3d7615852123eded0c98114b72
+  metadata.gz: 250ba0d6203d7a76ee0deab3ed581783048960851f280821be7670507b4cee18115d5593f97c74a790a628b5c342e4ac9bba6a63b9997bfba2ae1a76a94857cc
+  data.tar.gz: aa64bb2f335e6e480c8ae2b0f3dbb70a70d5a45f924920238ac416a19550e54f0d7e652cb3118769c8af3f351329a4365a6accd7ab2c522c5c8f1cfaaca0d2bf

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## master
 
+## 0.40.0 [2013-05-21]
+
+- Added dirty attribute tracking.
+- Implemented attribute lazy loading!
+- Query methods (`find`, `save` and `destroy`) no longer support multiple entities.
+  - e.g. `UserRepository.find([1, 2, 3])` is no longer valid.
+- Added `exists?`, `create`, `create!`, `update` and `update!` to repository.
+- Implemented callbacks (e.g. `before_save` and `after_save`, etc).
+
 ## 0.30.0 [2013-04-12]
 
 - __Completely reimplemented Datamappify__

data/README.md

@@ -1,6 +1,4 @@
-# Datamappify [![Gem Version](https://badge.fury.io/rb/datamappify.png)](http://badge.fury.io/rb/datamappify) [![Build Status](https://api.travis-ci.org/fredwu/datamappify.png)](http://travis-ci.org/fredwu/datamappify) [![Coverage Status](https://coveralls.io/repos/fredwu/datamappify/badge.png)](https://coveralls.io/r/fredwu/datamappify) [![Code Climate](https://codeclimate.com/github/fredwu/datamappify.png)](https://codeclimate.com/github/fredwu/datamappify)
-
-__Datamappify is current in Proof-of-Concept stage, do NOT use it for anything other than experimentation.__
+# Datamappify [![Gem Version](https://badge.fury.io/rb/datamappify.png)](http://badge.fury.io/rb/datamappify) [![Build Status](https://api.travis-ci.org/fredwu/datamappify.png?branch=master)](http://travis-ci.org/fredwu/datamappify) [![Coverage Status](https://coveralls.io/repos/fredwu/datamappify/badge.png)](https://coveralls.io/r/fredwu/datamappify) [![Code Climate](https://codeclimate.com/github/fredwu/datamappify.png)](https://codeclimate.com/github/fredwu/datamappify)
 
 ## Overview
 
@@ -8,15 +6,21 @@ Compose and manage domain logic and data persistence separately and intelligentl
 
 Datamappify is built using [Virtus](https://github.com/solnic/virtus) and existing ORMs (ActiveRecord and Sequel, etc). The design goal is to utilise the powerfulness of existing ORMs as well as to separate domain logic (model behaviour) from data persistence.
 
+My motivation for creating Datamappify is to hide the complexity of dealing with data in different data sources including the ones from external web services. Features like lazy loading and dirty tracking are designed to enhance the usability of dealing with web services.
+
 Datamappify consists of three components:
 
 - __Entity__ contains models behaviour, think an ActiveRecord model with the persistence specifics removed.
-- __Data__ as the name suggests, holds your model data. It is an ORM object (ActiveRecord and Sequel, etc).
 - __Repository__ is responsible for data retrieval and persistence, e.g. `find`, `save` and `destroy`, etc.
+- __Data__ as the name suggests, holds your model data. It contains ORM objects (ActiveRecord and Sequel, etc).
+
+![](ERD.png)
 
 Note: Datamappify is NOT affiliated with the [Datamapper](https://github.com/datamapper/) project.
 
-### Supported ORMs for Persistence
+### Built-in ORMs for Persistence
+
+You may implement your own [data provider and criterias](lib/datamappify/data), but Datamappify comes with build-in support for the following ORMS:
 
 - ActiveRecord
 - Sequel
@@ -55,6 +59,19 @@ class User
 end
 ```
 
+#### Lazy loading
+
+Datamappify supports attribute lazy loading via the `Lazy` module.
+
+```ruby
+class User
+  include Datamappify::Entity
+  include Datamappify::Lazy
+end
+```
+
+When an entity is lazy loaded, only attributes from the default source will be loaded. Other attributes will only be loaded once they are called. This is especially useful if some of your data sources are external services.
+
 ### Repository
 
 Map entity attributes to DB columns - better yet, you can even map attributes to __different ORMs__!
@@ -85,48 +102,93 @@ end
 
 #### Retrieving entities
 
-Pass in an id or an array of ids.
+Pass in an id.
 
 ```ruby
 user  = UserRepository.find(1)
-users = UserRepository.find([1, 2, 3])
+```
+
+#### Checking if an entity exists in the repository
+
+Pass in an entity.
+
+```ruby
+UserRepository.exists?(user)
 ```
 
 #### Saving/updating entities
 
-Pass in an entity or an array of entities.
+Pass in an entity.
 
 There is also `save!` that raises `Datamappify::Data::EntityNotSaved`.
 
 ```ruby
 UserRepository.save(user)
-UserRepository.save([user, user2, user3])
 ```
 
+Datamappify supports attribute dirty tracking - only dirty attributes will be saved.
+
 #### Destroying an entity
 
-Pass in an entity, an id, an array of entities or an array of ids.
+Pass in an entity.
 
 There is also `destroy!` that raises `Datamappify::Data::EntityNotDestroyed`.
 
 Note that due to the attributes mapping, any data found in mapped ActiveRecord objects are not touched.
 
 ```ruby
-UserRepository.destroy(1)
-UserRepository.destroy([1, 2, 3])
 UserRepository.destroy(user)
-UserRepository.destroy([user, user2, user3])
 ```
 
+#### Callbacks
+
+Datamappify supports the following callbacks via [Hooks](https://github.com/apotonick/hooks):
+
+- before_create
+- before_update
+- before_save
+- before_destroy
+- after_create
+- after_update
+- after_save
+- after_destroy
+
+Callbacks are defined in repositories, and they have access to the entity. Example:
+
+```ruby
+class UserRepository
+  include Datamappify::Repository
+
+  before_create :make_me_admin
+  before_create :make_me_awesome
+  after_save    :make_me_smile
+
+  private
+
+  def make_me_admin(entity)
+    # ...
+  end
+
+  def make_me_awesome(entity)
+    # ...
+  end
+
+  def make_me_smile(entity)
+    # ...
+  end
+
+  # ...
+end
+```
+
+Note: Returning either `nil` or `false` from the callback will cancel all subsequent callbacks (and the action itself, it it's a `before_` callback).
+
 ## Changelog
 
 Refer to [CHANGELOG](CHANGELOG.md).
 
 ## Todo
 
-- Track dirty entity attributes.
-- Attribute lazy-loading.
-- Hooks for persistence (`before_save` and `after_save`, etc).
 - [Authoritative source](http://msdn.microsoft.com/en-au/library/ff649505.aspx).
 - Enforce attribute type casting.
 - Support for configurable primary keys and foreign keys.

data/datamappify.gemspec

@@ -18,8 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "virtus",        "~> 0.5"
-  spec.add_dependency "activesupport", ">= 4.0.0.beta1", "< 5"
+  spec.add_dependency "virtus",      "~> 0.5"
+  spec.add_dependency "activemodel", ">= 4.0.0.rc1", "< 5"
+  spec.add_dependency "hooks",       "~> 0.2.2"
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
@@ -32,6 +33,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "coveralls"
   spec.add_development_dependency "sqlite3"
   spec.add_development_dependency "sequel"
-  spec.add_development_dependency "activerecord",  ">= 4.0.0.beta1", "< 5"
+  spec.add_development_dependency "activerecord",     ">= 4.0.0.rc1", "< 5"
   spec.add_development_dependency "database_cleaner", ">= 1.0.0.RC1", "< 2"
 end

data/lib/datamappify/data/criteria/active_record/destroy.rb

@@ -7,7 +7,7 @@ module Datamappify
             super(source_class, nil, id)
           end
 
-          def result
+          def perform
             source_class.destroy(criteria)
           end
         end

data/lib/datamappify/data/criteria/active_record/exists.rb

@@ -3,8 +3,8 @@ module Datamappify
     module Criteria
       module ActiveRecord
         class Exists < Common
-          def result
-            source_class.exists?(entity.id)
+          def perform
+            !!source_class.exists?(entity.id)
           end
         end
       end

data/lib/datamappify/data/criteria/active_record/transaction.rb

@@ -3,7 +3,7 @@ module Datamappify
     module Criteria
       module ActiveRecord
         class Transaction < Common
-          def result
+          def perform
             source_class.transaction(&@block)
           end
         end

data/lib/datamappify/data/criteria/common.rb

@@ -13,7 +13,7 @@ module Datamappify
         # @return [void]
         attr_reader :criteria
 
-        # @return [Set]
+        # @return [Set<Mapper::Attribute>]
         attr_reader :attributes
 
         # @param source_class [Class]
@@ -28,6 +28,17 @@ module Datamappify
           @block = block
         end
 
+        # Performs the action (defined by child method classes) with callbacks
+        #
+        # @return [void]
+        def perform_with_callbacks
+          result = perform
+
+          store_attribute_value if attributes
+
+          result
+        end
+
         protected
 
         # Key name of either the primary key (e.g. +id+) or foreign key (e.g. +user_id+)
@@ -80,6 +91,15 @@ module Datamappify
           hash
         end
 
+        # Stores the attribute value in {Mapper::Attribute} for later use
+        #
+        # @return [void]
+        def store_attribute_value
+          attributes.each do |attribute|
+            attribute.value = entity.instance_variable_get("@#{attribute.name}")
+          end
+        end
+
         private
 
         # Ignores the attribute if it isn't dirty or if it's a primary key

data/lib/datamappify/data/criteria/relational/count.rb

@@ -3,7 +3,7 @@ module Datamappify
     module Criteria
       module Relational
         class Count < Common
-          def result
+          def perform
             source_class.count
           end
         end

data/lib/datamappify/data/criteria/relational/find.rb

@@ -3,7 +3,7 @@ module Datamappify
     module Criteria
       module Relational
         class Find < Common
-          def result
+          def perform
             record = source_class.where(criteria).first
 
             update_entity_with(record) if record

data/lib/datamappify/data/criteria/relational/save.rb

@@ -3,7 +3,7 @@ module Datamappify
     module Criteria
       module Relational
         class Save < Common
-          def result
+          def perform
             new_record? ? create_record : save_record unless ignore?
           end
 

data/lib/datamappify/data/criteria/sequel/destroy.rb

@@ -7,7 +7,7 @@ module Datamappify
             super(source_class, nil, id)
           end
 
-          def result
+          def perform
             source_class.where(:id => criteria).destroy
           end
         end

data/lib/datamappify/data/criteria/sequel/exists.rb

@@ -3,7 +3,7 @@ module Datamappify
     module Criteria
       module Sequel
         class Exists < Common
-          def result
+          def perform
             source_class.where(:id => entity.id).any?
           end
         end

data/lib/datamappify/data/criteria/sequel/transaction.rb

@@ -3,7 +3,7 @@ module Datamappify
     module Criteria
       module Sequel
         class Transaction < Common
-          def result
+          def perform
             source_class.db.transaction(&@block)
           end
         end

data/lib/datamappify/data/mapper/attribute.rb

@@ -3,6 +3,11 @@ module Datamappify
     class Mapper
       # Represents an entity attribute and its associated data source
       class Attribute
+        # Same as name, but in symbol
+        #
+        # @return [Symbol]
+        attr_reader :key
+
         # @return [String]
         attr_reader :name
 
@@ -15,6 +20,9 @@ module Datamappify
         # @return [String]
         attr_reader :source_attribute_name
 
+        # @return [any]
+        attr_accessor :value
+
         # @param name [Symbol]
         #   name of the attribute
         #
@@ -22,6 +30,7 @@ module Datamappify
         #   data provider, class and attribute,
         #   e.g. "ActiveRecord::User#surname"
         def initialize(name, source)
+          @key  = name
           @name = name.to_s
 
           @provider_name, @source_class_name, @source_attribute_name = parse_source(source)

data/lib/datamappify/data/mapper.rb

@@ -34,10 +34,15 @@ module Datamappify
         @default_source_class ||= default_provider.find_or_build_record_class(entity_class.name)
       end
 
-      # @return [Hash]
+      # @return [Set<Attribute>]
+      def attributes
+        @attributes ||= Set.new(default_attributes + custom_attributes)
+      end
+
+      # @return [Hash<Set>]
       #   attribute sets classified by the names of their data provider
       def classified_attributes
-        @classified_attributes ||= Set.new(custom_attributes + default_attributes).classify(&:provider_name)
+        @classified_attributes ||= Set.new(attributes).classify(&:provider_name)
       end
 
       private

data/lib/datamappify/data/provider/common_provider.rb

@@ -59,7 +59,7 @@ module Datamappify
         # @yield
         #   an optional block passed to the +Criteria+ {Criteria::Common#initialize initialiser}
         def build_criteria(name, *args, &block)
-          Data::Criteria.const_get(class_name).const_get(name).new(*args, &block).result
+          Data::Criteria.const_get(class_name).const_get(name).new(*args, &block).perform_with_callbacks
         end
       end
     end

data/lib/datamappify/entity/lazy_checking.rb

@@ -0,0 +1,12 @@
+module Datamappify
+  module Entity
+    module LazyChecking
+      # Whether the entity is lazy loaded
+      #
+      # @return [Boolean]
+      def lazy_loaded?
+        self.respond_to?(:repository)
+      end
+    end
+  end
+end

data/lib/datamappify/entity.rb

@@ -1,12 +1,16 @@
+require 'observer'
 require 'virtus'
+require 'datamappify/entity/lazy_checking'
 
 module Datamappify
   module Entity
     def self.included(klass)
       klass.class_eval do
+        include Observable
         include Virtus
         include Virtus::Equalizer.new(inspect)
         include ActiveModel::Validations
+        include LazyChecking
 
         attribute :id, Integer
       end

data/lib/datamappify/lazy/attributes_handler.rb

@@ -0,0 +1,123 @@
+module Datamappify
+  module Lazy
+    # Overrides attribute setters and getters for lazy loading
+    class AttributesHandler
+      # @return [Array]
+      attr_accessor :uncached_attributes
+
+      # @param entity [Entity]
+      def initialize(entity)
+        @entity              = entity
+        @uncached_attributes = entity.attributes.keys
+
+        entity.add_observer(self)
+      end
+
+      # Triggers only when a reader query (e.g. {Repository::QueryMethod::Find}) is performed
+      #
+      # @param (see Repository::QueryMethod::Method::SourceAttributesWalker#walk_performed)
+      def update(query_method, attributes)
+        if query_method && query_method.reader?
+          cache_attributes!
+          uncached_attributes.each { |name| override_attribute(name) }
+        end
+      end
+
+      private
+
+      # @see Data::Mapper#attributes
+      #
+      # @return (see Data::Mapper#attributes)
+      def all_attributes
+        @all_attributes ||= @entity.repository.data_mapper.attributes
+      end
+
+      # Removes the cached attributes from the uncached attributes array
+      #
+      # @return [void]
+      def cache_attributes!
+        @uncached_attributes = @uncached_attributes - @entity.cached_attributes.keys
+      end
+
+      # Overrides attribute setters and getters
+      #
+      # @param name [Symbol]
+      #
+      # @return [void]
+      def override_attribute(name)
+        override_attribute_setter(name)
+        override_attribute_getter(name)
+      end
+
+      # @param (see #override_attribute)
+      #
+      # @return [void]
+      def override_attribute_setter(name)
+        @entity.define_singleton_method "#{name}=" do |value|
+          super(value)
+
+          self.define_singleton_method name do
+            instance_variable_set "@#{name}", value
+          end
+        end
+      end
+
+      # @param (see #override_attribute)
+      #
+      # @return [void]
+      def override_attribute_getter(name)
+        entity     = @entity
+        attributes = attributes_from_same_source(name)
+
+        entity.define_singleton_method name do
+          Logger.performed(:override_attribute, name)
+
+          AttributesHandler.walk_attributes(name, entity, attributes)
+
+          instance_variable_get "@#{name}"
+        end
+      end
+
+      # @param name [Symbol]
+      #
+      # @return [Set<Data::Mapper::Attribute>]
+      def attributes_from_same_source(name)
+        source_class_name = attribute_by_name(name).source_class_name
+
+        attributes = all_attributes.select do |attribute|
+          attribute.source_class_name == source_class_name
+        end
+
+        Set.new(attributes)
+      end
+
+      # @param name [Symbol]
+      #
+      # @return [Data::Mapper::Attribute]
+      def attribute_by_name(name)
+        all_attributes.find { |attribute| attribute.key == name }
+      end
+
+      class << self
+        # @param name [Symbol]
+        #
+        # @param attributes [Set<Data::Mapper::Attribute>]
+        #
+        # @return [void]
+        def walk_attributes(name, entity, attributes)
+          SourceAttributesWalker.new({
+            :entity           => entity,
+            :provider_name    => attributes.first.provider_name,
+            :attributes       => attributes,
+            :dirty_aware?     => true,
+            :dirty_attributes => []
+          }).execute do |provider_name, source_class, attributes|
+            entity.repository.data_mapper.provider(provider_name).build_criteria(
+              :FindByKey, source_class, entity, attributes
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datamappify/lazy/source_attributes_walker.rb

@@ -0,0 +1,49 @@
+require 'datamappify/repository/query_method/method/source_attributes_walker'
+
+module Datamappify
+  module Lazy
+    class SourceAttributesWalker < Repository::QueryMethod::Method::SourceAttributesWalker
+      private
+
+      # @param (see Repository::QueryMethod::Method::SourceAttributesWalker#do_walk?)
+      #
+      # @see Repository::QueryMethod::Method::SourceAttributesWalker#do_walk?
+      #
+      # @return (see Repository::QueryMethod::Method::SourceAttributesWalker#do_walk?)
+      def do_walk?(source_class, attributes)
+        read_only? ? default_source_class?(source_class) : true
+      end
+
+      # @param (see Repository::QueryMethod::Method::SourceAttributesWalker#walk_performed)
+      #
+      # @see Repository::QueryMethod::Method::SourceAttributesWalker#walk_performed
+      #
+      # @return (see Repository::QueryMethod::Method::SourceAttributesWalker#walk_performed)
+      def walk_performed(attributes)
+        attributes.each do |attribute|
+          @entity.cached_attributes[attribute.key] = attribute.value
+        end
+
+        @entity.changed
+        @entity.notify_observers(@query_method, attributes)
+
+        super
+      end
+
+      # @param source_class [Class]
+      #
+      # @return [Boolean]
+      def default_source_class?(source_class)
+        @entity.repository.data_mapper.default_source_class == source_class
+      end
+
+      # Whether the walker is in read-only mode, it is determined from
+      # the {Repository::QueryMethod::Method query method} if available
+      #
+      # @return [Boolean]
+      def read_only?
+        !!@query_method && @query_method.reader?
+      end
+    end
+  end
+end

data/lib/datamappify/lazy.rb

@@ -0,0 +1,24 @@
+require 'datamappify/lazy/source_attributes_walker'
+require 'datamappify/lazy/source_attributes_walker'
+require 'datamappify/lazy/attributes_handler'
+
+module Datamappify
+  module Lazy
+    def self.included(klass)
+      klass.class_eval do
+        # @return [Repository]
+        cattr_accessor :repository
+
+        # @return [Hash]
+        attr_accessor :cached_attributes
+      end
+    end
+
+    def initialize(*args)
+      super
+
+      @cached_attributes  = {}
+      @attributes_handler = AttributesHandler.new(self)
+    end
+  end
+end

data/lib/datamappify/logger.rb

@@ -0,0 +1,13 @@
+module Datamappify
+  class Logger
+    # A meta method to help record whether an action has been performed
+    #
+    # @param args [any]
+    #   optional args for logging/tracking purpose
+    #
+    # @return [TrueClass]
+    def self.performed(*args)
+      true
+    end
+  end
+end

data/lib/datamappify/repository/lazy_checking.rb

@@ -0,0 +1,19 @@
+module Datamappify
+  module Repository
+    module LazyChecking
+      # Is the repository for an entity that requires lazy loading?
+      #
+      # @return [Boolean]
+      def lazy_load?
+        data_mapper.entity_class.included_modules.include?(Datamappify::Lazy)
+      end
+
+      # Assign the repository itself to the lazy entity
+      #
+      # @return [void]
+      def assign_to_entity
+        data_mapper.entity_class.repository = self
+      end
+    end
+  end
+end