mediate 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06e45660926271c9435a4c2dd1634974b3873091f12160b907833cab8c9b7abf
-  data.tar.gz: 8b1fe7523830f57f8e2499bf8c3575ffc0eef7716478a554f683947a8958dd95
+  metadata.gz: 6bf88906a3d562b832c1581d5775d2f6ae2b5a7d93b59166882edec77217dde5
+  data.tar.gz: 0c49d3981d01e37c29e3276672e2527a2fb61a67d9f17d6d51a48a0247ebffcb
 SHA512:
-  metadata.gz: 6f29b77858c6361cbdc54ccc79656d470dd2feb274fe341746fa66d9fc33e34a7c1906bc8df859dfbb0dbf68fa73fc5f1b7819a2bb889565c91388abfbd8d090
-  data.tar.gz: 20c32a19443169eb74e41524b8ae9a342a023a2f54a306d182c3419988dbc5479a739c5866012d29a83e1cb1aeace714f6677efaab7c6368d90082fa0655c879
+  metadata.gz: efe642b92ac4763623c79af4bdc79b330544eb320e07075061ba5cec489b98cc5af62f07de4baaf34435c13ebbeedddd91611b6b137e7811bfe79d091b84d7c4
+  data.tar.gz: 34e033244ffcd8438060c5d6c7e05046a572b5583047b75f3438323f10e9c774d5a140066a6d7911e8da43fc01ebb52354fee7d60a9f5fbf951517aa58237d79

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mediate (0.1.0)
+    mediate (0.1.3)
       concurrent-ruby (~> 1.1)
 
 GEM

data/README.md

@@ -1,5 +1,7 @@
 # Mediate
 
