wisper 1.0.0 → 1.0.1

data/README.md

@@ -3,10 +3,10 @@
 Simple pub/sub for Ruby objects
 
 [![Code Climate](https://codeclimate.com/github/krisleech/wisper.png)](https://codeclimate.com/github/krisleech/wisper)
-[![Build Status](https://travis-ci.org/krisleech/wisper.png)](https://travis-ci.org/krisleech/wisper)
+[![Build Status](https://travis-ci.org/krisleech/wisper.png?branch=master)](https://travis-ci.org/krisleech/wisper)
 
 While this is not dependent on Rails in any way it was extracted from a Rails
-project and is used as an alternative to ActiveRecord callbacks and Observers.
+project and can used as an alternative to ActiveRecord callbacks and Observers.
 
 The problem with callbacks and Observers is that they always happen. How many
 times have you wanted to do `User.create` without firing off a welcome email?
@@ -19,7 +19,9 @@ models.
 
 Add this line to your application's Gemfile:
 
-    gem 'wisper'
+```ruby
+gem 'wisper', '~>1.0.0'
+```
 
 ## Usage
 
@@ -33,6 +35,7 @@ class MyPublisher
   include Wisper
 
   def do_something
+    # ...
     publish(:done_something, self)
   end
 end
@@ -49,17 +52,17 @@ publish(:done_something, self, 'hello', 'world')
 
 #### Listeners
 
-The listener is subscribed to all events it responds to.
+Any object can be a listener and by default they are only subscribed to events
+they can respond to.
 
 ```ruby
-listener = Object.new # any object
 my_publisher = MyPublisher.new
-my_publisher.subscribe(listener)
+my_publisher.subscribe(MyListener.new)
 ```
 
 #### Blocks
 
-The block is subscribed to a single event.
+Blocks are subscribed to single events.
 
 ```ruby
 my_publisher = MyPublisher.new
@@ -68,6 +71,23 @@ my_publisher.on(:done_something) do |publisher|
 end
 ```
 
+### Asynchronous Publishing (Experimental)
+
+There is support for publishing events asynchronously by passing the `async`
+option.
+
+```ruby
+my_publisher.add_subscriber(MySubscriber.new, :async => true)
+```
+
+This leans on Celluloid, which must be included in your Gemfile.
+
+The listener is transparently turned in to a Celluloid Actor.
+
+Please refer to [Celluloid](https://github.com/celluloid/celluloid/wiki)
+for more information, particually the
+[Gotchas](https://github.com/celluloid/celluloid/wiki/Gotchas).
+
 ### ActiveRecord
 
 ```ruby
@@ -103,34 +123,38 @@ class PostsController < ApplicationController
 end
 ```
 
-### Service/Use case object
-
-The downside to publishing directly from ActiveRecord models is that an event
-can get fired and then rolled back if a transaction fails.
+### Service/Use Case/Command objects
 
-Since I am trying to make my models dumb I tend to use a separate service 
-object which contains all the logic and wraps it all in a transaction.
-
-The follow is contrived, but you can imagine it doing more than just updating a
-record, maybe sending an email or updating other records.
+A Service object is useful when an operation is complex, interacts with more
+than one model, accesses an external API or would burden a model with too much
+responsibility.
 
 ```ruby
-class CreateThing
+class PlayerJoiningTeam
   include Wisper
 
-  def execute(attributes)
-    thing = Thing.new(attributes)
+  def execute(player, team)
+    membership = Membership.new(player, team)
 
-    if thing.valid?
-      ActiveRecord::Base.transaction do
-        thing.save
-        # ...
-      end
-      publish(:create_thing_successful, thing)
+    if membership.valid?
+      membership.save!
+      email_player(player, team)
+      assign_first_mission(player, team)
+      publish(:player_joining_team_successful, player, team)
     else
-      publish(:create_thing_failed, thing)
+      publish(:player_joining_team_failed, player, team)
     end
   end
+
+  private
+
+  def email_player(player, team)
+    # ...
+  end
+
+  def assign_first_mission(player, team)
+    # ...
+  end
 end
 ```
 
@@ -157,13 +181,40 @@ class StatisticsListener
     # ...
   end
 end
+
+class CacheListener
+  def create_thing_successful(thing)
+    # ...
+  end
+end
+
+class IndexingListener
+  def create_thing_successful(thing)
+    # ...
+  end
+end
 ```
 
+## Global listeners
+
+If you become tired of adding the same listeners to _every_ publisher you can
+add global listeners. They receive all published events which they can respond
+to.
+
+However it means that when looking at the code it will not be obvious that the
+global listeners are being executed in additional to the regular listeners.
+
+```ruby
+Wisper::GlobalListeners.add_listener(MyListener.new)
+```
+
+In a Rails app you might want to add your global listeners in an initalizer.
+
 ## Subscribing to selected events
 
-By default a listener will get notified of all events it responds to. You can
-limit which events a listener is notified of by passing an event or array of
-events to `:on`.
+By default a listener will get notified of all events it can respond to. You
+can limit which events a listener is notified of by passing an event or array
+of events to `:on`.
 
 ```ruby
 post_creater.subscribe(PusherListener.new, :on => :create_post_successful)
@@ -207,6 +258,57 @@ post.on(:success) { |post| redirect_to post }
     .on(:failure) { |post| render :action => :edit, :locals => :post => post }
 ```
 
+## RSpec
+
+Wisper comes with a method for stubbing event publishers so that you can create isolation tests
+that only care about reacting to events.
+
+Given this piece of code:
+
+```ruby
+class CodeThatReactsToEvents
+  def do_something
+    publisher = MyPublisher.new
+    publisher.on(:some_event) do |variable|
+      return "Hello with #{variable}!"
+    end
+    publisher.execute
+  end
+end
+```
+
+You can test it like this:
+
+```ruby
+require 'wisper/rspec/stub_wisper_publisher'
+
+describe CodeThatReactsToEvents do
+  context "on some_event" do
+    before do
+      stub_wisper_publisher("MyPublisher", :execute, :some_event, "foo")
+    end
+
+    it "renders" do
+      response = CodeThatReactsToEvents.new.do_something
+      response.should == "Hello with foo!"
+    end
+  end
+end
+```
+
+This becomes important when testing, for example, Rails controllers in
+isolation from the business logic.  This technique is used at the controller
+layer to isolate testing the controller from testing the encapsulated business
+logic.
+
+You can use any number of args to pass to the event:
+
+```ruby
+stub_wisper_publisher("MyPublisher", :execute, :some_event, "foo1", "foo2", ...)
+```
+
+See `spec/lib/rspec_extensions_spec.rb` for a runnable example.
+
 ## Compatibility
 
 Tested with 1.9.x on MRI, JRuby and Rubinius.

data/lib/wisper.rb

@@ -1,7 +1,9 @@
 require "wisper/version"
 require "wisper/registration/registration"
 require "wisper/registration/object"
+require "wisper/registration/object/async_listener"
 require "wisper/registration/block"
+require 'wisper/global_listeners'
 
 module Wisper
   def listeners
@@ -29,8 +31,12 @@ module Wisper
 
   private
 
+  def all_listeners
+    listeners.merge(GlobalListeners.listeners)
+  end
+
   def broadcast(event, *args)
-    listeners.each do | listener |
+    all_listeners.each do | listener |
       listener.broadcast(clean_event(event), *args)
     end
   end

data/lib/wisper/global_listeners.rb

@@ -0,0 +1,28 @@
+require 'singleton'
+
+module Wisper
+  class GlobalListeners
+    include Singleton
+
+    def initialize
+      @listeners = Set.new
+    end
+
+    def add_listener(listener, options = {})
+      listeners << ObjectRegistration.new(listener, options)
+      self
+    end
+
+    def listeners
+      @listeners
+    end
+
+    def self.add_listener(listener, options = {})
+      instance.add_listener(listener, options)
+    end
+
+    def self.listeners
+      instance.listeners
+    end
+  end
+end

data/lib/wisper/registration/object.rb

@@ -1,16 +1,27 @@
+begin
+  require 'celluloid/autostart'
+rescue LoadError
+  # no-op
+end
+
 module Wisper
   class ObjectRegistration < Registration
-    attr_reader :with
+    attr_reader :with, :async
 
     def initialize(listener, options)
       super(listener, options)
-      @with = options[:with]
+      @with  = options[:with]
+      @async = options.fetch(:async, false)
     end
 
     def broadcast(event, *args)
       method_to_call = map_event_to_method(event)
       if should_broadcast?(event) && listener.respond_to?(method_to_call)
-        listener.public_send(method_to_call, *args)
+        unless async
+          listener.public_send(method_to_call, *args)
+        else
+          AsyncListener.new(listener, method_to_call).async.public_send(method_to_call, *args)
+        end
       end
     end
 

data/lib/wisper/registration/object/async_listener.rb

@@ -0,0 +1,23 @@
+class AsyncListener
+  include Celluloid if defined?(Celluloid)
+
+  attr_reader :listener, :event_method
+
+  def initialize(listener, event_method)
+    @listener     = listener
+    @event_method = event_method.to_sym
+  end
+
+  def method_missing(method, *args, &block)
+    if listener.respond_to?(method)
+      if method == event_method
+        listener.public_send(method, *args, &block)
+        terminate
+      else
+        listener.public_send(method, *args, &block)
+      end
+    else
+      super(method, *args, &block)
+    end
+  end
+end

data/lib/wisper/rspec/stub_wisper_publisher.rb

@@ -0,0 +1,15 @@
+### Wisper Stubbing
+# This is a proposal for integration as part of wisper core
+# for testing: https://github.com/krisleech/wisper/issues/1
+class TestWisperPublisher
+  include Wisper
+  def initialize(*args); end
+end
+
+def stub_wisper_publisher(clazz, called_method, event_to_publish, *published_event_args)
+  stub_const(clazz, Class.new(TestWisperPublisher) do
+    define_method(called_method) do
+      publish(event_to_publish, *published_event_args)
+    end
+  end)
+end

data/lib/wisper/version.rb

@@ -1,3 +1,3 @@
 module Wisper
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/spec/lib/async_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+class MyService
+  include Wisper
+
+  def execute
+    broadcast('success', self)
+  end
+end
+
+# help me...
+$global = 'no'
+
+class MyListener
+  def success(command)
+    $global = 'yes'
+  end
+end
+
+describe Wisper do
+
+  it 'subscribes object to all published events' do
+    listener = MyListener.new
+
+    command = MyService.new
+
+    command.add_listener(listener, :async => true)
+
+    command.execute
+    sleep(1) # seriously...
+    $global.should == 'yes'
+  end
+end
+

data/spec/lib/global_subscribers_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe Wisper::GlobalListeners do
+  let(:global_listener)  { double('listener') }
+  let(:local_listener)   { double('listener') }
+  let(:publisher)        { Object.new.extend(Wisper) }
+
+  describe '.add_listener' do
+    it 'adds given listener to every publisher' do
+      Wisper::GlobalListeners.add_listener(global_listener)
+      global_listener.should_receive(:it_happened)
+      publisher.send(:broadcast, :it_happened)
+    end
+
+    it 'works along side local listeners' do
+      # global listener
+      Wisper::GlobalListeners.add_listener(global_listener)
+
+      # local listener
+      publisher.add_listener(local_listener)
+
+      global_listener.should_receive(:it_happened)
+      local_listener.should_receive(:it_happened)
+
+      publisher.send(:broadcast, :it_happened)
+    end
+  end
+end

data/spec/lib/integration_spec.rb

@@ -56,7 +56,9 @@ describe Wisper do
 
   it 'subscribes block can be chained' do
     insider = double('Insider')
+
     insider.should_receive(:render).with('success')
+    insider.should_receive(:render).with('failure')
 
     command = MyCommand.new
 
@@ -64,5 +66,6 @@ describe Wisper do
            .on(:failure) { |message| insider.render('failure') }
 
     command.execute(true)
+    command.execute(false)
   end
 end

data/spec/lib/rspec_extensions_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+require 'wisper/rspec/stub_wisper_publisher'
+
+describe Wisper do
+  describe "given a piece of code invoking a publisher" do
+    class CodeThatReactsToEvents
+      def do_something
+        publisher = MyPublisher.new
+        publisher.on(:some_event) do |variable1, variable2|
+          return "Hello with #{variable1} #{variable2}!"
+        end
+        publisher.execute
+      end
+    end
+
+    context "when stubbing the publisher to emit an event" do
+      before do
+        stub_wisper_publisher("MyPublisher", :execute, :some_event, "foo1", "foo2")
+      end
+
+      it "emits the event" do
+        response = CodeThatReactsToEvents.new.do_something
+        response.should == "Hello with foo1 foo2!"
+      end
+    end
+  end
+end

data/spec/lib/wisper_spec.rb

@@ -62,8 +62,9 @@ describe Wisper do
   end
 
   describe '.add_block_listener' do
+    let(:insider) { double('insider') }
+
     it 'subscribes given block to all events' do
-      insider = double('insider')
       insider.should_receive(:it_happened).twice
 
       publisher.add_block_listener do
@@ -76,7 +77,6 @@ describe Wisper do
 
     describe ':on argument' do
       it '.add_block_listener subscribes block to an event' do
-        insider = double('insider')
         insider.should_not_receive(:it_happened).once
 
         publisher.add_block_listener(:on => 'something_happened') do

data/wisper.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'celluloid'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wisper
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-07 00:00:00.000000000 Z
+date: 2013-05-02 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2152451840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,15 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *2152451840
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2152451300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -37,15 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *2152451300
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2152450760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -53,12 +43,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  version_requirements: *2152450760
+- !ruby/object:Gem::Dependency
+  name: celluloid
+  requirement: &2152450220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2152450220
 description: pub/sub for Ruby objects
 email:
 - kris.leech@gmail.com
@@ -74,11 +70,17 @@ files:
 - README.md
 - Rakefile
 - lib/wisper.rb
+- lib/wisper/global_listeners.rb
 - lib/wisper/registration/block.rb
 - lib/wisper/registration/object.rb
+- lib/wisper/registration/object/async_listener.rb
 - lib/wisper/registration/registration.rb
+- lib/wisper/rspec/stub_wisper_publisher.rb
 - lib/wisper/version.rb
+- spec/lib/async_spec.rb
+- spec/lib/global_subscribers_spec.rb
 - spec/lib/integration_spec.rb
+- spec/lib/rspec_extensions_spec.rb
 - spec/lib/simple_example_spec.rb
 - spec/lib/wisper_spec.rb
 - spec/spec_helper.rb
@@ -95,26 +97,24 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -3667309302433800657
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -3667309302433800657
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: pub/sub for Ruby objects
 test_files:
+- spec/lib/async_spec.rb
+- spec/lib/global_subscribers_spec.rb
 - spec/lib/integration_spec.rb
+- spec/lib/rspec_extensions_spec.rb
 - spec/lib/simple_example_spec.rb
 - spec/lib/wisper_spec.rb
 - spec/spec_helper.rb
+has_rdoc: