datamappify 0.51.1 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2eb31e15b5957467c3d496b2ddaf6f584d4b652
-  data.tar.gz: 7515f3c6935418a502e22213c75b7465a5faaf4e
+  metadata.gz: cd079889034877268b854c9c1402e747eb84348a
+  data.tar.gz: ea1988a5cea43748d9d55658e999b9c1a95a9de6
 SHA512:
-  metadata.gz: 5f014a40766499d0f3e076d7ff82117a1e1bb5b5752741c917f14bcd5d5daceb1c5e080211f3bdd83cd8478425eb87d7ebee20582622fc0d23542f0150dcf91a
-  data.tar.gz: c13d2de1a9596ccfe8951a7d447e749529f4ab5539b2f33bed0499a12e000dca871e36a040401d2f405f96037d3c440d585326bfbb94db880154b35bea06a149
+  metadata.gz: 18fde8f5ddccee08904440fdd706f0563130a78566a8860bc3a67017b35320444655db5226e6019d73e29e069750a80ddc267dd7e0bcc63d64a84daf05d263c8
+  data.tar.gz: 91fa0a11fd1af61e398b0b22e6dcad429c4123653dafabcb9c70bc39681ce0a8a9b1e61944996f688eac8221b771344a02679f9b137d3cc278a57a4b6b9114f6

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## master
 
+## 0.52.0 [2013-06-26]
+
+- Added support for reverse mapping attributes.
+
 ## 0.51.1 [2013-06-17]
 
 - Fixed an issue with attribute name and validation conflicts.

data/README.md

@@ -1,18 +1,29 @@
 # 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)
 
+#### Compose, decouple and manage domain logic and data persistence separately. Works great with forms!
+
 ## Overview
 
