vorpal 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NjI3OWU1NDlmYjJjZjAyOTZkZmU5NThmZjJjMDI4NzVlNGE1MjFjZA==
+    OGY3ZWI5YTQ3OWEyNDJlYjFkNmQwOTlkNWQyMmUyMzc1YmJhOTY1Yg==
   data.tar.gz: !binary |-
-    ZGJlYjljY2ViYTk0MzdhMWYxZjEyMWU5NmZjMGUxMzU2YTI3MzRmMw==
+    MGI1ZmVhOWMyNTQ3NWY0MTdjOThlOGQ0NzAyNDNkNTg0OTVkMTNkYQ==
 SHA512:
   metadata.gz: !binary |-
-    ZDAzMmU1MmVlNzYwYTlmNTk0NGIxMGExZTgwMDIwN2I5YzQ4NTNiNTQ5ZGRi
-    ZjRiYjhjNDJiM2RmN2I4MGRiMzY3NTNiOTE0ZGUwMzhjZGE5ZWE1Y2EyZTk2
-    Y2JmMmY3YzUyZDZkODYxYzVlMzhkNTg3ZThiMDIzY2ZlNzNhYzU=
+    ZWI5MWU2ZGY4YWM1OWZkNjk2M2UzYWE5MzgyOTlhNzFjYjYyYzgyYTczNGUz
+    NWEzMTExYmVlOTI3YmM4YjAxZTc1NGM4MDM1YTE4MzgwNTVkN2RhYWIxNWZm
+    ZGZhOGM0OGFlMTMxYjlhNzgzOWEzOTkyNjhjOWY4ZDhhYTMyZTg=
   data.tar.gz: !binary |-
-    ZTZhZWExODIxYWQzNTlkNDJkMzg0OWI4NWVlOTMxYzZlNzk1ZTQzZmZlYjEz
-    NGRhM2Q1MjIxYjQ4N2M5NWRiMjc4YmNmMjQ5MWNiYTEwZWU3NGYwYjhjNzkx
-    OTc0YzFiODY3NWNkZTMyOWJiODVhYzQyZGJkYjRlYzAwMGFiMjk=
+    ZDE2YjJkNjk1Mzk0NDlmNmVlYjU4YmUzZTA4MjMyZWY0MDhkYTYzNWExMjI3
+    YmFkMzMxM2ExODEzNzVlMDYyZjZjNzRhZTFlM2IxNWQwNTI0MWIzNjU3MjUy
+    MjQwOGRkYzU4Nzc0ZjY3NGYwODcxNDhlZDNjMWUxM2RjZmE1YWE=

data/.gitignore

@@ -13,3 +13,4 @@
 *.o
 *.a
 mkmf.log
+/projectFilesBackup

data/README.md

@@ -1,21 +1,29 @@
 # Vorpal
 
-Separate your domain model from your delivery mechanism.
+Separate your domain model from your persistence mechanism. Some problems call for a really sharp tool.
+
+
+> One, two! One, two! and through and through
+
+> The vorpal blade went snicker-snack!
+
+> He left it dead, and with its head
+
+> He went galumphing back.
+
 
 ## Overview
