light-services 3.1.1 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7b40ae2a9930c6ee5831c6d5f64f84aeab383b4f35295a41faf8ae9e0735c82
-  data.tar.gz: 8bb7c192556ec28c904bd931abbf502c2533b39137c2d7d989469c11c61cd70d
+  metadata.gz: 1c9112f92c81696cc02f0d3440b848abca3a501f503b9bf95e645296d0a122dc
+  data.tar.gz: 22c0672f290fc82f843d55f31060941dceedae0a991eb25697010ffd12b5fae9
 SHA512:
-  metadata.gz: 671d913a895af97d0c37e45d21e930794317d60fac03bd46df3e43ef3dc6190617b5b5522f445f57143d96434104df636f5d29cf9c6c35d60604f61f54781dfa
-  data.tar.gz: eacef0ee6679653963d6b09a6c660c9ee503e8edc3df04411547f36e07bea91210d2683ff02ed1ee6d96924062c6e1620f95b87959e40ac80e78a211c7048f96
+  metadata.gz: 4b851d34f2c6a89a63a2d2f747db12b75f50741aabcbb3cbda4d8154a1ba65560894c2cabe4ac94f7f50f4ffc8fcdeb6280b83aa61a53888f76dd691c3cf1770
+  data.tar.gz: 1e2ca16aaf58aee4d8adcda2d83ea881761a3f1c09543461edf5ad2516d91ee76b639eae20477c66c94619437b51a7e717932d5cc9750d18a0d6b2bd9e0e4036

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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
@@ -10,7 +20,7 @@
 
 ### 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/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/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

@@ -136,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/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.1"
+    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.1
+  version: 3.1.2
 platform: ruby
 authors:
 - Andrew Kodkod