datamappify 0.20.1 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aab0e76c26e21e69f4dde9c839a3bd355603a951
-  data.tar.gz: f1d641f0606a824b7d64248da741f564d88e54cf
+  metadata.gz: afcba7b889daac95e25ea353220e7f418082515d
+  data.tar.gz: d0cd4d8e8a01595ffe831c204ad52cccdafef85f
 SHA512:
-  metadata.gz: 72b68c7e226f06476b2f59f52ab0708fdd38d126942c308d7282f72c64b541599943df433d9a1e8d6737d8fadd600874227757c0ab9ef7c9ed76df1f208a64ab
-  data.tar.gz: 09b5962a27a1425601ad067dd5e15426ec92ea7ad04dcc223ae09d23676723ba447c26428de74ca3870318ebe8331678b998fc1a1c52ddb0f844e9ae87883722
+  metadata.gz: d95340abf96122fc88f136f028d31b0bf5b15915bbab6bc72e8a9180202ac8220e723c0b39f55b24b223640231580cbf8ae17636c118b86530bd9c81c0fceb40
+  data.tar.gz: e90bcfb79e7f232bcab801f73326d3088891454aa93db4cf6060590fc2fafc3f5bbf0bb8cd172aa3b017ab8677442db95a369c3d7615852123eded0c98114b72

data/.gitignore

@@ -1,3 +1,5 @@
 Gemfile.lock
 pkg
 coverage
+.yardoc
+doc

data/.yardopts

@@ -0,0 +1 @@
+--protected --private

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## master
 
+## 0.30.0 [2013-04-12]
+
+- __Completely reimplemented Datamappify__
+  - Things are more decoupled and cleaner in general.
+- Leaner `Repository` syntax, i.e. `UserRepository` instead of the more verbose `UserRepository.instance`.
+
 ## 0.20.1 [2013-03-19]
 
 - Fixed the leftover `require 'active_record'` in the code so the gem works without ActiveRecord.
@@ -7,11 +13,11 @@
 ## 0.20.0 [2013-03-19]
 
 - __Completely rewritten Repository__
-  - Repository now handles data construction from different ORM objects
+  - Repository now handles data construction from different ORM objects.
   - ActiveRecord has now been demoted to being a data provider, it is no longer tightly coupled with Repository, this means __we could have multiple data providers__!
-  - Repository is now much more robust
-  - As a result of robustness, it fixed an issue where updating an existing entity with new data records from mapped attributes will not persist the new data records correctly
-  - `#save` and `#destroy` now support accepting an array as their argument
+  - Repository is now much more robust.
+  - As a result of robustness, it fixed an issue where updating an existing entity with new data records from mapped attributes will not persist the new data records correctly.
+  - `#save` and `#destroy` now support accepting an array as their argument.
   - Added support for Sequel!
   - Added support for mapping entity attributes to different ORMs!
 

data/README.md

@@ -1,34 +1,31 @@
 # 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)
 
-Separate domain logic from data persistence, based on the [Repository Pattern](http://martinfowler.com/eaaCatalog/repository.html).
-
-Datamappify is NOT associated with the [Datamapper](https://github.com/datamapper/) project.
-
 __Datamappify is current in Proof-of-Concept stage, do NOT use it for anything other than experimentation.__
 
 ## Overview
 
-Datamappify is a thin layer on top of [Virtus](https://github.com/solnic/virtus) and existing ORMs (ActiveRecord, etc). The design goal is to utilise the powerfulness of existing ORMs but separate domain logic (behaviour) from data persistence.
+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).
+
+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 consists of three components:
 
-- __Entity__ is your model, it is responsible for mainly storing behaviour.
-- __Data__ as the name suggests, holds your model data. It is an ActiveRecord object.
+- __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.
 
-## Installation
+Note: Datamappify is NOT affiliated with the [Datamapper](https://github.com/datamapper/) project.
 
-Add this line to your application's Gemfile:
+### Supported ORMs for Persistence
 
-    gem 'datamappify'
-
-And then execute:
+- ActiveRecord
+- Sequel
 
-    $ bundle
+## Installation
 
-Or install it yourself as:
+Add this line to your application's Gemfile:
 
-    $ gem install datamappify
+    gem 'datamappify'
 
 ## Usage
 
@@ -91,8 +88,8 @@ end
 Pass in an id or an array of ids.
 
 ```ruby
-user  = UserRepository.instance.find(1)
-users = UserRepository.instance.find([1, 2, 3])
+user  = UserRepository.find(1)
+users = UserRepository.find([1, 2, 3])
 ```
 
 #### Saving/updating entities
@@ -102,8 +99,8 @@ Pass in an entity or an array of entities.
 There is also `save!` that raises `Datamappify::Data::EntityNotSaved`.
 
 ```ruby
-UserRepository.instance.save(user)
-UserRepository.instance.save([user, user2, user3])
+UserRepository.save(user)
+UserRepository.save([user, user2, user3])
 ```
 
 #### Destroying an entity
@@ -115,28 +112,24 @@ 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.instance.destroy(1)
-UserRepository.instance.destroy([1, 2, 3])
-UserRepository.instance.destroy(user)
-UserRepository.instance.destroy([user, user2, user3])
+UserRepository.destroy(1)
+UserRepository.destroy([1, 2, 3])
+UserRepository.destroy(user)
+UserRepository.destroy([user, user2, user3])
 ```
 
-## Supported ORMs
-
-- ActiveRecord
-- Sequel
-
 ## Changelog
 
 Refer to [CHANGELOG](CHANGELOG.md).
 
 ## Todo
 
-- Enforce attribute type casting.
+- Track dirty entity attributes.
+- Attribute lazy-loading.
 - Hooks for persistence (`before_save` and `after_save`, etc).
-- Track dirty entity attributes to avoid unnecessary DB queries.
+- [Authoritative source](http://msdn.microsoft.com/en-au/library/ff649505.aspx).
+- Enforce attribute type casting.
 - Support for configurable primary keys and foreign keys.
-- Entity should dictate Data, so schema and migrations should be automatically generated.
 
 ## Similar Projects
 
@@ -144,9 +137,11 @@ Refer to [CHANGELOG](CHANGELOG.md).
 - [Edr](https://github.com/nulogy/edr)
 - [Minimapper](https://github.com/joakimk/minimapper)
 
-## Author
+## Credits
 
-[Fred Wu](http://fredwu.me/)
+- [Fred Wu](http://fredwu.me/) - author.
+- [James Ladd](http://jamesladdcode.com/) for reviewing the code and giving advice on architectural decisions.
+- [Locomote](http://www.locomote.com.au/) - where Datamappify is built and being tested in product development.
 
 ## License
 

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{Separate domain logic from data persistence.}
+  spec.description   = %q{Compose and manage domain logic and data persistence separately and intelligently.}
   spec.summary       = spec.description
   spec.homepage      = "https://github.com/fredwu/datamappify"
   spec.license       = "MIT"
@@ -23,6 +23,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "yard"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "simplecov"

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

@@ -0,0 +1,12 @@
+require 'datamappify/data/criteria/relational/count'
+
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class Count < Relational::Count
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class Destroy < Common
+          def initialize(source_class, id)
+            super(source_class, nil, id)
+          end
+
+          def result
+            source_class.destroy(criteria)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class Exists < Common
+          def result
+            source_class.exists?(entity.id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+require 'datamappify/data/criteria/relational/find'
+
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class Find < Relational::Find
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+require 'datamappify/data/criteria/relational/find_by_key'
+
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class FindByKey < Relational::FindByKey
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+require 'datamappify/data/criteria/relational/save'
+
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class Save < Relational::Save
+          private
+
+          def save_record
+            record = source_class.where(criteria).first_or_initialize
+            save(record)
+          end
+
+          def save(record)
+            record.update_attributes attributes_and_values
+            record
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+require 'datamappify/data/criteria/relational/save_by_key'
+require 'datamappify/data/criteria/active_record/save'
+
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class SaveByKey < Save
+          include Relational::SaveByKey
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Datamappify
+  module Data
+    module Criteria
+      module ActiveRecord
+        class Transaction < Common
+          def result
+            source_class.transaction(&@block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+module Datamappify
+  module Data
+    module Criteria
+      # Provides a set of useful methods for common criteria tasks,
+      # all +Criteria+ objects inherit from +Common+
+      class Common
+        # @return [Class]
+        attr_reader :source_class
+
+        # @return [Entity]
+        attr_reader :entity
+
+        # @return [void]
+        attr_reader :criteria
+
+        # @return [Set]
+        attr_reader :attributes
+
+        # @param source_class [Class]
+        #
+        # @param args [any]
+        #
+        # @yield
+        #   an optional block
+        def initialize(source_class, *args, &block)
+          @source_class = source_class
+          @entity, @criteria, @attributes = *args
+          @block = block
+        end
+
+        protected
+
+        # Key name of either the primary key (e.g. +id+) or foreign key (e.g. +user_id+)
+        #
+        # @return [Symbol]
+        def key_name
+          primary_record? ? :id : "#{entity.class.name.demodulize.underscore}_id".to_sym
+        end
+
+        # The value of {#key_name}
+        #
+        # @return [void]
+        def key_value
+          criteria.with_indifferent_access[key_name]
+        end
+
+        # Determines whether or not it's going to be a new record by looking at the {#key_value}
+        #
+        # @return [Boolean]
+        def new_record?
+          key_value.nil?
+        end
+
+        # Determines whether or not it's a primary record by comparing the source class and the entity class
+        #
+        # @return [Boolean]
+        def primary_record?
+          source_class.name.demodulize == entity.class.name.demodulize
+        end
+
+        # Ignores the current Criteria's operation if there is no dirty attributes
+        #
+        # @return [Boolean]
+        def ignore?
+          attributes_and_values.empty?
+        end
+
+        # Attributes with their corresponding values
+        #
+        # @return [Hash]
+        def attributes_and_values
+          hash = {}
+
+          attributes.each do |attribute|
+            unless ignore_attribute?(attribute)
+              hash[attribute.source_attribute_name] = entity.send(attribute.name)
+            end
+          end
+
+          hash
+        end
+
+        private
+
+        # Ignores the attribute if it isn't dirty or if it's a primary key
+        #
+        # @todo implement proper dirty attribute tracking
+        #
+        # @return [Boolean]
+        def ignore_attribute?(attribute)
+          entity.send(attribute.name).nil? || attribute.primary_key?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Relational
+        class Count < Common
+          def result
+            source_class.count
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Relational
+        class Find < Common
+          def result
+            record = source_class.where(criteria).first
+
+            update_entity_with(record) if record
+          end
+
+          private
+
+          def update_entity_with(record)
+            attributes.each do |attribute|
+              entity.send("#{attribute.name}=", record.send(attribute.source_attribute_name))
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+require 'datamappify/data/criteria/relational/find'
+
+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)
+
+            @criteria = { key_name => entity.id }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Relational
+        class Save < Common
+          def result
+            new_record? ? create_record : save_record unless ignore?
+          end
+
+          private
+
+          def create_record
+            record = source_class.new(criteria)
+            saved_record = save(record)
+
+            update_entity_with(saved_record) if primary_record?
+          end
+
+          def update_entity_with(record)
+            entity.id = record.send(key_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Relational
+        module SaveByKey
+          def initialize(source_class, entity, attributes, &block)
+            super(source_class, entity, {}, attributes, &block)
+
+            @criteria = { key_name => entity.id } unless entity.id.nil?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+require 'datamappify/data/criteria/relational/count'
+
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class Count < Relational::Count
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class Destroy < Common
+          def initialize(source_class, id)
+            super(source_class, nil, id)
+          end
+
+          def result
+            source_class.where(:id => criteria).destroy
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class Exists < Common
+          def result
+            source_class.where(:id => entity.id).any?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+require 'datamappify/data/criteria/relational/find'
+
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class Find < Relational::Find
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+require 'datamappify/data/criteria/relational/find_by_key'
+
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class FindByKey < Relational::FindByKey
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+require 'datamappify/data/criteria/relational/save'
+
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class Save < Relational::Save
+          private
+
+          def save_record
+            record = source_class.find(criteria) || source_class.new(criteria)
+            save(record)
+          end
+
+          def save(record)
+            record.update attributes_and_values
+            record
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+require 'datamappify/data/criteria/relational/save_by_key'
+require 'datamappify/data/criteria/sequel/save'
+
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class SaveByKey < Save
+          include Relational::SaveByKey
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Datamappify
+  module Data
+    module Criteria
+      module Sequel
+        class Transaction < Common
+          def result
+            source_class.db.transaction(&@block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datamappify/data/criteria.rb

@@ -0,0 +1,8 @@
+require 'datamappify/data/criteria/common'
+
+module Datamappify
+  module Data
+    module Criteria
+    end
+  end
+end

data/lib/datamappify/data/errors.rb

@@ -7,6 +7,7 @@ module Datamappify
     end
 
     class EntityInvalid < Error
+      # @param entity [Entity]
       def initialize(entity)
         super entity.errors.full_messages.join(', ')
       end