siftery-wisper 2.0.1

data/lib/wisper/registration/registration.rb

@@ -0,0 +1,19 @@
+# @api private
+
+module Wisper
+  class Registration
+    attr_reader :on, :listener, :options
+
+    def initialize(listener, options)
+      @listener = listener
+      @options = options
+      @on = ValueObjects::Events.new options[:on]
+    end
+
+    private
+
+    def should_broadcast?(event)
+      on.include? event
+    end
+  end
+end

data/lib/wisper/temporary_listeners.rb

@@ -0,0 +1,41 @@
+# Handles temporary global subscriptions
+
+# @api private
+
+module Wisper
+  class TemporaryListeners
+
+    def self.subscribe(*listeners, &block)
+      new.subscribe(*listeners, &block)
+    end
+
+    def self.registrations
+      new.registrations
+    end
+
+    def subscribe(*listeners, &block)
+      options = listeners.last.is_a?(Hash) ? listeners.pop : {}
+      begin
+        listeners.each { |listener| registrations << ObjectRegistration.new(listener, options) }
+        yield
+      ensure
+        clear
+      end
+      self
+    end
+
+    def registrations
+      Thread.current[key] ||= Set.new
+    end
+
+    private
+
+    def clear
+      registrations.clear
+    end
+
+    def key
+      '__wisper_temporary_listeners'
+    end
+  end
+end

data/lib/wisper/value_objects/events.rb

@@ -0,0 +1,61 @@
+module Wisper
+  module ValueObjects #:nodoc:
+    # Describes allowed events
+    #
+    # Duck-types the argument to quack like array of strings
+    # when responding to the {#include?} method call.
+    class Events
+
+      # @!scope class
+      # @!method new(on)
+      # Initializes a 'list' of events
+      #
+      # @param [NilClass, String, Symbol, Array, Regexp] list
+      #
+      # @raise [ArgumentError]
+      #   if an argument if of unsupported type
+      #
+      # @return [undefined]
+      def initialize(list)
+        @list = list
+      end
+
+      # Check if given event is 'included' to the 'list' of events
+      #
+      # @param [#to_s] event
+      #
+      # @return [Boolean]
+      def include?(event)
+        appropriate_method.call(event.to_s)
+      end
+
+      private
+
+      def methods
+        {
+          NilClass   => ->(_event) { true },
+          String     => ->(event)  { list == event },
+          Symbol     => ->(event)  { list.to_s == event },
+          Enumerable => ->(event)  { list.map(&:to_s).include? event },
+          Regexp     => ->(event)  { list.match(event) || false }
+        }
+      end
+
+      def list
+        @list
+      end
+
+      def appropriate_method
+        @appropriate_method ||= methods[recognized_type]
+      end
+
+      def recognized_type
+        methods.keys.detect(&list.method(:is_a?)) || type_not_recognized
+      end
+
+      def type_not_recognized
+        fail(ArgumentError, "#{list.class} not supported for `on` argument")
+      end
+    end # class Events
+  end # module ValueObjects
+end # module Wisper

data/lib/wisper/value_objects/prefix.rb

@@ -0,0 +1,29 @@
+module Wisper
+  module ValueObjects #:nodoc:
+    # Prefix for notifications
+    #
+    # @example
+    #   Wisper::ValueObjects::Prefix.new nil    # => ""
+    #   Wisper::ValueObjects::Prefix.new "when" # => "when_"
+    #   Wisper::ValueObjects::Prefix.new true   # => "on_"
+    class Prefix < String
+      class << self
+        attr_accessor :default
+      end
+
+      # @param [true, nil, #to_s] value
+      #
+      # @return [undefined]
+      def initialize(value = nil)
+        super "#{ (value == true) ? default : value }_"
+        replace "" if self == "_"
+      end
+
+      private
+
+      def default
+        self.class.default || 'on'
+      end
+    end # class Prefix
+  end # module ValueObjects
+end # module Wisper

data/lib/wisper/version.rb

@@ -0,0 +1,3 @@
+module Wisper
+  VERSION = "2.0.1"
+end

data/siftery-wisper.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'wisper/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "siftery-wisper"
+  gem.version       = Wisper::VERSION
+  gem.authors       = ["Shubham Kumar"]
+  gem.email         = ["shubh2336@gmail.com"]
+  gem.description   = <<-DESC
+    A micro library providing objects with Publish-Subscribe capabilities.
+    Both synchronous (in-process) and asynchronous (out-of-process) subscriptions are supported.
+    Check out the Wiki for articles, guides and examples: https://github.com/shubh2336/wisper/wiki
+  DESC
+  gem.summary       = "A micro library providing objects with Publish-Subscribe capabilities"
+  gem.homepage      = "https://github.com/shubh2336/wisper"
+  gem.license       = "MIT"
+
+  signing_key = File.expand_path(ENV['HOME'].to_s + '/.ssh/gem-private_key.pem')
+
+  if File.exist?(signing_key)
+    gem.signing_key = signing_key
+    gem.cert_chain  = ['gem-public_cert.pem']
+  end
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/spec/lib/global_listeners_spec.rb

@@ -0,0 +1,82 @@
+describe Wisper::GlobalListeners do
+  let(:global_listener)  { double('listener') }
+  let(:local_listener)   { double('listener') }
+  let(:publisher)        { publisher_class.new }
+
+  describe '.subscribe' do
+    it 'adds given listener to every publisher' do
+      Wisper::GlobalListeners.subscribe(global_listener)
+      expect(global_listener).to receive(:it_happened)
+      publisher.send(:broadcast, :it_happened)
+    end
+
+    it 'works with options' do
+      Wisper::GlobalListeners.subscribe(global_listener, :on => :it_happened,
+                                                   :with => :woot)
+      expect(global_listener).to receive(:woot).once
+      expect(global_listener).not_to receive(:it_happened_again)
+      publisher.send(:broadcast, :it_happened)
+      publisher.send(:broadcast, :it_happened_again)
+    end
+
+    it 'works along side local listeners' do
+      # global listener
+      Wisper::GlobalListeners.subscribe(global_listener)
+
+      # local listener
+      publisher.subscribe(local_listener)
+
+      expect(global_listener).to receive(:it_happened)
+      expect(local_listener).to receive(:it_happened)
+
+      publisher.send(:broadcast, :it_happened)
+    end
+
+    it 'can be scoped to classes' do
+      publisher_1 = publisher_class.new
+      publisher_2 = publisher_class.new
+      publisher_3 = publisher_class.new
+
+      Wisper::GlobalListeners.subscribe(global_listener, :scope => [publisher_1.class,
+                                                              publisher_2.class])
+
+      expect(global_listener).to receive(:it_happened_1).once
+      expect(global_listener).to receive(:it_happened_2).once
+      expect(global_listener).not_to receive(:it_happened_3)
+
+      publisher_1.send(:broadcast, :it_happened_1)
+      publisher_2.send(:broadcast, :it_happened_2)
+      publisher_3.send(:broadcast, :it_happened_3)
+    end
+
+    it 'is threadsafe' do
+      num_threads = 100
+      (1..num_threads).to_a.map do
+        Thread.new do
+          Wisper::GlobalListeners.subscribe(Object.new)
+          sleep(rand) # a little chaos
+        end
+      end.each(&:join)
+
+      expect(Wisper::GlobalListeners.listeners.size).to eq num_threads
+    end
+  end
+
+  describe '.listeners' do
+    it 'returns collection of global listeners' do
+      Wisper::GlobalListeners.subscribe(global_listener)
+      expect(Wisper::GlobalListeners.listeners).to eq [global_listener]
+    end
+
+    it 'returns an immutable collection' do
+      expect(Wisper::GlobalListeners.listeners).to be_frozen
+      expect { Wisper::GlobalListeners.listeners << global_listener }.to raise_error(RuntimeError)
+    end
+  end
+
+  it '.clear clears all global listeners' do
+    Wisper::GlobalListeners.subscribe(global_listener)
+    Wisper::GlobalListeners.clear
+    expect(Wisper::GlobalListeners.listeners).to be_empty
+  end
+end

data/spec/lib/integration_spec.rb

@@ -0,0 +1,56 @@
+# Example
+class MyCommand
+  include Wisper::Publisher
+
+  def execute(be_successful)
+    if be_successful
+      broadcast('success', 'hello')
+    else
+      broadcast('failure', 'world')
+    end
+  end
+end
+
+describe Wisper do
+
+  it 'subscribes object to all published events' do
+    listener = double('listener')
+    expect(listener).to receive(:success).with('hello')
+
+    command = MyCommand.new
+
+    command.subscribe(listener)
+
+    command.execute(true)
+  end
+
+  it 'maps events to different methods' do
+    listener_1 = double('listener')
+    listener_2 = double('listener')
+    expect(listener_1).to receive(:happy_days).with('hello')
+    expect(listener_2).to receive(:sad_days).with('world')
+
+    command = MyCommand.new
+
+    command.subscribe(listener_1, :on => :success, :with => :happy_days)
+    command.subscribe(listener_2, :on => :failure, :with => :sad_days)
+
+    command.execute(true)
+    command.execute(false)
+  end
+
+  it 'subscribes block can be chained' do
+    insider = double('Insider')
+
+    expect(insider).to receive(:render).with('success')
+    expect(insider).to receive(:render).with('failure')
+
+    command = MyCommand.new
+
+    command.on(:success) { |message| insider.render('success') }
+           .on(:failure) { |message| insider.render('failure') }
+
+    command.execute(true)
+    command.execute(false)
+  end
+end

data/spec/lib/simple_example_spec.rb

@@ -0,0 +1,21 @@
+class MyPublisher
+  include Wisper::Publisher
+
+  def do_something
+    # ...
+    broadcast(:bar, self)
+    broadcast(:foo, self)
+  end
+end
+
+describe 'simple publishing' do
+  it 'subscribes listener to events' do
+    listener = double('listener')
+    expect(listener).to receive(:foo).with instance_of MyPublisher
+    expect(listener).to receive(:bar).with instance_of MyPublisher
+
+    my_publisher = MyPublisher.new
+    my_publisher.subscribe(listener)
+    my_publisher.do_something
+  end
+end

data/spec/lib/temporary_global_listeners_spec.rb

@@ -0,0 +1,67 @@
+describe Wisper::TemporaryListeners do
+  let(:listener_1) { double('listener', :to_a => nil) } # [1]
+  let(:listener_2) { double('listener', :to_a => nil) }
+
+  let(:publisher)  { publisher_class.new }
+
+  describe '.subscribe' do
+    it 'globally subscribes listener for duration of given block' do
+
+      expect(listener_1).to receive(:success)
+      expect(listener_1).to_not receive(:failure)
+
+      Wisper::TemporaryListeners.subscribe(listener_1) do
+        publisher.instance_eval { broadcast(:success) }
+      end
+
+      publisher.instance_eval { broadcast(:failure) }
+    end
+
+    it 'globally subscribes listeners for duration of given block' do
+
+      expect(listener_1).to receive(:success)
+      expect(listener_1).to_not receive(:failure)
+
+      expect(listener_2).to receive(:success)
+      expect(listener_2).to_not receive(:failure)
+
+      Wisper::TemporaryListeners.subscribe(listener_1, listener_2) do
+        publisher.instance_eval { broadcast(:success) }
+      end
+
+      publisher.instance_eval { broadcast(:failure) }
+    end
+
+    it 'is thread safe' do
+      num_threads = 20
+      (1..num_threads).to_a.map do
+        Thread.new do
+          Wisper::TemporaryListeners.registrations << Object.new
+          expect(Wisper::TemporaryListeners.registrations.size).to eq 1
+        end
+      end.each(&:join)
+
+      expect(Wisper::TemporaryListeners.registrations).to be_empty
+    end
+
+    it 'clears registrations when an exception occurs' do
+      MyError = Class.new(StandardError)
+
+      begin
+        Wisper::TemporaryListeners.subscribe(listener_1) do
+          raise MyError
+        end
+      rescue MyError
+      end
+
+      expect(Wisper::TemporaryListeners.registrations).to be_empty
+    end
+
+    it 'returns self' do
+      expect(Wisper::TemporaryListeners.subscribe {}).to be_an_instance_of(Wisper::TemporaryListeners)
+    end
+  end
+end
+
+# [1] stubbing `to_a` prevents `Double "listener" received unexpected message
+# :to_a with (no args)` on MRI 1.9.2 when a double is passed to `Array()`.

