servus 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f382ed3d92dd577c93965ae207c00d28cac6dfddf452cf22fb5dafcd69d56eb
-  data.tar.gz: f5a4394a33f5a3061d3c5746fdd058eb457cb29baa2f0adb9cc97c0679f5c158
+  metadata.gz: 15cec1ebe831437428e84374b7b7a83cc34c1f4cbcdc13bfe1c847eca5c1c9b3
+  data.tar.gz: 2b371d1069a549fab5af3de5aca80d8be029850cc0c1e3378e7643c742b917dd
 SHA512:
-  metadata.gz: 5ccb1adc1b0bd4b7ff9f8b754571be541bbf7e3b9246746fe73c9e1259ad4b6f6e3a5a4d6c07d3b9f30cb8ddda94dfc2cad7c78fb6dc31fb17440c1d3a19b6be
-  data.tar.gz: 0107e7e4d770913a5e86de5c496791e6311c913dc6b2bdad03417b78a2e66be6d50c2fc5d213f87b51162ac4a15d3c6c9dcb9b323267a9db9d0b222099f60245
+  metadata.gz: a66d2a07c3c564148e612fac96ab22e350c9483938226a495cc7b97b3b96ad979a4dba26b3bc2b5090bb3fc4c3c5016647f186f34cbe93bdc9f8f0f329205572
+  data.tar.gz: 56d23b1caac58e6d1c62062b80ecd85bb50784f034709fb5228d742e5de0c76e6a096bf59d45d67d84b0e024e2a0ba7f8f283db2027e543aa5543ad383eee2b3

data/lib/servus/events/emitter.rb

@@ -33,12 +33,15 @@ module Servus
         # Declares an event that this service will emit.
         #
         # Events are automatically emitted when the service completes with the specified
-        # trigger condition (:success, :failure, or :error). Use the `with` option to
-        # provide a custom payload builder, or pass a block.
+        # trigger condition (:success, :failure, or :error). Use the `with` option or a
+        # block to provide a custom payload builder. Use `if` or `unless` to gate emission
+        # on a runtime condition.
         #
         # @param event_name [Symbol] the name of the event to emit
-        # @param on [Symbol] when to emit (:success, :failure, or :error)
-        # @param with [Symbol, nil] optional instance method name for building the payload
+        # @param on [Symbol] when to emit (:success, :failure, or :error!)
+        # @option options [Symbol, nil] :with instance method name for building the payload
+        # @option options [Proc, Symbol, nil] :if condition proc or method name; event only emits when truthy
+        # @option options [Proc, Symbol, nil] :unless condition proc or method name; event only emits when falsy
         # @yield [result] optional block for building the payload
         # @yieldparam result [Servus::Support::Response] the service result
         # @yieldreturn [Hash] the event payload
@@ -67,6 +70,22 @@ module Servus
         #     end
         #   end
         #
+        # @example Conditional emission with if: lambda
+        #   class CreateUser < Servus::Base
+        #     emits :premium_user_created, on: :success, if: ->(result) { result.data[:plan] == :premium }
+        #   end
+        #
+        # @example Conditional emission with unless: method reference
+        #   class CreateUser < Servus::Base
+        #     emits :user_created, on: :success, unless: :suppressed?
+        #
+        #     private
+        #
+        #     def suppressed?(result)
+        #       result.data[:suppressed]
+        #     end
+        #   end
+        #
         # @note Best Practice: Services should typically emit ONE event per trigger
         #   that represents their core concern. Multiple downstream reactions should
         #   be coordinated by Event classes, not by emitting multiple events
@@ -87,7 +106,7 @@ module Servus
         #
         # @see Servus::Events::Bus
         # @see Servus::Event
-        def emits(event_name, on:, with: nil, &block)
+        def emits(event_name, on:, **options, &block)
           valid_triggers = %i[success failure error!]
 
           unless valid_triggers.include?(on)
@@ -95,10 +114,7 @@ module Servus
           end
 
           @event_emissions ||= { success: [], failure: [], error!: [] }
-          @event_emissions[on] << {
-            event_name: event_name,
-            payload_builder: block || with
-          }
+          @event_emissions[on] << build_emission(event_name, options, block)
         end
 
         # Returns all event emissions declared for this service.
@@ -116,6 +132,17 @@ module Servus
         def emissions_for(trigger)
           event_emissions[trigger] || []
         end
+
+        private
+
+        def build_emission(event_name, options, block)
+          {
+            event_name: event_name,
+            if_condition: options[:if],
+            unless_condition: options[:unless],
+            payload_builder: block || options[:with]
+          }
+        end
       end
 
       # Emits events for a specific trigger with the given result.
@@ -126,6 +153,8 @@ module Servus
       # @api private
       def emit_events_for(trigger, result)
         self.class.emissions_for(trigger).each do |emission|
+          next unless emission_condition_met?(emission, result)
+
           payload = build_event_payload(emission, result)
           validate_event_payload!(emission[:event_name], payload)
           Servus::Events::Bus.emit(emission[:event_name], payload)
@@ -133,7 +162,35 @@ module Servus
       end
 
       # Instance methods for emitting events during service execution
-      private
+
+      # Returns true when all declared conditions on the emission pass.
+      #
+      # @param emission [Hash] the emission configuration
+      # @param result [Servus::Support::Response] the service result
+      # @return [Boolean]
+      # @api private
+      def emission_condition_met?(emission, result)
+        if_condition = emission[:if_condition]
+        unless_condition = emission[:unless_condition]
+
+        return false if if_condition && !evaluate_emission_condition(if_condition, result)
+        return false if unless_condition && evaluate_emission_condition(unless_condition, result)
+
+        true
+      end
+
+      # Evaluates a single emission condition — either a Proc/lambda or a Symbol method reference.
+      #
+      # Both forms receive the result object so conditions can inspect result.data,
+      # result.error, result.success?, etc.
+      #
+      # @param condition [Proc, Symbol] the condition to evaluate
+      # @param result [Servus::Support::Response] the service result
+      # @return [Object] truthy or falsy value
+      # @api private
+      def evaluate_emission_condition(condition, result)
+        condition.is_a?(Proc) ? instance_exec(result, &condition) : send(condition, result)
+      end
 
       # Validates the payload against the Event class's schema registered for the event.
       #
@@ -159,8 +216,7 @@ module Servus
         builder = emission[:payload_builder]
 
         if builder.is_a?(Proc)
-          # Block-based payload builder
-          builder.call(result)
+          instance_exec(result, &builder)
         elsif builder.is_a?(Symbol)
           # Method-based payload builder
           send(builder, result)

data/lib/servus/testing/matchers.rb

@@ -55,6 +55,11 @@ RSpec::Matchers.define :emit_event do |event_class_or_symbol|
         "got: #{@matching_event[:payload].inspect}"
     end
   end
+
+  failure_message_when_negated do
+    "expected event :#{@event_name} not to be emitted, but it was.\n" \
+      "Payload: #{@matching_event[:payload].inspect}"
+  end
 end
 
 # Matcher for asserting service invocation

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = '0.5.0'
+  VERSION = '0.5.2'
 end

data/lib/servus.rb

@@ -4,8 +4,7 @@
 require 'json-schema'
 require 'active_support'
 require 'active_support/core_ext/class/attribute'
-require 'active_model_serializers'
-
+require 'active_support/core_ext/hash/indifferent_access'
 # Servus namespace
 module Servus; end
 

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-07 00:00:00.000000000 Z
+date: 2026-05-25 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: active_model_serializers
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.10.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement