event_sorcerer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58f7bb946b104e7e64a07a78e3bcb5271295aae6
-  data.tar.gz: b6fe6643e1f836722cdb917d24be90af205352a3
+  metadata.gz: 204474547eba7a0e9289b8dda4f55548ba225fa6
+  data.tar.gz: 84fb8dfbd0220067c63bfe526899bb33ac9b4982
 SHA512:
-  metadata.gz: 31129950df220d9672037b3bf205a4f3450e0ee81735024736058f40b12a1e00ba209d9cadec8f2003f66e281ae7fc724b0d99b668e3d0ab2e8969239061a624
-  data.tar.gz: 798db082c7343649a0c529a1ec3d91880cf00af0e9b87785d7f4277912f2b76d0154cccc42bb28a64c7bd2e4e6a1286a46c6233b458f691b7975e6eb77fa691c
+  metadata.gz: bd80f51216f11bd01f9a6d4eace6accfa0f703bbd0c9a8fff5e0265862a1e66f749e7592fd5d20b91ecb8ff980c30ba582f023d8118242d75256897bef9abb8a
+  data.tar.gz: d13b3e23dc632637ce415212b60873a038a443fc13a585a46072afeb944f5d803df62bf835d4ac35695bc99720d0731b900968797cfa784b88d971ab1f696f97

data/README.md

@@ -2,8 +2,145 @@
 
 Generic event-sourcing scaffold.
 
