interceptors 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4c31ab76d3b09a2a51c674ceb27aaaaf82cda31e6267b56be86b67ee77a9155
-  data.tar.gz: f1a4039246aa384126f1391faa4e879d3f4a8d3b98900f95f88e5b5bbe7aa60e
+  metadata.gz: 6f06c031c777b039546473d09618c1b7c76c1709879e4c9f516384811599a770
+  data.tar.gz: b7bc835285431b9784a5d4c492f5c1b3851e3638d0856be5e146412b68d6d367
 SHA512:
-  metadata.gz: 8a5edaa5997b949864f547e50d2226b75af99fd9bc214cbff7b8e4eec4f23e6546e104edc46978aed03d6ae0b860d1955f2125a92b5b7c2a1105d9ceef3ab9fb
-  data.tar.gz: 942e90230e3bd6ecbff48ab19d2bbb81543cf09e805c3dec779731fbab1515537270d522172a97c08c03e7efb9c69031b9920245272beb1c89844e3458fc5842
+  metadata.gz: eab8fd67835c55d4ec907f30ca5a9fdb182542336e48d915b11204cbb6fbd14e065b4ab41d1b2cf25bf57a638f732c6b92810e0e79755c1a9904f54a5ef0502d
+  data.tar.gz: bbf17a658891f4e88f8295ac03b00de649cfc0b1ba483b2065286f1b4c85e710ff4f96cb8119c5c60c57e0a843b8752559b147bceadfdc7860c08175da988a97

data/README.md

@@ -116,6 +116,25 @@ else
 end
 ```
 
+### Using the mixin instead of inheritance
+
+If you prefer not to inherit from `Interceptors::UseCase`, include the mixin to add the same DSL and runtime behaviour to any PORO:
+
+```ruby
+class RefundOrder
+  include Interceptors::UseCaseMixin
+
+  use Interceptors::LoggingInterceptor.new
+
+  def execute(ctx)
+    refund = RefundProcessor.call!(order_id: ctx[:order_id])
+    Interceptors::Result.ok(refund)
+  rescue RefundProcessor::Error => e
+    Interceptors::Result.err(Interceptors::AppError.new(e.message, code: "refund_failed"))
+  end
+end
+```
+
 Instrument use cases with ActiveSupport:
 
 ```ruby
@@ -124,6 +143,48 @@ ActiveSupport::Notifications.subscribe("use_case.finish") do |_name, _start, _fi
 end
 ```
 
+### Writing custom interceptors
+
+Interceptors respond to three optional hooks:
+
+- `before(ctx)` runs before the next step and can mutate the context or raise to halt execution.
+- `around(ctx) { |ctx| ... }` wraps the remainder of the pipeline; call `yield ctx` to continue or return a `Result` to short-circuit.
+- `after(ctx, result)` executes after the inner handler returns; return value is ignored unless you return a new `Result`.
+
+To build your own interceptor:
+
+```ruby
+class AuditInterceptor < Interceptors::Interceptor
+  def before(ctx)
+    AuditTrail.write(event: "start", use_case: ctx[:use_case])
+  end
+
+  def around(ctx)
+    super
+  rescue => e
+    AuditTrail.write(event: "error", use_case: ctx[:use_case], error: e.class.name)
+    raise
+  end
+
+  def after(_ctx, result)
+    AuditTrail.write(event: "finish", ok: result.ok?)
+    result
+  end
+end
+
+class ProcessPayment < Interceptors::UseCase
+  use AuditInterceptor.new
+
+  # ...
+end
+```
+
+Checklist for custom interceptors:
+
+1. Subclass `Interceptors::Interceptor` (or include behavior manually) and implement whichever hooks you need.
+2. Ensure `around` always yields or returns an `Interceptors::Result` to keep the pipeline consistent.
+3. Register the interceptor with `use` on your use case, or reuse it across multiple use cases.
+
 For Rails controllers, include the responder helper:
 
 ```ruby

data/lib/interceptors/use_case.rb

@@ -2,116 +2,6 @@
 
 module Interceptors
   class UseCase
