event_sourced_record 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 572708800666a6ac438befd0004e290e42cde341
-  data.tar.gz: bd813aa2a7f22f68fd9578c4793725c8e990a57f
+  metadata.gz: 5b7ec38af25ac7107acc8351ccbc38b7a7844296
+  data.tar.gz: c55c45d7a1ed2e00a85b23da21451eba99854cb8
 SHA512:
-  metadata.gz: c7dd4787019fa7924f435bf9e62515a77ee3df7f201a13763868296fea317ace10f1bdcc4fe660b49eeaf7254358d6017f5725d76e05bde3cdffa61c34236e02
-  data.tar.gz: 6271f822d88dd64ebc65d0c22800596a5674393354b0110b0e64b17c598f7329c19673dddf6ab1171954ed80b1d95d43667eef85135dfdb9bc37278ad635273c
+  metadata.gz: c289c63573fce64a567ff6acb8283d810f0ad141bd7b28044457ffb34cce09fba2483fceebda9450c951459b3bdd5050630d16e8313c6824c88ca6b06a9896fb
+  data.tar.gz: c647debe68752c5146dce9f11427477b1233715ef47a6e286fb3757b99907bd6de14b1394a5acefaa35233d78e5a5e4dd248398de351816243e0ce0ac7c5f51f

data/Getting_Started.md

@@ -45,7 +45,10 @@ This takes the same attribute list as `rails generate model`, but generates a nu
 This is the model that you'd create in a typical Rails application, but here you'll find that we don't do much with it directly.
 
     class Subscription < ActiveRecord::Base
-      has_many :subscription_events
+      has_many :events, 
+        class_name: 'SubscriptionEvent', 
+        foreign_key: 'subscription_uuid', 
+        primary_key: 'uuid'
 
       validates :uuid, uniqueness: true
     end
@@ -63,6 +66,9 @@ You might never end up showing this model to end-users, but in fact it's the aut
     class SubscriptionEvent < ActiveRecord::Base
       include EventSourcedRecord::Event
 
+      belongs_to :subscription, 
+        foreign_key: 'subscription_uuid', primary_key: 'uuid'
+
       event_type :creation do
         # attributes :user_id
         #
@@ -99,6 +105,20 @@ The generator registers this observer in `config/application.rb`:
 
     config.active_record.observers = :subscription_event_observer
 
+### A Subscription rake file
+
+The Rake file gives you a convenient command to rebuild every
+`Subscription` whenever necessary.  Since you'll be building
+`SubscriptionCalculator` to be idempotent, this will be a fairly safe operation.
+
+    namespace :subscription do
+      task :recalculate => :environment do
+        Subscription.all.each do |subscription| 
+          SubscriptionCalculator.new(subscription).run.save!
+        end
+      end
+    end
+
 ## Creation
 
 The generated code starts you out with a `creation` event, but we'll want to define it to get some use out of it.
@@ -107,18 +127,14 @@ Above, we specified that subscriptions will have `user_id`, `bottles_per_shipmen
 
 ### Define the creation event type
 
-Fill out the `event_type` block in `subscription_event.rb`:
+Fill out the `event_type` block in `SubscriptionEvent`:
 
-    class SubscriptionEvent < ActiveRecord::Base
-      include EventSourcedRecord::Event
-
-      event_type :creation do
-        attributes :bottles_per_shipment, :bottles_purchased, :user_id
+    event_type :creation do
+      attributes :bottles_per_shipment, :bottles_purchased, :user_id
 
-        validates :bottles_per_shipment, presence: true, numericality: true
-        validates :bottles_purchased, presence: true, numericality: true
-        validates :user_id, presence: true
-      end
+      validates :bottles_per_shipment, presence: true, numericality: true
+      validates :bottles_purchased, presence: true, numericality: true
+      validates :user_id, presence: true
     end
     
 This lets you build and save events with the attributes `bottles_per_shipment`,
@@ -134,21 +150,17 @@ This lets you build and save events with the attributes `bottles_per_shipment`,
 
 ### Handle the creation in the calculator
 
-Fill out the `advance_creation` method in `subscription_calculator.rb`:
-
-    class SubscriptionCalculator < EventSourcedRecord::Calculator
-      events :subscription_events
+Fill out the `advance_creation` method in `SubscriptionCalculator`:
 
-      def advance_creation(event)
-        @subscription.user_id = event.user_id
-        @subscription.bottles_per_shipment = event.bottles_per_shipment
-        @subscription.bottles_left = event.bottles_purchased
-      end
+    def advance_creation(event)
+      @subscription.user_id = event.user_id
+      @subscription.bottles_per_shipment = event.bottles_per_shipment
+      @subscription.bottles_left = event.bottles_purchased
     end
     
 Note that for `user_id` and `bottles_per_shipment` we simply copy the field from the event to the subscription, but in the case of `bottles_purchased`, that is translated to `Subscription#bottles_left`.  This field will go up and down over time.
 
