light-services 3.0.0 → 3.1.1

data/lib/light/services/base_with_context.rb

@@ -1,9 +1,22 @@
 # frozen_string_literal: true
 
-# This class allows running a service object with context (parent class and custom config)
 module Light
   module Services
+    # Wrapper for running a service with a parent context or custom configuration.
+    # Created via {Base.with} method.
+    #
+    # @example Running with parent service context
+    #   ChildService.with(self).run(data: value)
+    #
+    # @example Running with custom configuration
+    #   MyService.with(use_transactions: false).run(name: "test")
     class BaseWithContext
+      # Initialize a new context wrapper.
+      #
+      # @param service_class [Class] the service class to run
+      # @param parent_service [Base, nil] parent service for error/warning propagation
+      # @param config [Hash] configuration overrides
+      # @raise [ArgTypeError] if parent_service is not a Base subclass
       def initialize(service_class, parent_service, config)
         @service_class = service_class
         @config = config
@@ -14,10 +27,19 @@ module Light
         raise Light::Services::ArgTypeError, "#{parent_service.class} - must be a subclass of Light::Services::Base"
       end
 
+      # Run the service with the configured context.
+      #
+      # @param args [Hash] arguments to pass to the service
+      # @return [Base] the executed service instance
       def run(args = {})
         @service_class.new(extend_arguments(args), @config, @parent_service).tap(&:call)
       end
 
+      # Run the service and raise an error if it fails.
+      #
+      # @param args [Hash] arguments to pass to the service
+      # @return [Base] the executed service instance
+      # @raise [Error] if the service fails
       def run!(args = {})
         @config[:raise_on_error] = true
         run(args)

data/lib/light/services/callbacks.rb

@@ -2,7 +2,38 @@
 
 module Light
   module Services
+    # Provides callback hooks for service and step lifecycle events.
+    #
+    # @example Service-level callbacks
+    #   class MyService < Light::Services::Base
+    #     before_service_run :log_start
+    #     after_service_run { |service| Rails.logger.info("Done!") }
+    #     on_service_success :send_notification
+    #     on_service_failure :log_error
+    #   end
+    #
+    # @example Step-level callbacks
+    #   class MyService < Light::Services::Base
+    #     before_step_run :log_step_start
+    #     after_step_run { |service, step_name| puts "Finished #{step_name}" }
+    #     on_step_failure :handle_step_error
+    #   end
+    #
+    # @example Around callbacks
+    #   class MyService < Light::Services::Base
+    #     around_service_run :with_timing
+    #
+    #     private
+    #
+    #     def with_timing(service)
+    #       start = Time.now
+    #       yield
+    #       puts "Took #{Time.now - start}s"
+    #     end
+    #   end
     module Callbacks
+      # Available callback events.
+      # @return [Array<Symbol>] list of callback event names
       EVENTS = [
         :before_step_run,
         :after_step_run,
@@ -17,47 +48,12 @@ module Light
         :on_service_failure,
       ].freeze
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      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 all callbacks for a specific event (including inherited ones)
-        def callbacks_for(event)
-          @callbacks ||= {}
-          @callbacks[event] ||= []
-        end
-
-        # Get all callbacks including inherited ones
-        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 callbacks for a given event
-      # For around callbacks, yields to the block
-      # For other callbacks, just executes them in order
+      # Run all callbacks for a given event.
+      #
+      # @param event [Symbol] the callback event name
+      # @param args [Array] arguments to pass to callbacks
+      # @yield for around callbacks, the block to wrap
+      # @return [void]
       def run_callbacks(event, *args, &block)
         callbacks = self.class.all_callbacks_for(event)
 
@@ -99,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/collection.rb

@@ -2,15 +2,34 @@
 
 require_relative "constants"
 
-# Collection to store arguments and outputs values
 module Light
   module Services
+    # Collection module for storing argument and output values.
     module Collection