data/spec/lib/wisper/broadcasters/logger_broadcaster_spec.rb

@@ -0,0 +1,93 @@
+module Wisper
+  module Broadcasters
+
+    describe LoggerBroadcaster do
+
+      describe 'integration tests:' do
+        let(:publisher) { publisher_class.new }
+        let(:listener)  { double }
+        let(:logger)    { double.as_null_object }
+
+        it 'broadcasts the event to the listener' do
+          publisher.subscribe(listener, :broadcaster => LoggerBroadcaster.new(logger, Wisper::Broadcasters::SendBroadcaster.new))
+          expect(listener).to receive(:it_happened).with(1, 2)
+          publisher.send(:broadcast, :it_happened, 1, 2)
+        end
+      end
+
+      describe 'unit tests:' do
+        let(:publisher)   { classy_double('Publisher',  id: 1) }
+        let(:listener)  { classy_double('Listener', id: 2) }
+        let(:logger)      { double('Logger').as_null_object }
+        let(:broadcaster) { double('Broadcaster').as_null_object }
+        let(:event)       { 'thing_created' }
+
+        subject           { LoggerBroadcaster.new(logger, broadcaster) }
+
+        describe '#broadcast' do
+          context 'without arguments' do
+            let(:args) { [] }
+
+            it 'logs published event' do
+              expect(logger).to receive(:info).with('[WISPER] Publisher#1 published thing_created to Listener#2 with no arguments')
+              subject.broadcast(listener, publisher, event, args)
+            end
+
+            it 'delegates broadcast to a given broadcaster' do
+              expect(broadcaster).to receive(:broadcast).with(listener, publisher, event, args)
+              subject.broadcast(listener, publisher, event, args)
+            end
+          end
+
+          context 'with arguments' do
+            let(:args) { [arg_double(id: 3), arg_double(id: 4)] }
+
+            it 'logs published event and arguments' do
+              expect(logger).to receive(:info).with('[WISPER] Publisher#1 published thing_created to Listener#2 with Argument#3, Argument#4')
+              subject.broadcast(listener, publisher, event, args)
+            end
+
+            it 'delegates broadcast to a given broadcaster' do
+              expect(broadcaster).to receive(:broadcast).with(listener, publisher, event, args)
+              subject.broadcast(listener, publisher, event, args)
+            end
+
+            context 'when argument is a hash' do
+              let(:args) { [hash] }
+              let(:hash) { {key: 'value'} }
+
+              it 'logs published event and arguments' do
+                expect(logger).to receive(:info).with("[WISPER] Publisher#1 published thing_created to Listener#2 with Hash##{hash.object_id}: #{hash.inspect}")
+                subject.broadcast(listener, publisher, event, args)
+              end
+            end
+
+            context 'when argument is an integer' do
+              let(:args) { [number] }
+              let(:number) { 10 }
+
+              it 'logs published event and arguments' do
+                expect(logger).to receive(:info).with("[WISPER] Publisher#1 published thing_created to Listener#2 with #{number.class.name}##{number.object_id}: 10")
+                subject.broadcast(listener, publisher, event, args)
+              end
+            end
+          end
+
+        end
+
+        # provides a way to specify `double.class.name` easily
+        def classy_double(klass, options)
+          double(klass, options.merge(class: double_class(klass)))
+        end
+
+        def arg_double(options)
+          classy_double('Argument', options)
+        end
+
+        def double_class(name)
+          double(name: name)
+        end
+      end
+    end
+  end
+end