-### Create a subscription (indirectly)
+### Create a subscription, indirectly
 
 Creating a subscription is a matter of creating the event itself:
 
@@ -178,26 +190,22 @@ This is a lot of indirection, which you don't have to understand right away.  Wh
 
 Occasionally, subscribers will want to change their settings.  Let's say in this case we'll only allow them to change `bottles_per_shipment`.  So we add a new event type in `SubscriptionEvent`:
 
-    class SubscriptionEvent < ActiveRecord::Base
-      event_type :change_settings do
-        attributes :bottles_per_shipment
+    event_type :change_settings do
+      attributes :bottles_per_shipment
 
-        validates :bottles_per_shipment, numericality: true
-      end
+      validates :bottles_per_shipment, numericality: true
     end
     
-And we add a method to handle this new event type in the calculator:
+And we add a method to handle this new event type to `SubscriptionCalculator`:
 
-    class SubscriptionCalculator < EventSourcedRecord::Calculator
-      def advance_change_settings(event)
-        @subscription.bottles_per_shipment = event.bottles_per_shipment
-      end
+    def advance_change_settings(event)
+      @subscription.bottles_per_shipment = event.bottles_per_shipment
     end
 
 If we want to change the subscription from the last example from 1 bottle per shipment to 2 bottles per shipment, this looks like this:
 
     subscription.bottles_per_shipment # 1
-    SubscriptionEvent.change_settings.create!(
+    subscription.events.change_settings.create!(
       subscription_uuid: subscription.uuid, bottles_per_shipment: 2
     )
     subscription.reload
@@ -217,6 +225,8 @@ In `subscription_calculator.rb` we make two changes.  First, we add `:shipments`
 
     class SubscriptionCalculator < EventSourcedRecord::Calculator
       events :subscription_events, :shipments
+      
+      # Other methods omitted
 
       def advance_shipment(shipment)
         @subscription.bottles_left -= shipment.num_bottles
@@ -252,25 +262,22 @@ Because `Subscription` is just a cache, event sourcing gives us a consistent way
 1. Write a migration if needed to add or change fields on the `subscriptions` table.
 1. Modify `SubscriptionCalculator` to take the new fields into account.
 1. Test, merge, and deploy to production.
-1. Rebuild every `Subscription`, with code such as:
-
-
-    Subscription.all.each do |subscription|
-      SubscriptionCalculator.new(subscription).run.save!
-    end
+1. Rebuild every `Subscription` by running `rake
+   subscription:recalculate`.
     
 Because you have designed `SubscriptionCalculator` to be idempotent, it is safe to re-run at any time you want -- for example, if you want to fill in a database column that didn't exist before.
 
 ## Debugging Subscription in production
 
-The same process can work for fixing many bugs in production. Events themselves are usually a simple act of recording the user's intention.  Errors usually emerge in `SubscriptionCalculator`, which is responsible for the tougher work of interpreting a sequence of events.
+The same process can work for fixing many bugs in production. Events themselves are usually a simple act of recording the user's intention.  Errors usually emerge in the calculator, which is responsible for the tougher work of interpreting a sequence of events.
 
 So when you find a bug, you can often fix it via this process:
 
 1. Write a test to reproduce the bug.
 1. Fix `SubscriptionCalculator` to fix the bug.
 1. Merge and deploy to production.
-1. Rebuild every `Subscription` with the code above.
+1. Rebuild every `Subscription` by running `rake
+   subscription:recalculate`.
 
 Remember, `SubscriptionCalculator` is idempotent, so this process will fix all the records affected by the bug will leaving the others unchanged.  It will also spare you the agonizing effort of picking through data in `rails console` to guess which records are broken. Why go to the trouble?  Just re-run the whole thing and move on.
 
@@ -282,3 +289,4 @@ Because `SubscriptionCalculator` rebuilds a record in sequence, it's a piece of
     sub_at_end_of_year = calculator.run(last_event_time: Date.new(2014,12,31))
     
 Note that the returned instance is un-saved, and shouldn't be saved to `subscriptions`, but it's now a piece of cake to take those values and send them to whatever reporting system you have in place.
+

data/README.md

@@ -38,7 +38,9 @@ Generate the required classes with `rails generate event_sourced_record`:
           user_id:integer bottles_per_shipment:integer \
           bottles_left:integer
 
-The argument list is the same as with `rails generate model`.  This will generate the event model, the projection, the calculator, and the observer.
+The argument list is the same as with `rails generate model`.  This will
+generate the event model, the projection, the calculator, the observer,
+and a Rake file.
 
 ### Event model
 
@@ -47,6 +49,9 @@ The event model is an ActiveRecord model but it can act significantly different
     class SubscriptionEvent < ActiveRecord::Base
       include EventSourcedRecord::Event
 
+      belongs_to :subscription, 
+        foreign_key: 'subscription_uuid', primary_key: 'uuid'
+
       event_type :creation do
         attributes :bottles_per_shipment, :bottles_purchased, :user_id
 
@@ -73,7 +78,10 @@ The easiest way to create these records is with the scopes that are automaticall
 The projection is the ActiveRecord model that is generated deterministically with the data in the timestamped events combined with the logic in the calculator.  Projections shouldn't have any code for modifying themselves, as that will be done externally.  Accordingly, projections end up being fairly small classes:
 
     class Subscription < ActiveRecord::Base
-      has_many :subscription_events
+      has_many :events, 
+        class_name: 'SubscriptionEvent', 
+        foreign_key: 'subscription_uuid', 
+        primary_key: 'uuid'
 
       validates :uuid, uniqueness: true
     end
@@ -125,6 +133,20 @@ If you use other models as events, simply add them to the `observe` method:
     class SubscriptionEventObserver < ActiveRecord::Observer
       observe :subscription_event, :shipment
 
+## Rake file
+
+The Rake file gives you a convenient command to rebuild every
+projection whenever necessary.  Since you'll be building the calculator
+to be idempotent, this will be a fairly safe operation.
+
+    namespace :subscription do
+      task :recalculate => :environment do
+        Subscription.all.each do |subscription| 
+          SubscriptionCalculator.new(subscription).run.save!
+        end
+      end
+    end
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/event_sourced_record/fork )

