light-services 3.1.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14b80318915db3dc20bd40365dc9ad00160938bb6836c1cda14bfba5301c7d7a
-  data.tar.gz: 80515890786ed055972e5b52bbc6cdee8e79b85d4fa1227b217f4b746c9fb899
+  metadata.gz: 1c9112f92c81696cc02f0d3440b848abca3a501f503b9bf95e645296d0a122dc
+  data.tar.gz: 22c0672f290fc82f843d55f31060941dceedae0a991eb25697010ffd12b5fae9
 SHA512:
-  metadata.gz: 454b6f2cd8fdf8615bc29c6b69e16fe704a3b19abd8f7e48fbd1e848505038db013e41396399dd5caa721d7179ae1bc3a6a99989a3adfc0f6868e9fe49a63c85
-  data.tar.gz: 50dbf071f72a242c0c36daeb83db94db5826dca4e3e2bbe7a47f9c81006b4d2c2266731715e1948b6528df86633735839f6eee525abde302a76b7a046e484b72
+  metadata.gz: 4b851d34f2c6a89a63a2d2f747db12b75f50741aabcbb3cbda4d8154a1ba65560894c2cabe4ac94f7f50f4ffc8fcdeb6280b83aa61a53888f76dd691c3cf1770
+  data.tar.gz: 1e2ca16aaf58aee4d8adcda2d83ea881761a3f1c09543461edf5ad2516d91ee76b639eae20477c66c94619437b51a7e717932d5cc9750d18a0d6b2bd9e0e4036

data/CHANGELOG.md

@@ -1,10 +1,26 @@
 # Changelog
 
+## 3.1.2 (2025-12-13)
+
+### Added
+
+- Add `fail!` and `fail_immediately!` helpers
+
+### Changed
+
+- Split `config.require_type` into `config.require_arg_type` and `config.require_output_type`
+
+## 3.1.1 (2025-12-13)
+
+### Added
+
+- Better IDE support for callbacks DSL
+
 ## 3.1.0 (2025-12-13)
 
 ### Breaking changes
 
-- Enforce arguments and output types by default. Add `config.require_type = false` to your config to disable this behavior.
+- Enforce arguments and output types by default. Use `config.require_arg_type = false` and `config.require_output_type = false` to disable this behavior. The convenience setter `config.require_type = false` sets both options at once for backward compatibility.
 
 ### Added
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.1.0)
+    light-services (3.1.1)
 
 GEM
   remote: https://rubygems.org/

data/docs/{summary.md → SUMMARY.md}

@@ -1,8 +1,13 @@
-# Table of contents
+# Summary​
+
+## Introduction
 
 * [Light Services](README.md)
 * [Quickstart](quickstart.md)
 * [Concepts](concepts.md)
+
+## Deep Dive
+
 * [Arguments](arguments.md)
 * [Steps](steps.md)
 * [Outputs](outputs.md)
@@ -14,6 +19,9 @@
 * [Rails Generators](generators.md)
 * [RuboCop Integration](rubocop.md)
 * [Ruby LSP Integration](ruby-lsp.md)
+
+## Examples
+
 * [Best Practices](best-practices.md)
 * [Recipes](recipes.md)
   * [CRUD](crud.md)

data/docs/arguments.md

@@ -66,13 +66,13 @@ class MyService < ApplicationService
 end
 ```
 
-To disable type enforcement for a specific service:
+To disable type enforcement for arguments in a specific service:
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_arg_type: false
   
-  arg :name              # Allowed when require_type is disabled
+  arg :name              # Allowed when require_arg_type is disabled
 end
 ```
 

data/docs/concepts.md

@@ -7,39 +7,39 @@ This section covers the core concepts of Light Services: **Arguments**, **Steps*
 When you call `MyService.run(args)`, the following happens:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────┐
 │                      Service.run(args)                       │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  1. Load default values for arguments and outputs            │
 │  2. Validate argument types                                  │
 │  3. Run before_service_run callbacks                         │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  4. Begin around_service_run callback                        │
 │  5. Begin database transaction (if use_transactions: true)   │
-│     ┌─────────────────────────────────────────────────────┐ │
-│     │  6. Execute steps in order                          │ │
-│     │     - Run before_step_run / around_step_run         │ │
-│     │     - Execute step method                           │ │
-│     │     - Run after_step_run / on_step_success          │ │
-│     │     - Skip if condition (if:/unless:) not met       │ │
-│     │     - Stop if errors.break? is true                 │ │
-│     │     - Stop if stop! was called                      │ │
-│     ├─────────────────────────────────────────────────────┤ │
-│     │  7. On error → Rollback transaction                 │ │
-│     │     On success → Commit transaction                 │ │
-│     └─────────────────────────────────────────────────────┘ │
+│     ┌─────────────────────────────────────────────────────┐  │
+│     │  6. Execute steps in order                          │  │
+│     │     - Run before_step_run / around_step_run         │  │
+│     │     - Execute step method                           │  │
+│     │     - Run after_step_run / on_step_success          │  │
+│     │     - Skip if condition (if:/unless:) not met       │  │
+│     │     - Stop if errors.break? is true                 │  │
+│     │     - Stop if stop! was called                      │  │
+│     ├─────────────────────────────────────────────────────┤  │
+│     │  7. On error → Rollback transaction                 │  │
+│     │     On success → Commit transaction                 │  │
+│     └─────────────────────────────────────────────────────┘  │
 │  8. End around_service_run callback                          │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  9. Run steps marked with always: true (unless stop! called) │
 │ 10. Validate output types (if success)                       │
 │ 11. Copy errors/warnings to parent service (if in context)   │
 │ 12. Run after_service_run callback                           │
 │ 13. Run on_service_success or on_service_failure callback    │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │ 14. Return service instance                                  │
 │     - service.success? / service.failed?                     │
 │     - service.outputs / service.errors                       │
-└─────────────────────────────────────────────────────────────┘
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ## Arguments

data/docs/configuration.md

@@ -8,8 +8,9 @@ Configure Light Services globally using an initializer. For Rails applications,
 
 ```ruby
 Light::Services.configure do |config|
-# Type enforcement
-  config.require_type = true            # Require type option for all arguments and outputs
+  # Type enforcement
+  config.require_arg_type = true        # Require type option for all arguments
+  config.require_output_type = true     # Require type option for all outputs
 
   # Transaction settings
   config.use_transactions = true        # Wrap each service in a database transaction
@@ -32,7 +33,8 @@ end
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `require_type` | `true` | Raises `Light::Services::MissingTypeError` when defining arguments or outputs without a `type` option |
+| `require_arg_type` | `true` | Raises `Light::Services::MissingTypeError` when defining arguments without a `type` option |
+| `require_output_type` | `true` | Raises `Light::Services::MissingTypeError` when defining outputs without a `type` option |
 | `use_transactions` | `true` | Wraps service execution in `ActiveRecord::Base.transaction` |
 | `load_errors` | `true` | Propagates errors to parent service when using `.with(self)` |
 | `break_on_error` | `true` | Stops executing remaining steps when an error is added |
@@ -159,7 +161,8 @@ To disable type enforcement globally (not recommended):
 
 ```ruby
 Light::Services.configure do |config|
-  config.require_type = false
+  config.require_arg_type = false     # Disable for arguments
+  config.require_output_type = false  # Disable for outputs
 end
 ```
 
@@ -167,10 +170,22 @@ Or disable for specific services:
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_arg_type: false, require_output_type: false
   
-  arg :data              # Allowed when require_type is disabled
-  output :result         # Allowed when require_type is disabled
+  arg :data              # Allowed when require_arg_type is disabled
+  output :result         # Allowed when require_output_type is disabled
+end
+```
+
+You can also control them independently:
+
+```ruby
+class StrictInputService < ApplicationService
+  # Require types for arguments but not outputs
+  config require_arg_type: true, require_output_type: false
+  
+  arg :data, type: Hash  # Type required
+  output :result         # Type not required
 end
 ```
 

data/docs/errors.md

@@ -44,6 +44,24 @@ class ParsePage < ApplicationService
 end
 ```
 
+## Quick Error with `fail!`
+
+The `fail!` method is a shortcut for adding an error to the `:base` key:
+
+```ruby
+class ParsePage < ApplicationService
+  def validate
+    fail!("URL is required") if url.blank?
+  end
+end
+```
+
+This is equivalent to:
+
+```ruby
+errors.add(:base, "URL is required")
+```
+
 ## Reading Errors
 
 To check if a service has errors, you can use the `#failed?` method. You can also use methods like `errors.any?` to inspect errors.
