light-services 2.2.1 → 3.0.0

data/lib/light/services/config.rb

@@ -13,7 +13,6 @@ module Light
     end
 
     class Config
-      # Constants
       DEFAULTS = {
         use_transactions: true,
 
@@ -25,34 +24,21 @@ module Light
         load_warnings: true,
         break_on_warning: false,
         raise_on_warning: false,
-        rollback_on_warning: false
+        rollback_on_warning: false,
       }.freeze
 
-      # Getters / Setters
-      attr_accessor :use_transactions,
-                    :load_errors, :break_on_error, :raise_on_error, :rollback_on_error,
-                    :load_warnings, :break_on_warning, :raise_on_warning, :rollback_on_warning
+      attr_accessor(*DEFAULTS.keys)
 
       def initialize
         reset_to_defaults!
       end
 
-      def set(key, value)
-        instance_variable_set(:"@#{key}", value)
-      end
-
-      def get(key)
-        instance_variable_get(:"@#{key}")
-      end
-
       def reset_to_defaults!
-        DEFAULTS.each do |key, value|
-          set(key, value)
-        end
+        DEFAULTS.each { |key, value| public_send(:"#{key}=", value) }
       end
 
       def to_h
-        DEFAULTS.keys.to_h { |key| [key, get(key)] }
+        DEFAULTS.keys.to_h { |key| [key, public_send(key)] }
       end
 
       def merge(config)

data/lib/light/services/constants.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    # Collection type constants
+    module CollectionTypes
+      ARGUMENTS = :arguments
+      OUTPUTS = :outputs
+
+      ALL = [ARGUMENTS, OUTPUTS].freeze
+    end
+
+    # Field type constants
+    module FieldTypes
+      ARGUMENT = :argument
+      OUTPUT = :output
+
+      ALL = [ARGUMENT, OUTPUT].freeze
+    end
+
+    # Reserved names that cannot be used for arguments, outputs, or steps
+    # These names would conflict with existing gem methods
+    module ReservedNames
+      # Instance methods from Base class and concerns
+      BASE_METHODS = [
+        :outputs,
+        :arguments,
+        :errors,
+        :warnings,
+        :success?,
+        :failed?,
+        :errors?,
+        :warnings?,
+        :done!,
+        :done?,
+        :call,
+        :run_callbacks,
+      ].freeze
+
+      # Class methods that could conflict
+      CLASS_METHODS = [
+        :config,
+        :run,
+        :run!,
+        :with,
+        :arg,
+        :remove_arg,
+        :output,
+        :remove_output,
+        :step,
+        :remove_step,
+        :steps,
+        :outputs,
+        :arguments,
+      ].freeze
+
+      # Callback method names
+      CALLBACK_METHODS = [
+        :before_step_run,
+        :after_step_run,
+        :around_step_run,
+        :on_step_success,
+        :on_step_failure,
+        :on_step_crash,
+        :before_service_run,
+        :after_service_run,
+        :around_service_run,
+        :on_service_success,
+        :on_service_failure,
+      ].freeze
+
+      # Ruby reserved words and common Object methods
+      RUBY_RESERVED = [
+        :initialize,
+        :class,
+        :object_id,
+        :send,
+        :__send__,
+        :public_send,
+        :respond_to?,
+        :method,
+        :methods,
+        :instance_variable_get,
+        :instance_variable_set,
+        :instance_variables,
+        :extend,
+        :include,
+        :new,
+        :allocate,
+        :superclass,
+      ].freeze
+
+      # All reserved names combined (used for validation)
+      ALL = (BASE_METHODS + CALLBACK_METHODS + RUBY_RESERVED).uniq.freeze
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "validation"
+
+module Light
+  module Services
+    module Dsl
+      # DSL for defining and managing service arguments
+      module ArgumentsDsl
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Define an argument for the service
+          #
+          # @param name [Symbol] the argument name
+          # @param opts [Hash] options for configuring the argument
+          # @option opts [Class, Array<Class>] :type Type(s) to validate against
+          #   (e.g., String, Integer, [String, Symbol])
+          # @option opts [Boolean] :optional (false) Whether nil values are allowed
+          # @option opts [Object, Proc] :default Default value or proc to evaluate in instance context
+          # @option opts [Boolean] :context (false) Whether to pass this argument to child services
+          #
+          # @example Define a required string argument
+          #   arg :name, type: String
+          #
+          # @example Define an optional argument with default
+          #   arg :age, type: Integer, optional: true, default: 25
+          #
+          # @example Define an argument with multiple allowed types
+          #   arg :id, type: [String, Integer]
+          #
+          # @example Define an argument with proc default
+          #   arg :timestamp, type: Time, default: -> { Time.now }
+          #
+          # @example Define a context argument passed to child services
+          #   arg :current_user, type: User, context: true
+          def arg(name, opts = {})
+            Validation.validate_symbol_name!(name, :argument, self)
+            Validation.validate_reserved_name!(name, :argument, self)
+            Validation.validate_name_conflicts!(name, :argument, self)
+
+            own_arguments[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::ARGUMENT))
+            @arguments = nil # Clear memoized arguments since we're modifying them
+          end
+
+          # Remove an argument from the service
+          #
+          # @param name [Symbol] the argument name to remove
+          def remove_arg(name)
+            own_arguments.delete(name)
+            @arguments = nil # Clear memoized arguments since we're modifying them
+          end
+
+          # Get all arguments including inherited ones
+          #
+          # @return [Hash] all arguments defined for this service
+          def arguments
+            @arguments ||= build_arguments
+          end
+
+          # Get only arguments defined in this class
+          #
+          # @return [Hash] arguments defined in this class only
+          def own_arguments
+            @own_arguments ||= {}
+          end
+
+          private
+
+          # Build arguments by merging inherited arguments with own arguments
+          #
+          # @return [Hash] merged arguments
+          def build_arguments
+            inherited = superclass.respond_to?(:arguments) ? superclass.arguments.dup : {}
+            inherited.merge(own_arguments)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "validation"
+
+module Light
+  module Services
+    module Dsl
+      # DSL for defining and managing service outputs
+      module OutputsDsl
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Define an output for the service
+          #
+          # @param name [Symbol] the output name
+          # @param opts [Hash] options for configuring the output
+          # @option opts [Class, Array<Class>] :type Type(s) to validate against
+          #   (e.g., Hash, String, [String, Symbol])
+          # @option opts [Boolean] :optional (false) Whether nil values are allowed
+          # @option opts [Object, Proc] :default Default value or proc to evaluate in instance context
+          #
+          # @example Define a required hash output
+          #   output :result, type: Hash
+          #
+          # @example Define an optional output with default
+          #   output :status, type: String, optional: true, default: "pending"
+          #
+          # @example Define an output with multiple allowed types
+          #   output :data, type: [Hash, Array]
+          #
+          # @example Define an output with proc default
+          #   output :metadata, type: Hash, default: -> { {} }
+          def output(name, opts = {})
+            Validation.validate_symbol_name!(name, :output, self)
+            Validation.validate_reserved_name!(name, :output, self)
+            Validation.validate_name_conflicts!(name, :output, self)
+
+            own_outputs[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::OUTPUT))
+            @outputs = nil # Clear memoized outputs since we're modifying them
+          end
+
+          # Remove an output from the service
+          #
+          # @param name [Symbol] the output name to remove
+          def remove_output(name)
+            own_outputs.delete(name)
+            @outputs = nil # Clear memoized outputs since we're modifying them
+          end
+
+          # Get all outputs including inherited ones
+          #
+          # @return [Hash] all outputs defined for this service
+          def outputs
+            @outputs ||= build_outputs
+          end
+
+          # Get only outputs defined in this class
+          #
+          # @return [Hash] outputs defined in this class only
+          def own_outputs
+            @own_outputs ||= {}
+          end
+
+          private
+
+          # Build outputs by merging inherited outputs with own outputs
+          #
+          # @return [Hash] merged outputs
+          def build_outputs
+            inherited = superclass.respond_to?(:outputs) ? superclass.outputs.dup : {}
+            inherited.merge(own_outputs)
+          end
+        end
+      end
+    end
+  end
+end

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,132 @@
+# 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
+      end
+    end
+  end
+end

data/lib/light/services/exceptions.rb

@@ -4,7 +4,12 @@ module Light
   module Services
     class Error < StandardError; end
     class ArgTypeError < Error; end
-    class NoStepError < Error; end
-    class TwoConditions < Error; end
+    class ReservedNameError < Error; end
+    class InvalidNameError < Error; end
+    class NoStepsError < Error; end
+
+    # Backwards compatibility aliases (deprecated)
+    NoStepError = Error
+    TwoConditions = Error
   end
 end