medi8-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d97412258c38426f13a8e52fb52454a37a38228e2d466b285b65c205f7408424
+  data.tar.gz: e5f88badb5678bfd8d5a5fdc1d27c51b249cbbf1d673f03842db241adeb91bce
+SHA512:
+  metadata.gz: 45fa60fb8b43af3fcd1c2ef7aad298e2a8948ab5355dc0078e6205f39fbde87a14d7044e8879a1eb4ba52fb8c0fd4d4fef8b72dec549e4d99a44624846ca81c5
+  data.tar.gz: 1aadd7477bdb056b0dd8d3bff61708194dad02de6c541362dc6086f2b073a6b626c84c59693759bac6dc1c0e76cd8a1a9867d5f78c1c93e17a2472ad063db465

data/README.md

@@ -0,0 +1,330 @@
+# Medi8-rb
+
+[![Gem Version](https://badge.fury.io/rb/medi8-rb.svg)](https://badge.fury.io/rb/medi8-rb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Medi8 is a lightweight, idiomatic mediator pattern implementation for Ruby and Rails, inspired by MediatR (from .NET)
+
+Medi8 is not a 1:1 Ruby analog of MediatR, but it faithfully implements its core principles in an idiomatic Ruby way.
+
+Medi8 is compatible with pure Ruby, Sinatra, and Rails.
+
+---
+
+## Features
+
+- Simple `send` method for commands and queries
+- `publish` notifications to many subscribers
+- Middleware pipeline
+- Async notifications with ActiveJob
+- Rails integration via `Railtie`
+- Fully modular, no inheritance required
+
+---
+
+## Design
+
+```plantuml
+@startuml
+title Medi8 Logical Flow and Event Sequence
+
+actor "Caller (e.g. Controller)" as Caller
+participant "Medi8" as Medi8
+participant "Mediator" as Mediator
+participant "RegisterUserHandler" as Handler
+participant "Medi8.publish" as Publisher
+participant "SendWelcomeEmailHandler" as Emailer
+participant "TrackRegistrationHandler" as Tracker
+
+== Command Dispatch ==
+
+Caller -> Medi8: send(RegisterUser)
+Medi8 -> Mediator: new(registry)\nsend(request)
+Mediator -> Handler: call(request)
+
+== Event Publishing ==
+
+Handler -> Medi8: publish(UserRegistered)
+Medi8 -> Mediator: new(registry)\npublish(event)
+Mediator -> Publisher: NotificationDispatcher.publish(event)
+
+== Notify Subscribers ==
+
+Publisher -> Emailer: call(event)
+Publisher -> Tracker: call(event)
+
+@enduml
+```
+
+---
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem "medi8-rb"
+```
+
+Then bundle:
+
+```bash
+$ bundle install
+```
+
+Or install it directly:
+
+```bash
+$ gem install medi8-rb
+```
+
+---
+
+## Concept
+
+Use `Medi8.send(request)` for command/query behavior, and `Medi8.publish(event)` for notifications. Handlers are registered with a simple DSL.
+
+---
+
+## Configuration
+
+Set up in an initializer:
+
+```ruby
+# config/initializers/medi8.rb
+Medi8.configure do |config|
+  config.use AwesomeMiddleware
+end
+```
+
+Example middleware:
+
+```ruby
+class AwesomeMiddleware
+  def call(request)
+    Rails.logger.info("Processing #{request.class.name}")
+    yield
+  end
+end
+```
+
+---
+
+## Usage
+
+Medi8 uses a simple request/handler model. You define a request class, register a handler using handles, and then invoke `Medi8.send(request)`.
+
+### Create a Request
+
+```ruby
+# app/requests/create_user.rb
+class CreateUser
+  attr_reader :name
+
+  def initialize(name:)
+    @name = name
+  end
+end
+```
+
+### Create a Handler
+
+```ruby
+# app/handlers/create_user_handler.rb
+class CreateUserHandler
+  include Medi8::Handler
+
+  handles CreateUser
+
+  def call(request)
+    User.create!(name: request.name)
+  end
+end
+```
+
+### Send
+
+```ruby
+Medi8.send(CreateUser.new(name: "Alice"))
+```
+
+---
+
+## Notifications
+
+### Define an Event
+
+```ruby
+class UserRegistered
+  attr_reader :user_id
+
+  def initialize(user_id:)
+    @user_id = user_id
+  end
+end
+```
+
+### Define a Subscriber
+
+```ruby
+class SendWelcomeEmail
+  include Medi8::NotificationHandler
+
+  subscribes_to UserRegistered, async: true
+
+  def call(event)
+    UserMailer.welcome_email(User.find(event.user_id)).deliver_later
+  end
+end
+```
+
+### Publish
+
+```ruby
+Medi8.publish(UserRegistered.new(user_id: 1))
+```
+
+---
+
+## Advanced Usage
+
+Medi8 is compatible with [Active CQRS](https://github.com/kiebor81/active_cqrs).
+
+For project layout consistency, use `events` and `handlers/events` for your Medi8 classes. This will align nicely with the expected folder structures of Active CQRS. If following this advice, remember to auto-load these directories.
+
+```ruby
+    config.autoload_paths += %W[
+      #{config.root}/app/events
+      #{config.root}/app/handlers/events
+    ]
+
+    config.eager_load_paths += %W[
+      #{config.root}/app/events
+      #{config.root}/app/handlers/events
+    ]
+```
+
+Alternatively, namespace appropriately if you prefer nested classes.
+
+### Mediator Pattern with CQRS
+
+Example Active CQRS command:
+
+```ruby
+# app/commands/create_user_command.rb
+class CreateUserCommand
+  attr_reader :name, :email
+
+  def initialize(name:, email:)
+    @name = name
+    @email = email
+  end
+end
+```
+
+Active CQRS handler with Medi8:
+
+```ruby
+# app/handlers/commands/create_user_handler.rb
+class CreateUserHandler
+  def call(command)
+    user = User.create!(name: command.name, email: command.email)
+
+    Medi8.publish(UserRegistered.new(user_id: user.id, email: user.email))
+
+    user
+  end
+end
+```
+
+Medi8 notification published from the handler:
+
+```ruby
+# app/events/user_registered.rb
+class UserRegistered
+  attr_reader :user_id, :email
+
+  def initialize(user_id:, email:)
+    @user_id = user_id
+    @email = email
+  end
+end
+```
+
+Medi8 notification handler(s):
+
+```ruby
+# app/handlers/events/send_welcome_email_handler.rb
+class SendWelcomeEmailHandler
+  include Medi8::NotificationHandler
+  subscribes_to UserRegistered
+
+  def call(event)
+    UserMailer.welcome_email(event.email).deliver_later
+  end
+end
+```
+
+```ruby
+# app/handlers/events/track_user_registration_handler.rb
+class TrackUserRegistrationHandler
+  include Medi8::NotificationHandler
+  subscribes_to UserRegistered
+
+  def call(event)
+    Rails.logger.info("=> User registered: #{event.user_id} (#{event.email})")
+  end
+end
+```
+
+Example controller:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    command = CreateUserCommand.new(
+      name: params[:name],
+      email: params[:email]
+    )
+
+    user = CQRS_COMMAND_BUS.call(command)
+    render json: user, status: :created
+  rescue ActiveRecord::RecordInvalid => e
+    render json: { errors: e.record.errors.full_messages }, status: :unprocessable_entity
+  end
+end
+```
+
+---
+
+## Testing
+
+```bash
+$ bundle exec rspec
+```
+
+### Mock E2E
+
+Provided is an end-to-end mock flow under `mock_e2e`. Test this from the terminal.
+
+```bash
+ruby mock_e2e.rb
+```
+
+---
+
+## License
+
+MIT License © kiebor81
+
+---
+
+## Contributing
+
+Bug reports and pull requests welcome.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin my-feature`)
+5. Create a new Pull Request

data/lib/medi8/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Medi8
+  # Configuration class for Medi8, allowing users to set up middleware and registry.
+  class Configuration
+    # Initializes a new configuration instance with an empty registry and middleware stack.
+    def initialize
+      @registry = Medi8::Registry.new
+      @middleware_stack = Medi8::MiddlewareStack.new
+    end
+
+    attr_reader :registry, :middleware_stack
+
+    # Adds a new middleware registry entry.
+    def use(middleware)
+      @middleware_stack.use(middleware)
+    end
+  end
+end

data/lib/medi8/handler.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Medi8
+  # The Handler module is used to define classes that can handle specific types of requests.
+  module Handler
+    # This method is called when the module is included in a class.
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # This method is used to register a handler for a specific request class.
+    module ClassMethods
+      def handles(request_class)
+        Medi8.registry.register(request_class, self)
+      end
+    end
+  end
+end

data/lib/medi8/jobs/notification_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Medi8
+  # This job is used to handle notifications in Medi8.
+  module Jobs
+    # NotificationJob is an ActiveJob that processes notifications.
+    class NotificationJob < ActiveJob::Base
+      queue_as :default
+
+      # Perform the job with the given handler class name, event hash, and event class name.
+      def perform(handler_class_name, event_hash, event_class_name)
+        handler = handler_class_name.constantize.new
+        event = event_class_name.constantize.new(**event_hash.symbolize_keys)
+        handler.call(event)
+      end
+    end
+  end
+end

data/lib/medi8/mediator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Medi8
+  # Mediator is the main entry point for handling requests and publishing events.
+  class Mediator
+    def initialize(registry)
+      @registry = registry
+    end
+
+    # Sends a request to the appropriate handler.
+    def send(request)
+      handler_class = @registry.find_handler_for(request.class)
+      raise "No handler registered for #{request.class}" unless handler_class
+
+      final = -> { handler_class.new.call(request) }
+
+      if defined?(Medi8.middleware_stack)
+        Medi8.middleware_stack.call(request, &final)
+      else
+        final.call
+      end
+    end
+
+    # Publishes an event to all registered subscribers.
+    def publish(event)
+      NotificationDispatcher.new(@registry).publish(event)
+    end
+  end
+end

data/lib/medi8/middleware_stack.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Medi8
+  # MiddlewareStack is a stack of middleware that can be used to process requests.
+  class MiddlewareStack
+    # Initializes a new MiddlewareStack.
+    def initialize
+      @middlewares = []
+    end
+
+    # Adds a middleware to the stack.
+    def use(middleware)
+      @middlewares << middleware
+    end
+
+    # Calls the middlewares in reverse order, passing the request and a final block.
+    def call(request, &final)
+      @middlewares.reverse.inject(final) do |next_middleware, middleware|
+        -> { middleware.new.call(request, &next_middleware) }
+      end.call
+    end
+  end
+end

data/lib/medi8/notifications.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Medi8
+  # Medi8 Notifications Module
+  module NotificationHandler
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Registers a class as a notification handler for a specific event class.
+    module ClassMethods
+      def subscribes_to(event_class, async: false)
+        Medi8.registry.register_notification(event_class, self, async: async)
+      end
+    end
+  end
+
+  # Medi8 Notification dispatcher
+  class NotificationDispatcher
+    def initialize(registry)
+      @registry = registry
+    end
+
+    # Publishes an event to all registered handlers for that event class.
+    def publish(event) # rubocop:disable Metrics/MethodLength
+      handlers = @registry.find_notification_handlers_for(event.class)
+      handlers.each do |handler_def|
+        handler_class, async = handler_def
+
+        if async
+          Medi8::Jobs::NotificationJob.perform_later(
+            handler_class.name,
+            event.instance_variables.to_h { |var| [var.to_s.delete("@"), event.instance_variable_get(var)] },
+            event.class.name
+          )
+        else
+          handler_class.new.call(event)
+        end
+      end
+    end
+  end
+end

data/lib/medi8/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Medi8
+  # Railtie for integrating Medi8 with Rails
+  class Railtie < Rails::Railtie
+    initializer "medi8.load_handlers" do
+      ActiveSupport.on_load(:after_initialize) do
+        # Auto-load files like app/requests/** and app/handlers/**
+        Dir[Rails.root.join("app", "handlers", "**", "*.rb")].each { |file| require file }
+        Dir[Rails.root.join("app", "requests", "**", "*.rb")].each { |file| require file }
+      end
+    end
+  end
+end

data/lib/medi8/registry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Medi8
+  # Registry for managing request handlers and event notifications
+  class Registry
+    def initialize
+      @handlers = {}
+    end
+
+    # Singleton instance of the Registry
+    def register(request_class, handler_class)
+      @handlers[request_class] = handler_class
+    end
+
+    # Find the handler for a given request class
+    def find_handler_for(request_class)
+      @handlers[request_class]
+    end
+
+    # Register a notification event and its handler
+    def register_notification(event_class, handler_class, async: false)
+      @notifications ||= Hash.new { |h, k| h[k] = [] }
+      @notifications[event_class] << [handler_class, async]
+    end
+
+    # Find all handlers for a given notification event class
+    def find_notification_handlers_for(event_class)
+      (@notifications && @notifications[event_class]) || []
+    end
+  end
+end

data/lib/medi8/version.rb

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

data/lib/medi8.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "medi8/version"
+require_relative "medi8/registry"
+require_relative "medi8/mediator"
+require_relative "medi8/handler"
+require_relative "medi8/railtie" if defined?(Rails)
+require_relative "medi8/configuration"
+require_relative "medi8/middleware_stack"
+require_relative "medi8/notifications"
+
+# Medi8 is a lightweight event-driven framework for Ruby applications.
+module Medi8
+  class << self
+    # Configures the Medi8 framework.
+    def configure
+      yield configuration
+    end
+
+    # Returns the current configuration for Medi8.
+    def configuration
+      @configuration ||= Medi8::Configuration.new
+    end
+
+    # Provides a convenient way to access the Mediator instance.
+    def send(request)
+      Mediator.new(registry).send(request)
+    end
+
+    # Publishes an event to the Mediator, which will notify all registered handlers.
+    def publish(event)
+      Mediator.new(registry).publish(event)
+    end
+
+    # Returns the registry instance used by Medi8.
+    def registry
+      configuration.registry
+    end
+
+    # Returns the middleware stack used by Medi8.
+    def middleware_stack
+      configuration.middleware_stack
+    end
+
+    # Adds a middleware to the Medi8 middleware stack.
+    def use(middleware)
+      middleware_stack.use(middleware)
+    end
+  end
+end

data/sig/medi8.rbs

@@ -0,0 +1,51 @@
+# medi8.rbs
+module Medi8
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.registry: () -> Registry
+  def self.send: (untyped request) -> untyped
+  def self.publish: (untyped event) -> void
+  def self.middleware_stack: () -> MiddlewareStack
+  def self.use: (untyped middleware) -> void
+
+  class Configuration
+    def registry: () -> Registry
+    def middleware_stack: () -> MiddlewareStack
+    def use: (untyped middleware) -> void
+  end
+
+  class Registry
+    def register: (untyped request_class, untyped handler_class) -> void
+    def find_handler_for: (untyped request_class) -> untyped
+    def register_notification: (untyped event_class, untyped handler_class, ?async: bool) -> void
+    def find_notification_handlers_for: (untyped event_class) -> Array[[untyped, bool]]
+  end
+
+  class MiddlewareStack
+    def use: (untyped middleware) -> void
+    def call: (untyped request, &block) -> untyped
+  end
+
+  class Mediator
+    def initialize: (Registry registry) -> void
+    def send: (untyped request) -> untyped
+    def publish: (untyped event) -> void
+  end
+
+  module Handler
+    module ClassMethods
+      def handles: (untyped request_class) -> void
+    end
+  end
+
+  module NotificationHandler
+    module ClassMethods
+      def subscribes_to: (untyped event_class, ?async: bool) -> void
+    end
+  end
+
+  module Jobs
+    class NotificationJob < ::ActiveJob::Base
+      def perform: (String handler_class_name, Hash[String, untyped] event_hash, String event_class_name) -> void
+    end
+  end
+end

data/spec/medi8/configuration_spec.rb

@@ -0,0 +1,15 @@
+# spec/medi8/configuration_spec.rb
+RSpec.describe Medi8::Configuration do
+  it "exposes registry and middleware stack" do
+    config = described_class.new
+    expect(config.registry).to be_a(Medi8::Registry)
+    expect(config.middleware_stack).to be_a(Medi8::MiddlewareStack)
+  end
+
+  it "accepts middleware via use" do
+    mw = Class.new
+    config = described_class.new
+    config.use(mw)
+    expect(config.middleware_stack.instance_variable_get(:@middlewares)).to include(mw)
+  end
+end

data/spec/medi8/handler_spec.rb

@@ -0,0 +1,18 @@
+RSpec.describe Medi8::Handler do
+  it "registers a handler for a request class" do
+    request_class = Struct.new(:value, keyword_init: true)
+
+    handler_class = Class.new do
+      include Medi8::Handler
+
+      # The constant must be defined *inside* the test where the request_class is in scope
+      handles request_class
+
+      def call(req)
+        "Handled #{req.value}"
+      end
+    end
+
+    expect(Medi8.registry.find_handler_for(request_class)).to eq(handler_class)
+  end
+end

data/spec/medi8/mediator_spec.rb

@@ -0,0 +1,12 @@
+# spec/medi8/mediator_spec.rb
+RSpec.describe Medi8::Mediator do
+  let(:registry) { Medi8::Registry.new }
+  let(:request_class) { Class.new { attr_reader :val; def initialize(val:); @val = val; end } }
+  let(:handler_class) { Class.new { def call(req); "got #{req.val}"; end } }
+
+  it "dispatches a request to its handler" do
+    registry.register(request_class, handler_class)
+    result = described_class.new(registry).send(request_class.new(val: "x"))
+    expect(result).to eq("got x")
+  end
+end

data/spec/medi8/middleware_stack_spec.rb

@@ -0,0 +1,18 @@
+# spec/medi8/middleware_stack_spec.rb
+RSpec.describe Medi8::MiddlewareStack do
+  let(:stack) { described_class.new }
+
+  class TestMiddleware
+    def call(req)
+      req[:trace] << :middleware
+      yield
+    end
+  end
+
+  it "wraps execution in middleware layers" do
+    req = { trace: [] }
+    stack.use TestMiddleware
+    result = stack.call(req) { req[:trace] << :handler }
+    expect(req[:trace]).to eq([:middleware, :handler])
+  end
+end

data/spec/medi8/notifications_spec.rb

@@ -0,0 +1,20 @@
+RSpec.describe Medi8::NotificationHandler do
+  it "registers and executes notification handlers" do
+    event_class = Struct.new(:data, keyword_init: true)
+
+    Class.new do
+      include Medi8::NotificationHandler
+      subscribes_to event_class
+
+      def call(event)
+        event.data << :called
+      end
+    end
+
+    data = []
+    event = event_class.new(data: data)
+    Medi8.publish(event)
+
+    expect(data).to include(:called)
+  end
+end

data/spec/medi8/registry_spec.rb

@@ -0,0 +1,16 @@
+# spec/medi8/registry_spec.rb
+RSpec.describe Medi8::Registry do
+  let(:registry) { described_class.new }
+  let(:request_class) { Class.new }
+  let(:handler_class) { Class.new }
+
+  it "registers and retrieves a handler" do
+    registry.register(request_class, handler_class)
+    expect(registry.find_handler_for(request_class)).to eq(handler_class)
+  end
+
+  it "registers and retrieves notification handlers" do
+    registry.register_notification(String, handler_class)
+    expect(registry.find_notification_handlers_for(String)).to include([handler_class, false])
+  end
+end

data/spec/medi8_spec.rb

@@ -0,0 +1,15 @@
+# spec/medi8_spec.rb
+RSpec.describe Medi8 do
+  let(:request_class) { Class.new { attr_reader :value; def initialize(value:); @value = value; end } }
+  let(:handler_class) {
+    Class.new do
+      def call(req); "handled #{req.value}"; end
+    end
+  }
+
+  it "registers and sends a request to a handler" do
+    Medi8.registry.register(request_class, handler_class)
+    request = request_class.new(value: "test")
+    expect(Medi8.send(request)).to eq("handled test")
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: medi8-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kiebor81
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: Medi8 is a lightweight, idiomatic mediator pattern implementation for
+  Ruby and Rails, inspired by MediatR (from .NET)
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- sig/medi8.rbs
+files:
+- README.md
+- lib/medi8.rb
+- lib/medi8/configuration.rb
+- lib/medi8/handler.rb
+- lib/medi8/jobs/notification_job.rb
+- lib/medi8/mediator.rb
+- lib/medi8/middleware_stack.rb
+- lib/medi8/notifications.rb
+- lib/medi8/railtie.rb
+- lib/medi8/registry.rb
+- lib/medi8/version.rb
+- sig/medi8.rbs
+- spec/medi8/configuration_spec.rb
+- spec/medi8/handler_spec.rb
+- spec/medi8/mediator_spec.rb
+- spec/medi8/middleware_stack_spec.rb
+- spec/medi8/notifications_spec.rb
+- spec/medi8/registry_spec.rb
+- spec/medi8_spec.rb
+homepage: https://github.com/kiebor81/medi8-rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key: 
+specification_version: 4
+summary: Lightweight Ruby/Rails mediator inspired by MediatR
+test_files:
+- spec/medi8/configuration_spec.rb
+- spec/medi8/handler_spec.rb
+- spec/medi8/mediator_spec.rb
+- spec/medi8/middleware_stack_spec.rb
+- spec/medi8/notifications_spec.rb
+- spec/medi8/registry_spec.rb
+- spec/medi8_spec.rb