@@ -205,11 +223,13 @@ Light Services defines several exception classes for different error scenarios:
 | `Light::Services::ReservedNameError` | Raised when using a reserved name for arguments, outputs, or steps |
 | `Light::Services::InvalidNameError` | Raised when using an invalid name format |
 | `Light::Services::NoStepsError` | Raised when a service has no steps defined and no `run` method |
-| `Light::Services::MissingTypeError` | Raised when defining an argument or output without a `type` option when `require_type` is enabled |
+| `Light::Services::MissingTypeError` | Raised when defining an argument or output without a `type` option when `require_arg_type` or `require_output_type` is enabled |
+| `Light::Services::StopExecution` | Control flow exception raised by `stop_immediately!` to halt execution without rollback |
+| `Light::Services::FailExecution` | Control flow exception raised by `fail_immediately!` to halt execution and rollback transactions |
 
 ### MissingTypeError
 
-This exception is raised when you define an argument or output without a `type` option. Since `require_type` is enabled by default, all arguments and outputs must have a type.
+This exception is raised when you define an argument or output without a `type` option. Since `require_arg_type` and `require_output_type` are enabled by default, all arguments and outputs must have a type.
 
 ```ruby
 class MyService < ApplicationService
@@ -230,9 +250,10 @@ If you need to disable type enforcement for legacy services, you can use the `co
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_arg_type: false, require_output_type: false
   
-  arg :data              # Allowed when require_type is disabled
+  arg :data              # Allowed when require_arg_type is disabled
+  output :result         # Allowed when require_output_type is disabled
 end
 ```
 

data/docs/outputs.md

@@ -89,13 +89,13 @@ class MyService < ApplicationService
 end
 ```
 
-To disable type enforcement for a specific service:
+To disable type enforcement for outputs in a specific service:
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_output_type: false
   
-  output :data             # Allowed when require_type is disabled
+  output :data             # Allowed when require_output_type is disabled
 end
 ```
 

data/docs/steps.md

@@ -292,6 +292,58 @@ end
 **Database Transactions:** Calling `stop_immediately!` does NOT rollback database transactions. All database changes made before `stop_immediately!` was called will be committed.
 {% endhint %}
 
+## Immediate Failure with `fail_immediately!`
+
+Use `fail_immediately!` when you need to halt execution immediately AND rollback any database transactions. Unlike `stop_immediately!`, this method adds an error and causes transaction rollback.
+
+```ruby
+class Payment::Process < ApplicationService
+  arg :amount, type: Integer
+  arg :card_token, type: String
+
+  step :validate_card
+  step :charge_card
+  step :send_receipt
+
+  output :transaction_id, type: String
+
+  private
+
+  def validate_card
+    unless valid_card?(card_token)
+      fail_immediately!("Card validation failed")
+    end
+    
+    # This code won't run if card is invalid
+    log_validation_success
+  end
+
+  def charge_card
+    # This step won't run if fail_immediately! was called
+    self.transaction_id = PaymentGateway.charge(amount, card_token)
+  end
+end
+```
+
+{% hint style="warning" %}
+`fail_immediately!` raises an internal exception to halt execution. Steps marked with `always: true` will NOT run when `fail_immediately!` is called.
+{% endhint %}
+
+{% hint style="danger" %}
+**Database Transactions:** Calling `fail_immediately!` DOES rollback database transactions. All database changes made before `fail_immediately!` was called will be rolled back.
+{% endhint %}
+
+### Comparison Table
+
+| Method | Adds Error | Stops Execution | Transaction Rollback |
+|--------|------------|-----------------|---------------------|
+| `stop!` | No | After current step | No |
+| `stop_immediately!` | No | Immediately | No |
+| `fail!(msg)` | Yes (:base) | After current step* | No |
+| `fail_immediately!(msg)` | Yes (:base) | Immediately | Yes |
+
+*By default, adding an error stops subsequent steps from running due to `break_on_add` configuration.
+
 ## Removing Inherited Steps
 
 When inheriting from a parent service, you can remove steps using `remove_step`:

data/lib/light/services/base.rb

@@ -43,6 +43,7 @@ module Light
     #   result.success? # => true
     #   result.user     # => #<User id: 1, name: "John">
     class Base
+      extend CallbackDsl
       include Callbacks
       include Dsl::ArgumentsDsl
       include Dsl::OutputsDsl
@@ -135,6 +136,25 @@ module Light
         raise Light::Services::StopExecution
       end
 
+      # Add an error to the :base key.
+      #
+      # @param message [String] the error message
+      # @return [void]
+      def fail!(message)
+        errors.add(:base, message)
+      end
+
+      # Add an error and stop execution immediately, causing transaction rollback.
+      #
+      # @param message [String] the error message
+      # @raise [FailExecution] always raises to halt execution and rollback
+      # @return [void]
+      def fail_immediately!(message)
+        @stopped = true
+        errors.add(:base, message, rollback: false)
+        raise Light::Services::FailExecution
+      end
+
       # Execute the service steps.
       #
       # @return [void]

data/lib/light/services/callbacks.rb

@@ -48,64 +48,6 @@ module Light
         :on_service_failure,
       ].freeze
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      # Class methods for registering callbacks.
-      #
-      # Each callback event has a corresponding class method:
-      # - {before_step_run} - before each step executes
-      # - {after_step_run} - after each step executes
-      # - {around_step_run} - wraps step execution (must yield)
-      # - {on_step_success} - when a step completes without adding errors
-      # - {on_step_failure} - when a step adds errors
-      # - {on_step_crash} - when a step raises an exception
-      # - {before_service_run} - before the service starts
-      # - {after_service_run} - after the service completes
-      # - {around_service_run} - wraps service execution (must yield)
-      # - {on_service_success} - when service completes without errors
-      # - {on_service_failure} - when service completes with errors
-      module ClassMethods
-        # Define DSL methods for each callback event
-        EVENTS.each do |event|
-          define_method(event) do |method_name = nil, &block|
-            callback = method_name || block
-            raise ArgumentError, "#{event} requires a method name (symbol) or a block" unless callback
-
-            unless callback.is_a?(Symbol) || callback.is_a?(Proc)
-              raise ArgumentError,
-                    "#{event} callback must be a Symbol or Proc"
-            end
-
-            callbacks_for(event) << callback
-          end
-        end
-
-        # Get callbacks defined in this class for a specific event.
-        #
-        # @param event [Symbol] the callback event name
-        # @return [Array<Symbol, Proc>] callbacks for this event
-        def callbacks_for(event)
-          @callbacks ||= {}
-          @callbacks[event] ||= []
-        end
-
-        # Get all callbacks for an event including inherited ones.
-        #
-        # @param event [Symbol] the callback event name
-        # @return [Array<Symbol, Proc>] all callbacks for this event
-        def all_callbacks_for(event)
-          if superclass.respond_to?(:all_callbacks_for)
-            inherited = superclass.all_callbacks_for(event)
-          else
-            inherited = []
-          end
-
-          inherited + callbacks_for(event)
-        end
-      end
-
       # Run all callbacks for a given event.
       #
       # @param event [Symbol] the callback event name
@@ -153,5 +95,261 @@ module Light
         end
       end
     end
+
+    # Class methods for registering callbacks.
+    # Extend this module in your service class to get callback DSL methods.
+    #
+    # @example
+    #   class MyService < Light::Services::Base
+    #     before_service_run :setup
+    #     after_service_run :cleanup
+    #   end
+    module CallbackDsl
+      # Registers a callback to run before each step executes.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the step about to run
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   before_step_run :log_step_start
+      #
+      # @example With block
+      #   before_step_run { |service, step_name| puts "Starting #{step_name}" }
+      def before_step_run(method_name = nil, &block)
+        register_callback(:before_step_run, method_name, &block)
+      end
+
+      # Registers a callback to run after each step executes.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the step that just ran
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   after_step_run :log_step_complete
+      #
+      # @example With block
+      #   after_step_run { |service, step_name| puts "Finished #{step_name}" }
+      def after_step_run(method_name = nil, &block)
+        register_callback(:after_step_run, method_name, &block)
+      end
+
+      # Registers an around callback that wraps each step execution.
+      # The callback must yield to execute the step.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the step being wrapped
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   around_step_run :with_step_timing
+      #
+      #   def with_step_timing(service, step_name)
+      #     start = Time.now
+      #     yield
+      #     puts "#{step_name} took #{Time.now - start}s"
+      #   end
+      def around_step_run(method_name = nil, &block)
+        register_callback(:around_step_run, method_name, &block)
+      end
+
+      # Registers a callback to run when a step completes successfully (without adding errors).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the successful step
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_step_success :track_step_success
+      #
+      # @example With block
+      #   on_step_success { |service, step_name| Analytics.track("step.success", step: step_name) }
+      def on_step_success(method_name = nil, &block)
+        register_callback(:on_step_success, method_name, &block)
+      end
+
+      # Registers a callback to run when a step fails (adds errors).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the failed step
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_step_failure :handle_step_error
+      #
+      # @example With block
+      #   on_step_failure { |service, step_name| Rails.logger.error("Step #{step_name} failed") }
+      def on_step_failure(method_name = nil, &block)
+        register_callback(:on_step_failure, method_name, &block)
+      end
+
+      # Registers a callback to run when a step raises an exception.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name, exception] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the crashed step
+      # @yieldparam exception [Exception] the exception that was raised
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_step_crash :report_crash
+      #
+      # @example With block
+      #   on_step_crash { |service, step_name, error| Sentry.capture_exception(error) }
+      def on_step_crash(method_name = nil, &block)
+        register_callback(:on_step_crash, method_name, &block)
+      end
+
+      # Registers a callback to run before the service starts executing.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   before_service_run :log_start
+      #
+      # @example With block
+      #   before_service_run { |service| Rails.logger.info("Starting #{service.class.name}") }
+      def before_service_run(method_name = nil, &block)
+        register_callback(:before_service_run, method_name, &block)
+      end
+
+      # Registers a callback to run after the service completes (regardless of success/failure).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   after_service_run :cleanup
+      #
+      # @example With block
+      #   after_service_run { |service| Rails.logger.info("Done!") }
+      def after_service_run(method_name = nil, &block)
+        register_callback(:after_service_run, method_name, &block)
+      end
+
+      # Registers an around callback that wraps the entire service execution.
+      # The callback must yield to execute the service.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   around_service_run :with_timing
+      #
+      #   def with_timing(service)
+      #     start = Time.now
+      #     yield
+      #     puts "Took #{Time.now - start}s"
+      #   end
+      def around_service_run(method_name = nil, &block)
+        register_callback(:around_service_run, method_name, &block)
+      end
+
+      # Registers a callback to run when the service completes successfully (without errors).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_service_success :send_notification
+      #
+      # @example With block
+      #   on_service_success { |service| NotificationMailer.success(service.user).deliver_later }
+      def on_service_success(method_name = nil, &block)
+        register_callback(:on_service_success, method_name, &block)
+      end
+
+      # Registers a callback to run when the service completes with errors.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_service_failure :log_error
+      #
+      # @example With block
+      #   on_service_failure { |service| Rails.logger.error(service.errors.full_messages) }
+      def on_service_failure(method_name = nil, &block)
+        register_callback(:on_service_failure, method_name, &block)
+      end
+
+      # Get callbacks defined in this class for a specific event.
+      #
+      # @param event [Symbol] the callback event name
+      # @return [Array<Symbol, Proc>] callbacks for this event
+      def callbacks_for(event)
+        @callbacks ||= {}
+        @callbacks[event] ||= []
+      end
+
+      # Get all callbacks for an event including inherited ones.
+      #
+      # @param event [Symbol] the callback event name
+      # @return [Array<Symbol, Proc>] all callbacks for this event
+      def all_callbacks_for(event)
+        if superclass.respond_to?(:all_callbacks_for)
+          inherited = superclass.all_callbacks_for(event)
+        else
+          inherited = []
+        end
+
+        inherited + callbacks_for(event)
+      end
+
+      private
+
+      # Registers a callback for a given event.
+      #
+      # @param event [Symbol] the callback event name
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield block to execute if no method name provided
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      # @api private
+      def register_callback(event, method_name = nil, &block)
+        callback = method_name || block
+        raise ArgumentError, "#{event} requires a method name (symbol) or a block" unless callback
+
+        unless callback.is_a?(Symbol) || callback.is_a?(Proc)
+          raise ArgumentError, "#{event} callback must be a Symbol or Proc"
+        end
+
+        callbacks_for(event) << callback
+      end
+    end
   end
 end

data/lib/light/services/concerns/execution.rb

@@ -44,6 +44,10 @@ module Light
             # Gracefully handle stop_immediately! inside transaction to prevent rollback
             @stopped = true
           end
+        rescue Light::Services::FailExecution
+          # FailExecution bubbles out of transaction (causing rollback) but is caught here
+          # @stopped is already set by fail_immediately!
+          nil
         end
 
         # Run steps with parameter `always` if they weren't launched because of errors/warnings

data/lib/light/services/config.rb

@@ -10,7 +10,8 @@ module Light
       #
       # @example
       #   Light::Services.configure do |config|
-      #     config.require_type = true
+      #     config.require_arg_type = true
+      #     config.require_output_type = true
       #     config.use_transactions = false
       #   end
       def configure
@@ -28,13 +29,16 @@ module Light
     # Configuration class for Light::Services global settings.
     #
     # @example Accessing configuration
-    #   Light::Services.config.require_type # => true
+    #   Light::Services.config.require_arg_type # => true
     #
     # @example Modifying configuration
     #   Light::Services.config.use_transactions = false
     class Config
-      # @return [Boolean] whether arguments and outputs must have a type specified
-      attr_reader :require_type
+      # @return [Boolean] whether arguments must have a type specified
+      attr_reader :require_arg_type
+
+      # @return [Boolean] whether outputs must have a type specified
+      attr_reader :require_output_type
 
       # @return [Boolean] whether to wrap service execution in a database transaction
       attr_reader :use_transactions
@@ -69,7 +73,8 @@ module Light
       attr_reader :ruby_lsp_type_mappings
 
       DEFAULTS = {
-        require_type: true,
+        require_arg_type: true,
+        require_output_type: true,
         use_transactions: true,
 
         load_errors: true,
@@ -92,6 +97,16 @@ module Light
         end
       end
 
+      # Convenience setter for backward compatibility.
+      # Sets both require_arg_type and require_output_type.
+      #
+      # @param value [Boolean] whether to require types for arguments and outputs
+      # @return [void]
+      def require_type=(value)
+        self.require_arg_type = value
+        self.require_output_type = value
+      end
+
       # Initialize configuration with default values.
       def initialize
         reset_to_defaults!

data/lib/light/services/dsl/validation.rb

@@ -135,26 +135,37 @@ module Light
         # @param opts [Hash] the options hash to check for type
         def self.validate_type_required!(name, field_type, service_class, opts)
           return if opts.key?(:type)
-          return unless require_type_enabled?(service_class)
+          return unless require_type_enabled_for?(field_type, service_class)
 
+          config_name = field_type == :argument ? "require_arg_type" : "require_output_type"
           raise Light::Services::MissingTypeError,
                 "#{field_type.to_s.capitalize} `#{name}` in #{service_class} must have a type specified " \
-                "(require_type is enabled)"
+                "(#{config_name} is enabled)"
         end
 
-        # Check if require_type is enabled for the service class
-        def self.require_type_enabled?(service_class)
+        # Check if require_type is enabled for the given field type and service class
+        #
+        # @param field_type [Symbol] the type of field (:argument, :output)
+        # @param service_class [Class] the service class to check
+        # @return [Boolean] whether type is required for the field type
+        def self.require_type_enabled_for?(field_type, service_class)
+          config_key = field_type == :argument ? :require_arg_type : :require_output_type
+
           # Check class-level config in the inheritance chain, then fall back to global config
           klass = service_class
           while klass.respond_to?(:class_config)
             class_config = klass.class_config
 
+            # Check specific config first (require_arg_type or require_output_type)
+            return class_config[config_key] if class_config&.key?(config_key)
+
+            # Check convenience config (require_type) for backward compatibility
             return class_config[:require_type] if class_config&.key?(:require_type)
 
             klass = klass.superclass
           end
 
-          Light::Services.config.require_type
+          Light::Services.config.public_send(config_key)
         end
       end
     end

data/lib/light/services/exceptions.rb

@@ -24,6 +24,10 @@ module Light
     # Not an error - used to halt execution gracefully.
     class StopExecution < StandardError; end
 
+    # Control flow exception for fail_immediately!
+    # Unlike StopExecution, this exception causes transaction rollback.
+    class FailExecution < StandardError; end
+
     # @deprecated Use {Error} instead
     NoStepError = Error
 

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "3.1.0"
+    VERSION = "3.1.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.2
 platform: ruby
 authors:
 - Andrew Kodkod
@@ -34,6 +34,8 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/README.md
+- docs/SUMMARY.md
 - docs/arguments.md
 - docs/best-practices.md
 - docs/callbacks.md
@@ -46,13 +48,11 @@ files:
 - docs/outputs.md
 - docs/pundit-authorization.md
 - docs/quickstart.md
-- docs/readme.md
 - docs/recipes.md
 - docs/rubocop.md
 - docs/ruby-lsp.md
 - docs/service-rendering.md
 - docs/steps.md
-- docs/summary.md
 - docs/testing.md
 - lib/generators/light_services/install/USAGE
 - lib/generators/light_services/install/install_generator.rb