+      # Storage for service arguments or outputs with type validation.
+      #
+      # @example Accessing values
+      #   service.arguments[:name]  # => "John"
+      #   service.outputs[:user]    # => #<User id: 1>
       class Base
         extend Forwardable
 
+        # @!method key?(key)
+        #   Check if a key exists in the collection.
+        #   @param key [Symbol] the key to check
+        #   @return [Boolean] true if key exists
+
+        # @!method to_h
+        #   Convert collection to a hash.
+        #   @return [Hash] the stored values
         def_delegators :@storage, :key?, :to_h
 
+        # Initialize a new collection.
+        #
+        # @param instance [Base] the service instance
+        # @param collection_type [String] "arguments" or "outputs"
+        # @param storage [Hash] initial values
+        # @raise [ArgTypeError] if storage is not a Hash
         def initialize(instance, collection_type, storage = {})
           validate_collection_type!(collection_type)
 
@@ -23,22 +42,43 @@ module Light
           raise Light::Services::ArgTypeError, "#{instance.class} - #{collection_type} must be a Hash"
         end
 
+        # Set a value in the collection.
+        #
+        # @param key [Symbol] the key to set
+        # @param value [Object] the value to store
+        # @return [Object] the stored value
         def set(key, value)
           @storage[key] = value
         end
 
+        # Get a value from the collection.
+        #
+        # @param key [Symbol] the key to retrieve
+        # @return [Object, nil] the stored value or nil
         def get(key)
           @storage[key]
         end
 
+        # Get a value using bracket notation.
+        #
+        # @param key [Symbol] the key to retrieve
+        # @return [Object, nil] the stored value or nil
         def [](key)
           get(key)
         end
 
+        # Set a value using bracket notation.
+        #
+        # @param key [Symbol] the key to set
+        # @param value [Object] the value to store
+        # @return [Object] the stored value
         def []=(key, value)
           set(key, value)
         end
 
+        # Load default values for fields that haven't been set.
+        #
+        # @return [void]
         def load_defaults
           settings_collection.each do |name, settings|
             next if !settings.default_exists || key?(name)
@@ -51,6 +91,10 @@ module Light
           end
         end
 
+        # Validate all values against their type definitions.
+        #
+        # @return [void]
+        # @raise [ArgTypeError] if a value fails type validation
         def validate!
           settings_collection.each do |name, field|
             next if field.optional && (!key?(name) || get(name).nil?)
@@ -62,7 +106,11 @@ module Light
           end
         end
 
-        # Extend args with context values (only for arguments)
+        # Extend arguments hash with context values from this collection.
+        # Only applies to arguments collections.
+        #
+        # @param args [Hash] arguments hash to extend
+        # @return [Hash] the extended arguments hash
         def extend_with_context(args)
           return args unless @collection_type == CollectionTypes::ARGUMENTS
 

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

@@ -40,6 +40,9 @@ module Light
 
               break if @errors.break? || @warnings.break?
             end
+          rescue Light::Services::StopExecution
+            # Gracefully handle stop_immediately! inside transaction to prevent rollback
+            @stopped = true
           end
         end
 

data/lib/light/services/config.rb

@@ -3,17 +3,73 @@
 module Light
   module Services
     class << self
+      # Configure Light::Services with a block.
+      #
+      # @yield [Config] the configuration object
+      # @return [void]
+      #
+      # @example
+      #   Light::Services.configure do |config|
+      #     config.require_type = true
+      #     config.use_transactions = false
+      #   end
       def configure
         yield config
       end
 
+      # Get the global configuration object.
+      #
+      # @return [Config] the configuration instance
       def config
         @config ||= Config.new
       end
     end
 
