Description
Note: Wisper was originally extracted from a Rails codebase but is not dependant on Rails.
wisper alternatives and similar gems
Based on the "Abstraction" category.
Alternatively, view wisper alternatives based on common mentions on social networks and blogs.
-
Amoeba
A ruby gem to allow the copying of ActiveRecord objects and their associated children, configurable with a DSL on the model -
Waterfall
A slice of functional programming to chain ruby services and blocks, thus providing a new approach to flow control. Make them flow! -
u-service
Represent use cases in a simple and powerful way while writing modular, expressive and sequentially logical code. -
Smart Init - Simple service objects in Ruby
A simple gem for eliminating Ruby initializers boilerplate code, and providing unified service objects API -
SuperModule
SuperModule allows defining class methods and method invocations the same way a super class does without using def included(base). This also succeeds ActiveSupport::Concern by offering lighter syntax -
Invokable
Objects are functions! Treat any Object or Class as a Proc (like Enumerable but for Procs). -
EasilyTypable
Ruby module that facilitates English-like type checking in an inheritance hierarchy via "type_name?" methods -
dry-rb
dry-rb is a collection of next-generation Ruby libraries, each intended to encapsulate a common task.
Scout Monitoring - Performance metrics and, now, Logs Management Monitoring with Scout Monitoring
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest.
Do you think we are missing an alternative of wisper or a related project?
README
Wisper
A micro library providing Ruby objects with Publish-Subscribe capabilities
- Decouple core business logic from external concerns in Hexagonal style architectures
- Use as an alternative to ActiveRecord callbacks and Observers in Rails apps
- Connect objects based on context without permanence
- Publish events synchronously or asynchronously
Note: Wisper was originally extracted from a Rails codebase but is not dependant on Rails.
Please also see the Wiki for more additional information and articles.
For greenfield applications you might also be interested in WisperNext and Ma.
Installation
Add this line to your application's Gemfile:
gem 'wisper', '2.0.0'
Usage
Any class with the Wisper::Publisher
module included can broadcast events
to subscribed listeners. Listeners subscribe, at runtime, to the publisher.
Publishing
class CancelOrder
include Wisper::Publisher
def call(order_id)
order = Order.find_by_id(order_id)
# business logic...
if order.cancelled?
broadcast(:cancel_order_successful, order.id)
else
broadcast(:cancel_order_failed, order.id)
end
end
end
When a publisher broadcasts an event it can include any number of arguments.
The broadcast
method is also aliased as publish
.
You can also include Wisper.publisher
instead of Wisper::Publisher
.
Subscribing
Objects
Any object can be subscribed as a listener.
cancel_order = CancelOrder.new
cancel_order.subscribe(OrderNotifier.new)
cancel_order.call(order_id)
The listener would need to implement a method for every event it wishes to receive.
class OrderNotifier
def cancel_order_successful(order_id)
order = Order.find_by_id(order_id)
# notify someone ...
end
end
Blocks
Blocks can be subscribed to single events and can be chained.
cancel_order = CancelOrder.new
cancel_order.on(:cancel_order_successful) { |order_id| ... }
.on(:cancel_order_failed) { |order_id| ... }
cancel_order.call(order_id)
You can also subscribe to multiple events using on
by passing
additional events as arguments.
cancel_order = CancelOrder.new
cancel_order.on(:cancel_order_successful) { |order_id| ... }
.on(:cancel_order_failed,
:cancel_order_invalid) { |order_id| ... }
cancel_order.call(order_id)
Do not return
from inside a subscribed block, due to the way
Ruby treats blocks
this will prevent any subsequent listeners having their events delivered.
Handling Events Asynchronously
cancel_order.subscribe(OrderNotifier.new, async: true)
Wisper has various adapters for asynchronous event handling, please refer to wisper-celluloid, wisper-sidekiq, wisper-activejob, wisper-que or wisper-resque.
Depending on the adapter used the listener may need to be a class instead of an object. In this situation, every method corresponding to events should be declared as a class method, too. For example:
class OrderNotifier
# declare a class method if you are subscribing the listener class instead of its instance like:
# cancel_order.subscribe(OrderNotifier)
#
def self.cancel_order_successful(order_id)
order = Order.find_by_id(order_id)
# notify someone ...
end
end
ActionController
class CancelOrderController < ApplicationController
def create
cancel_order = CancelOrder.new
cancel_order.subscribe(OrderMailer, async: true)
cancel_order.subscribe(ActivityRecorder, async: true)
cancel_order.subscribe(StatisticsRecorder, async: true)
cancel_order.on(:cancel_order_successful) { |order_id| redirect_to order_path(order_id) }
cancel_order.on(:cancel_order_failed) { |order_id| render action: :new }
cancel_order.call(order_id)
end
end
ActiveRecord
If you wish to publish directly from ActiveRecord models you can broadcast events from callbacks:
class Order < ActiveRecord::Base
include Wisper::Publisher
after_commit :publish_creation_successful, on: :create
after_validation :publish_creation_failed, on: :create
private
def publish_creation_successful
broadcast(:order_creation_successful, self)
end
def publish_creation_failed
broadcast(:order_creation_failed, self) if errors.any?
end
end
There are more examples in the Wiki.
Global Listeners
Global listeners receive all broadcast events which they can respond to.
This is useful for cross cutting concerns such as recording statistics, indexing, caching and logging.
Wisper.subscribe(MyListener.new)
In a Rails app you might want to add your global listeners in an initializer.
Global listeners are threadsafe. Subscribers will receive events published on all threads.
Scoping by publisher class
You might want to globally subscribe a listener to publishers with a certain class.
Wisper.subscribe(MyListener.new, scope: :MyPublisher)
Wisper.subscribe(MyListener.new, scope: MyPublisher)
Wisper.subscribe(MyListener.new, scope: "MyPublisher")
Wisper.subscribe(MyListener.new, scope: [:MyPublisher, :MyOtherPublisher])
This will subscribe the listener to all instances of the specified class(es) and their subclasses.
Alternatively you can also do exactly the same with a publisher class itself:
MyPublisher.subscribe(MyListener.new)
Temporary Global Listeners
You can also globally subscribe listeners for the duration of a block.
Wisper.subscribe(MyListener.new, OtherListener.new) do
# do stuff
end
Any events broadcast within the block by any publisher will be sent to the listeners.
This is useful for capturing events published by objects to which you do not have access in a given context.
Temporary Global Listeners are threadsafe. Subscribers will receive events published on the same thread.
Subscribing to selected events
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 a string, symbol,
array or regular expression to on
:
post_creator.subscribe(PusherListener.new, on: :create_post_successful)
Prefixing broadcast events
If you would prefer listeners to receive events with a prefix, for example
on
, you can do so by passing a string or symbol to prefix:
.
post_creator.subscribe(PusherListener.new, prefix: :on)
If post_creator
were to broadcast the event post_created
the subscribed
listeners would receive on_post_created
. You can also pass true
which will
use the default prefix, "on".
Mapping an event to a different method
By default the method called on the listener is the same as the event
broadcast. However it can be mapped to a different method using with:
.
report_creator.subscribe(MailResponder.new, with: :successful)
This is pretty useless unless used in conjunction with on:
, since all events
will get mapped to :successful
. Instead you might do something like this:
report_creator.subscribe(MailResponder.new, on: :create_report_successful,
with: :successful)
If you pass an array of events to on:
each event will be mapped to the same
method when with:
is specified. If you need to listen for select events
and map each one to a different method subscribe the listener once for
each mapping:
report_creator.subscribe(MailResponder.new, on: :create_report_successful,
with: :successful)
report_creator.subscribe(MailResponder.new, on: :create_report_failed,
with: :failed)
You could also alias the method within your listener, as such
alias successful create_report_successful
.
Testing
Testing matchers and stubs are in separate gems.
Clearing Global Listeners
If you use global listeners in non-feature tests you might want to clear them in a hook to prevent global subscriptions persisting between tests.
after { Wisper.clear }
Need help?
The Wiki has more examples, articles and talks.
Got a specific question, try the Wisper tag on StackOverflow.
Compatibility
Tested with MRI 2.x, JRuby and Rubinius.
See the build status for details.
Running Specs
bundle exec rspec
To run the specs on code changes try entr:
ls **/*.rb | entr bundle exec rspec
Contributing
Please read the Contributing Guidelines.
Security
- gem releases are signed (public key)
- commits are GPG signed (public key)
- My Keybase.io profile
License
(The MIT License)
Copyright (c) 2013 Kris Leech
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*Note that all licence references and agreements mentioned in the wisper README section above
are relevant to that project's source code only.