-Vorpal is a [Data Mapper](http://martinfowler.com/eaaCatalog/dataMapper.html)-style ORM (object relational mapper) framelet that persists POROs (plain old Ruby objects) to a relational DB.
+Vorpal is a [Data Mapper](http://martinfowler.com/eaaCatalog/dataMapper.html)-style ORM (object relational mapper) framelet that persists POROs (plain old Ruby objects) to a relational DB. It has been heavily influenced by concepts from [Domain Driven Design](http://www.infoq.com/minibooks/domain-driven-design-quickly).
 
-We say 'framelet' because it doesn't attempt to give you all the goodies that ORMs usually provide. Instead, it layers on top of an existing ORM and allows you to use the simplicity of the Active Record pattern where appropriate and the power of the Data Mapper pattern when you need it.
+We say 'framelet' because it doesn't attempt to give you all the goodies that ORMs usually provide. Instead, it layers on top of an existing ORM and allows you to take advantage of the ease of the [Active Record](http://www.martinfowler.com/eaaCatalog/activeRecord.html) pattern where appropriate and the power of the [Data Mapper](http://martinfowler.com/eaaCatalog/dataMapper.html) pattern when you need it.
 
-3 things set it apart from existing Ruby ORMs (ActiveRecord and Datamapper):
+3 things set it apart from existing main-stream Ruby ORMs ([ActiveRecord](http://api.rubyonrails.org/files/activerecord/README_rdoc.html), [Datamapper](http://datamapper.org/), and [Sequel](http://sequel.jeremyevans.net/)):
 
 1. It keeps persistence concerns separate from domain logic. In other words, your domain models don't have to extend ActiveRecord::Base (or something else) in order to get saved to a DB.
 1. It works with [Aggregates](http://martinfowler.com/bliki/DDD_Aggregate.html) rather than individual objects.
 1. It plays nicely with ActiveRecord objects!
 
-[Perpetuity](https://github.com/jgaskins/perpetuity) has a great introduction.
-
-Talk about EDR? Victor has a good explanation of why domain model and delivery mechanism should be separated.
+This last point is incredibly important because applications that grow organically can get very far without needing to separate persistence and domain logic. But when they do, Vorpal will play nicely with all that legacy code.
 
 ## Installation
 
@@ -34,25 +42,24 @@ Or install it yourself as:
     $ gem install vorpal
 
 ## Usage
-Start with a domain model of POROs that form an aggregate:
+
+**Warning! API still in flux! Expect it to change with every release until 0.1.0. After this point, semantic versioning will be used.**
+
+Start with a domain model of POROs and AR::Base objects that form an aggregate:
 
 ```ruby
 class Tree; end
 
-class Trunk
+class Branch
   include Virtus.model
 
   attribute :id, Integer
   attribute :length, Decimal
+  attribute :diameter, Decimal
   attribute :tree, Tree
 end
 
-class Branch
-  include Virtus.model
-
-  attribute :id, Integer
-  attribute :length, Decimal
-  attribute :tree, Tree
+class Gardener < ActiveRecord::Base
 end
 
 class Tree
@@ -60,103 +67,167 @@ class Tree
 
   attribute :id, Integer
   attribute :name, String
-  attribute :trunk, Trunk
+  attribute :gardener, Gardener
   attribute :branches, Array[Branch]
 end
 ```
 
-Along with a relational model:
+In this aggregate, the Tree is the root and the Branches are inside the aggregate boundary. The Gardener is not technically part of the aggregate but is required for the aggregate to make sense so we say that it is on the aggregate boundary.
+
+POROs must have setters and getters for all fields and associations that are to be persisted. They must also provide a no argument constructor.
+
+Along with a relational model (in PostgreSQL):
 
 ```sql
 CREATE TABLE trees
 (
   id serial NOT NULL,
   name text,
-  trunk_id integer
-)
+  gardener_id integer
+);
 
-CREATE TABLE trunks
+CREATE TABLE gardeners
 (
   id serial NOT NULL,
-  length numeric
-)
+  name text
+);
 
 CREATE TABLE branches
 (
   id serial NOT NULL,
   length numeric,
+  diameter numeric,
   tree_id integer
-)
+);
 ```
 
 Create a repository configured to persist the aggregate to the relational model:
 
 ```ruby
-repository = Persistence::Configuration.define do
-  map Tree do
-    fields :name
-    belongs_to :trunk
-    has_many :branches
-  end
+require 'vorpal'
 
-  map Trunk do
-    fields :length
-    has_one :tree
+module TreeRepository
+  extend self
+  
+  @repository = Vorpal.define do
+    map Tree do
+      fields :name
+      belongs_to :gardener, owned: false
+      has_many :branches
+    end
+
+    map Gardener
+  
+    map Branch do
+      fields :length, :diameter
+      belongs_to :tree
+    end
+  end
+  
+  def find(id)
+    @repository.load(id, Tree)
+  end
+  
+  def save(tree)
+    @repository.persist(tree)
+  end
+  
+  def destroy(tree)
+    @repository.destroy(tree)
   end
   
-  map Branch do
-    fields :length
-    belongs_to :tree
+  class ARTree < ActiveRecord::Base
+    self.table_name = 'trees'
+  end
+  
+  class ARBranch < ActiveRecord::Base
+    self.table_name = 'branches'
   end
 end
 ```
-Why don't we use DDD language? I see no mention of aggregates and entities!
+
+Here we've used the `owned` flag on the `belongs_to` from the Tree to the Gardener to show that the Gardener is on the aggregate boundary.
 
 And use it:
 
 ```ruby
-repository.persist(big_tree)
+# Saves/updates the given Tree as well as all Branches referenced by it,
+# but not Gardeners.
+TreeRepository.save(big_tree)
 
-small_tree = repository.load(small_tree_id, Tree)
+# Loads the given Tree as well as all Branches and Gardeners 
+# referenced by it.
+small_tree = TreeRepository.find(small_tree_id)
 
-repository.destroy(dead_tree)
+# Destroys the given Tree as well as all Branches referenced by it,
+# but not Gardeners.
+TreeRepository.destroy(dead_tree)
 ```
 
-Show implementation of a repository using the aggregate repository!!!
-
-Talk about aggregate boundary.
-
-### With ActiveRecord
-TBD
-
 ## API Documentation
 
-(http://rubydoc.info/github/nulogy/vorpal/master/frames)
+http://rubydoc.info/github/nulogy/vorpal/master/frames
 
 ## Caveats
 It also does not do some things that you might expect from other ORMs:
 
-1. There is no lazy loading of associations. This might sound like a big deal, but with [correctly designed aggregates](http://dddcommunity.org/library/vernon_2011/) it turns out to be very minor.
-1. There is no managing of transactions. It is the strong opinion of the authors that managing transactions is an application-level concern.
+1. No lazy loading of associations. This might sound like a big deal, but with [correctly designed aggregates](http://dddcommunity.org/library/vernon_2011/) it turns out not to be.
+1. No managing of transactions. It is the strong opinion of the authors that managing transactions is an application-level concern.
 1. No support for validations. Validations are not a persistence concern.
-1. Only supports primary keys called `id`.
+1. No AR-style callbacks. Use Infrastructure, Application, or Domain [services](http://martinfowler.com/bliki/EvansClassification.html) instead.
+1. No has-many-through associations. Use two has-many associations to a join entity instead.
+1. The `id` field is reserved for database primary keys. If you have a natural key/id on your domain model, name it something that makes sense for your domain. It is the strong opinion of the authors that using natural keys as foreign keys is a bad idea. This mixes domain and persistence concerns.
+
+## Constraints
+1. Persisted entities must have getters and setters for all persisted fields and associations. They do not need to be public.
 1. Only supports PostgreSQL.
-1. Requires domain entities to have a special implementation of `#initialize`.
-1. Has a dependency on ActiveRecord.
-1. No facilities for querying the DB.
-1. Identity map only applies to a single `#load` or `#load_all` call.
-1. Clients cannot specify primary key values.
 
 ## Future Enhancements
 * Aggregate updated_at.
 * Support for other DBMSs.
-* Identity map for an entire application transaction.
+* Support for other ORMs.
 * Value objects.
-* Remove dependency on ActiveRecord (optimistic locking? connection pooling?)
-* Application-generated primary key ids.
+* Remove dependency on ActiveRecord (optimistic locking? updated_at, created_at support? Data type conversions?)
 * More efficient object loading (use fewer queries.)
-* Do not require special `#initialize` method? Provide a hook for an instance factory?
-* Single table inheritance?
+* Different fields names in domain models than in the DB.
+ 
+## FAQ
+
+**Q.** Why do I care about separating my persistence mechanism from my domain models?
+
+**A.** It generally comes back to the [Single Responsibility Principle](http://en.wikipedia.org/wiki/Single_responsibility_principle). Here are some resources for the curious:
+* [Architecture, the Lost Years](https://www.youtube.com/watch?v=WpkDN78P884) - talk by Bob Martin.
+* [Hexagonal Architecture Pattern](http://alistair.cockburn.us/Hexagonal+architecture) - Alistair Cockburn.
+* [Perpetuity](https://github.com/jgaskins/perpetuity) - a Ruby [Data Mapper](http://martinfowler.com/eaaCatalog/dataMapper.html)-style ORM.
+* [EDR](http://victorsavkin.com/post/41016739721/building-rich-domain-models-in-rails-separating) - another [Data Mapper](http://martinfowler.com/eaaCatalog/dataMapper.html)-style ORM framelet by Victor Savkin.
+
+**Q.** How do I do more complicated queries against the DB without direct access to ActiveRecord?
+
+**A.** Create a method on a [Repository](http://martinfowler.com/eaaCatalog/repository.html)! They have full access to the DB/ORM so you can use [Arel](https://github.com/rails/arel) and go [crazy](http://asciicasts.com/episodes/239-activerecord-relation-walkthrough) or use direct SQL if you want.
+
+**Q.** How do I do validations now that I don't have access to ActiveRecord anymore?
+
+**A.** Depends on what kind of validations you want to do:
+* For validating single attributes on a model: [ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations.html) work very well.
+* For validating whole objects or object compositions (like the state of an Aggregate): Validator objects are preferred. Chapter 5 of [Implementing Domain Driven Design](https://vaughnvernon.co/?page_id=168) contains more guidance.
+
+**Q.** How do I use Rails view helpers like [`form_for`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_for)?
+
+**A.** Check out [ActiveModel::Model](http://api.rubyonrails.org/classes/ActiveModel/Model.html). For more complex use-cases consider using a [Form](http://rhnh.net/2012/12/03/form-objects-in-rails) [Object](https://www.reinteractive.net/posts/158-form-objects-in-rails).
+
+**Q.** How do I get dirty checking?
+
+**A.** Check out [ActiveModel::Dirty](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html).
+
+**Q.** How do I get serialization?
+
+**A.** You can use [ActiveModel::Serialization](http://api.rubyonrails.org/classes/ActiveModel/Serialization.html) or [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers) but they are not heartily recommended. The former is too coupled to the model and the latter is too coupled to Rails controllers. Vorpal includes the [SimpleSerializer](http://rubydoc.info/github/nulogy/vorpal/master/SimpleSerializer) and [SimpleDeserializer](http://rubydoc.info/github/nulogy/vorpal/master/SimpleDeserializer) for this purpose.
+
+## Contributors
+
+* [Sean Kirby](https://github.com/sskirby)
+* [Paul Sobocinski](https://github.com/psobocinski)
+* [Jason Cheong-Kee-You](https://github.com/jchunky)
 
 ## Contributing
 

data/lib/vorpal.rb

@@ -1,5 +1,28 @@
 require "vorpal/version"
+require "vorpal/configuration"
 
+# Allows easy creation of {Vorpal::AggregateRepository}
+# instances.
+#
+# ```ruby
+# repository = Vorpal.define do
+#   map Tree do
+#     fields :name
+#     belongs_to :trunk
+#     has_many :branches
+#   end
+#
+#   map Trunk do
+#     fields :length
+#     has_one :tree
+#   end
+#
+#   map Branch do
+#     fields :length
+#     belongs_to :tree
+#   end
+# end
+# ```
 module Vorpal
-  # Your code goes here...
+  extend Vorpal::Configuration
 end

data/lib/vorpal/aggregate_repository.rb

@@ -61,8 +61,7 @@ class AggregateRepository
   #   aggregates to be loaded.
   # @param domain_class [Class] Type of the roots of the aggregate to be loaded.
   # @return [[Object]] Entities with the given primary key values and type.
-  def load_all(ids, domain_class)
-    identity_map = IdentityMap.new
+  def load_all(ids, domain_class, identity_map=IdentityMap.new)
     ids.map { |id| load(id, domain_class, identity_map) }
   end
 

data/lib/vorpal/configuration.rb

@@ -2,30 +2,8 @@ require 'vorpal/aggregate_repository'
 require 'vorpal/config_builder'
 
 module Vorpal
-# Allows easy creation of {Vorpal::AggregateRepository}
-# instances.
-#
-# ```ruby
-# repository = Vorpal::Configuration.define do
-#   map Tree do
-#     fields :name
-#     belongs_to :trunk
-#     has_many :branches
-#   end
-#
-#   map Trunk do
-#     fields :length
-#     has_one :tree
-#   end
-#
-#   map Branch do
-#     fields :length
-#     belongs_to :tree
-#   end
-# end
-# ```
+
 module Configuration
-  extend self
 
   # Configures and creates a {Vorpal::AggregateRepository} instance.
   #

data/lib/vorpal/version.rb

@@ -1,3 +1,3 @@
 module Vorpal
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/vorpal/aggregate_repository_spec.rb

@@ -1,6 +1,6 @@
 require 'integration_spec_helper'
 
-require 'vorpal/configuration'
+require 'vorpal'
 
 require 'virtus'
 
@@ -596,7 +596,7 @@ describe 'Aggregate Repository' do
 private
 
   def configure_polymorphic_has_many
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Tree do
         fields :name
         has_many :branches
@@ -620,7 +620,7 @@ private
   end
 
   def configure_polymorphic_belongs_to
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Bug do
         fields :name
         belongs_to :lives_on, fk: :lives_on_id, fk_type: :lives_on_type, child_classes: [Trunk, Branch]
@@ -637,7 +637,7 @@ private
   end
 
   def configure_ar_polymorphic_belongs_to
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Tree do
         fields :name
         belongs_to :environment, owned: false, fk: :environment_id, fk_type: :environment_type, child_class: Swamp
@@ -648,7 +648,7 @@ private
   end
 
   def configure_unowned_polymorphic_belongs_to
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Bug do
         fields :name
         belongs_to :lives_on, owned: false, fk: :lives_on_id, fk_type: :lives_on_type, child_classes: [Trunk, Branch]
@@ -665,7 +665,7 @@ private
   end
 
   def configure_unowned
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Tree do
         fields :name
         has_many :branches, owned: false
@@ -683,7 +683,7 @@ private
   end
 
   def configure_recursive
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Branch do
         fields :length
         has_many :branches
@@ -697,7 +697,7 @@ private
   end
 
   def configure_with_cycle
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Branch do
         fields :length
         belongs_to :tree
@@ -711,7 +711,7 @@ private
   end
   
   def configure
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Tree do
         fields :name
         belongs_to :trunk
@@ -732,7 +732,7 @@ private
   end
 
   def configure_has_one
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Trunk do
         fields :length
         has_one :tree
@@ -745,7 +745,7 @@ private
   end
 
   def configure_unowned_has_one
-    Vorpal::Configuration.define do
+    Vorpal.define do
       map Trunk do
         fields :length
         has_one :tree, owned: false

data/spec/vorpal/class_config_builder_spec.rb

@@ -1,10 +1,12 @@
 require 'integration_spec_helper'
 
-describe ConfigBuilder do
+require 'vorpal/config_builder'
+
+describe Vorpal::ConfigBuilder do
   class Tester; end
 
   it 'includes the primary key in the list of fields' do
-    builder = ConfigBuilder.new(Tester, {})
+    builder = Vorpal::ConfigBuilder.new(Tester, {})
     config = builder.build
     # config.field
   end

data/vorpal.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = Vorpal::VERSION
   spec.authors       = ["Sean Kirby"]
   spec.email         = ["seank@nulogy.com"]
-  spec.summary       = %q{Separate your domain model from your delivery mechanism.}
+  spec.summary       = %q{Separate your domain model from your persistence mechanism.}
   spec.description   = %q{An ORM framelet that fits on top of ActiveRecord to give you 'Data Mapper' semantics.}
   spec.homepage      = "https://github.com/nulogy/vorpal"
   spec.license       = "MIT"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vorpal
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Sean Kirby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-28 00:00:00.000000000 Z
+date: 2015-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -142,12 +142,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: Separate your domain model from your delivery mechanism.
+summary: Separate your domain model from your persistence mechanism.
 test_files:
 - spec/integration_spec_helper.rb
 - spec/vorpal/aggregate_repository_spec.rb
 - spec/vorpal/class_config_builder_spec.rb
-has_rdoc: