wisper-compat 4.0.0

data/lib/wisper/configuration.rb

@@ -0,0 +1,44 @@
+require 'forwardable'
+
+module Wisper
+  class Configuration
+    attr_reader :broadcasters
+
+    def initialize
+      @broadcasters = Broadcasters.new
+    end
+
+    # registers a broadcaster, referenced by key
+    #
+    # @param key [String, #to_s] an arbitrary key
+    # @param broadcaster [#broadcast] a broadcaster
+    def broadcaster(key, broadcaster)
+      @broadcasters[key] = broadcaster
+      self
+    end
+
+    # sets the default value for prefixes
+    #
+    # @param [#to_s] value
+    #
+    # @return [String]
+    def default_prefix=(value)
+      ValueObjects::Prefix.default = value
+    end
+
+    class Broadcasters
+      extend Forwardable
+
+      def_delegators :@data, :[], :[]=, :empty?, :include?, :clear, :keys, :to_h
+
+      def initialize
+        @data = {}
+      end
+
+      def fetch(key)
+        raise KeyError, "broadcaster not found for #{key}" unless include?(key)
+        @data[key]
+      end
+    end
+  end
+end

data/lib/wisper/global_listeners.rb

@@ -0,0 +1,72 @@
+# Handles global subscriptions
+
+# @api private
+
+require 'singleton'
+
+module Wisper
+  class GlobalListeners
+    include Singleton
+
+    def initialize
+      @registrations = Set.new
+      @mutex         = Mutex.new
+    end
+
+    def subscribe(*listeners, **options)
+      with_mutex do
+        listeners.each do |listener|
+          @registrations << ObjectRegistration.new(listener, **options)
+        end
+      end
+      self
+    end
+
+    def unsubscribe(*listeners)
+      with_mutex do
+        @registrations.delete_if do |registration|
+          listeners.include?(registration.listener)
+        end
+      end
+      self
+    end
+
+    def registrations
+      with_mutex { @registrations }
+    end
+
+    def listeners
+      registrations.map(&:listener).freeze
+    end
+
+    def clear
+      with_mutex { @registrations.clear }
+    end
+
+    def self.subscribe(*listeners, **options)
+      instance.subscribe(*listeners, **options)
+    end
+
+    def self.unsubscribe(*listeners)
+      instance.unsubscribe(*listeners)
+    end
+
+    def self.registrations
+      instance.registrations
+    end
+
+    def self.listeners
+      instance.listeners
+    end
+
+    def self.clear
+      instance.clear
+    end
+
+    private
+
+    def with_mutex
+      @mutex.synchronize { yield }
+    end
+  end
+end

data/lib/wisper/publisher.rb

@@ -0,0 +1,89 @@
+module Wisper
+  module Publisher
+    def listeners
+      registrations.map(&:listener).freeze
+    end
+
+    # subscribe a listener
+    #
+    # @example
+    #   my_publisher.subscribe(MyListener.new)
+    #
+    # @return [self]
+    def subscribe(listener, **options)
+      raise ArgumentError, "#{__method__} does not take a block, did you mean to call #on instead?" if block_given?
+      local_registrations << ObjectRegistration.new(listener, **options)
+      self
+    end
+
+    # subscribe a block
+    #
+    # @example
+    #   my_publisher.on(:order_created) { |args| ... }
+    #
+    # @return [self]
+    def on(*events, &block)
+      raise ArgumentError, 'must give at least one event' if events.empty?
+      raise ArgumentError, 'must pass a block' if !block
+      local_registrations << BlockRegistration.new(block, on: events)
+      self
+    end
+
+    # broadcasts an event
+    #
+    # @example
+    #   def call
+    #     # ...
+    #     broadcast(:finished, self)
+    #   end
+    #
+    # @return [self]
+    def broadcast(event, *args, **kwargs)
+      registrations.each do | registration |
+        registration.broadcast(clean_event(event), self, *args, **kwargs)
+      end
+      self
+    end
+
+    alias :publish :broadcast
+
+    private :broadcast, :publish
+
+    module ClassMethods
+      # subscribe a listener
+      #
+      # @example
+      #   MyPublisher.subscribe(MyListener.new)
+      #
+      def subscribe(listener, **options)
+        GlobalListeners.subscribe(listener, **options.merge(:scope => self))
+      end
+    end
+
+    private
+
+    def local_registrations
+      @local_registrations ||= Set.new
+    end
+
+    def global_registrations
+      GlobalListeners.registrations
+    end
+
+    def temporary_registrations
+      TemporaryListeners.registrations
+    end
+
+    def registrations
+      local_registrations + global_registrations + temporary_registrations
+    end
+
+    def clean_event(event)
+      event.to_s.gsub('-', '_')
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/wisper/registration/block.rb