data/lib/event_sourced_record/version.rb

@@ -1,3 +1,3 @@
 module EventSourcedRecord
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/generators/event_sourced_record/event_generator.rb

@@ -39,6 +39,14 @@ class EventSourcedRecord::EventGenerator < ActiveRecord::Generators::Base
 
   private
 
+  def belongs_to_foreign_key
+    belongs_to_name +  '_uuid'
+  end
+
+  def belongs_to_name
+    file_name.gsub(/_event/, '')
+  end
+
   def event_migration_class_name
     "create_#{event_table_name}".camelize
   end

data/lib/generators/event_sourced_record/event_sourced_record_generator.rb

@@ -33,9 +33,20 @@ class EventSourcedRecord::EventSourcedRecordGenerator < Rails::Generators::Named
     generate "event_sourced_record:projection", "#{file_name} #{projection_attributes}"
   end
 
+  def create_rake_file
+    template(
+      "event_sourced_record.rake", 
+      File.join("lib/tasks", class_path, "#{file_name}.rake")
+    )
+  end
+
   protected
 
   def calculator_class_name
     class_name + 'Calculator'
   end
+
+  def projection_class_name
+    class_name
+  end
 end

data/lib/generators/event_sourced_record/projection_generator.rb

@@ -35,6 +35,14 @@ class EventSourcedRecord::ProjectionGenerator < ActiveRecord::Generators::Base
 
   private
 
+  def event_class_name
+    projection_class_name + 'Event'
+  end
+
+  def has_many_foreign_key
+    file_name + '_uuid'
+  end
+
   def migration_attributes
     attr_strings = attributes.map { |attr|
       attr_string = attr.name

data/lib/generators/event_sourced_record/templates/event_model.rb

@@ -2,6 +2,9 @@
 class <%= event_class_name %> < ActiveRecord::Base
   include EventSourcedRecord::Event
 
+  belongs_to :<%= belongs_to_name %>,
+    foreign_key: '<%= belongs_to_foreign_key %>', primary_key: 'uuid'
+
   event_type :creation do
     # attributes :user_id
     #

data/lib/generators/event_sourced_record/templates/event_sourced_record.rake

@@ -0,0 +1,8 @@
+namespace :<%= file_name %> do
+  task :recalculate => :environment do
+    <%= projection_class_name %>.all.each do |<%= file_name %>| 
+      <%= calculator_class_name%>.new(<%= file_name %>).run.save!
+    end
+  end
+end
+

data/lib/generators/event_sourced_record/templates/projection_model.ar3.rb

@@ -3,7 +3,10 @@ class <%= projection_class_name %> < <%= projection_parent_class_name.classify %
 <% attributes.select {|attr| attr.reference? }.each do |attribute| -%>
   belongs_to :<%= attribute.name %>
 <% end -%>
-  has_many :<%= file_name %>_events
+  has_many :events,
+    class_name: '<%= event_class_name %>',
+    foreign_key: '<%= has_many_foreign_key %>',
+    primary_key: 'uuid'
 
   validates :uuid, uniqueness: true
 end

data/lib/generators/event_sourced_record/templates/projection_model.ar4.rb

@@ -3,7 +3,10 @@ class <%= projection_class_name %> < <%= projection_parent_class_name.classify %
 <% attributes.select(&:reference?).each do |attribute| -%>
   belongs_to :<%= attribute.name %><%= ', polymorphic: true' if attribute.polymorphic? %>
 <% end -%>
-  has_many :<%= file_name %>_events
+  has_many :events,
+      class_name: '<%= event_class_name %>',
+      foreign_key: '<%= has_many_foreign_key %>',
+      primary_key: 'uuid'
 <% if attributes.any?(&:password_digest?) -%>
   has_secure_password
 <% end -%>

data/test/generators/event_generator_test.rb

@@ -36,6 +36,10 @@ class EventSourcedRecord::EventGeneratorTest < Rails::Generators::TestCase
     assert_file("app/models/subscription_event.rb") do |contents|
       assert_match(/class SubscriptionEvent < ActiveRecord::Base/, contents)
       assert_match(/include EventSourcedRecord::Event/, contents)
+      assert_match(/belongs_to :subscription,/, contents)
+      assert_match(
+        /foreign_key: 'subscription_uuid', primary_key: 'uuid'/, contents
+      )
       assert_match(/event_type :creation do/, contents)
     end
   end

data/test/generators/event_sourced_record_generator_test.rb

@@ -35,4 +35,17 @@ class EventSourcedRecord::EventSourcedRecordGeneratorTest < Rails::Generators::T
       "shampoo_subscription_calculator"
     )
   end
+
+  test "creates a rake file" do
+    assert_file("lib/tasks/shampoo_subscription.rake") do |contents|
+      assert_match(/namespace :shampoo_subscription do/, contents)
+      assert_match(
+        /ShampooSubscription.all.each do |shampoo_subscription|/, contents
+      )
+      assert_match(
+        /ShampooSubscriptionCalculator.new\(shampoo_subscription\).run.save!/, 
+        contents
+      )
+    end
+  end
 end

data/test/generators/projection_generator_test.rb

@@ -39,6 +39,10 @@ class EventSourcedRecord::ProjectionGeneratorTest < Rails::Generators::TestCase
       assert_match(/class Subscription < ActiveRecord::Base/, contents)
       assert_match(/validates :uuid, uniqueness: true/, contents)
       assert_no_match(/attr_accessible :bottles_left/, contents)
+      assert_match(/has_many :events,/, contents)
+      assert_match(/class_name: 'SubscriptionEvent',/, contents)
+      assert_match(/foreign_key: 'subscription_uuid',/, contents)
+      assert_match(/primary_key: 'uuid'/, contents)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: event_sourced_record
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Francis Hwang
@@ -166,6 +166,7 @@ files:
 - lib/generators/event_sourced_record/templates/calculator.rb
 - lib/generators/event_sourced_record/templates/event_migration.ar3.rb
 - lib/generators/event_sourced_record/templates/event_model.rb
+- lib/generators/event_sourced_record/templates/event_sourced_record.rake
 - lib/generators/event_sourced_record/templates/observer.rb
 - lib/generators/event_sourced_record/templates/projection_migration.ar3.rb
 - lib/generators/event_sourced_record/templates/projection_model.ar3.rb