+[![CI](https://github.com/rferg/mediate/actions/workflows/ci.yml/badge.svg)](https://github.com/rferg/mediate/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/mediate.svg)](https://badge.fury.io/rb/mediate)
+
 A simple mediator implementation for Ruby inspired by [Mediatr](https://github.com/jbogard/MediatR).
 
 Decouple application components by sending a request through the mediator and receiving a response from a handler, instead of directly calling methods on imported classes.
@@ -17,6 +19,8 @@ Supports request/response, notifications (i.e., events), pre- and post-request h
   - [Testing](#testing)
     - [Testing implicit request handlers](#testing-implicit-request-handlers)
   - [Using with Rails](#using-with-rails)
+    - [Nest request handler definitions within request classes](#nest-request-handler-definitions-within-request-classes)
+    - [Configure Rails to eager load other handlers in non-production environments](#configure-rails-to-eager-load-other-handlers-in-non-production-environments)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -96,7 +100,7 @@ Note that only one handler can be registered for a particular request class; att
 
 #### Implicit handler declaration
 
-For simple handlers, you can skip the explicit `RequestHandler` declaration above and instead pass a block to `Request.handle_with`.
+For simple handlers, you can skip the explicit `RequestHandler` declaration above and instead pass a lambda to `Request.handle_with`.
 
 ```ruby
 class Ping < Mediate::Request
@@ -107,14 +111,14 @@ class Ping < Mediate::Request
         super()
     end
     # This will have the same behavior as the PingHandler declaration above.
-    handle_with { |request| "Received: #{request.message}" }
+    handle_with ->(request) { "Received: #{request.message}" }
 end
 
 response = Mediate.dispatch(Ping.new('hello'))
 puts response # 'Received: hello'
 ```
 
-Behind the scenes, this defines a `Ping::Handler` class that calls the given block in its `handle` method.  For testing purposes, you can get an instance of this handler class by calling `Mediate::Request.create_implicit_handler` (see [Testing implicit request handlers](#testing-implicit-request-handlers)).
+Behind the scenes, this defines a `Ping::Handler` class that calls the given lambda in its `handle` method.  For testing purposes, you can get an instance of this handler class by calling `Mediate::Request.create_implicit_handler` (see [Testing implicit request handlers](#testing-implicit-request-handlers)).
 
 #### Request polymorphism
 
@@ -129,7 +133,7 @@ Unless we registered a handler for `SubPing` explicitly.
 
 ```ruby
 class SubPing < Ping
-    handle_with { |request| "Received from SubPing: #{request.message}" }
+    handle_with ->(request) { "Received from SubPing: #{request.message}" }
 end
 puts Mediate.dispatch(SubPing.new('howdy')) # 'Received from SubPing: howdy'
 ```
@@ -252,13 +256,13 @@ Special consideration is only required when testing paths that invoke methods on
 
 #### Testing implicit request handlers
 
-How can you test a request handler defined using `handle_with` and a block like the following?
+How can you test a request handler defined using `handle_with` and a lambda like the following?
 
 ```ruby
 class ExampleRequest < Mediate::Request
-    handle_with do |request|
+    handle_with lambda { |request|
         # ....
-    end
+    }
 end
 ```
 
@@ -276,7 +280,51 @@ end
 
 ### Using with Rails
 
-TODO
+Handler registrations occur within methods called from class definitions.  In non-production environments, by default, Rails [lazy loads](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html) constants.  Therefore, if handlers are not explicitly referenced, which is typical, their class definitions will not be loaded and they will not be registered as handlers on the mediator.
+
+There are two things that need to be done to work around this behavior:
+
+#### Nest request handler definitions within request classes
+
+Since requests will be explicitly referenced in, say, controllers, we can force their handler constants to load with them by nesting those definitions within the request definitions.  For example:
+
+```ruby
+class MyRequest < Mediate::Request
+  # ...
+  class MyRequestHandler < Mediate::RequestHandler
+    handles MyRequest
+    
+    def handle(request)
+      # ...
+    end
+  end
+end
+```
+
+This has the added benefit of colocating a handler with its request, making it easy to find.  This is therefore the recommended way to declare requests and their handlers.  [Implicit handler declarations](#implicit-handler-declaration) do this automatically.
+
+#### Configure Rails to eager load other handlers in non-production environments
+
+For other handlers (pre- and post-request behaviors, error handlers, notification handlers), it is typically either not possible or not practical to nest their declarations within the class definitions they handle.  You will have to add configuration to eager load these in environments where global eager loading is turned off.  This can be accomplished by adding their file paths to `config.eager_load_paths` in the relevant environment files, like so:
+
+```ruby
+# config/environments/development.rb
+
+Rails.application.configure do
+  # ...
+  [
+    'app/use_cases/common/**/*.rb',
+    'app/use_cases/**/event_handlers/**/*.rb'
+  ].each do |path|
+    config.eager_load_paths += Dir[path]
+    ActiveSupport::Reloader.to_prepare do
+      Dir[path].each { |f| require_dependency("#{Dir.pwd}/#{f}") }
+    end
+  end
+end
+```
+
+(In the above, we're assuming, for example, that we have pre- and post-request behaviors and error handlers in `app/use_cases/common/` and notification handlers in `app/use_cases/**/event_handlers/**/`.)
 
 ## Development
 

data/lib/mediate/mediator.rb

@@ -42,16 +42,16 @@ module Mediate
     def dispatch(request)
       raise ArgumentError, "request cannot be nil" if request.nil?
 
-      request_handler = resolve_handler(@request_handlers, request.class, REQUEST_BASE)
+      request_handler = resolve_handler(request_handlers, request.class, REQUEST_BASE)
       raise Errors::NoHandlerError, request.class if request_handler == NullHandler
 
-      prerequest_handlers = collect_by_inheritance(@prerequest_behaviors, request.class, REQUEST_BASE)
-      postrequest_handlers = collect_by_inheritance(@postrequest_behaviors, request.class, REQUEST_BASE)
-      run_request_pipeline(request, prerequest_handlers, request_handler, postrequest_handlers)
+      prerequest = collect_by_inheritance(prerequest_behaviors, request.class, REQUEST_BASE)
+      postrequest = collect_by_inheritance(postrequest_behaviors, request.class, REQUEST_BASE)
+      run_request_pipeline(request, prerequest, request_handler, postrequest)
     end
 
     #
-    # Sends a notification to all register handlers for the given notification's type.
+    # Sends a notification to all registered handlers for the given notification's type.
     #
     # @param [Mediate::Notification] notification
     #
@@ -60,7 +60,7 @@ module Mediate
     def publish(notification)
       raise ArgumentError, "notification cannot be nil" if notification.nil?
 
-      handler_classes = collect_by_inheritance(@notification_handlers, notification.class, NOTIF_BASE)
+      handler_classes = collect_by_inheritance(notification_handlers, notification.class, NOTIF_BASE)
       handler_classes.each do |handler_class|
         handler_class.new.handle(notification)
       rescue StandardError => e
@@ -73,26 +73,31 @@ module Mediate
     def register_request_handler(handler_class, request_class)
       validate_base_class(handler_class, Mediate::RequestHandler)
       validate_base_class(request_class, REQUEST_BASE)
-      raise_if_request_handler_exists(request_class, handler_class)
-      @request_handlers[request_class] = handler_class
+      request_handlers.compute(request_class) do |old_value|
+        unless old_value.nil? || old_value == handler_class
+          raise Errors::RequestHandlerAlreadyExistsError.new(request_class, old_value, handler_class)
+        end
+
+        handler_class
+      end
     end
 
     def register_notification_handler(handler_class, notif_class)
       validate_base_class(handler_class, Mediate::NotificationHandler)
       validate_base_class(notif_class, NOTIF_BASE, allow_base: true)
-      append_to_hash_value(@notification_handlers, notif_class, handler_class)
+      append_to_hash_value(notification_handlers, notif_class, handler_class)
     end
 
     def register_prerequest_behavior(behavior_class, request_class)
       validate_base_class(behavior_class, Mediate::PrerequestBehavior)
       validate_base_class(request_class, REQUEST_BASE, allow_base: true)
-      append_to_hash_value(@prerequest_behaviors, request_class, behavior_class)
+      append_to_hash_value(prerequest_behaviors, request_class, behavior_class)
     end
 
     def register_postrequest_behavior(behavior_class, request_class)
       validate_base_class(behavior_class, Mediate::PostrequestBehavior)
       validate_base_class(request_class, REQUEST_BASE, allow_base: true)
-      append_to_hash_value(@postrequest_behaviors, request_class, behavior_class)
+      append_to_hash_value(postrequest_behaviors, request_class, behavior_class)
     end
 
     def register_error_handler(handler_class, exception_class, dispatch_class)
@@ -119,18 +124,14 @@ module Mediate
 
     private
 
-    def raise_if_request_handler_exists(request_class, new_handler)
-      registered = @request_handlers.fetch(request_class, nil)
-      return if registered.nil? || registered == new_handler
-
-      raise Errors::RequestHandlerAlreadyExistsError.new(request_class, registered, new_handler)
-    end
+    attr_reader :exception_handlers, :postrequest_behaviors, :prerequest_behaviors, :notification_handlers,
+                :request_handlers
 
     def register_error_handler_for_dispatch(handler_class, exception_class, dispatch_class, dispatch_base_class)
       validate_base_class(handler_class, Mediate::ErrorHandler)
       validate_base_class(exception_class, StandardError, allow_base: true)
       validate_base_class(dispatch_class, dispatch_base_class, allow_base: true)
-      map = @exception_handlers.fetch_or_store(exception_class, Concurrent::Map.new)
+      map = exception_handlers.fetch_or_store(exception_class, Concurrent::Map.new)
       append_to_hash_value(map, dispatch_class, handler_class)
     end
 
@@ -157,7 +158,7 @@ module Mediate
     end
 
     def handle_exception(dispatched, exception, dispatch_base_class)
-      exception_to_dispatched_maps = collect_by_inheritance(@exception_handlers, exception.class, StandardError)
+      exception_to_dispatched_maps = collect_by_inheritance(exception_handlers, exception.class, StandardError)
       handler_classes = exception_to_dispatched_maps.reduce(Concurrent::Set.new) do |memo, curr|
         collect_by_inheritance(curr, dispatched.class, dispatch_base_class, memo)
       end

data/lib/mediate/request.rb

@@ -9,27 +9,25 @@ module Mediate
     IMPLICIT_HANDLER_CLASS_NAME = "Handler"
 
     #
-    # Registers a handler for this Request type using the given block as the handle method.
+    # Registers a handler for this Request type using the given lambda as the handle method.
     #
+    # @param [Lambda] lmbda the block that will handle the request
     # @param [Mediate::Mediator] mediator the instance to register the handler on
-    # @param [Proc] &proc the block that will handle the request
     #
-    # @raises [ArgumentError] if no block is given
+    # @raises [ArgumentError] if no lambda is given
+    # @raises [RequestHandlerAlreadyExistsError] if handler already defined for this class
     #
-    # @example When a request of this type is dispatched, the handle_with block will run
+    # @example When a request of this type is dispatched, the handle_with lambda will run
     #   class MyRequest < Mediate::Request
-    #     handle_with do |request|
+    #     handle_with lambda do |request|
     #       ## do something with request...
     #     end
     #   end
-    def self.handle_with(mediator = Mediate.mediator, &proc)
-      raise ArgumentError, "expected block to be passed to #handle_with." unless proc
+    def self.handle_with(lmbda, mediator = Mediate.mediator)
+      raise ArgumentError, "expected lambda to be passed to #handle_with." if lmbda.nil?
 
-      if implicit_handler_defined?
-        raise "#{name}::#{IMPLICIT_HANDLER_CLASS_NAME} is already defined. Cannot create implicit handler."
-      end
-
-      handler_class = define_handler(proc)
+      handler_class = define_handler(lmbda)
+      undefine_implicit_handler # remove any previous definition (this will do nothing if it doesn't exist)
       const_set(IMPLICIT_HANDLER_CLASS_NAME, handler_class)
       mediator.register_request_handler(handler_class, self)
     end
@@ -57,17 +55,14 @@ module Mediate
       remove_const(IMPLICIT_HANDLER_CLASS_NAME)
     end
 
-    def self.define_handler(proc)
+    def self.define_handler(lmbda)
       Class.new(RequestHandler) do
-        @@handle_proc = proc # rubocop:disable Style/ClassVars
-        def handle(request)
-          @@handle_proc.call(request)
-        end
+        define_method(:handle, lmbda)
       end
     end
 
     def self.implicit_handler_defined?
-      const_defined?(IMPLICIT_HANDLER_CLASS_NAME)
+      const_defined?(IMPLICIT_HANDLER_CLASS_NAME, false) # do not check ancestors
     end
 
     private_constant :IMPLICIT_HANDLER_CLASS_NAME

data/lib/mediate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mediate
-  VERSION = "0.1.0"
+  VERSION = "0.1.3"
 end

data/lib/mediate.rb

@@ -33,7 +33,7 @@ module Mediate
   end
 
   #
-  # Sends a notification to all register handlers for the given notification's type.
+  # Sends a notification to all registered handlers for the given notification's type.
   #
   # @param [Mediate::Notification] notification
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mediate
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Ryan Ferguson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-02 00:00:00.000000000 Z
+date: 2023-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby