activeshepherd 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6aedd38764552813b40c075d7215d87b588d37cf
+  data.tar.gz: 53fa8aa99d06d683c778a4b045a9f051e0c47c10
+SHA512:
+  metadata.gz: d2c9ed3ee3217b7d9ebe2c0e153742e1b6f721bab5c929a19b4936809e49d13fbe1bfa6f60111f48a3c3bc883e8d964fda86313ac1006dc8c4d02815113c0c97
+  data.tar.gz: 43dbfc71a82519448d42a9d1abaf8ec1647d804498ff5bc65ff3f61a322d38e8bd70d34284db7537f392336f4e3af8c07c916fe5b4c2b19ab57e64d9ca1fc83e

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+tmp
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in activeshepherd.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,16 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'minitest' do
+  # with Minitest::Unit
+  watch(%r|^test/(.*)\/?(.*)_test\.rb|)
+  watch(%r{^lib/active_shepherd/(.*/)?([^/]+)\.rb$})  { |m| "test/unit/#{m[1]}#{m[2]}_test.rb" }
+  watch(%r{^lib/active_shepherd.rb})  { "test" }
+  watch(%r|^test/test_helper\.rb|)    { "test" }
+
+  watch(%r|^test/integration/project_todo_scenario/(.*)\.rb$|) do 
+    "test/integration/project_todo_scenario_test.rb"
+  end
+
+  watch(%r{^lib/.*\.rb$})  { |m| "test/integration/project_todo_scenario_test.rb" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 ntl
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# WARNING: DANGER AHEAD!
+
+*This repo is titled "eat-my-babies" for a reason. It's essentially scratch code at this point.*
+
+# ActiveShepherd
+
+Is your app/models directory growing unweildy? Do you find yourself desiring the notion of aggregates to help corral your less important models under the umbrella of more important "business entities?" That's the problem I had that led me to write this gem. I wanted to be able to reason about an entire namespace of models as one thing; or an "aggregate" in enterprisey development parlance.
+
+My main goal was to be able to keep using ActiveRecord and intrude on it as little as possible. The result was an approach that requires you to wire up your models a bit more strictly -- you need to be setting options like `dependent: 'destroy'`, `autosave: true`, and `inverse_of` on all associations to the sub objects. The benefit you get from this gem is to be able to both query and manipulate the state of the entire aggregate all at once.
+
+There are more requirements that are outlined by Eric Evans in his brilliant Domain Driven Design book, whose self titled concept is still very new to me.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'activeshepherd'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install activeshepherd
+
+In your `config/initializers` directory, add a tiny shim into ActiveRecord::Base:
+
+    ActiveShepherd.enable!(ActiveRecord::Base)
+
+## Usage
+
+1. Pick a model you'd like to make into an aggregate root
+2. Add `act_as_aggregate_root!` to the model, e.g.:
+     end
+3. Make sure it follows the rules (e.g. [see this blog post](http://lostechies.com/jimmybogard/2008/05/21/entities-value-objects-aggregates-and-roots/))
+4. ??
+5. Profit!
+
+## Examples:
+
+See the test suite for more fleshed out examples. For now, say you have two models:
+
+```ruby
+# app/models/my_model.rb
+class MyModel < ActiveRecord::Base
+  act_as_aggregate_root!
+
+  has_many :bunnies, autosave: true, dependent: :destroy, inverse_of: :my_model,
+    validate: true
+end
+
+# app/models/my_model/bunny.rb
+class MyModel::Bunny < ActiveRecord::Base
+  belongs_to :my_model, inverse_of: :bunnies, touch: true
+end
+```
+<!-- ` -->
+
+Now add a test to make sure your models always meet the requirements for being an aggregate root:
+
+```ruby
+# spec/models/my_model_spec.rb
+describe MyModel do
+  it "is an aggregate root" do
+    MyModel.should be_able_to_act_as_aggregate_root
+  end
+end
+
+# test/unit/my_model_test.rb
+class MyModel::TestCase < Minitest::Unit::TestCase
+  def test_should_be_aggregate_root
+    assert MyModel.able_to_act_as_aggregate_root?
+  end
+end
+```
+<!-- ` -->
+
+You now get some new behavior on MyModel that will let you deal with the entire aggregate nicely:
+
+```ruby
+>> @my_model = MyModel.new
+>> @my_model.bunnies.build({ name: "Roger"})
+>> @my_model.save
+
+# Nothing new, right? wrong.
+
+>> @my_model.aggregate_state
+=> {
+     bunnies: [
+       { name: "Roger" }
+     ]
+   }
+
+# Sweet, what about changes?
+
+>> @my_model.bunnies.first.name = "Roger Rabbit"
+>> @my_model.bunnies.build({ name: "Energizer" })
+
+# BAM!
+
+>> @my_model.aggregate_changes
+=> {
+     bunnies: {
+       0 => { name: ["Roger", "Roger Rabbit"] },
+       1 => { name: [nil, "Energizer"] }
+     }
+  }
+```
+<!-- ` -->
+
+So `#aggregate_changes` is just like ActiveRecord's `#changes`, except it includes all of the nested changes within the aggregate.
+
+That's a brief description of what this gem does. Here are the main methods that `acts_as_aggregate_root!` brings to your ActiveRecord models:
+
+| Method name           | Description                                                                        |
+|:---------------------:|:----------------------------------------------------------------------------------:|
+| `#aggregate_state`    | Serializes the entire state of the aggregate                                       |
+| `#aggregate_state=`   | Takes a serialized blob and uses it to set the entire state of the aggregate       |
+| `#aggregate_changes`  | Analagous to `#changes`; it tells you what all has changes in the entire aggregate |
+| `#aggregate_changes=` | Takes an existing set of changes and applies it to the aggregate                   |
+
+## Todo
+
+This project is way alpha right now, hence the "eat-my-babies" project name.
+
+1. Implement `ClassValidator` which will correctly tell you if a class can be an aggregate root (e.g. are your associations wired up correctly?)
+2. Implement `ChangeValidator` that adds a little more niceness around `#aggregate_changes=`
+
+My main goal right now is to use the code as it exists for a while and deal with problems as they arise. Consider the entire gem incomplete for right now.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,24 @@
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+desc "Update ctags"
+task :ctags do
+  `ctags -R lib test`
+end
+
+desc "Jump into a console with the test environment loaded"
+task :console do
+  $:.push File.expand_path("../test", __FILE__)
+  require "test_helper"
+  require "irb"
+
+  binding.pry
+end
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/**/*_test.rb"
+  t.libs << "test"
+end
+
+task default: "test"

data/activeshepherd.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_shepherd/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "activeshepherd"
+  gem.version       = ActiveShepherd::VERSION
+  gem.authors       = ["ntl"]
+  gem.email         = ["nathanladd+github@gmail.com"]
+  gem.description   = %q{Wrangle unweildy app/models directories by unobtrusively adding the aggregate pattern into ActiveRecord}
+  gem.summary       = %q{Wrangle unweildy app/models directories with aggregates}
+  gem.homepage      = "http://github.com/ntl/activeshepherd"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "activerecord", ">= 2.3.17"
+  gem.add_dependency "activesupport", ">= 2.3.17"
+
+  gem.add_development_dependency "activerecord", "4.0.0.beta1"
+  gem.add_development_dependency "guard"
+  gem.add_development_dependency "guard-minitest"
+  gem.add_development_dependency "hashie"
+  gem.add_development_dependency "minitest-reporters"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "pry-debugger"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rb-fsevent"
+  gem.add_development_dependency "sqlite3"
+end

data/lib/active_shepherd.rb

@@ -0,0 +1,24 @@
+module ActiveShepherd ; end
+
+require 'active_shepherd/active_record_shim'
+require 'active_shepherd/aggregate'
+require 'active_shepherd/aggregate_root'
+require 'active_shepherd/changes_validator'
+require 'active_shepherd/deep_reverse_changes'
+require 'active_shepherd/method'
+require 'active_shepherd/methods/apply_changes'
+require 'active_shepherd/methods/apply_state'
+require 'active_shepherd/methods/query_changes'
+require 'active_shepherd/methods/query_state'
+require 'active_shepherd/traversal'
+require 'active_shepherd/version'
+
+module ActiveShepherd
+  AggregateMismatchError = Class.new(StandardError)
+  BadChangeError         = Class.new(StandardError)
+  InvalidChangesError    = Class.new(StandardError)
+
+  def self.deep_reverse_changes(changes)
+    DeepReverseChanges.new(changes).reverse
+  end
+end

data/lib/active_shepherd/active_record_shim.rb

@@ -0,0 +1,15 @@
+module ActiveShepherd
+  def self.enable!(activerecord_base)
+    class << activerecord_base
+      # FIXME: make this actually check the model to meet the criteria for being
+      # an Aggregate Root
+      def able_to_act_as_aggregate_root?
+        true
+      end
+
+      def act_as_aggregate_root!
+        include ::ActiveShepherd::AggregateRoot
+      end
+    end
+  end
+end

data/lib/active_shepherd/aggregate.rb

@@ -0,0 +1,69 @@
+class ActiveShepherd::Aggregate
+  attr_reader :excluded_attributes
+  attr_reader :model
+
+  def initialize(model, excluded_attributes = [])
+    @model = model
+
+    @excluded_attributes = ["id", "created_at", "updated_at"]
+    @excluded_attributes.concat(Array.wrap(excluded_attributes).map(&:to_s))
+  end
+
+  def default_attributes
+    model.class.new.attributes
+  end
+
+  def raw_attributes
+    model.attributes_before_type_cast
+  end
+
+  def traversable_associations
+    associations.traversable
+  end
+
+  def untraversable_association_names
+    associations.untraversable.keys
+  end
+
+  def serialize_value(attribute_name, value)
+    run_through_serializer(attribute_name, value, :dump)
+  end
+
+  def deserialize_value(attribute_name, value)
+    run_through_serializer(attribute_name, value, :load)
+  end
+
+private
+
+  def associations
+    @associations ||= begin
+      all_associations = model.class.reflect_on_all_associations
+      ostruct = OpenStruct.new untraversable: {}, traversable: {}
+      all_associations.each_with_object(ostruct) do |association_reflection, ostruct|
+        if traverse_association?(association_reflection)
+          key = :traversable
+        else
+          key = :untraversable
+        end
+        ostruct.send(key)[association_reflection.name] = association_reflection
+      end
+    end
+  end
+
+  def run_through_serializer(attribute_name, value, method)
+    serializer = model.class.serialized_attributes[attribute_name.to_s]
+    if serializer
+      serializer.send(method, value)
+    else
+      value
+    end
+  end
+
+  def traverse_association?(association)
+    return false if association.options[:readonly]
+    return false if association.macro == :belongs_to
+
+    true
+  end
+
+end

data/lib/active_shepherd/aggregate_root.rb

@@ -0,0 +1,152 @@
+module ActiveShepherd::AggregateRoot
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # Private: returns the behind the scenes object that does all the work
+  def aggregate
+    @aggregate ||= ActiveShepherd::Aggregate.new(self)
+  end
+  private :aggregate
+  
+  # Public: Given a serializable blob of changes (Hash, Array, and String)
+  # objects, apply those changes to 
+  #
+  # Examples:
+  # 
+  #   @project.aggregate_changes = { name: ["Clean House", "Clean My House"] }
+  #
+  # Returns nothing.
+  # Raises ActiveShepherd::InvalidChangesError if the changes supplied do not
+  #   pass #valid_aggregate_changes? (see below)
+  # Raises ActiveShepherd::BadChangeError if a particular attribute change
+  #   cannot be applied.
+  # Raises an ActiveShepherd::AggregateMismatchError if any objects in the
+  #   aggregate are being asked to change attributes that do not exist.
+  def aggregate_changes=(changes)
+    changes_errors = ActiveShepherd::ChangesValidator.new(self).validate changes
+    unless changes_errors.empty?
+      raise ActiveShepherd::InvalidChangesError, "changes hash is invalid: "\
+        "#{changes_errors.join(', ')}"
+    end
+    # The validation process actually runs the changes internally. This means
+    # we don't have to explicitly invoke # #apply_changes here.
+    # XXX: remove when ChangesValidator does this
+    ActiveShepherd::Methods::ApplyChanges.apply_changes aggregate, changes
+  end
+
+  # Public: Reverses the effect of #aggregate_changes=
+  def reverse_aggregate_changes=(changes)
+    self.aggregate_changes = ActiveShepherd::DeepReverseChanges.new(changes).reverse
+  end
+
+  # Public: Returns the list of changes to the aggregate that would persist if
+  # #save were called on the aggregate root.
+  #
+  # Examples
+  #
+  #   @project.aggregate_changes
+  #   # => { name: ["Clean House", "Clean My House"], todos: [{ text: ["Take out trash", "Take out the trash" ...
+  #
+  # Returns all changes in the aggregate
+  def aggregate_changes
+    ActiveShepherd::Methods::QueryChanges.query_changes aggregate
+  end
+
+  # Public: Injects the entire state of the aggregate from a serializable blob.
+  #
+  # Examples:
+  # 
+  #   @project.aggregate_state = { name: "Clean House", todos: [{ text: "Take out trash" ...
+  #
+  # Returns nothing.
+  # Raises an AggregateMismatchError if the blob contains references to objects
+  #   or attributes that do not exist in this aggregate.
+  def aggregate_state=(blob)
+    ActiveShepherd::Methods::ApplyState.apply_state aggregate, blob
+  end
+
+  # Public: Returns the entire state of the aggregate as a serializable blob.
+  # All id values (primary keys) are extracted.
+  #
+  # Examples
+  # 
+  #   @project.aggregate_state
+  #   # => { name: "Clean House", todos: [{ text: "Take out trash" ...
+  #
+  # Returns serializable blob.
+  def aggregate_state
+    ActiveShepherd::Methods::QueryState.query_state aggregate
+  end
+
+  # Public: Reloads the entire aggregate by invoking #reload on each of the
+  # records in the aggregate.
+  def reload_aggregate
+    reload
+    raise "NYI"
+  end
+
+  # Public: Validates a set of changes for the aggregate root.
+  #
+  #  * Does deep_reverse(deep_reverse(changes)) == changes?
+  #  * Assuming the model is currently valid, if the changes were applied,
+  #    would the aggregate be valid?
+  #  * If I apply the changes, and then apply deep_reverse(changes), does
+  #    #aggregate_state change?
+  #
+  # See ActiveShepherd.deep_reverse
+  #
+  # Examples:
+  # 
+  #   @project.valid_aggregate_changes?(@project.aggregate_changes)
+  #   # => true
+  #
+  # Returns true if and only if the supplied changes pass muster.
+  def valid_aggregate_changes?(changes, emit_boolean = true)
+    validator = ActiveShepherd::ChangesValidator.new(self)
+    errors = validator.validate changes
+    emit_boolean ? errors.blank? : errors
+  ensure
+    reload_aggregate
+  end
+
+  module ClassMethods
+    # Public: Determines whether or not the including class can behave like an
+    # aggregate. Designed to be used by tests that want to make sure that any
+    # of the models that make up the aggregate never change in a way that would
+    # break the functionality of Aggregate::Root.
+    #
+    # In order for this method to return true, this model and its associated 
+    # models are each checked rigorously to ensure they are wired up in a way
+    # that meets the requirements of ActiveShepherd. These requirements are:
+    #
+    #  * All models in the namespace defined by the root itself are visible to
+    #    associations that meet this criteria:
+    #    * The root model autosaves all associated models in the aggregate.
+    #      (:autosave is true on the association)
+    #    * The root model validates all associated models in the aggregate.
+    #      (:validate is true on the association)
+    #    * Associated objects touch the root model when they are updated
+    #      (:touch is true on the association)
+    #    * When any root model is destroyed, all associated models in the
+    #      aggregate boundary are also destroyed, or else their references are
+    #      nullified. (:dependent => :destroy/:nullify)
+    #    * The entire object constellation within the boundary can be traversed
+    #      without accessing the persistence layer, providing they have all been
+    #      eager loaded. (:inverse_of is set on the associations)
+    #    * If the association references any external aggregate root, then
+    #      when that root is deleted, then either the associations reference
+    #      must be nullified, or else the associated model itself must be
+    #      deleted.
+    #  * All models within the aggregate are only referenced inside this
+    #    aggregate boundary, with the exception of the root itself.
+    #  * Any model in the namespace of the root that has its own sub namespace
+    #    under it is recursively checked.
+    #
+    # Returns true if and only if this model is an aggregate root.
+    def behave_like_an_aggregate?(emit_boolean = true)
+      errors = ActiveShepherd::ClassValidator.new(self).validate
+      emit_boolean ? errors.blank? : errors
+    end
+  end
+end