+Disclaimer: This is still a work-in-progress, is not feature complete and _is_ subject to change.
+
 [![Code Climate](https://codeclimate.com/github/SebastianEdwards/event_sorcerer/badges/gpa.svg)](https://codeclimate.com/github/SebastianEdwards/event_sorcerer)
 
+## What is event-sourcing?
+
+Event-sourcing means using events as the primary source of truth for your domain models. Rather than storing the current state of your domain ala ActiveRecord or any other ORM, you append all mutating events to a log. To restore the current state of a domain object you initialize a new instance and replay the stored events against it.
+
+## That sounds unconventional. Why would I want to do that?
+
+Event-sourcing captures the intent of user's interacting with your system, gives you an audit log for free and allows for painless creation of new projections of your data in the future.
+
+## New projections of your data?
+
+Imagine replaying a domain model's events into objects that prepare it for being loaded into a relational store. Then, using those same events preparing it for a graph database or a full-text search engine. Use the right tool (read model) for the job.
+
+## I still don't really understand...
+
+Greg Young gave a talk on the subject which will probably explain ES concepts much better than I can. It's available here: [CQRS and Event Sourcing - Code on the Beach 2014](https://www.youtube.com/watch?v=JHGkaShoyNs).
+
+## So what does this gem give me?
+
+You can mixin `EventSorcerer::Aggregate` to your domain model and get a DSL for defining your events, plus an ActiveRecord-like interface for creating, finding and saving. It also gives you a unit-of-work, event-bus hooks and time-shifts your system during event replay.
+
+## What's the catch?
+
+This gem is like a coloring book. You get an outline but you have to color it in with your own storage engine and event bus.
+
+## That sounds scary.
+
+It isn't; you just need to subclass a couple of classes and implement a few methods. I'll add some examples at some point showing how to use it with a couple of different datastores.
+    
+## Example
+
+Here we have a domain model representing a good ol' game of rugby. It allows the game to be started and stopped and points to be scored. Things to notice:
+
+- Event definition is very simple. Just wrap the event methods in an `events` block. Note: as it stands in the current version your arguments must all be JSON serializable. Keyword arguments are supported.
+- Validation is done with exceptions, a conceptually simple model, give invalid input and it blows up (for you to rescue and give a reasonable response to the user of course).
+- Rather than keeping a current score in the database, we use events to track score-increasing events. Now, we not only know the score at any point in the game but we also know the context (the why) around the score (tries vs penalties, etc.)
+- We could use fat events to allow interesting projections in the future. Fat events means storing more context than we currently need (storage is cheap!). For example we could track the scoring player for each try and create a projection which shows how many tries each player made during the entire game. We could even replay multiple games into one projection to find a player's total tally for a season.
+
+```ruby
+class RugbyGame
+  class Team < Struct.new(:name, :score)
+    def add_points(points)
+      @score += points
+    end
+
+    def to_s
+      "#{name}: #{score}"
+    end
+  end
+
+  class DuplicateTeamName < RuntimeError; end
+  class GameNotInProgress < RuntimeError; end
+  class TeamNotPlaying < RuntimeError; end
+
+  attr_reader :team_one
+  attr_reader :team_two
+
+  def game_in_progress?
+    @game_in_progress == true
+  end
+
+  def scores
+    "#{team_one} - #{team_two}"
+  end
+
+  def team_by_name(name)
+    return team_one if name == team_one.name
+    return team_two if name == team_two.name
+
+    fail TeamNotPlaying
+  end
+
+  events do
+    def game_started(first_team, second_team)
+      fail DuplicateTeamName if first_team_name == second_team_name
+
+      @team_one = Team.new(first_team_name,  0)
+      @team_two = Team.new(second_team_name, 0)
+      @game_in_progress = true
+
+      self
+    end
+
+    def game_ended
+      @game_in_progress = false
+
+      self
+    end
+
+    def try_scored(scoring_team)
+      fail GameNotInProgress unless game_in_progress?
+
+      team_by_name(scoring_team).add_points 5
+
+      self
+    end
+
+    def try_converted(scoring_team)
+      fail GameNotInProgress unless game_in_progress?
+
+      team_by_name(scoring_team).add_points 2
+
+      self
+    end
+
+    def drop_goal_scored(scoring_team)
+      ...
+    end
+
+    def penalty_kick_scored(scoring_team)
+      ...
+    end
+  end
+end
+```
+
+Here's how you'd use the above class:
+
+```ruby
+game = RugbyGame.new
+game.game_started('All Blacks', 'Wallabies')
+game.try_scored('All Blacks')
+game.try_converted('All Blacks')
+game.drop_goal_scored('Wallabies')
+
+...
+
+game.game_ended
+game.scores => "All Blacks: 29 - Wallabies: 28"
+game.save
+
+... later ...
+game = RugbyGame.find(6)
+game.scores => "All Blacks: 29 - Wallabies: 28"
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/event_sorcerer.gemspec

@@ -23,6 +23,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rake'
 
-  spec.add_runtime_dependency 'invokr', '0.0.5'
+  spec.add_runtime_dependency 'invokr', '~> 0.9.6'
   spec.add_runtime_dependency 'timecop', '0.7.1'
 end

data/lib/event_sorcerer.rb

@@ -52,17 +52,25 @@ module EventSorcerer
       @message_bus || fail(UnsetMessageBus)
     end
 
-    # Public: Mutex to synchronize usage of non-threadsafe time-traveling gems.
-    def time_travel_lock
-      @time_travel_lock ||= Mutex.new
-    end
-
     # Public: Returns the unit_of_work for the current thread. Defaults to
     #         NoUnitOfWork.
     def unit_of_work
       Thread.current[:unit_of_work] || NoUnitOfWork
     end
 
+    # Public: Executes a block with time frozen to a given moment.
+    #
+    # time - Time to freeze time at.
+    #
+    # Returns value of block.
+    def with_time(time)
+      time_travel_lock.synchronize do
+        Timecop.freeze(time) do
+          yield
+        end
+      end
+    end
+
     # Public: Creates a new UnitOfWork and sets it for the current thread
     #         within the block. Executes the work after block completion.
     #
@@ -79,5 +87,12 @@ module EventSorcerer
 
       result
     end
+
+    private
+
+    # Private: Mutex to synchronize usage of non-threadsafe time-traveling gem.
+    def time_travel_lock
+      @time_travel_lock ||= Mutex.new
+    end
   end
 end

data/lib/event_sorcerer/aggregate.rb

@@ -111,7 +111,7 @@ module EventSorcerer
       # block - the block to yield the event stream to.
       #
       # Returns the return value of the given block.
-      def with_all_event_streams_for_type(&block)
+      def with_all_event_streams_for_type()
         yield event_store.read_event_streams_for_type(name)
       end
 
@@ -122,7 +122,7 @@ module EventSorcerer
       # block        - the block to yield the event stream to.
       #
       # Returns the return value of the given block.
-      def with_all_loaders_for_type(prohibit_new = true, &block)
+      def with_all_loaders_for_type(prohibit_new = true)
         with_all_event_streams_for_type do |streams|
           loaders = streams.map do |stream|
             AggregateLoader.new(self, stream.id, stream.events,
@@ -140,7 +140,7 @@ module EventSorcerer
       # block - the block to yield the event stream to.
       #
       # Returns the return value of the given block.
-      def with_event_stream_for_id(id, &block)
+      def with_event_stream_for_id(id)
         yield event_store.read_event_stream(id)
       end
 
@@ -151,7 +151,7 @@ module EventSorcerer
       # block - the block to yield the event stream to.
       #
       # Returns the return value of the given block.
-      def with_loader_for_id(id, prohibit_new = true, &block)
+      def with_loader_for_id(id, prohibit_new = true)
         with_event_stream_for_id(id) do |stream|
           yield AggregateLoader.new(self, stream.id, stream.events,
                                     stream.current_version, prohibit_new)

data/lib/event_sorcerer/aggregate_proxy.rb

@@ -60,14 +60,14 @@ module EventSorcerer
     # Private: Handles the serialization of event arguments and pushes the
     #          Event object onto the _dirty_events array. Increments the local
     #          version number for the aggregate.
-    def add_dirty_event!(method_sym, *arguments)
+    def add_dirty_event!(time, method_sym, *arguments)
       increment_version!
 
       method = @_aggregate.method(method_sym)
       method.parameters.each.with_index.select { |(type, _), _| type == :req }
 
       details = ArgumentHashifier.hashify(method.parameters, arguments.dup)
-      @_dirty_events << Event.new(method_sym, Time.now, details)
+      @_dirty_events << Event.new(method_sym, time, details)
 
       self
     end
@@ -103,9 +103,14 @@ module EventSorcerer
     def send_event_to_aggregate(method_sym, *arguments, &block)
       fail EventArgumentError if block
 
-      add_dirty_event!(method_sym, *arguments)
+      time = Time.now
+      add_dirty_event!(time, method_sym, *arguments)
 
-      @_aggregate.send method_sym, *arguments
+      expected_args = arguments.slice(0, @_aggregate.method(method_sym).arity)
+
+      EventSorcerer.with_time(time) do
+        @_aggregate.send method_sym, *expected_args
+      end
     rescue StandardError => e
       undo_dirty_event!
       raise e

data/lib/event_sorcerer/event_applicator.rb

@@ -12,10 +12,8 @@ module EventSorcerer
     #
     # Returns self.
     def self.apply_event!(aggregate, event)
-      EventSorcerer.time_travel_lock.synchronize do
-        Timecop.freeze(event.created_at) do
-          Invokr.invoke method: event.name, on: aggregate, with: event.details
-        end
+      EventSorcerer.with_time(event.created_at) do
+        Invokr.invoke method: event.name, on: aggregate, using: event.details
       end
 
       self

data/lib/event_sorcerer/version.rb

@@ -1,4 +1,4 @@
 # Public: Defines a constant for the current version number.
 module EventSorcerer
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_sorcerer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sebastian Edwards
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-17 00:00:00.000000000 Z
+date: 2014-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -84,16 +84,16 @@ dependencies:
   name: invokr
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.9.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.9.6
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement