light-services 2.2.1 → 3.1.0

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "validation"
+
+module Light
+  module Services
+    module Dsl
+      # DSL for defining and managing service steps
+      module StepsDsl
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Define a step for the service
+          #
+          # @param name [Symbol] the step name (must correspond to a private method)
+          # @param opts [Hash] options for configuring the step
+          # @option opts [Symbol, Proc] :if Condition to determine if step should run
+          # @option opts [Symbol, Proc] :unless Condition to skip step (returns truthy to skip)
+          # @option opts [Boolean] :always (false) Run step even after errors/warnings
+          # @option opts [Symbol] :before Insert this step before the specified step
+          # @option opts [Symbol] :after Insert this step after the specified step
+          #
+          # @example Define a simple step
+          #   step :validate_input
+          #
+          # @example Define a conditional step
+          #   step :send_notification, if: :should_notify?
+          #   step :skip_validation, unless: :production?
+          #
+          # @example Define a step that always runs
+          #   step :cleanup, always: true
+          #
+          # @example Define step ordering
+          #   step :log_start, before: :validate_input
+          #   step :log_end, after: :process_data
+          #
+          # @example Define a step with proc condition
+          #   step :premium_feature, if: -> { user.premium? && feature_enabled? }
+          def step(name, opts = {}) # rubocop:disable Metrics/MethodLength
+            Validation.validate_symbol_name!(name, :step, self)
+            Validation.validate_reserved_name!(name, :step, self)
+            Validation.validate_name_conflicts!(name, :step, self)
+            validate_step_opts!(name, opts)
+
+            # Build current steps to check for duplicates and find insertion targets
+            current = steps
+            if current.key?(name)
+              raise Light::Services::Error,
+                    "Step `#{name}` is already defined in service #{self}. Each step must have a unique name."
+            end
+
+            if (target = opts[:before] || opts[:after]) && !current.key?(target)
+              available = current.keys.join(", ")
+              raise Light::Services::Error,
+                    "Cannot find target step `#{target}` in service #{self}. Available steps: [#{available}]"
+            end
+
+            step_obj = Settings::Step.new(name, self, opts)
+
+            if opts[:before] || opts[:after]
+              step_operations << { action: :insert, name: name, step: step_obj, before: opts[:before],
+                                   after: opts[:after], }
+            else
+              step_operations << { action: :add, name: name, step: step_obj }
+            end
+
+            # Clear memoized steps since we're modifying them
+            @steps = nil
+          end
+
+          # Remove a step from the service
+          #
+          # @param name [Symbol] the step name to remove
+          def remove_step(name)
+            step_operations << { action: :remove, name: name }
+
+            # Clear memoized steps since we're modifying them
+            @steps = nil
+          end
+
+          # Get all steps including inherited ones
+          #
+          # @return [Hash] all steps defined for this service
+          def steps
+            @steps ||= build_steps
+          end
+
+          # Get the list of step operations to be applied
+          #
+          # @return [Array] list of operations
+          def step_operations
+            @step_operations ||= []
+          end
+
+          # Validate that the service has steps defined
+          # Called before executing the service
+          #
+          # @raise [NoStepsError] if no steps are defined
+          def validate_steps!
+            return unless steps.empty?
+
+            raise Light::Services::NoStepsError,
+                  "Service #{self} has no steps defined. Define at least one step or implement a `run` method."
+          end
+
+          private
+
+          # Validate step options to ensure they are valid
+          #
+          # @param name [Symbol] the step name
+          # @param opts [Hash] the step options
+          def validate_step_opts!(name, opts)
+            return unless opts[:before] && opts[:after]
+
+            raise Light::Services::Error, "You cannot specify `before` and `after` " \
+                                          "for step `#{name}` in service #{self} at the same time"
+          end
+
+          # Build steps by applying operations to inherited steps
+          #
+          # @return [Hash] the final steps hash
+          def build_steps
+            # Start with inherited steps
+            result = inherit_steps
+
+            # Apply operations in order
+            step_operations.each { |op| apply_step_operation(result, op) }
+
+            # If no steps defined, check for `run` method as fallback
+            result[:run] = Settings::Step.new(:run, self, {}) if result.empty? && instance_method_defined?(:run)
+
+            result
+          end
+
+          # Check if an instance method is defined in this class or its ancestors
+          # (excluding Light::Services::Base and its modules)
+          #
+          # @param method_name [Symbol] the method name to check
+          # @return [Boolean] true if the method is defined
+          def instance_method_defined?(method_name)
+            # Check if method exists and is not from base service classes
+            return false unless method_defined?(method_name) || private_method_defined?(method_name)
+
+            # Get the method owner to ensure it's defined in user's service class
+            owner = instance_method(method_name).owner
+
+            # Method should be defined in a class that inherits from Base,
+            # not in Base itself or its included modules
+            !owner.to_s.start_with?("Light::Services")
+          end
+
+          # Inherit steps from parent class
+          #
+          # @return [Hash] inherited steps
+          def inherit_steps
+            superclass.respond_to?(:steps) ? superclass.steps.dup : {}
+          end
+
+          # Apply a single step operation to the steps hash
+          #
+          # @param steps [Hash] the steps hash
+          # @param operation [Hash] the operation to apply
+          def apply_step_operation(steps, operation)
+            case operation[:action]
+            when :add
+              steps[operation[:name]] = operation[:step]
+            when :remove
+              steps.delete(operation[:name])
+            when :insert
+              insert_step(steps, operation)
+            end
+          end
+
+          # Insert a step before or after a target step
+          #
+          # @param steps [Hash] the steps hash
+          # @param operation [Hash] the insert operation details
+          def insert_step(steps, operation)
+            target = operation[:before] || operation[:after]
+            keys = steps.keys
+            index = keys.index(target)
+            return unless index
+
+            # More efficient insertion using ordered hash reconstruction
+            new_steps = {}
+
+            keys.each_with_index do |key, i|
+              # Insert before target
+              new_steps[operation[:name]] = operation[:step] if operation[:before] && i == index
+              new_steps[key] = steps[key]
+
+              # Insert after target
+              new_steps[operation[:name]] = operation[:step] if operation[:after] && i == index
+            end
+
+            steps.replace(new_steps)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Light
+  module Services
+    module Dsl
+      # Shared validation logic for DSL modules
+      module Validation
+        # Validate that the name is a symbol
+        #
+        # @param name [Object] the name to validate
+        # @param field_type [Symbol] the type of field (:argument, :output, :step)
+        # @param service_class [Class] the service class for error messages
+        def self.validate_symbol_name!(name, field_type, service_class)
+          return if name.is_a?(Symbol)
+
+          raise Light::Services::InvalidNameError,
+                "#{field_type.to_s.capitalize} name must be a Symbol, " \
+                "got #{name.class} (#{name.inspect}) in #{service_class}"
+        end
+
+        # Validate that the name is not a reserved word
+        #
+        # @param name [Symbol] the name to validate
+        # @param field_type [Symbol] the type of field (:argument, :output, :step)
+        # @param service_class [Class] the service class for error messages
+        def self.validate_reserved_name!(name, field_type, service_class)
+          return unless ReservedNames::ALL.include?(name.to_sym)
+
+          raise Light::Services::ReservedNameError,
+                "Cannot use `#{name}` as #{field_type} name in #{service_class} - " \
+                "it is a reserved word that conflicts with gem methods"
+        end
+
+        # Validate that the name doesn't conflict with other defined names
+        #
+        # @param name [Symbol] the name to validate
+        # @param field_type [Symbol] the type of field being defined (:argument, :output, :step)
+        # @param service_class [Class] the service class to check for conflicts
+        def self.validate_name_conflicts!(name, field_type, service_class)
+          name_sym = name.to_sym
+
+          case field_type
+          when :argument
+            validate_argument_conflicts!(name_sym, service_class)
+          when :output
+            validate_output_conflicts!(name_sym, service_class)
+          when :step
+            validate_step_conflicts!(name_sym, service_class)
+          end
+        end
+
+        # Validate argument name doesn't conflict with outputs or steps
+        def self.validate_argument_conflicts!(name_sym, service_class)
+          # Check against existing outputs
+          if has_output?(name_sym, service_class)
+            raise Light::Services::ReservedNameError,
+                  "Cannot use `#{name_sym}` as argument name in #{service_class} - " \
+                  "it is already defined as an output"
+          end
+
+          # Check against existing steps
+          if has_step?(name_sym, service_class)
+            raise Light::Services::ReservedNameError,
+                  "Cannot use `#{name_sym}` as argument name in #{service_class} - " \
+                  "it is already defined as a step"
+          end
+        end
+
+        # Validate output name doesn't conflict with arguments or steps
+        def self.validate_output_conflicts!(name_sym, service_class)
+          # Check against existing arguments
+          if has_argument?(name_sym, service_class)
+            raise Light::Services::ReservedNameError,
+                  "Cannot use `#{name_sym}` as output name in #{service_class} - " \
+                  "it is already defined as an argument"
+          end
+
+          # Check against existing steps
+          if has_step?(name_sym, service_class)
+            raise Light::Services::ReservedNameError,
+                  "Cannot use `#{name_sym}` as output name in #{service_class} - " \
+                  "it is already defined as a step"
+          end
+        end
+
+        # Validate step name doesn't conflict with arguments or outputs
+        def self.validate_step_conflicts!(name_sym, service_class)
+          # Check against existing arguments
+          if has_argument?(name_sym, service_class)
+            raise Light::Services::ReservedNameError,
+                  "Cannot use `#{name_sym}` as step name in #{service_class} - " \
+                  "it is already defined as an argument"
+          end
+
+          # Check against existing outputs
+          if has_output?(name_sym, service_class)
+            raise Light::Services::ReservedNameError,
+                  "Cannot use `#{name_sym}` as step name in #{service_class} - " \
+                  "it is already defined as an output"
+          end
+        end
+
+        # Check if a name is already defined as an argument
+        def self.has_argument?(name_sym, service_class)
+          # Check own_arguments (current class)
+          (service_class.respond_to?(:own_arguments) && service_class.own_arguments.key?(name_sym)) ||
+            # Check inherited arguments
+            (service_class.superclass.respond_to?(:arguments) && service_class.superclass.arguments.key?(name_sym))
+        end
+
+        # Check if a name is already defined as an output
+        def self.has_output?(name_sym, service_class)
+          # Check own_outputs (current class)
+          (service_class.respond_to?(:own_outputs) && service_class.own_outputs.key?(name_sym)) ||
+            # Check inherited outputs
+            (service_class.superclass.respond_to?(:outputs) && service_class.superclass.outputs.key?(name_sym))
+        end
+
+        # Check if a name is already defined as a step
+        def self.has_step?(name_sym, service_class)
+          # Check step_operations (current class) for non-removed steps
+          (service_class.respond_to?(:step_operations) &&
+           service_class.step_operations.any? { |op| op[:name] == name_sym && op[:action] != :remove }) ||
+            # Check inherited steps
+            (service_class.superclass.respond_to?(:steps) && service_class.superclass.steps.key?(name_sym))
+        end
+
+        # Validate that the type option is provided when require_type is enabled
+        #
+        # @param name [Symbol] the field name
+        # @param field_type [Symbol] the type of field (:argument, :output)
+        # @param service_class [Class] the service class for error messages
+        # @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)
+
+          raise Light::Services::MissingTypeError,
+                "#{field_type.to_s.capitalize} `#{name}` in #{service_class} must have a type specified " \
+                "(require_type is enabled)"
+        end
+
+        # Check if require_type is enabled for the service class
+        def self.require_type_enabled?(service_class)
+          # 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
+
+            return class_config[:require_type] if class_config&.key?(:require_type)
+
+            klass = klass.superclass
+          end
+
+          Light::Services.config.require_type
+        end
+      end
+    end
+  end
+end

