jouba 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a950ed83af66e155fdc222f59f7d19fc75b794bc
-  data.tar.gz: 9f1c29d98bb2629d203fa1d488835dba5e7fe596
+  metadata.gz: 9e6660abb8c21ca75fd3e50326ac42be55042e44
+  data.tar.gz: 8275f30c736cc526a067dd62133c9793b9d54a70
 SHA512:
-  metadata.gz: 2ea2281b2b8e62388b3c881de115e43b9e88db12e92e2005098edc8b0a27517d27a8f5558a5d80e2eb78014558707e29b7adad18b2235f7a9951ff48bbef844b
-  data.tar.gz: 748a5ef33c0af9a63d5b306988b2117cb25e6b9bfea4d7a80a651a551240cd99849013b314c905db85b4cee5068991484428b42133c88dacf2b4ef8bab05b8f5
+  metadata.gz: 3db76134f73e65253c60d0ffce827641d50b7039e8f0d42481a25cc572229cd903619485efe1e93acd4d9a91d2998cb858c47b64e245e7191c2ce9b8f7da4c2c
+  data.tar.gz: cd2a7c8db64aececdf803d9c55ebd9df5cdafaaea0fdd12b03c913746d46e9f026988c7f66c2cd1c5d9044788fa67710443fa755aff8b552760544c7d1ca15cb

data/Gemfile

@@ -1,7 +1,7 @@
 source "http://rubygems.org"
 
 gem 'hashie', '~> 3.4'
-gem 'wisper', '~>1.6'
+gem 'wisper', '~>2.0.0.rc1'
 gem 'locality-uuid'
 
 group :development do

data/Gemfile.lock

@@ -88,7 +88,7 @@ GEM
     slop (3.5.0)
     systemu (2.6.4)
     thread_safe (0.3.4)
-    wisper (1.6.0)
+    wisper (2.0.0.rc1)
 
 PLATFORMS
   ruby
@@ -103,4 +103,4 @@ DEPENDENCIES
   rspec (~> 2.14)
   rubocop (~> 0.23)
   simplecov (~> 0)
-  wisper (~> 1.6)
+  wisper (~> 2.0.0.rc1)

data/README.md

@@ -1,70 +1,69 @@
-# jouba
+# Jouba
 