-Compose and manage domain logic and data persistence separately and intelligently, Datamappify is loosely based on the [Repository Pattern](http://martinfowler.com/eaaCatalog/repository.html) and [Entity Aggregation](http://msdn.microsoft.com/en-au/library/ff649505.aspx).
+The typical Rails (and ActiveRecord) way of building applications is great for small to medium sized projects, but when projects grow larger and more complex, your models too become larger and more complex - it is not uncommon to have god classes such as a User model.
+
+Datamappify tries to solve two common problems in web applications:
+
+1. The coupling between domain logic and data persistence.
+2. The coupling between forms and models.
 
-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.
+Datamappify is loosely based on the [Repository Pattern](http://martinfowler.com/eaaCatalog/repository.html) and [Entity Aggregation](http://msdn.microsoft.com/en-au/library/ff649505.aspx), and is built on top of [Virtus](https://github.com/solnic/virtus) and existing ORMs (ActiveRecord and Sequel, etc).
 
-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.
+There are three main design goals:
+
+1. To utilise the powerfulness of existing ORMs so that using Datamappify doesn't interrupt too much of your current workflow. For example, [Devise](https://github.com/plataformatec/devise) would still work if you use it with a `UserAccount` ActiveRecord model that is attached to a `User` entity managed by Datamappify.
+2. To have a flexible entity model that works great with dealing with form data. For example, [SimpleForm](https://github.com/plataformatec/simple_form) would still work with nested attributes from different ORM models if you map entity attributes smartly in your repositories managed by Datamappify.
+3. To have a set of data providers to encapsulate the handling of how the data is persisted. This is especially useful for dealing with external data sources such as a web service. For example, by calling `UserRepository.save(user)`, certain attributes of the user entity are now persisted on a remote web service. Better yet, dirty tracking and lazy loading are supported out of the box!
 
 Datamappify consists of three components:
 
 - __Entity__ contains models behaviour, think an ActiveRecord model with the persistence specifics removed.
 - __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).
+- __Data__ as the name suggests, holds your model data. It contains ORM objects (e.g. ActiveRecord models).
 
 Below is a high level and somewhat simplified overview of Datamappify's architecture.
 
@@ -39,6 +50,10 @@ Add this line to your application's Gemfile:
 
 Entity uses [Virtus](https://github.com/solnic/virtus) DSL for defining attributes and [ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations.html) DSL for validations.
 
+The cool thing about Virtus is that all your attributes get [coercion](https://github.com/solnic/virtus#collection-member-coercions) for free!
+
+Below is an example of a User entity, with inline comments on how some of the DSLs work.
+
 ```ruby
 class User
   include Datamappify::Entity
@@ -142,11 +157,13 @@ class User
 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.
+When an entity is lazy loaded, only attributes from the primary source (e.g. `User` entity's primary source would be `ActiveRecord::User` as specified in the corresponding repository) 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 web services.
 
 ### Repository
 
-Map entity attributes to DB columns - better yet, you can even map attributes to __different ORMs__!
+Repository maps entity attributes to DB columns - better yet, you can even map attributes to __different ORMs__!
+
+Below is an example of a repository for the User entity, you can have more than one repositories for the same entity.
 
 ```ruby
 class UserRepository
@@ -160,6 +177,8 @@ class UserRepository
 
   # specify any attributes that need to be mapped
   #
+  # for attributes mapped from a different source class, a foreign key on the source class is required
+  #
   # for example:
   #   - 'last_name' is mapped to the 'User' ActiveRecord class and its 'surname' attribute
   #   - 'driver_license' is mapped to the 'UserDriverLicense' ActiveRecord class and its 'number' attribute
@@ -169,6 +188,14 @@ class UserRepository
   map_attribute :driver_license, 'ActiveRecord::UserDriverLicense#number'
   map_attribute :passport,       'Sequel::UserPassport#number'
   map_attribute :health_care,    'Sequel::UserHealthCare#number'
+
+  # attributes can also be reverse mapped by specifying the `via` option
+  #
+  # for example, the below attribute will look for `hobby_id` on the user object,
+  # and map `hobby_name` from the `name` attribute of `ActiveRecord::Hobby`
+  #
+  # this is useful for mapping form fields (similar to ActiveRecord's nested attributes)
+  map_attribute :hobby_name,     'ActiveRecord::Hobby#name', :via => :hobby_id
 end
 ```
 
@@ -186,7 +213,7 @@ class GuestUserRepository < UserRepository
 end
 ```
 
-In the above example, both repositories deal with the `User` data model.
+In the above example, both repositories deal with the `ActiveRecord::User` data model.
 
 ### Repository APIs
 
@@ -194,7 +221,7 @@ _More repository APIs are being added, below is a list of the currently implemen
 
 #### Retrieving an entity
 
-Pass in an id.
+Accepts an id.
 
 ```ruby
 user = UserRepository.find(1)
@@ -202,7 +229,7 @@ user = UserRepository.find(1)
 
 #### Checking if an entity exists in the repository
 
-Pass in an entity.
+Accepts an entity.
 
 ```ruby
 UserRepository.exists?(user)
@@ -228,7 +255,7 @@ _Note: it does not currently support searching attributes from different data pr
 
 #### Saving/updating entities
 
-Pass in an entity.
+Accepts an entity.
 
 There is also `save!` that raises `Datamappify::Data::EntityNotSaved`.
 
@@ -240,10 +267,10 @@ Datamappify supports attribute dirty tracking - only dirty attributes will be sa
 
 ##### Mark attributes as dirty
 
-Sometimes it's useful to manually mark the whole entity, or some attributes in the entity to be dirty - i.e. when you are submitting a form and only want to update the changed attributes. In this case, you could:
+Sometimes it's useful to manually mark the whole entity, or some attributes in the entity to be dirty. In this case, you could:
 
 ```ruby
-UserRepository.states.mark_as_dirty(user)
+UserRepository.states.mark_as_dirty(user) # marks the whole entity as dirty
 
 UserRepository.states.find(user).changed?            #=> true
 UserRepository.states.find(user).first_name_changed? #=> true
@@ -254,7 +281,7 @@ UserRepository.states.find(user).age_changed?        #=> true
 Or:
 
 ```ruby
-UserRepository.states.mark_as_dirty(user, :first_name, :last_name)
+UserRepository.states.mark_as_dirty(user, :first_name, :last_name) # marks only first_name and last_name as dirty
 
 UserRepository.states.find(user).changed?            #=> true
 UserRepository.states.find(user).first_name_changed? #=> true
@@ -264,11 +291,11 @@ UserRepository.states.find(user).age_changed?        #=> false
 
 #### Destroying an entity
 
-Pass in an entity.
+Accepts 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.
+Note that due to the attributes mapping, any data found in mapped records are not touched. For example the corresponding `ActiveRecord::User` record will be destroyed, but `ActiveRecord::Hobby` that is associated will not.
 
 ```ruby
 UserRepository.destroy(user)
@@ -287,7 +314,7 @@ Datamappify supports the following callbacks via [Hooks](https://github.com/apot
 - after_save
 - after_destroy
 
-Callbacks are defined in repositories, and they have access to the entity. Example:
+Callbacks are defined in repositories, and they have access to the entity. For example:
 
 ```ruby
 class UserRepository
@@ -315,7 +342,7 @@ class UserRepository
 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).
+Note: Returning either `nil` or `false` from the callback will cancel all subsequent callbacks (and the action itself, if it's a `before_` callback).
 
 ## Changelog
 

data/datamappify.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = Datamappify::VERSION
   spec.authors       = ["Fred Wu"]
   spec.email         = ["ifredwu@gmail.com"]
-  spec.description   = %q{Compose and manage domain logic and data persistence separately and intelligently.}
+  spec.description   = %q{Compose, decouple and manage domain logic and data persistence separately. Works great with forms!}
   spec.summary       = spec.description
   spec.homepage      = "https://github.com/fredwu/datamappify"
   spec.license       = "MIT"
@@ -18,7 +18,7 @@ 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 "virtus",      ">= 1.0.0.beta0", "<= 2.0"
   spec.add_dependency "activemodel", ">= 4.0.0.rc1", "< 5"
   spec.add_dependency "hooks",       "~> 0.3.0"
 

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

@@ -1,10 +1,13 @@
 require 'datamappify/data/criteria/relational/save'
+require 'datamappify/data/criteria/concerns/update_primary_record'
 
 module Datamappify
   module Data
     module Criteria
       module ActiveRecord
         class Save < Relational::Save
+          include Concerns::UpdatePrimaryRecord
+
           private
 
           def save_record
@@ -14,7 +17,8 @@ module Datamappify
 
           def save(record)
             record.update_attributes attributes_and_values
-            record
+
+            super
           end
         end
       end

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

@@ -11,11 +11,17 @@ module Datamappify
         attr_reader :entity
 
         # @return [void]
-        attr_reader :criteria
+        attr_accessor :criteria
 
         # @return [Set<Mapper::Attribute>]
         attr_reader :attributes
 
+        # @return [Hash]
+        attr_accessor :attributes_and_values
+
+        # @return [Hash]
+        attr_reader :options
+
         # @param source_class [Class]
         #
         # @param args [any]
@@ -24,7 +30,7 @@ module Datamappify
         #   an optional block
         def initialize(source_class, *args, &block)
           @source_class = source_class
-          @entity, @criteria, @attributes = *args
+          @entity, @criteria, @attributes, @options = *args
           @block = block
         end
 
@@ -39,6 +45,23 @@ module Datamappify
           result
         end
 
+        # Attributes with their corresponding values
+        #
+        # @return [Hash]
+        def attributes_and_values
+          @attributes_and_values ||= begin
+            hash = {}
+
+            attributes.each do |attribute|
+              unless ignore_attribute?(attribute)
+                hash[attribute.source_attribute_name] = entity.send(attribute.name)
+              end
+            end
+
+            hash
+          end
+        end
+
         protected
 
         # Name of the default source class, e.g. +"User"+,
@@ -84,23 +107,6 @@ module Datamappify
           attributes_and_values.empty?
         end
 
-        # Attributes with their corresponding values
-        #
-        # @return [Hash]
-        def attributes_and_values
-          @attributes_and_values ||= begin
-            hash = {}
-
-            attributes.each do |attribute|
-              unless ignore_attribute?(attribute)
-                hash[attribute.source_attribute_name] = entity.send(attribute.name)
-              end
-            end
-
-            hash
-          end
-        end
-
         # Stores the attribute value in {Mapper::Attribute} for later use
         #
         # @return [void]
@@ -117,7 +123,7 @@ module Datamappify
 
         # @return [Attribute]
         def pk
-          @pk ||= attributes.find { |attribute| attribute.key == :id }
+          @pk ||= attributes.find(&:primary_key?)
         end
 
         private

data/lib/datamappify/data/criteria/concerns/update_primary_record.rb

@@ -0,0 +1,28 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Concerns
+        module UpdatePrimaryRecord
+          private
+
+          def save(record)
+            if options && options[:via] && options[:primary_record]
+              update_primary_record_with(record)
+            end
+
+            record
+          end
+
+          def update_primary_record_with(record)
+            save = self.class.superclass.new(options[:primary_record].class, entity, {
+              :id => options[:primary_record].id
+            })
+
+            save.attributes_and_values = { options[:via] => record.id }
+            save.send(:save_record)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datamappify/data/criteria/relational/concerns/set_criteria.rb

@@ -0,0 +1,36 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Relational
+        module Concerns
+          module SetCriteria
+            def initialize(*args)
+              super
+
+              set_criteria if entity.id
+            end
+
+            private
+
+            def set_criteria
+              self.criteria = if options[:via]
+                criteria_for_reverse_mapping
+              else
+                criteria_for_normal_mapping
+              end
+            end
+
+            def criteria_for_reverse_mapping
+              reverse_id = options[:primary_record].send(options[:via])
+              reverse_id ? { :id => reverse_id } : {}
+            end
+
+            def criteria_for_normal_mapping
+              { key_name => entity.id }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,8 @@ module Datamappify
             record = source_class.where(criteria).first
 
             update_entity_with(record) if record
+
+            record
           end
 
           private

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

@@ -1,14 +1,15 @@
 require 'datamappify/data/criteria/relational/find'
+require 'datamappify/data/criteria/relational/concerns/set_criteria'
 
 module Datamappify
   module Data
     module Criteria
       module Relational
         class FindByKey < Find
-          def initialize(source_class, entity, attributes, &block)
-            super(source_class, entity, nil, attributes, &block)
+          include Concerns::SetCriteria
 
-            @criteria = { key_name => entity.id }
+          def initialize(source_class, entity, attributes, options = {}, &block)
+            super(source_class, entity, nil, attributes, options, &block)
           end
         end
       end

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

@@ -14,6 +14,8 @@ module Datamappify
             saved_record = save(record)
 
             update_entity_with(saved_record) if primary_record?
+
+            record
           end
 
           def update_entity_with(record)

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

@@ -1,12 +1,14 @@
+require 'datamappify/data/criteria/relational/concerns/set_criteria'
+
 module Datamappify
   module Data
     module Criteria
       module Relational
         module SaveByKey
-          def initialize(source_class, entity, attributes, &block)
-            super(source_class, entity, {}, attributes, &block)
+          include Concerns::SetCriteria
 
-            @criteria = { key_name => entity.id } unless entity.id.nil?
+          def initialize(source_class, entity, attributes, options = {}, &block)
+            super(source_class, entity, {}, attributes, options, &block)
           end
         end
       end

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

@@ -1,10 +1,13 @@
 require 'datamappify/data/criteria/relational/save'
+require 'datamappify/data/criteria/concerns/update_primary_record'
 
 module Datamappify
   module Data
     module Criteria
       module Sequel
         class Save < Relational::Save
+          include Concerns::UpdatePrimaryRecord
+
           private
 
           def save_record
@@ -14,7 +17,8 @@ module Datamappify
 
           def save(record)
             record.update attributes_and_values
-            record
+
+            super
           end
         end
       end

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

@@ -23,6 +23,9 @@ module Datamappify
         # @return [Class]
         attr_reader :primary_source_class
 
+        # @return [Hash]
+        attr_reader :options
+
         # @return [any]
         attr_accessor :value
 
@@ -33,16 +36,21 @@ module Datamappify
         #   data provider, class and attribute,
         #   e.g. "ActiveRecord::User#surname"
         #
-        # @param primary_source_class [Class]
-        def initialize(name, source, primary_source_class)
+        # @param options [Hash]
+        def initialize(name, source, options)
           @key                  = name
           @name                 = name.to_s
-          @primary_source_class = primary_source_class
+          @options              = options
+          @primary_source_class = options[:primary_source_class]
 
           @provider_name, @source_class_name, @source_attribute_name = parse_source(source)
 
-          unless primary_attribute? || external_attribute?
-            Record.build_association(self, primary_source_class)
+          if secondary_attribute?
+            if reverse_mapped?
+              Record.build_reversed_association(self, primary_source_class)
+            else
+              Record.build_association(self, primary_source_class)
+            end
           end
         end
 
@@ -96,18 +104,6 @@ module Datamappify
           source_attribute_name == 'id'
         end
 
-        # @return [Boolean]
-        def primary_attribute?
-          provider_name == primary_provider_name && primary_source_class == source_class
-        end
-
-        # External attribute is from a different data provider than the primary data provider
-        #
-        # @return [Boolean]
-        def external_attribute?
-          provider_name != primary_provider_name
-        end
-
         # @return [String]
         def primary_provider_name
           @primary_provider_name ||= primary_source_class.parent.to_s.demodulize
@@ -124,6 +120,31 @@ module Datamappify
           @primary_reference_key ||= :"#{primary_source_class.to_s.demodulize.underscore}_id"
         end
 
+        # Primary attribute is from the same data provider and the same source class
+        #
+        # @return [Boolean]
+        def primary_attribute?
+          provider_name == primary_provider_name && primary_source_class == source_class
+        end
+
+        # Secondary attribute is from the same data provider but a different source class
+        #
+        # @return [Boolean]
+        def secondary_attribute?
+          provider_name == primary_provider_name && primary_source_class != source_class
+        end
+
+        # External attribute is from a different data provider than the primary data provider
+        #
+        # @return [Boolean]
+        def external_attribute?
+          provider_name != primary_provider_name
+        end
+
+        def reverse_mapped?
+          @options[:via]
+        end
+
         private
 
         # @return [Array<String>]

data/lib/datamappify/data/mapper.rb

@@ -78,24 +78,26 @@ module Datamappify
       # @return [Array<Attribute>]
       def default_attributes
         @default_attributes ||= default_attribute_names.collect do |attribute|
-          Attribute.new(attribute, default_source_for(attribute), default_source_class)
+          Attribute.new(attribute, default_source_for(attribute), :primary_source_class => default_source_class)
         end
       end
 
       # @return [Array<Attribute>]
       def custom_attributes
-        @custom_attributes ||= custom_mapping.collect do |attribute, source|
-          map_custom_attribute(attribute, source)
+        @custom_attributes ||= custom_mapping.collect do |attribute, source_and_options|
+          map_custom_attribute(attribute, *source_and_options)
         end
       end
 
       # @param (see Data::Mapper::Attribute#initialize)
       #
       # @return [Attribute]
-      def map_custom_attribute(name, source)
+      def map_custom_attribute(name, source, options)
         @custom_attribute_names << name
 
-        Attribute.new(name, source, default_source_class)
+        options.merge!(:primary_source_class => default_source_class)
+
+        Attribute.new(name, source, options)
       end
 
       # @param attribute [Symbol]

data/lib/datamappify/data/provider/active_record.rb

@@ -24,6 +24,13 @@ module Datamappify
               belongs_to :#{default_source_class.model_name.element}
             CODE
           end
+
+          # @return [void]
+          def build_record_reversed_association(attribute, default_source_class)
+            default_source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
+              belongs_to :#{attribute.source_key}
+            CODE
+          end
         end
       end
     end

data/lib/datamappify/data/provider/sequel.rb

@@ -27,7 +27,14 @@ module Datamappify
             CODE
 
             attribute.source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
-              one_to_one :#{default_source_class.table_name.to_s.singularize}
+              many_to_one :#{default_source_class.table_name.to_s.singularize}
+            CODE
+          end
+
+          # @return [void]
+          def build_record_reversed_association(attribute, default_source_class)
+            default_source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
+              many_to_one :#{attribute.source_key}
             CODE
           end
         end

data/lib/datamappify/data/record.rb

@@ -20,6 +20,10 @@ module Datamappify
         def build_association(attribute, default_source_class)
           Provider.const_get(attribute.provider_name).build_record_association(attribute, default_source_class)
         end
+
+        def build_reversed_association(attribute, default_source_class)
+          Provider.const_get(attribute.provider_name).build_record_reversed_association(attribute, default_source_class)
+        end
       end
     end
   end

data/lib/datamappify/entity/composable/attribute.rb

@@ -0,0 +1,16 @@
+module Datamappify
+  module Entity
+    module Composable
+      class Attribute
+        # @param name [Virtus::Attribute]
+        #
+        # @param prefix [Symbol]
+        #
+        # @return [void]
+        def self.prefix(name, prefix)
+          :"#{prefix}_#{name}"
+        end
+      end
+    end
+  end
+end