+    # Configuration class for Light::Services global settings.
+    #
+    # @example Accessing configuration
+    #   Light::Services.config.require_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 to wrap service execution in a database transaction
+      attr_reader :use_transactions
+
+      # @return [Boolean] whether to copy errors to parent service in chain
+      attr_reader :load_errors
+
+      # @return [Boolean] whether to stop executing steps when an error is added
+      attr_reader :break_on_error
+
+      # @return [Boolean] whether to raise Light::Services::Error when service fails
+      attr_reader :raise_on_error
+
+      # @return [Boolean] whether to rollback the transaction when an error is added
+      attr_reader :rollback_on_error
+
+      # @return [Boolean] whether to copy warnings to parent service in chain
+      attr_reader :load_warnings
+
+      # @return [Boolean] whether to stop executing steps when a warning is added
+      attr_reader :break_on_warning
+
+      # @return [Boolean] whether to raise Light::Services::Error when service has warnings
+      attr_reader :raise_on_warning
+
+      # @return [Boolean] whether to rollback the transaction when a warning is added
+      attr_reader :rollback_on_warning
+
+      # @return [Hash{String => String}] custom type mappings for Ruby LSP addon.
+      #   Maps dry-types or custom types to Ruby types for hover/completion.
+      #   @example { "Types::UUID" => "String", "CustomTypes::Money" => "BigDecimal" }
+      attr_reader :ruby_lsp_type_mappings
+
       DEFAULTS = {
+        require_type: true,
         use_transactions: true,
 
         load_errors: true,
@@ -25,22 +81,46 @@ module Light
         break_on_warning: false,
         raise_on_warning: false,
         rollback_on_warning: false,
+
+        ruby_lsp_type_mappings: {}.freeze,
       }.freeze
 
-      attr_accessor(*DEFAULTS.keys)
+      DEFAULTS.each_key do |name|
+        define_method(:"#{name}=") do |value|
+          instance_variable_set(:"@#{name}", value)
+          @to_h = nil # Invalidate memoized hash
+        end
+      end
 
+      # Initialize configuration with default values.
       def initialize
         reset_to_defaults!
       end
 
+      # Reset all configuration options to their default values.
+      #
+      # @return [void]
       def reset_to_defaults!
-        DEFAULTS.each { |key, value| public_send(:"#{key}=", value) }
+        DEFAULTS.each do |key, value|
+          instance_variable_set(:"@#{key}", value)
+        end
+
+        @to_h = nil # Invalidate memoized hash
       end
 
+      # Convert configuration to a hash.
+      #
+      # @return [Hash{Symbol => Object}] all configuration options as a hash
       def to_h
-        DEFAULTS.keys.to_h { |key| [key, public_send(key)] }
+        @to_h ||= DEFAULTS.keys.to_h do |key|
+          [key, public_send(key)]
+        end
       end
 
+      # Merge configuration with additional options.
+      #
+      # @param config [Hash] options to merge
+      # @return [Hash] merged configuration hash
       def merge(config)
         to_h.merge(config)
       end

data/lib/light/services/constants.rb

@@ -31,6 +31,9 @@ module Light
         :failed?,
         :errors?,
         :warnings?,
+        :stop!,
+        :stopped?,
+        :stop_immediately!,
         :done!,
         :done?,
         :call,

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

@@ -41,6 +41,7 @@ module Light
             Validation.validate_symbol_name!(name, :argument, self)
             Validation.validate_reserved_name!(name, :argument, self)
             Validation.validate_name_conflicts!(name, :argument, self)
+            Validation.validate_type_required!(name, :argument, self, opts)
 
             own_arguments[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::ARGUMENT))
             @arguments = nil # Clear memoized arguments since we're modifying them

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

@@ -37,6 +37,7 @@ module Light
             Validation.validate_symbol_name!(name, :output, self)
             Validation.validate_reserved_name!(name, :output, self)
             Validation.validate_name_conflicts!(name, :output, self)
+            Validation.validate_type_required!(name, :output, self, opts)
 
             own_outputs[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::OUTPUT))
             @outputs = nil # Clear memoized outputs since we're modifying them