light-services 2.2.1 → 3.1.0

data/lib/light/services/collection.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+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)
+
+          @instance = instance
+          @collection_type = collection_type
+          @storage = storage
+
+          return if storage.is_a?(Hash)
+
+          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)
+
+            if settings.default.is_a?(Proc)
+              set(name, @instance.instance_exec(&settings.default))
+            else
+              set(name, Utils.deep_dup(settings.default))
+            end
+          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?)
+
+            # validate_type! returns the (possibly coerced) value
+            coerced_value = field.validate_type!(get(name))
+            # Store the coerced value back (supports dry-types coercion)
+            set(name, coerced_value) if coerced_value != get(name)
+          end
+        end
+
+        # 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
+
+          settings_collection.each do |name, field|
+            next if !field.context || args.key?(name) || !key?(name)
+
+            args[field.name] = get(name)
+          end
+
+          args
+        end
+
+        private
+
+        def validate_collection_type!(type)
+          return if CollectionTypes::ALL.include?(type)
+
+          raise ArgumentError,
+                "collection_type must be one of #{CollectionTypes::ALL.join(', ')}, got: #{type.inspect}"
+        end
+
+        def settings_collection
+          @instance.class.public_send(@collection_type)
+        end
+      end
+
+      # Aliases for backwards compatibility
+      Arguments = Base
+      Outputs = Base
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module Concerns
+      # Handles service execution logic including steps and validation
+      module Execution
+        private
+
+        # Execute the main service logic
+        def execute_service
+          self.class.validate_steps!
+          run_steps
+          run_steps_with_always
+          @outputs.validate! if success?
+
+          copy_warnings_to_parent_service
+          copy_errors_to_parent_service
+        end
+
+        # Run all service result callbacks based on success/failure
+        def run_service_result_callbacks
+          run_callbacks(:after_service_run, self)
+
+          if success?
+            run_callbacks(:on_service_success, self)
+          else
+            run_callbacks(:on_service_failure, self)
+          end
+        end
+
+        # Run normal steps within transaction
+        def run_steps
+          within_transaction do
+            # Cache steps once for both normal and always execution
+            @cached_steps = self.class.steps
+
+            @cached_steps.each do |name, step|
+              @launched_steps << name if step.run(self)
+
+              break if @errors.break? || @warnings.break?
+            end
+          rescue Light::Services::StopExecution
+            # Gracefully handle stop_immediately! inside transaction to prevent rollback
+            @stopped = true
+          end
+        end
+
+        # Run steps with parameter `always` if they weren't launched because of errors/warnings
+        def run_steps_with_always
+          # Use cached steps from run_steps, or get them if run_steps wasn't called
+          steps_to_check = @cached_steps || self.class.steps
+
+          steps_to_check.each do |name, step|
+            next if !step.always || @launched_steps.include?(name)
+
+            @launched_steps << name if step.run(self)
+          end
+        end
+
+        # Load defaults for outputs and arguments, then validate arguments
+        def load_defaults_and_validate
+          @outputs.load_defaults
+          @arguments.load_defaults
+          @arguments.validate!
+        end
+
+        # Execute block within transaction if configured
+        def within_transaction(&block)
+          if @config[:use_transactions] && defined?(ActiveRecord::Base)
+            ActiveRecord::Base.transaction(requires_new: true, &block)
+          else
+            yield
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module Concerns
+      # Handles copying errors and warnings to parent services
+      module ParentService
+        private
+
+        # Copy warnings from this service to parent service
+        def copy_warnings_to_parent_service
+          return if !@parent_service || !@config[:load_warnings]
+
+          @parent_service.warnings.copy_from(
+            @warnings,
+            break: @config[:self_break_on_warning],
+            rollback: @config[:self_rollback_on_warning],
+          )
+        end
+
+        # Copy errors from this service to parent service
+        def copy_errors_to_parent_service
+          return if !@parent_service || !@config[:load_errors]
+
+          @parent_service.errors.copy_from(
+            @errors,
+            break: @config[:self_break_on_error],
+            rollback: @config[:self_rollback_on_error],
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module Concerns
+      # Manages service state including errors and warnings initialization
+      module StateManagement
+        private
+
+        # Initialize errors collection with configuration
+        def initialize_errors
+          @errors = Messages.new(
+            break_on_add: @config[:break_on_error],
+            raise_on_add: @config[:raise_on_error],
+            rollback_on_add: @config[:use_transactions] && @config[:rollback_on_error],
+          )
+        end
+
+        # Initialize warnings collection with configuration
+        def initialize_warnings
+          @warnings = Messages.new(
+            break_on_add: @config[:break_on_warning],
+            raise_on_add: @config[:raise_on_warning],
+            rollback_on_add: @config[:use_transactions] && @config[:rollback_on_warning],
+          )
+        end
+      end
+    end
+  end
+end

data/lib/light/services/config.rb

@@ -3,18 +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
-      # Constants
+      # @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,36 +80,47 @@ module Light
         load_warnings: true,
         break_on_warning: false,
         raise_on_warning: false,
-        rollback_on_warning: false
+        rollback_on_warning: false,
+
+        ruby_lsp_type_mappings: {}.freeze,
       }.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
+      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
 
-      def set(key, value)
-        instance_variable_set(:"@#{key}", value)
-      end
-
-      def get(key)
-        instance_variable_get(:"@#{key}")
-      end
-
+      # Reset all configuration options to their default values.
+      #
+      # @return [void]
       def reset_to_defaults!
         DEFAULTS.each do |key, value|
-          set(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, get(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

@@ -0,0 +1,100 @@
+# 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?,
+        :stop!,
+        :stopped?,
+        :stop_immediately!,
+        :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,85 @@
+# 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)
+            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
+          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,81 @@
+# 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)
+            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
+          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