@@ -0,0 +1,11 @@
+# @api private
+
+module Wisper
+  class BlockRegistration < Registration
+    def broadcast(event, publisher, *args, **kwargs)
+      if should_broadcast?(event)
+        listener.call(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/wisper/registration/object.rb

@@ -0,0 +1,43 @@
+# @api private
+
+module Wisper
+  class ObjectRegistration < Registration
+    attr_reader :with, :prefix, :allowed_classes, :broadcaster
+
+    def initialize(listener, **options)
+      super(listener, **options)
+      @with   = options[:with]
+      @prefix = ValueObjects::Prefix.new options[:prefix]
+      @allowed_classes = Array(options[:scope]).map(&:to_s).to_set
+      @broadcaster = map_broadcaster(options[:async] || options[:broadcaster])
+    end
+
+    def broadcast(event, publisher, *args, **kwargs)
+      method_to_call = map_event_to_method(event)
+      if should_broadcast?(event) && listener.respond_to?(method_to_call) && publisher_in_scope?(publisher)
+        broadcaster.broadcast(listener, publisher, method_to_call, *args, **kwargs)
+      end
+    end
+
+    private
+
+    def publisher_in_scope?(publisher)
+      allowed_classes.empty? || publisher.class.ancestors.any? { |ancestor| allowed_classes.include?(ancestor.to_s) }
+    end
+
+    def map_event_to_method(event)
+      prefix + (with || event).to_s
+    end
+
+    def map_broadcaster(value)
+      return value if value.respond_to?(:broadcast)
+      value = :async   if value == true
+      value = :default if value == nil
+      configuration.broadcasters.fetch(value)
+    end
+
+    def configuration
+      Wisper.configuration
+    end
+  end
+end

data/lib/wisper/registration/registration.rb

@@ -0,0 +1,18 @@
+# @api private
+
+module Wisper
+  class Registration
+    attr_reader :on, :listener
+
+    def initialize(listener, **options)
+      @listener = listener
+      @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, **options, &block)
+      new.subscribe(*listeners, **options, &block)
+    end
+
+    def self.registrations
+      new.registrations
+    end
+
+    def subscribe(*listeners, **options, &_block)
+      new_registrations = build_registrations(*listeners, **options)
+
+      begin
+        registrations.merge new_registrations
+        yield
+      ensure
+        registrations.subtract new_registrations
+      end
+      self
+    end
+
+    def registrations
+      Thread.current[key] ||= Set.new
+    end
+
+    private
+
+    def build_registrations(*listeners, **options)
+      listeners.map { |listener| ObjectRegistration.new(listener, **options) }
+    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 = "4.0.0"
+end

data/lib/wisper.rb

@@ -0,0 +1,65 @@
+require 'set'
+require 'wisper/version'
+require 'wisper/configuration'
+require 'wisper/publisher'
+require 'wisper/value_objects/prefix'
+require 'wisper/value_objects/events'
+require 'wisper/registration/registration'
+require 'wisper/registration/object'
+require 'wisper/registration/block'
+require 'wisper/global_listeners'
+require 'wisper/temporary_listeners'
+require 'wisper/broadcasters/send_broadcaster'
+require 'wisper/broadcasters/logger_broadcaster'
+
+module Wisper
+  # Examples:
+  #
+  #   Wisper.subscribe(AuditRecorder.new)
+  #
+  #   Wisper.subscribe(AuditRecorder.new, StatsRecorder.new)
+  #
+  #   Wisper.subscribe(AuditRecorder.new, on: 'order_created')
+  #
+  #   Wisper.subscribe(AuditRecorder.new, scope: 'MyPublisher')
+  #
+  #   Wisper.subscribe(AuditRecorder.new, StatsRecorder.new) do
+  #     # ..
+  #   end
+  #
+  def self.subscribe(*args, **kwargs, &block)
+    if block_given?
+      TemporaryListeners.subscribe(*args, **kwargs, &block)
+    else
+      GlobalListeners.subscribe(*args, **kwargs)
+    end
+  end
+
+  def self.unsubscribe(*listeners)
+    GlobalListeners.unsubscribe(*listeners)
+  end
+
+  def self.publisher
+    Publisher
+  end
+
+  def self.clear
+    GlobalListeners.clear
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.setup
+    configure do |config|
+      config.broadcaster(:default, Broadcasters::SendBroadcaster.new)
+    end
+  end
+end
+
+Wisper.setup

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