https://github.com/krisleech/wisper

A micro library providing Ruby objects with Publish-Subscribe capabilities
https://github.com/krisleech/wisper

Keywords

events publish-subscribe pubsub ruby

Keywords from Contributors

activerecord activejob mvc rspec rubygems grape rubocop dry-rb crash-reporting coercion

Last synced: about 22 hours ago
JSON representation

Repository metadata

A micro library providing Ruby objects with Publish-Subscribe capabilities

Host: GitHub
URL: https://github.com/krisleech/wisper
Owner: krisleech
Created: 2013-03-29T23:48:32.000Z (almost 13 years ago)
Default Branch: master
Last Pushed: 2024-08-15T15:29:18.000Z (over 1 year ago)
Last Synced: 2026-02-28T00:31:14.508Z (4 days ago)
Topics: events, publish-subscribe, pubsub, ruby
Language: Ruby
Homepage:
Size: 319 KB
Stars: 3,325
Watchers: 47
Forks: 154
Open Issues: 3
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md

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 dependent 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', '~> 3.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 like:

# config/initializers/listeners.rb
Rails.application.reloader.to_prepare do
  Wisper.clear if Rails.env.development?

  Wisper.subscribe(MyListener.new)
end

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

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)

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.

Owner metadata

Name: Kris Leech
Login: krisleech
Email: kris.leech@gmail.com
Kind: user
Description: Technical Lead
Website: http://teamcoding.com
Location: Nottingham, UK
Twitter: krisleech
Company:
Icon url: https://avatars.githubusercontent.com/u/66143?u=eee72641df468a5b1ad12672b33d37c699060f45&v=4
Repositories: 153
Last ynced at: 2026-01-12T18:50:19.036Z
Profile URL: https://github.com/krisleech

GitHub Events

Total

Fork event: 2
Issues event: 1
Watch event: 68
Issue comment event: 1

Last Year

Fork event: 1
Issues event: 1
Watch event: 32
Issue comment event: 1

Committers metadata

Last synced: 2 days ago

Total Commits: 232
Total Committers: 45
Avg Commits per committer: 5.156
Development Distribution Score (DDS): 0.332

Commits in past year: 0
Committers in past year: 0
Avg Commits per committer in past year: 0.0
Development Distribution Score (DDS) in past year: 0.0

Name	Email	Commits
Kris Leech	k**h@g**m	155
Kris Leech	k**h@h**m	12
Andrew Kozin	a**n@g**m	7
Sergey Mostovoy	s**y@g**m	4
Attila Domokos	a**s@g**m	4
tris	g**z@g**m	3
Ahmed Abdel Razzak	e**k@g**m	3
Larry Lv	z**v@f**v	2
Kris Leech	k**h@b**m	2
Douglas Greenshields	d**s@l**k	2
Keith Bennett	k**t@g**m	2
Yan Pritzker	y**n@p**s	2
kmehkeri	k**i@g**m	2
David Wilkie	d**e@g**m	1
David Stosik	d**y@g**m	1
Darren Coxall	d**n@d**m	1
Charlie Tran	c****n	1
Bartosz Żurkowski	z**z@g**m	1
Andy Waite	g**w@a**m	1
Akira Matsuda	r**e@d**p	1
Alex Heeton	a**x@h**e	1
Tomasz Szymczyszyn	t**n@g**m	1
orthographic-pedant	t**t@g**m	1
jake hoffner	j**r@g**m	1
Vasily Kolesnikov	r**v@g**m	1
Rob Miller	r**b@b**k	1
Pascal Betz	p**z@g**m	1
Mohammad Aboelnour	m**r@g**m	1
Mikey Hogarth	m**0@h**m	1
Mike Dalton	m**n@g**m	1
and 15 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 4 months ago

Total issues: 63
Total pull requests: 54
Average time to close issues: 10 months
Average time to close pull requests: 7 months
Total issue authors: 50
Total pull request authors: 45
Average comments per issue: 3.24
Average comments per pull request: 3.89
Merged pull request: 33
Bot issues: 0
Bot pull requests: 0

Past year issues: 1
Past year pull requests: 2
Past year average time to close issues: N/A
Past year average time to close pull requests: 13 days
Past year issue authors: 1
Past year pull request authors: 2
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.5
Past year merged pull request: 1
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/krisleech/wisper

Top Issue Authors

krisleech (12)
amex-doug (2)
kirantpatil (2)
olance (1)
harsjadh (1)
whysthatso (1)
benlieb (1)
veeral-patel (1)
rlopzc (1)
SebastianOsuna (1)
Hirurg103 (1)
MadBomber (1)
neyp (1)
lelutin (1)
apraditya (1)

Top Pull Request Authors

krisleech (6)
smostovoy (2)
h0lyalg0rithm (2)
stgeneral (2)
maboelnour (2)
wheeyls (2)
kianmeng (2)
pascalbetz (1)
amatsuda (1)
Looooong (1)
robmiller (1)
latortuga (1)
v-kolesnikov (1)
bzurkowski (1)
nepalez (1)