-    class << self
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@interceptors, interceptors.dup)
-      end
-
-      def interceptors
-        @interceptors ||= []
-      end
-
-      def use(interceptor)
-        interceptors << interceptor
-        self
-      end
-
-      def call(input = {}, **kwargs)
-        new.call(input, **kwargs)
-      end
-    end
-
-    def call(input = {}, **kwargs)
-      ctx = build_context(input, **kwargs)
-
-      instrument(event_name("start"), name: self.class.name, ctx: ctx)
-
-      result = pipeline.call(ctx) { |context| normalize_result(execute(context)) }
-      result = normalize_result(result)
-
-      instrument(event_name("finish"),
-                 name: self.class.name,
-                 ctx: ctx,
-                 ok: result.ok?,
-                 error: result.error&.message)
-
-      result
-    rescue AppError => e
-      instrument(event_name("error"),
-                 name: self.class.name,
-                 ctx: ctx,
-                 code: e.code,
-                 message: e.message)
-
-      Result.err(e, meta: base_meta)
-    rescue StandardError => e
-      instrument(event_name("error"),
-                 name: self.class.name,
-                 ctx: ctx,
-                 code: "unhandled_exception",
-                 message: e.message,
-                 error_class: e.class.name)
-
-      err = AppError.new("Unhandled exception",
-                         code: "unhandled_exception",
-                         http_status: 500,
-                         details: { cause: e.class.name })
-      Result.err(err, meta: base_meta.merge(error_class: e.class.name))
-    end
-
-    private
-
-    def execute(_ctx)
-      raise NotImplementedError, "#{self.class} must implement #execute"
-    end
-
-    def normalize_result(result)
-      case result
-      when Result
-        result
-      when nil
-        Result.ok
-      else
-        Result.ok(result)
-      end
-    end
-
-    def base_meta
-      { use_case: self.class.name }
-    end
-
-    def build_context(input, **kwargs)
-      ctx = default_context.merge(normalize_input(input))
-      ctx.merge!(kwargs) unless kwargs.empty?
-      ctx.with_indifferent_access
-    end
-
-    def normalize_input(input)
-      return input if input.is_a?(Hash)
-      return input.to_h if input.respond_to?(:to_h)
-
-      raise ArgumentError, "use case input must be a Hash or respond to #to_h (got #{input.class})"
-    end
-
-    def default_context
-      {}
-    end
-
-    def pipeline
-      Pipeline.new(self.class.interceptors)
-    end
-
-    def notification_namespace
-      Interceptors.configuration.notification_namespace
-    end
-
-    def instrument(event_name, payload, &block)
-      Interceptors.instrument(event_name, payload, &block)
-    end
-
-    def event_name(suffix)
-      "#{notification_namespace}.#{suffix}"
-    end
+    include UseCaseCore
   end
 end

data/lib/interceptors/use_case_core.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Interceptors
+  module UseCaseCore
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+      base.instance_variable_set(:@interceptors, [])
+    end
+
+    module ClassMethods
+      def interceptors
+        @interceptors ||= []
+      end
+
+      def use(interceptor)
+        interceptors << interceptor
+        self
+      end
+
+      def call(input = {}, **kwargs)
+        new.call(input, **kwargs)
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@interceptors, interceptors.dup)
+      end
+    end
+
+    module InstanceMethods
+      def call(input = {}, **kwargs)
+        ctx = build_context(input, **kwargs)
+
+        instrument(event_name("start"), name: self.class.name, ctx: ctx)
+
+        result = pipeline.call(ctx) { |context| normalize_result(execute(context)) }
+        result = normalize_result(result)
+
+        instrument(event_name("finish"),
+                   name: self.class.name,
+                   ctx: ctx,
+                   ok: result.ok?,
+                   error: result.error&.message)
+
+        result
+      rescue AppError => e
+        instrument(event_name("error"),
+                   name: self.class.name,
+                   ctx: ctx,
+                   code: e.code,
+                   message: e.message)
+
+        Result.err(e, meta: base_meta)
+      rescue StandardError => e
+        instrument(event_name("error"),
+                   name: self.class.name,
+                   ctx: ctx,
+                   code: "unhandled_exception",
+                   message: e.message,
+                   error_class: e.class.name)
+
+        err = AppError.new("Unhandled exception",
+                           code: "unhandled_exception",
+                           http_status: 500,
+                           details: { cause: e.class.name })
+        Result.err(err, meta: base_meta.merge(error_class: e.class.name))
+      end
+
+      private
+
+      def execute(_ctx)
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      def default_context
+        {}
+      end
+
+      def normalize_result(result)
+        case result
+        when Result
+          result
+        when nil
+          Result.ok
+        else
+          Result.ok(result)
+        end
+      end
+
+      def base_meta
+        { use_case: self.class.name }
+      end
+
+      def build_context(input, **kwargs)
+        ctx = default_context.merge(normalize_input(input))
+        ctx.merge!(kwargs) unless kwargs.empty?
+        ctx.with_indifferent_access
+      end
+
+      def normalize_input(input)
+        return input if input.is_a?(Hash)
+        return input.to_h if input.respond_to?(:to_h)
+
+        raise ArgumentError, "use case input must be a Hash or respond to #to_h (got #{input.class})"
+      end
+
+      def pipeline
+        Pipeline.new(self.class.interceptors)
+      end
+
+      def notification_namespace
+        Interceptors.configuration.notification_namespace
+      end
+
+      def instrument(event_name, payload, &block)
+        Interceptors.instrument(event_name, payload, &block)
+      end
+
+      def event_name(suffix)
+        "#{notification_namespace}.#{suffix}"
+      end
+    end
+  end
+end

data/lib/interceptors/use_case_mixin.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Interceptors
+  module UseCaseMixin
+    def self.included(base)
+      base.include(UseCaseCore)
+    end
+  end
+end

data/lib/interceptors/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Interceptors
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interceptors
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Laerti papa
@@ -78,6 +78,8 @@ files:
 - lib/interceptors/timeout_interceptor.rb
 - lib/interceptors/transaction_interceptor.rb
 - lib/interceptors/use_case.rb
+- lib/interceptors/use_case_core.rb
+- lib/interceptors/use_case_mixin.rb
 - lib/interceptors/validation_error.rb
 - lib/interceptors/validation_interceptor.rb
 - lib/interceptors/version.rb