data/lib/light/services/exceptions.rb

@@ -2,9 +2,32 @@
 
 module Light
   module Services
+    # Base exception class for all Light::Services errors.
     class Error < StandardError; end
+
+    # Raised when an argument or output value doesn't match the expected type.
     class ArgTypeError < Error; end
-    class NoStepError < Error; end
-    class TwoConditions < Error; end
+
+    # Raised when using a reserved name for an argument, output, or step.
+    class ReservedNameError < Error; end
+
+    # Raised when a name is invalid (e.g., not a Symbol).
+    class InvalidNameError < Error; end
+
+    # Raised when a service has no steps defined and no run method.
+    class NoStepsError < Error; end
+
+    # Raised when type is required but not specified for an argument or output.
+    class MissingTypeError < Error; end
+
+    # Control flow exception for stop_immediately!
+    # Not an error - used to halt execution gracefully.
+    class StopExecution < StandardError; end
+
+    # @deprecated Use {Error} instead
+    NoStepError = Error
+
+    # @deprecated Use {Error} instead
+    TwoConditions = Error
   end
 end

data/lib/light/services/message.rb

@@ -1,26 +1,51 @@
 # frozen_string_literal: true
 
-# This class stores errors and warnings
 module Light
   module Services
+    # Represents a single error or warning message.
+    #
+    # @example Creating a message
+    #   message = Message.new(:name, "can't be blank", break: true)
+    #   message.key    # => :name
+    #   message.text   # => "can't be blank"
+    #   message.break? # => true
     class Message
