wisper-compat 4.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aaf3ed2b13cd914cd672a6dbd4807be4b15768625ca23986f5a52816787e6d2e
+  data.tar.gz: 987559f11ef6927aef4481bbb2221d7e5f1f7e881b82e92371440ab3ed4391df
+SHA512:
+  metadata.gz: 30141f0611839a2e847e71b29e58f2e32615ce9786d792b0b735160a8cc3c70c0cc84b75720c6811251cd87ee494ff97d37090ca238ef054ebbe8d609d95819d
+  data.tar.gz: ebad69d7040bdf43ea1e45dc798c32d197c761211a19af37d5c60affd61075ba91bdbc658f59b0743a1675cc6152c3627b3662b4796de7012bea17f369d06cff

data/.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Test
+
+on:
+  push:
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [2.7, 3.0, 3.1, 3.2]
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec spec

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.tool-versions
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+tags
+vendor

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format progress
+--require spec_helper
+--warnings

data/.ruby-version

@@ -0,0 +1 @@
+3.2.1

data/CHANGELOG.md

@@ -0,0 +1,152 @@
+## HEAD (unreleased)
+
+## 4.0 (28th Feb 2023)
+Authors: Jamie Schembri
+
+* feature: rename gem from `wisper` to `wisper-compat`.
+
+## 3.0 (20th Jan 2023)
+Authors: doits, jstoks, merringtion
+
+* Adds: Support for Ruby 3.0 keyword arguments
+* Removes: Support for Ruby 2.6 and lower
+
+## 2.0.1 (29th Aug 2019)
+
+Authors: David Wilkie, hosseintoussi, Maxim Polunin, Tristan
+Harmer, Bartosz Żurkowski, Kris Leech
+
+* fix: support nested temporary global listeners
+* docs: add threadsafe notes to README for global and temporary listeners
+* docs: fix spelling mistakes in README
+* fix: safely get signing key in gemspec when HOME is not set
+* adds: add console to aid experiments and REPL driven development
+* adds: Latest Ruby to CI
+
+## 2.0.0 (7th Mar 2017)
+
+Authors: Sergey Mostovoy, Andrew Kozin, Kyle Tolle, Martin, Rob Miller, Mike
+Dalto, orthographic-pedant, Drew Ulmer, Mikey Hogarth, Attila Domokos, Josh
+Miltz, Pascal Betz, Vasily Kolesnikov, Julien Letessier, Kris Leech
+
+* Fix: logger raises exception if hash is passed as an argument to a listener #133, #136
+* Fix: deprecation warnings #120
+* Doc improvements: #106, #111, #116, #122, #128, #130, #147, #149, #150, #151
+* Adds: Allow configuration of default prefix when using `prefix: true`. #105
+* Adds: Allow unsubscribing of global listeners #118
+* Adds: Helpful error message when passing a block to `#subscribe` of `#on` #125
+* Adds: raise an error message when `#on` is not passed a block #146
+* Adds: Support for JRuby 9.x #148
+* Adds: Support for MRI 2.4.0 #155
+* Refactor specs #126, #131
+
+## 2.0.0.rc1 (17 Dec 2014)
+
+Authors: Kris Leech
+
+* remove: deprecated methods
+* remove: rspec matcher and stubbing (moved to [wisper-rspec](https://github.com/krisleech/wisper-rspec))
+* feature: add regexp support to `on` argument
+* remove: announce alias for broadcasting
+* docs: add Code of Conduct
+* drop support for Ruby 1.9
+
+## 1.6.0 (25 Oct 2014)
+
+Authors: Kris Leech
+
+* deprecate: add_listener, add_block_listener and respond_to
+* internal: make method naming more consistent
+
+## 1.5.0 (6th Oct 2014)
+
+Authors: Kris Leech
+
+* feature: allow events to be published asynchronously
+* feature: broadcasting of events is plugable and configurable
+* feature: broadcasters can be aliased via a symbol
+* feature: logging broadcaster
+
+## 1.4.0 (8th Sept 2014)
+
+Authors: Kris Leech, Marc Ignacio, Ahmed Abdel Razzak, kmehkeri, Jake Hoffner
+
+* feature: matcher for rspec 3
+* fix: temporary global listeners are cleared if an exception is raised
+* refactor: update all specs to rspec 3 expect syntax
+* docs: update README to rspec 3 expect syntax
+* feature: combine global and temporary listener methods as `Wisper.subscribe`
+* deprecate: `Wisper.add_listener` and `Wisper.with_listeners,` use `Wisper.subscribe` instead
+
+## 1.3.0 (18th Jan 2014)
+
+Authors: Kris Leech, Yan Pritzker, Charlie Tran
+
+* feature: global subscriptions can be scoped to a class (and sub-classes)
+* upgrade: use rspec 3
+* feature: allow prefixing of events with 'on'
+* feature: Allow stubbed publisher method to accept arbitrary args
+
+## 1.2.1 (7th Oct 2013)
+
+Authors: Kris Leech, Tomasz Szymczyszyn, Alex Heeton
+
+* feature: global subscriptions can be passed options
+* docs: improve README examples
+* docs: add license to gemspec
+
+## 1.2.0 (21st July 2013)
+
+Authors: Kris Leech, Darren Coxall
+
+* feature: support for multiple events at once
+* fix: clear global listeners after each spec
+
+## 1.1.0 (7th June 2013)
+
+Authors: Kris Leech, chatgris
+
+* feature: add temporary global listeners
+* docs: improve ActiveRecord example
+* refactor: improve specs
+* upgrade: add Ruby 2.0 support
+* fix: make listener collection immutable
+* remove: async publishing and Celluloid dependency
+* fix: Make global listeners getter and setter threadsafe [9]
+
+## 1.0.1 (2nd May 2013)
+
+Authors: Kris Leech, Yan Pritzker
+
+* feature: add async publishing using Celluloid
+* docs: improve README examples
+* feature: `stub_wisper_publisher` rspec helper
+* feature: global listeners
+* refactor: improve specs
+
+## 1.0.0 (7th April 2013)
+
+Authors: Kris Leech
+
+* refactor: specs
+* refactor: registrations
+* feature: Add `with` argument to `subscribe`
+* docs: improve README examples
+* feature: Allow subscriptions to be chainable
+* feature: Add `on` syntax for block subscription
+* remove: Remove support for Ruby 1.8.7
+* docs: Add badges to README
+
+## 0.0.2 (30th March 2013)
+
+Authors: Kris Leech
+
+* remove: ActiveSupport dependency
+* docs: fix syntax highlighting in README
+
+## 0.0.1 (30th March 2013)
+
+Authors: Kris Leech
+
+* docs: add README
+* feature: registration of objects and blocks

data/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# How to Contribute
+
+We very much welcome contributions to Wisper.
+
+This project is intended to be a safe, welcoming space for collaboration,
+and contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Getting started
+
+Please first check the existing [Issues](https://github.com/krisleech/wisper/issues) 
+and [Pull Requests](https://github.com/krisleech/wisper/pulls) to ensure your
+issue has not already been discused.
+
+## Bugs
+
+Please submit a bug report to the issue tracker, with the version of Wisper
+and Ruby you are using and a small code sample (or better yet a failing test).
+
+## Features
+
+Please open an issue with your proposed feature. We can discuss the feature and
+if it is acceptable we can also discuss implimentation details. You will in
+most cases have to submit a PR which adds the feature. 
+
+Wisper is a micro library and will remain lean. Some features would be most
+appropriate as an extension to Wisper.
+
+We also have a [Gitter channel](https://gitter.im/krisleech/wisper) if you wish to discuss your ideas.
+
+## Questions
+
+Try the [Wiki](https://github.com/krisleech/wisper/wiki) first, the examples
+and how to sections have lots of information.
+
+Please ask questions on StackOverflow, [tagged wisper](https://stackoverflow.com/questions/tagged/wisper).
+
+Feel free to ping me the URL on [Twitter](https://twitter.com/krisleech).
+
+## Pull requests
+
+* Fork the project, create a new branch `master`.
+* Squash commits which are related.
+* Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+* Documentation only changes should have `[skip ci]` in the commit message
+* Follow existing code style in terms of syntax, indentation etc.
+* Add an entry to the CHANGELOG
+* Do not bump the VERSION, but do indicate in the CHANGELOG if the change is
+not backwards compatible.
+* Issue a Pull Request
+
+## Versions
+
+The `v1` branch is a long lived branch and you should
+branch from this if you wish to fix an issue in version `~> 1.0`.
+
+Otherwise branch from `master` branch.

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+gem 'rspec'
+
+group :extras do
+  gem 'yard'
+end

data/README.md

@@ -0,0 +1,358 @@
+# Wisper
+
+*A micro library providing Ruby objects with Publish-Subscribe capabilities*
+
+[![Gem Version](https://badge.fury.io/rb/wisper-compat.svg)](http://badge.fury.io/rb/wisper-compat)
+
+* 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](https://github.com/krisleech/wisper/wiki) for more additional information and articles.
+
+**For greenfield applications you might also be interested in
+[WisperNext](https://gitlab.com/kris.leech/wisper_next) and [Ma](https://gitlab.com/kris.leech/ma).**
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wisper-compat', '4.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
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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](http://product.reverb.com/2015/02/28/the-strange-case-of-wisper-and-ruby-blocks-behaving-like-procs/)
+this will prevent any subsequent listeners having their events delivered.
+
+### Handling Events Asynchronously
+
+```ruby
+cancel_order.subscribe(OrderNotifier.new, async: true)
+```
+
+Wisper has various adapters for asynchronous event handling, please refer to
+[wisper-celluloid](https://github.com/krisleech/wisper-celluloid),
+[wisper-sidekiq](https://github.com/krisleech/wisper-sidekiq),
+[wisper-activejob](https://github.com/krisleech/wisper-activejob),
+[wisper-que](https://github.com/joevandyk/wisper-que) or
+[wisper-resque](https://github.com/bzurkowski/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:
+
+```ruby
+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
+
+```ruby
+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:
+
+```ruby
+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](https://github.com/krisleech/wisper/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.
+
+```ruby
+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.
+
+```ruby
+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:
+
+```ruby
+MyPublisher.subscribe(MyListener.new)
+```
+
+## Temporary Global Listeners
+
+You can also globally subscribe listeners for the duration of a block.
+
+```ruby
+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`:
+
+```ruby
+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:`.
+
+```ruby
+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:`.
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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.
+
+* [wisper-rspec](https://github.com/krisleech/wisper-rspec)
+* [wisper-minitest](https://github.com/digitalcuisine/wisper-minitest)
+
+### 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.
+
+```ruby
+after { Wisper.clear }
+```
+
+## Need help?
+
+The [Wiki](https://github.com/krisleech/wisper/wiki) has more examples,
+articles and talks.
+
+Got a specific question, try the
+[Wisper tag on StackOverflow](http://stackoverflow.com/questions/tagged/wisper).
+
+## Running Specs
+
+```
+bundle exec rspec
+```
+
+To run the specs on code changes try [entr](http://entrproject.org/):
+
+```
+ls **/*.rb | entr bundle exec rspec
+```
+
+## Contributing
+
+Please read the [Contributing Guidelines](https://github.com/nedap/wisper-compat/blob/master/CONTRIBUTING.md).
+
+## 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.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/lib/wisper/broadcasters/logger_broadcaster.rb

@@ -0,0 +1,41 @@
+# Provides a way of wrapping another broadcaster with logging
+
+module Wisper
+  module Broadcasters
+    class LoggerBroadcaster
+      def initialize(logger, broadcaster)
+        @logger      = logger
+        @broadcaster = broadcaster
+      end
+
+      def broadcast(listener, publisher, event, *args, **kwargs)
+        @logger.info("[WISPER] #{name(publisher)} published #{event} to #{name(listener)} with #{args_info(args)} and #{kwargs_info(kwargs)}")
+        @broadcaster.broadcast(listener, publisher, event, *args, **kwargs)
+      end
+
+      private
+
+      def name(object)
+        id_method  = %w(id uuid key object_id).find do |method_name|
+          object.respond_to?(method_name) && object.method(method_name).arity <= 0
+        end
+        id         = object.send(id_method)
+        class_name = object.class == Class ? object.name : object.class.name
+        "#{class_name}##{id}"
+      end
+
+      def args_info(args)
+        return 'no arguments' if args.empty?
+        args.map do |arg|
+          arg_string = name(arg)
+          arg_string += ": #{arg.inspect}" if [Numeric, Array, Hash, String].any? {|klass| arg.is_a?(klass) }
+          arg_string
+        end.join(', ')
+      end
+
+      def kwargs_info(kwargs)
+        kwargs.empty? ? 'no keyword arguments' : "keyword arguments #{kwargs.inspect}"
+      end
+    end
+  end
+end

data/lib/wisper/broadcasters/send_broadcaster.rb

@@ -0,0 +1,9 @@
+module Wisper
+  module Broadcasters
+    class SendBroadcaster
+      def broadcast(listener, publisher, event, *args, **kwargs)
+        listener.public_send(event, *args, **kwargs)
+      end
+    end
+  end
+end