Wisper Documentation

To process events asynchronously, pass async: true to the subscribe method. This requires an asynchronous adapter (e.g., wisper-sidekiq, wisper-activejob).

If you subscribe a class instead of an instance for async handling, the event methods must be defined as class methods.

To use Wisper in your Ruby application, add the following line to your Gemfile:

gem 'wisper', '~> 3.0'

Any object can be subscribed to a publisher at runtime. The listener object must implement a method named after the event being broadcast.

cancel_order = CancelOrder.new
cancel_order.subscribe(OrderNotifier.new)

# The listener must have a matching method:
class OrderNotifier
  def cancel_order_successful(order_id)
    # handle event
  end
end

You can limit global listeners so they only respond to events from specific publisher classes or their subclasses using the scope: option.

# Using symbols, classes, or strings
Wisper.subscribe(MyListener.new, scope: :MyPublisher)
Wisper.subscribe(MyListener.new, scope: MyPublisher)
Wisper.subscribe(MyListener.new, scope: "MyPublisher")

# Multiple scopes
Wisper.subscribe(MyListener.new, scope: [:MyPublisher, :MyOtherPublisher])

To enable a class to broadcast events, include the Wisper::Publisher module (or the alias Wisper.publisher). Use the broadcast method (aliased as publish) to emit events with any number of arguments.

class CancelOrder
  include Wisper::Publisher

  def call(order_id)
    # ... business logic ...
    if order.cancelled?
      broadcast(:cancel_order_successful, order.id)
    else
      broadcast(:cancel_order_failed, order.id)
    end
  end
end

You can subscribe blocks to specific events using the on method. You can chain multiple on calls or pass multiple event names to a single on call.

Warning: Do not use return inside a subscribed block, as it will prevent subsequent listeners from receiving the event.

# Chaining single events
cancel_order.on(:cancel_order_successful) { |order_id| ... }
            .on(:cancel_order_failed)     { |order_id| ... }

# Multiple events for one block
cancel_order.on(:cancel_order_successful) { |order_id| ... }
            .on(:cancel_order_failed, :cancel_order_invalid) { |order_id| ... }

Wisper provides several ways to customize how listeners receive events:

• on:: Limit a listener to specific events (accepts Symbol, String, Array, or Regexp).
• prefix:: Add a prefix to the event name (e.g., prefix: :on turns post_created into on_post_created). Passing true uses the default prefix on_.
• with:: Map an event to a specific method name on the listener.

Use the subscribe method to register an object as a listener for events broadcast by the publisher. You can subscribe an instance of a listener or, if using the class-level subscribe method, register a listener globally for that class.

Note: subscribe does not accept a block. If you want to use a block, use the on method instead.

Use Wisper::Broadcasters::LoggerBroadcaster to wrap an existing broadcaster. This decorator logs every broadcast event to the provided logger using the [WISPER] prefix. The log entry includes the publisher's identity, the event name, the listener's identity, and details about any passed arguments or keyword arguments.

To use it, initialize it with a logger object (that responds to .info) and the broadcaster you wish to wrap.