-      # Getters
-      attr_reader :key, :text
+      # @return [Symbol] the key/field this message belongs to
+      attr_reader :key
 
+      # @return [String] the message text
+      attr_reader :text
+
+      # Create a new message.
+      #
+      # @param key [Symbol] the key/field this message belongs to
+      # @param text [String] the message text
+      # @param opts [Hash] additional options
+      # @option opts [Boolean] :break whether to stop step execution
+      # @option opts [Boolean] :rollback whether to rollback the transaction
       def initialize(key, text, opts = {})
         @key = key
         @text = text
         @opts = opts
       end
 
+      # Check if this message should stop step execution.
+      #
+      # @return [Boolean] true if break option was set
       def break?
         @opts[:break]
       end
 
+      # Check if this message should trigger a transaction rollback.
+      #
+      # @return [Boolean] true if rollback option was set
       def rollback?
         @opts[:rollback]
       end
 
+      # Return the message text.
+      #
+      # @return [String] the message text
       def to_s
         text
       end

data/lib/light/services/messages.rb

@@ -1,23 +1,89 @@
 # frozen_string_literal: true
 
-# This class stores errors and warnings
 module Light
   module Services
+    # Collection of error or warning messages, organized by key.
+    #
+    # @example Adding and accessing errors
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:email, "is invalid")
+    #   errors[:name]  # => [#<Message key: :name, text: "can't be blank">]
+    #   errors.to_h    # => { name: ["can't be blank"], email: ["is invalid"] }
     class Messages
+      extend Forwardable
+
+      # @!method [](key)
+      #   Get messages for a specific key.
+      #   @param key [Symbol] the key to look up
+      #   @return [Array<Message>, nil] array of messages or nil
+
+      # @!method any?
+      #   Check if there are any messages.
+      #   @return [Boolean] true if messages exist
+
+      # @!method empty?
+      #   Check if the collection is empty.
+      #   @return [Boolean] true if no messages
+
+      # @!method size
+      #   Get number of keys with messages.
+      #   @return [Integer] number of keys
+
+      # @!method keys
+      #   Get all keys with messages.
+      #   @return [Array<Symbol>] array of keys
+
+      # @!method key?(key)
+      #   Check if a key has messages.
+      #   @param key [Symbol] the key to check
+      #   @return [Boolean] true if key has messages
+      def_delegators :@messages, :[], :any?, :empty?, :size, :keys, :values, :each, :each_with_index, :key?
+      alias has_key? key?
+
+      # Initialize a new messages collection.
+      #
+      # @param config [Hash] configuration options
+      # @option config [Boolean] :break_on_add stop execution when message added
+      # @option config [Boolean] :raise_on_add raise exception when message added
+      # @option config [Boolean] :rollback_on_add rollback transaction when message added
       def initialize(config)
         @break = false
         @config = config
         @messages = {}
       end
 
+      # Get total count of all messages across all keys.
+      #
+      # @return [Integer] total number of messages
+      def count
+        @messages.values.sum(&:size)
+      end
+
+      # Add a message to the collection.
+      #
+      # @param key [Symbol] the key/field for this message
+      # @param texts [String, Array<String>, Message] the message text(s) to add
+      # @param opts [Hash] additional options
+      # @option opts [Boolean] :break override break behavior for this message
+      # @option opts [Boolean] :rollback override rollback behavior for this message
+      # @return [void]
+      # @raise [Error] if text is nil or empty
+      #
+      # @example Add a single error
+      #   errors.add(:name, "can't be blank")
+      #
+      # @example Add multiple errors
+      #   errors.add(:email, ["is invalid", "is already taken"])
       def add(key, texts, opts = {})
-        raise Light::Services::Error, "Error text can't be blank" if !texts || texts.blank?
+        raise Light::Services::Error, "Error must be a non-empty string" unless texts
 
         message = nil
 
         [*texts].each do |text|
           message = text.is_a?(Message) ? text : Message.new(key, text, opts)
 
+          raise Light::Services::Error, "Error must be a non-empty string" unless valid_error_text?(message.text)
+
           @messages[key] ||= []
           @messages[key] << message
         end
@@ -27,10 +93,25 @@ module Light
         rollback!(opts.key?(:rollback) ? opts[:rollback] : message.rollback?) if !opts.key?(:last) || opts[:last]
       end
 
+      # Check if step execution should stop.
+      #
+      # @return [Boolean] true if a message triggered a break
       def break?
         @break
       end
 
+      # Copy messages from another source.
+      #
+      # @param entity [ActiveRecord::Base, Base, Hash, #each] source to copy from
+      # @param opts [Hash] options to pass to each added message
+      # @return [void]
+      # @raise [Error] if entity type is not supported
+      #
+      # @example Copy from ActiveRecord model
+      #   errors.copy_from(user) # copies user.errors
+      #
+      # @example Copy from another service
+      #   errors.copy_from(child_service)
       def copy_from(entity, opts = {})
         if defined?(ActiveRecord::Base) && entity.is_a?(ActiveRecord::Base)
           copy_from(entity.errors.messages, opts)
@@ -46,43 +127,22 @@ module Light
           raise Light::Services::Error, "Don't know how to import errors from #{entity}"
         end
       end
+      alias from_record copy_from
 
-      def copy_to(entity)
-        if (defined?(ActiveRecord::Base) && entity.is_a?(ActiveRecord::Base)) || entity.is_a?(Light::Services::Base)
-          each do |key, messages|
-            messages.each do |message|
-              entity.errors.add(key, message.to_s)
-            end
-          end
-        elsif entity.is_a?(Hash)
-          each do |key, messages|
-            entity[key] ||= []
-            entity[key] += messages.map(&:to_s)
-          end
-        else
-          raise Light::Services::Error, "Don't know how to export errors to #{entity}"
-        end
-
-        entity
-      end
-
+      # Convert messages to a hash with string values.
+      #
+      # @return [Hash{Symbol => Array<String>}] messages as hash
       def to_h
         @messages.to_h.transform_values { |value| value.map(&:to_s) }
       end
 
-      def method_missing(method, *args, &block)
-        if @messages.respond_to?(method)
-          @messages.public_send(method, *args, &block)
-        else
-          super
-        end
-      end
+      private
 
-      def respond_to_missing?(method, include_private = false)
-        @messages.respond_to?(method, include_private) || super
-      end
+      def valid_error_text?(text)
+        return false unless text.is_a?(String)
 
-      private
+        !text.strip.empty?
+      end
 
       def break!(break_execution)
         return unless break_execution.nil? ? @config[:break_on_add] : break_execution