Top Issue Labels

idea (5)
contribute (4)
docs (3)
enhancement (2)
in progress (1)
question (1)

Top Pull Request Labels

Package metadata

Total packages: 13
Total downloads:
- rubygems: 200,803,566 total
Total docker downloads: 965,289,998
Total dependent packages: 87 (may contain duplicates)
Total dependent repositories: 4,230 (may contain duplicates)
Total versions: 57
Total maintainers: 1

debian-13: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Documentation: https://packages.debian.org/trixie/ruby-wisper
Licenses:
Latest release: 2.0.1-2 (published 19 days ago)
Last Synced: 2026-02-13T13:20:52.043Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.202%
- Stargazers count: 0.265%
- Forks count: 0.543%

gem.coop: wisper

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/krisleech/wisper/wiki

Homepage: https://github.com/krisleech/wisper
Documentation: http://www.rubydoc.info/gems/wisper/
Licenses: MIT
Latest release: 3.0.0 (published almost 2 years ago)
Last Synced: 2026-03-01T21:03:20.542Z (2 days ago)
Versions: 17
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 100,396,613 Total
Docker Downloads: 482,644,999
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Docker downloads count: 0.271%
- Downloads: 0.272%
- Average: 0.568%
- Stargazers count: 0.653%
- Forks count: 2.21%
Maintainers (1)
- krisleech

rubygems.org: wisper

Homepage: https://github.com/krisleech/wisper
Documentation: http://www.rubydoc.info/gems/wisper/
Licenses: MIT
Latest release: 3.0.0 (published almost 2 years ago)
Last Synced: 2026-03-02T03:02:07.387Z (1 day ago)
Versions: 17
Dependent Packages: 86
Dependent Repositories: 4,230
Downloads: 100,406,953 Total
Docker Downloads: 482,644,999
Rankings:
- Docker downloads count: 0.256%
- Dependent packages count: 0.356%
- Downloads: 0.42%
- Dependent repos count: 0.483%
- Stargazers count: 0.636%
- Average: 0.719%
- Forks count: 2.159%
Maintainers (1)
- krisleech

proxy.golang.org: github.com/krisleech/wisper

Homepage:
Documentation: https://pkg.go.dev/github.com/krisleech/wisper#section-documentation
Licenses:
Latest release: v2.0.1+incompatible (published over 6 years ago)
Last Synced: 2026-02-28T21:01:01.687Z (3 days ago)
Versions: 12
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Stargazers count: 1.222%
- Forks count: 2.23%
- Average: 5.958%
- Dependent packages count: 9.576%
- Dependent repos count: 10.802%

conda-forge.org: rb-wisper

Homepage: https://rubygems.org/gems/wisper
Licenses: MIT
Latest release: 2.0.1 (published over 4 years ago)
Last Synced: 2026-03-02T15:17:05.738Z (1 day ago)
Versions: 2
Dependent Packages: 1
Dependent Repositories: 0
Rankings:
- Stargazers count: 6.559%
- Forks count: 13.936%
- Average: 20.835%
- Dependent packages count: 28.82%
- Dependent repos count: 34.025%

ubuntu-24.04: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Licenses:
Latest release: 2.0.1-2 (published 25 days ago)
Last Synced: 2026-02-06T16:17:01.789Z (25 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

ubuntu-23.04: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Licenses:
Latest release: 2.0.1-2 (published 21 days ago)
Last Synced: 2026-02-11T06:52:37.427Z (21 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.10: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Licenses:
Latest release: 2.0.1-2 (published 18 days ago)
Last Synced: 2026-02-13T18:35:46.506Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-24.10: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Licenses:
Latest release: 2.0.1-2 (published 22 days ago)
Last Synced: 2026-02-09T17:32:57.916Z (22 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-11: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Documentation: https://packages.debian.org/bullseye/ruby-wisper
Licenses:
Latest release: 2.0.1-2 (published 21 days ago)
Last Synced: 2026-02-13T08:26:15.680Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-20.04: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Licenses:
Latest release: 2.0.1-2 (published 19 days ago)
Last Synced: 2026-02-13T07:25:38.499Z (19 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-22.04: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Licenses:
Latest release: 2.0.1-2 (published 18 days ago)
Last Synced: 2026-02-13T13:28:43.912Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-12: ruby-wisper

Homepage: https://github.com/krisleech/wisper
Documentation: https://packages.debian.org/bookworm/ruby-wisper
Licenses:
Latest release: 2.0.1-2 (published 19 days ago)
Last Synced: 2026-02-12T23:44:16.205Z (19 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

Dependencies

Gemfile rubygems

flay >= 0 development
pry >= 0 development
yard >= 0 development
coveralls >= 0
rake >= 0
rspec >= 0

Score: 32.79371861954211