wisper-event 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e86546d0aef13dd7de8e6fb64877044ee9be46f00d5c32a6c63b6d3bbb66495f
+  data.tar.gz: 7956a180074ca8bce31ec686780e22e1fee8050f231336af39e77740d747f576
+SHA512:
+  metadata.gz: f299ed79f231c972f086e1bb19fe0f527a5f497a099b96fb9b1cd9b00435b6c40ea43622030491a8632af8962e2b04b32fb29f680b8634174438fddc46ebccc8
+  data.tar.gz: 7b9164c5b3ec3e06d55630822e0879fbc9522d10930e658011eb79975d84089e257a399db5deb2e30518edbffbe9c77cf601c63d689cc7cf01c88822bfc952ae

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial release

data/README.md

@@ -0,0 +1,310 @@
+# wisper-event
+
+A structured event extension for the Wisper gem.
+
+## Why wisper-event?
+
+The [Wisper gem](https://github.com/krisleech/wisper) is a popular micro-library for implementing the publisher-subscriber pattern in Ruby. While powerful and flexible, Wisper's approach of broadcasting symbols or strings with unstructured arguments can lead to:
+
+1. **Too loose coupling** - While loose coupling is generally desirable, Wisper's string/symbol-based events make it difficult to track relationships between publishers and subscribers as applications grow
+2. **Unclear interfaces** - Without structured events, argument signatures can change unexpectedly, causing silent failures
+3. **Poor discoverability** - It's challenging to find all handlers for a specific event across a large codebase
+
+**wisper-event** provides a more structured approach by allowing you to use proper Ruby objects as events while maintaining backward compatibility with Wisper's string/symbol-based events. This lets you:
+
+- Gradually migrate your codebase to structured events
+- Have clear, well-defined event interfaces
+- Implement compile-time checking of event handlers
+- Easily find event usage with standard code search tools
+
+This gem was inspired by the original Wisper author's other gems:
+- [wisper_next](https://gitlab.com/kris.leech/wisper_next)
+- [ma](https://gitlab.com/kris.leech/ma)
+
+It solves very particular problem and might be not a good fit for your application.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wisper-event'
+```
+
+And then execute:
+
+```
+bundle install
+```
+
+## Usage
+
+### Enabling wisper-event
+
+After installing the gem, you need to apply the monkey patches:
+
+```ruby
+WisperEvent.apply!
+```
+
+This is best done during your application's initialization.
+
+### Creating structured events
+
+Define your events as plain Ruby classes:
+
+```ruby
+module Event
+  class OrderCreated
+    attr_reader :order_id, :customer_id
+    
+    def initialize(order_id:, customer_id:)
+      @order_id = order_id
+      @customer_id = customer_id
+    end
+  end
+
+  class OrderFailed
+    attr_reader :reason
+    
+    def initialize(reason)
+      @reason = reason
+    end
+  end
+end
+```
+
+### Publishing events
+
+You can publish both traditional Wisper events and structured events from the same publisher:
+
+```ruby
+class OrderService
+  include Wisper::Publisher
+  
+  def create(params)
+    # Business logic...
+    if order.save
+      # Traditional event with arguments
+      broadcast('order_created', order_id: order.id, customer_id: order.customer_id)
+      
+      # Structured event
+      broadcast(Event::OrderCreated.new(order_id: order.id, customer_id: order.customer_id))
+    else
+      # Traditional event
+      broadcast('order_failed', order.errors.full_messages.join(", "))
+      
+      # Structured event
+      broadcast(Event::OrderFailed.new(order.errors.full_messages.join(", ")))
+    end
+  end
+end
+```
+
+### Handling events - traditional approach
+
+The traditional Wisper approach still works:
+
+```ruby
+class OrderNotifier
+  def order_created(order_id:, customer_id:)
+    # Handle the event...
+  end
+  
+  def order_failed(reason)
+    # Handle the failure...
+  end
+end
+
+service = OrderService.new
+service.subscribe(OrderNotifier.new)
+service.create(params)
+```
+
+### Handling events - structured approach
+
+To handle structured events, include the `Wisper::Listener` module and define your handlers using the `on` class method:
+
+```ruby
+lass StructuredOrderHandler
+  include Wisper::Listener
+  
+  def initialize(logger)
+    @logger = logger
+  end
+  
+  on(Event::OrderCreated) do |event|
+    @logger.info("Order #{event.order_id} was created for customer #{event.customer_id}")
+  end
+  
+  on(Event::OrderFailed) do |event|
+    @logger.error("Order creation failed: #{event.reason}")
+  end
+end
+
+service = OrderService.new
+service.subscribe(StructuredOrderHandler.new(logger))
+service.create(params)
+```
+
+### Subscribing with Blocks
+
+You can also subscribe to structured events using blocks:
+
+```ruby
+service = OrderService.new
+service.on(Event::OrderCreated) { |event| puts "Order created: #{event.order_id}" }
+       .on(Event::OrderFailed) { |event| puts "Order failed: #{event.reason}" }
+service.create(params)
+```
+
+## Required event handling
+
+When using `Wisper::Listener`, every structured event **must have** a corresponding handler. If an event is received that the listener doesn't handle, a `Wisper::Listener::UnhandledEventError` will be raised:
+
+```ruby
+class IncompleteListener
+  include Wisper::Listener
+  
+  on(Event::OrderCreated) do |event|
+    # This handles Event::OrderCreated
+  end
+  
+  # Missing handler for Event::OrderFailed!
+end
+
+# This will raise UnhandledEventError when Event::OrderFailed is broadcast
+```
+
+This helps ensure that your listeners are complete and don't silently ignore events.
+
+## Testing
+
+The gem includes RSpec matchers build on top of [wisper-rspec](https://github.com/krisleech/wisper-rspec) for testing broadcasted events:
+
+```ruby
+# Add this to your spec helper
+require 'wisper/rspec/matchers'
+require 'wisper/rspec/event_matchers'
+
+RSpec.configure do |config|
+  config.include(Wisper::RSpec::BroadcastMatcher)
+  config.include(Wisper::RSpec::BroadcastEventMatcher)
+end
+
+# In your specs
+it 'broadcasts the proper event' do
+  service = OrderService.new
+  
+  expect { service.create(valid_params) }
+    .to broadcast_event(Event::OrderCreated).with(order_id: 123, customer_id: 456)
+  
+  expect { service.create(invalid_params) }
+    .to broadcast_event(Event::OrderFailed).with(message: "Invalid params")
+end
+```
+
+## Migrating to structured events
+
+Here's a migration strategy:
+
+1. Start by creating structured events that match your existing string/symbol events
+1. Update your publishers to broadcast both formats
+1. Create structured listeners for new code
+1. Gradually convert existing listeners to the structured format
+1. Once all listeners are updated to use structured events, you can remove the old string/symbol style broadcasts
+
+### Example migration
+
+Before:
+
+```ruby
+# Publisher
+class OrderService
+  include Wisper::Publisher
+  
+  def create(params)
+    if order.save
+      broadcast('order_created', order_id: order.id)
+    else
+      broadcast('order_failed', reason: order.errors.full_messages)
+    end
+  end
+end
+
+# Listener
+class OrderNotifier
+  def order_created(order_id:)
+    # Handle event
+  end
+  
+  def order_failed(reason:)
+    # Handle failure
+  end
+end
+```
+
+After
+
+```ruby
+# Events
+module Event
+  class OrderCreated
+    attr_reader :order_id
+    
+    def initialize(order_id:)
+      @order_id = order_id
+    end
+  end
+
+  class OrderFailed
+    attr_reader :reason
+    
+    def initialize(reason:)
+      @reason = reason
+    end
+  end
+end
+
+# Publisher (during migration)
+class OrderService
+  include Wisper::Publisher
+  
+  def create(params)
+    if order.save
+      # You can remove this line once all listeners are updated
+      broadcast('order_created', order_id: order.id)
+      broadcast(Event::OrderCreated.new(order_id: order.id))
+    else
+      # You can remove this line once all listeners are updated
+      broadcast('order_failed', reason: order.errors.full_messages)
+      broadcast(Event::OrderFailed.new(reason: order.errors.full_messages))
+    end
+  end
+end
+
+# Modified structured listener
+class OrderNotifier
+  include Wisper::Listener
+  
+  on(Event::OrderCreated) do |event|
+    # Handle event
+  end
+  
+  on(Event::OrderFailed) do |event|
+    # Handle failure
+  end
+
+  # If listener is being re-used across different publishers you will be
+  # forced to broadcast structured events across those publishers and handle
+  # all those events in this listener - which is _desired_ behavior
+end
+```
+
+## Limitations and assumptions
+
+- This gem focuses on improving event structure, not on Wisper's delivery mechanisms
+- Global listeners are not supported with structured events
+- Asynchronous event handling is not directly supported - if you need to trigger async jobs, do so explicitly in your listeners
+- Every structured event must be handled by listeners that include `Wisper::Listener`
+- `on` / `with` events mapping is not supported as it makes no sense with structured events

data/lib/wisper/listener.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Wisper
+  module Listener
+    UnhandledEventError = Class.new(StandardError)
+
+    # NOTE: mostly copied from ActiveSupport#underscore
+    def self.generated_method_name(event_class)
+      class_name = event_class.gsub('::', '_')
+      name =
+        class_name
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+
+      "on_#{name}"
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def _wisper_listener?
+      true
+    end
+
+    def trigger(event)
+      method_name = Wisper::Listener.generated_method_name(event.class.name)
+      if respond_to?(method_name)
+        public_send(method_name, event)
+      else
+        raise(
+          UnhandledEventError,
+          "Event #{event.class} not handled in #{self.class}"
+        )
+      end
+    end
+
+    module ClassMethods
+      def on(event_class, &block)
+        method_name = Wisper::Listener.generated_method_name(event_class.name)
+
+        define_method(method_name) do |event|
+          instance_exec(event, &block)
+        end
+      end
+    end
+  end
+end

data/lib/wisper/rspec/event_matchers.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Wisper
+  module RSpec
+    class EventObjectRecorder
+      attr_reader :captured_events
+
+      def initialize
+        @captured_events = []
+      end
+
+      def respond_to?(_method_name, _include_private = false)
+        true
+      end
+
+      def respond_to_missing?(*)
+        true
+      end
+
+      def _wisper_listener?
+        true
+      end
+
+      def method_missing(_method_name, *args)
+        @captured_events << args[0]
+      end
+
+      def trigger(event)
+        @captured_events << event
+      end
+
+      def received_event?(expected_event, expected_attributes = nil)
+        @captured_events.any? do |event|
+          expected_class = expected_event.is_a?(Class) ? expected_event : expected_event.class
+
+          if event.is_a?(expected_class)
+            if expected_attributes.nil?
+              expected_event.is_a?(Class) || event == expected_event
+            else
+              expected_attributes.all? do |key, value|
+                event.respond_to?(key) && event.public_send(key) == value
+              end
+            end
+          end
+        end
+      end
+    end
+
+    module BroadcastEventMatcher
+      class EventMatcher
+        include ::RSpec::Matchers::Composable
+
+        def initialize(event)
+          @expected_event = event
+          @expected_attributes = nil
+          @is_class = event.is_a?(Class)
+        end
+
+        def with(attributes)
+          @expected_attributes = attributes
+          self
+        end
+
+        def supports_block_expectations?
+          true
+        end
+
+        def matches?(block)
+          @recorder = EventObjectRecorder.new
+
+          Wisper.subscribe(@recorder) do
+            block.call
+          end
+
+          @recorder.received_event?(@expected_event, @expected_attributes)
+        end
+
+        def description
+          desc = + "broadcast event of type #{event_class_name}"
+          desc << " with attributes #{@expected_attributes.inspect}" if @expected_attributes
+          desc
+        end
+
+        def failure_message
+          msg = + "expected publisher to broadcast event of type #{event_class_name}"
+          msg << " with attributes #{@expected_attributes.inspect}" if @expected_attributes
+          msg << captured_events_list
+          msg
+        end
+
+        def failure_message_when_negated
+          msg = + "expected publisher not to broadcast event of type #{event_class_name}"
+          msg << " with attributes #{@expected_attributes.inspect}" if @expected_attributes
+          msg
+        end
+
+        def diffable?
+          true
+        end
+
+        def expected
+          @expected_event
+        end
+
+        def actual
+          @recorder.captured_events
+        end
+
+        private
+
+        def captured_events_list
+          if @recorder.captured_events.any?
+            events = @recorder.captured_events.map do |event|
+              event.is_a?(Array) ? "#{event[0]}(#{event[1..].join(', ')})" : event.inspect
+            end
+            " (actual events broadcast: #{events.join(', ')})"
+          else
+            ' (no events broadcast)'
+          end
+        end
+
+        def event_class_name
+          @is_class ? @expected_event.name : @expected_event.class.name
+        end
+      end
+
+      def broadcast_event(event)
+        EventMatcher.new(event)
+      end
+    end
+  end
+end
+
+::RSpec::Matchers.define_negated_matcher :not_broadcast_event, :broadcast_event
+
+RSpec.configure do |config|
+  config.include Wisper::RSpec::BroadcastEventMatcher
+end

data/lib/wisper-event.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'wisper_event'

data/lib/wisper_event/patches/block_registration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module WisperEvent
+  module Patches
+    module BlockRegistration
+      def broadcast(event, _publisher, *args, **kwargs)
+        return unless should_broadcast?(event)
+
+        if event.is_a?(String) || event.is_a?(Symbol)
+          super
+        else
+          # Structured event
+          listener.call(event)
+        end
+      end
+    end
+  end
+end
+
+Wisper::BlockRegistration.prepend(WisperEvent::Patches::BlockRegistration)

data/lib/wisper_event/patches/events.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module WisperEvent
+  module Patches
+    module Events
+      def include?(event)
+        if event.is_a?(String) || event.is_a?(Symbol)
+          super
+        # Structured event
+        elsif list.is_a?(Class)
+          event.is_a?(list)
+        elsif list.is_a?(Enumerable) && list.any? { |item| item.is_a?(Class) }
+          list.any? { |item| item.is_a?(Class) && event.is_a?(item) }
+        else
+          super
+        end
+      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 },
+          # Structured event
+          Class => ->(event) { event.is_a?(list) }
+        }
+      end
+    end
+  end
+end
+
+Wisper::ValueObjects::Events.prepend(WisperEvent::Patches::Events)

data/lib/wisper_event/patches/object_registration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module WisperEvent
+  module Patches
+    module ObjectRegistration
+      def broadcast(event, publisher, *args, **kwargs)
+        if event.is_a?(String) || event.is_a?(Symbol)
+          super
+        # Structured event
+        # Wisper::Listeners are required to handle structured events
+        elsif listener.respond_to?(:_wisper_listener?)
+          listener.trigger(event)
+          # as method names for events are auto generated
+          # we might as well discard structured events for non-structured listeners
+        end
+      end
+    end
+  end
+end
+
+Wisper::ObjectRegistration.prepend(WisperEvent::Patches::ObjectRegistration)

data/lib/wisper_event/patches/publisher.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module WisperEvent
+  module Patches
+    module Publisher
+      def broadcast(event, *args, **kwargs)
+        registrations.each do |registration|
+          if event.is_a?(String) || event.is_a?(Symbol)
+            registration.broadcast(clean_event(event), self, *args, **kwargs)
+          else
+            # Structured event - pass them directly
+            registration.broadcast(event, self, *args, **kwargs)
+          end
+        end
+        self
+      end
+    end
+  end
+end
+
+Wisper::Publisher.prepend(WisperEvent::Patches::Publisher)

data/lib/wisper_event/patches.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'patches/object_registration'
+require_relative 'patches/block_registration'
+require_relative 'patches/events'
+require_relative 'patches/publisher'

data/lib/wisper_event/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WisperEvent
+  VERSION = '0.1.0'
+end

data/lib/wisper_event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'wisper'
+require_relative 'wisper_event/version'
+
+module WisperEvent
+  class << self
+    def apply!
+      require_relative 'wisper/listener'
+      require_relative 'wisper_event/patches'
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: wisper-event
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rafal Wojsznis
+bindir: bin
+cert_chain: []
+date: 2025-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: wisper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+description: Structured events for Wisper
+email:
+- rafal.wojsznis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/wisper-event.rb
+- lib/wisper/listener.rb
+- lib/wisper/rspec/event_matchers.rb
+- lib/wisper_event.rb
+- lib/wisper_event/patches.rb
+- lib/wisper_event/patches/block_registration.rb
+- lib/wisper_event/patches/events.rb
+- lib/wisper_event/patches/object_registration.rb
+- lib/wisper_event/patches/publisher.rb
+- lib/wisper_event/version.rb
+homepage: https://github.com/rwojsznis/wisper-event
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.1
+specification_version: 4
+summary: Backward-compatible support for structured events in Wisper
+test_files: []