+[![Join the chat at https://gitter.im/gregory/jouba](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/gregory/jouba?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-```ruby
-  class Customer < Hashie::Dash
-    include Jouba::Aggregate.new(prefix: :on)
-    property :uuid
-    property :name
+![](https://dl.dropboxusercontent.com/u/19927862/jouba.png)
 
-    def self.create(attributes)
-      Customer.new(uuid: SecureRandom.uuid).tap do |customer|
-        customer.create(attributes.merge(uuid: customer.uuid))
-      end
-    end
 
-    def create(attributes)
-      emit(:created, attributes)
-    end
+## WTF?
 
-  private
+Jouba aims to be a minimalist framework in pure ruby for [event sourcing](http://martinfowler.com/eaaDev/EventSourcing.html), [CQRS](http://martinfowler.com/bliki/CQRS.html) ready.
 
-    def on_created(attributes)
-      update_attributes!(attributes)
-    end
-  end
+**TL; DR**:
 
-  class Admin
-    include Jouba::Aggregate.new(prefix: :on) # include Wisper and Anima
+**Event sourcing**:
+> The fundamental idea of Event Sourcing is that of ensuring every change to the state of an application is captured in an event object, and that these event objects are themselves stored in the sequence they were applied for the same lifetime as the application state itself.
 
-    def self.create(attributes)
-      Admin.new(uuid: SecureRandom.uuid).tap do |admin|
-        admin.create(attributes.merge(uuid: customer.uuid))
-      end
-    end
 
-    def create(attributes)
-      emit(:created, attributes)
-    end
+**CQRS**: 
+> It's a pattern that I first heard described by Greg Young. At its heart is a simple notion that you can use a different model to update information than the model you use to read information.
 
-  private
+## FAQ:
 
-    def on_created(attributes)
-      update_attributes!(attributes)
-    end
-  end
+* Is it in production yet?
+  * Not that i know of. In my case, not yet since i've been pretty busy with other stuffs and this was initially part of a side project, but i should be pretty reactive for PR/issues so feel free to use/improve it.
+  
+  
 
+## Pub/Sub
 
-  Jouba.emit('us.computer1.cpu', :idle, {value: 50})
-  Jouba.stream('us.computer1.cpu').since(1.month.ago).where({value: ->(v) { v >= 20 }})
+Jouba ships with a minimalist API to emit events and subscribe listeners (listeners could operate asynchronously) and retrieve events from the store that is set at `Jouba.config.Store` (by default this will be an [in memory store](https://github.com/gregory/jouba/blob/master/lib/jouba/store.rb#L47). 
 
-  Jouba.config.Cache = Jouba::Cache::Memory.new
-  require 'jouba/aggregate'
-  customer_params = { fname: 'foo', lname: 'bar' }
+At it's core, it relies on the excellent [wisper](https://github.com/krisleech/wisper) gem so you have all it's awesomeness for free.
 
-  c = Customer.create(customer_params, true)
-  c.fname # => "foo"
-  c.uuid # => 123
-  c.to_key # => "Customer.123"
+```ruby
 
-  d = Customer.find(c.uuid)
+Jouba.emit('us.computer1.cpu', :idle, {value: 50})
+Jouba.subscribe(Logger, on: /.*/, with: :log)
+Jouba.subscribe(Graphite, on: /us.*/, with: :post, async: true).on_error do |error, name,payload|
+	#DO SOMETHING
+end
+	
+Jouba.stream('us.computer1.cpu').since(1.month.ago).where({value: ->(v) { v >= 20 }})
+
+class Logger
+  def log(params={})
+  	puts params.map{|k,v| "#{k}=#{v}"}.join(', ')
+  end
+end
 
+class Collector
+  def post(params={})
+    $statsd.increment params[:key]
+  end
+end
 ```
 
+## Event Store (stores all events that has happened)
+
+You are free to implement an Event Store as soon as they define `self.stream`and `self.track` methods.
+
+
 ```ruby
-  class Store < AR
-    set_table_name :events
 
+  class Store < ActiveRecord::Base
+    set_table_name :events
+ 
     scope :since, -> (time) { where('timestamp >= ?', time) }
 
     def self.stream(key, params={})
@@ -75,26 +74,179 @@
       create serialized_event
     end
   end
+  
 
   Jouba.config.Store = Store
+  Jouba.emit('us.computer1', :disk, {value: 60})
+	Jouba.emit('us.computer1', :cpu, {value: 50}) do |event|
+	  #DO SOME STUFFS
+    event.track
+  end
+  Jouba.stream('us.computer1').where(key: 'us.computer1', name: :cpu).count
+
+```
+
+## Aggregate (handles Commands and generates Events based on the current state)
+
+A core concept of CQRS is keeping up to date the state of the data when things changes through commands.
+[Aggregate](http://martinfowler.com/bliki/DDD_Aggregate.html) handles command and generate events based on the current state.
+
+Jouba ships with an aggregate module, that provides the host class with an `emit` method in order to emit events to the configured Store (pointed by `Jouba.config.Store`).
+On a distributed system, to avoid eventual consistency on reading data from the db, you should rebuild the state of the aggregate by replaying all the events.
+
+After a time, the aggregate could end up with a lot of events, so the trick here is to use what is called a [projection](http://martinfowler.com/eaaDev/EventSourcing.html#ApplicationStateStorage). This has been implemented through a Cach mechanisme, by default [NullCache](https://github.com/gregory/jouba/blob/master/lib/jouba/cache.rb#L5), but you could set it to anything you want.
+
+A UUID will be generated for any new aggregate, [even in distributed environment](https://github.com/groupon/locality-uuid.rb)
+
+```ruby
+
+require 'jouba/aggregate'
+class Customer < Hashie::Dash
+  include Jouba::Aggregate.new(prefix: :on)
+  
+  property :uuid
+  property :name
+
+  def self.create(attributes)
+    Customer.new(uuid: SecureRandom.uuid).tap do |customer|
+      customer.create(attributes.merge(uuid: customer.uuid))
+    end
+  end
+
+  def create(attributes)
+    emit(:created, attributes)
+  end
+
+	private
+
+  def on_created(attributes)
+    update_attributes!(attributes)
+  end
+end
+
+Jouba.config.Cache = Jouba::Cache::Memory.new
+Jouba.subscribe(CustomerAnalytics, on: /Customer.+/, with: :track)
+
+c = Customer.create({fname: 'foo', lname: 'bar'})
+c.fname # => "foo"
+c.uuid # => 123
+c.to_key # => "Customer.123"
+
+d = Customer.find(c.uuid)
+c == d #=> true
+Customer.stream(c.uuid).count #=> 1
+Customer.stream(c.uuid).first.class #=> Jouba::Event
+Customer.stream(c.uuid).first.uuid # 20be0ffc-314a-bd53-7a50-013a65ca76d2
+
+```
+
+Event Sourcing might seem overkill, but this is a little cost comparing to [the advantages](https://lostechies.com/jimmybogard/2011/10/11/event-sourcing-as-a-strategic-advantage/) it will bring to your business
+
+## Event (indicate that something has happened)
+
+If you are unhappy with the structure of Jouba::Event, feel free to implement your own! 
+
+You can access/update to the main parts of jouba from the config
+
+```ruby
+class MyEvent
+  # NOTE: the store is accessible from: Jouba.Store or Jouba.config.Store
+  def self.serialize(event); end              # serialize an event
+  def self.deserialize(serialized_event); end # deserialize a serialized event
+  def self.stream(key, params={}); end        # fetch all the matching events
+  def track; end                              # save to the event store
+end
+
+Jouba.config.Event = MyEvent
+```
+
+## Event Key (generate a key based on the aggregate)
+
+If you feels unhappy with the way Jouba::Key is building keys in the aggregate, feel free to implement your own! 
+
+
+```ruby
+	
+class MyKey
+  attr_reader :class_name, :uuid
+	  
+  def initialize(class_name, uuid);
+    @class_name, @uuid = class_name, uuid
+  end
+	  
+  def self.serialize(class_name, uuid); end #return a string of a key
+  def self.deserialize(string); end # return a new MyKey
+end
+```
+
+## Repository 
+
+Repository is a CQRS concept where you should use repositories to fetch your data for read only. You'll need to keep your repository up to date with all the latest changes. 
+The way to achieve this with jouba is by having the repository to subscribe to the aggregates. Repository will ideally translate events into state.
+
+```ruby
+  class Admin
+    include Jouba::Aggregate.new(prefix: :foo)
+
+    def self.create(attributes)
+      Admin.new(uuid: SecureRandom.uuid).tap do |admin|
+        admin.create(attributes.merge(uuid: admin.uuid))
+      end
+    end
+
+    def create(attributes)
+      emit(:created, attributes)
+    end
+
+    private
+
+    def foo_created(attributes)
+      update_attributes!(attributes)
+    end
+  end
 
   class UserRepository < AR
     set_table_name :users
     # must have a key column
 
-    def on_created(attributes)
-      self.create(attributes)
+    def self.has_been_created(attributes)
+      create(attributes)
     end
-    alias :on_created
   end
 
-  Wisper.subscribe(UserRepository.new, scope: :Customer)
+  Wisper.subscribe(UserRepository, scope: [:Customer, :Admin], prefix: :has_been) # Note here how 2 aggregates are using the same repository.
+```
+
+## Cache
+
+If you feels unhappy with Jouba::Cache, feel free to implement your own! 
+
+
+```ruby
+	
+class MyCache
+  def fetch(_)
+    yield
+  end
+
+  def refresh(_, _)
+    yield
+  end
+end
+
+Jouba.config.Cache = MyCache.new
 ```
+## Why Jouba? 
 
+Jouba is the name of the parrot i grew up with. He never talked but made a hell lot of noise. Going down the path of event sourcing, you'll have a lot of noise first, but then you'll figure out what to do with it.
 
+## TODO: 
 
-## Todo
-- write a how to in english :)
+* [ ] Better doc (this is a draft :))
+* [ ] Locking Mechanisme
+* [ ] more examples
+* [ ] clean the image
+* [ ] Rename EventStore.get/set into stream/track for better consistency
 
 ## Contributing to jouba
 

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

data/jouba.gemspec

@@ -2,16 +2,14 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: jouba 1.0.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "jouba"
-  s.version = "1.0.1"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.require_paths = ["lib"]
   s.authors = ["gregory"]
-  s.date = "2015-02-03"
+  s.date = "2015-04-01"
   s.description = "Jouba is a tool set for event sourcing: aggregate root, entities and storage"
   s.email = "greg2502@gmail.com"
   s.extra_rdoc_files = [
@@ -46,7 +44,8 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "http://github.com/gregory/jouba"
   s.licenses = ["MIT"]
-  s.rubygems_version = "2.2.2"
+  s.require_paths = ["lib"]
+  s.rubygems_version = "2.0.14"
   s.summary = "Jouba is a tool set for event sourcing: aggregate root, entities and storage"
 
   if s.respond_to? :specification_version then
@@ -54,7 +53,7 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<hashie>, ["~> 3.4"])
-      s.add_runtime_dependency(%q<wisper>, ["~> 1.6"])
+      s.add_runtime_dependency(%q<wisper>, ["~> 2.0.0.rc1"])
       s.add_runtime_dependency(%q<locality-uuid>, [">= 0"])
       s.add_development_dependency(%q<pry>, ["~> 0"])
       s.add_development_dependency(%q<rspec>, ["~> 2.14"])
@@ -65,7 +64,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<rubocop>, ["~> 0.23"])
     else
       s.add_dependency(%q<hashie>, ["~> 3.4"])
-      s.add_dependency(%q<wisper>, ["~> 1.6"])
+      s.add_dependency(%q<wisper>, ["~> 2.0.0.rc1"])
       s.add_dependency(%q<locality-uuid>, [">= 0"])
       s.add_dependency(%q<pry>, ["~> 0"])
       s.add_dependency(%q<rspec>, ["~> 2.14"])
@@ -77,7 +76,7 @@ Gem::Specification.new do |s|
     end
   else
     s.add_dependency(%q<hashie>, ["~> 3.4"])
-    s.add_dependency(%q<wisper>, ["~> 1.6"])
+    s.add_dependency(%q<wisper>, ["~> 2.0.0.rc1"])
     s.add_dependency(%q<locality-uuid>, [">= 0"])
     s.add_dependency(%q<pry>, ["~> 0"])
     s.add_dependency(%q<rspec>, ["~> 2.14"])

data/lib/jouba.rb

@@ -1,6 +1,6 @@
-require 'pry'
 require 'forwardable'
 require 'hashie'
+require 'wisper'
 require 'locality-uuid'
 
 require 'jouba/version'
@@ -20,6 +20,7 @@ module Jouba
   }
 
   class<<self
+    include Wisper::Publisher
     extend Forwardable
     def_delegators :config, :Key, :Event, :Cache, :Store
   end
@@ -29,7 +30,10 @@ module Jouba
   end
 
   def emit(key , name , data)
-    config.Event.new(key: key, name: name, data: data).track
+    config.Event.new(key: key, name: name, data: data).tap do |event|
+      block_given? ? yield(event) : event.track
+      publish(key, event)
+    end
   end
 
   def stream(key, params = {})

data/lib/jouba/aggregate.rb

@@ -1,6 +1,5 @@
 require 'jouba'
 require 'jouba/cache'
-require 'wisper'
 
 module Jouba
   class Aggregate < Module
@@ -27,10 +26,11 @@ module Jouba
 
     module InstanceMethods
       def emit(name, *args)
-        event = Jouba.Event.new(key: to_key, name: name, data: args)
-        apply_event(event)
-        Jouba.Cache.refresh(to_key, self) { event.track }
-        publish(event.name, event.data)
+        Jouba.emit(to_key, name, args) do |event|
+          apply_event(event)
+          Jouba.Cache.refresh(to_key, self) { event.track }
+          publish(event.name, event.data)
+        end
       end
 
       def replay(event)

data/spec/spec_helper.rb

@@ -1,5 +1,6 @@
 require 'simplecov'
 require 'rspec'
+require 'pry'
 
 module SimpleCov::Configuration
   def clean_filters

metadata

@@ -1,153 +1,153 @@
 --- !ruby/object:Gem::Specification
 name: jouba
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - gregory
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-03 00:00:00.000000000 Z
+date: 2015-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.4'
 - !ruby/object:Gem::Dependency
   name: wisper
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: 2.0.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: 2.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: locality-uuid
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '2.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '2.14'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.12'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
   name: jeweler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '0.23'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '0.23'
 description: 'Jouba is a tool set for event sourcing: aggregate root, entities and
@@ -159,9 +159,9 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
-- ".document"
-- ".rspec"
-- ".rubocop.yml"
+- .document
+- .rspec
+- .rubocop.yml
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -193,17 +193,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: 'Jouba is a tool set for event sourcing: aggregate root, entities and storage'