light-services 2.2.1 → 3.1.0

data/lib/generators/light_services/service/service_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module LightServices
+  module Generators
+    class ServiceGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, required: true,
+                      desc: "The name of the service (e.g., user/create or CreateUser)"
+
+      class_option :args, type: :array, default: [],
+                          desc: "List of arguments for the service"
+      class_option :steps, type: :array, default: [],
+                           desc: "List of steps for the service"
+      class_option :outputs, type: :array, default: [],
+                             desc: "List of outputs for the service"
+      class_option :skip_spec, type: :boolean, default: false,
+                               desc: "Skip creating the spec file"
+      class_option :parent, type: :string, default: "ApplicationService",
+                            desc: "Parent class for the service"
+
+      desc "Creates a new service class"
+
+      def create_service_file
+        template "service.rb.tt", "app/services/#{file_path}.rb"
+      end
+
+      def create_spec_file
+        return if options[:skip_spec]
+        return unless rspec_installed?
+
+        template "service_spec.rb.tt", "spec/services/#{file_path}_spec.rb"
+      end
+
+      private
+
+      def file_path
+        name.underscore
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def parent_class
+        options[:parent]
+      end
+
+      def arguments
+        options[:args]
+      end
+
+      def steps
+        options[:steps]
+      end
+
+      def outputs
+        options[:outputs]
+      end
+
+      def rspec_installed?
+        File.directory?(File.join(destination_root, "spec"))
+      end
+    end
+  end
+end

data/lib/generators/light_services/service/templates/service.rb.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < <%= parent_class %>
+<% if arguments.any? -%>
+  # Arguments
+<% arguments.each do |arg| -%>
+  arg :<%= arg %>
+<% end -%>
+
+<% end -%>
+<% if steps.any? -%>
+  # Steps
+<% steps.each do |step| -%>
+  step :<%= step %>
+<% end -%>
+
+<% end -%>
+<% if outputs.any? -%>
+  # Outputs
+<% outputs.each do |output| -%>
+  output :<%= output %>
+<% end -%>
+
+<% end -%>
+<% if steps.empty? -%>
+  # step :step_a
+  # step :step_b
+
+<% end -%>
+  private
+
+<% if steps.any? -%>
+<% steps.each_with_index do |step, index| -%>
+  def <%= step %>
+    # TODO: Implement <%= step %>
+  end
+<%= "\n" unless index == steps.length - 1 -%>
+<% end -%>
+<% else -%>
+  # def step_a
+  #   # TODO: Implement service logic
+  # end
+
+  # def step_b
+  #   # TODO: Implement service logic
+  # end
+<% end -%>
+end

data/lib/generators/light_services/service/templates/service_spec.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+# TODO: Add test implementation
+RSpec.describe <%= class_name %>, type: :service do
+<% if arguments.any? -%>
+  describe "arguments" do
+<% arguments.each do |arg| -%>
+    it { is_expected.to define_argument(:<%= arg %>) }
+<% end -%>
+  end
+
+<% end -%>
+<% if steps.any? -%>
+  describe "steps" do
+<% steps.each do |step| -%>
+    it { is_expected.to define_step(:<%= step %>) }
+<% end -%>
+  end
+
+<% end -%>
+<% if outputs.any? -%>
+  describe "outputs" do
+<% outputs.each do |output| -%>
+    it { is_expected.to define_output(:<%= output %>) }
+<% end -%>
+  end
+
+<% end -%>
+  describe "#run" do
+    subject(:service) { described_class.run(args) }
+
+    let(:args) { {} }
+
+    it "succeeds" do
+      expect(service).to be_success
+    end
+  end
+end

data/lib/light/services/base.rb

@@ -1,116 +1,208 @@
 # frozen_string_literal: true
 
-require "benchmark"
-
+require "light/services/constants"
 require "light/services/message"
 require "light/services/messages"
 require "light/services/base_with_context"
 
 require "light/services/settings/step"
-require "light/services/settings/output"
-require "light/services/settings/argument"
+require "light/services/settings/field"
+
+require "light/services/collection"
 
-require "light/services/collection/base"
-require "light/services/collection/outputs"
-require "light/services/collection/arguments"
+require "light/services/dsl/arguments_dsl"
+require "light/services/dsl/outputs_dsl"
+require "light/services/dsl/steps_dsl"
 
-require "light/services/class_based_collection/base"
-require "light/services/class_based_collection/mount"
+require "light/services/concerns/execution"
+require "light/services/concerns/state_management"
+require "light/services/concerns/parent_service"
 
 # Base class for all service objects
 module Light
   module Services
+    # Base class for building service objects with arguments, outputs, and steps.
+    #
+    # @example Basic service
+    #   class CreateUser < Light::Services::Base
+    #     arg :name, type: String
+    #     arg :email, type: String
+    #
+    #     output :user, type: User
+    #
+    #     step :create_user
+    #
+    #     private
+    #
+    #     def create_user
+    #       self.user = User.create!(name: name, email: email)
+    #     end
+    #   end
+    #
+    #   result = CreateUser.run(name: "John", email: "john@example.com")
+    #   result.success? # => true
+    #   result.user     # => #<User id: 1, name: "John">
     class Base
-      # Includes
-      extend ClassBasedCollection::Mount
-
-      # Settings
-      mount_class_based_collection :steps,     item_class: Settings::Step,     shortcut: :step
-      mount_class_based_collection :outputs,   item_class: Settings::Output,   shortcut: :output
-      mount_class_based_collection :arguments, item_class: Settings::Argument, shortcut: :arg, allow_redefine: true
-
-      # Arguments
-      arg :verbose, default: false
-      arg :benchmark, default: false
-      arg :deepness, default: 0, context: true
-
-      # Getters
-      attr_reader :outputs, :arguments, :errors, :warnings
-
+      include Callbacks
+      include Dsl::ArgumentsDsl
+      include Dsl::OutputsDsl
+      include Dsl::StepsDsl
+      include Concerns::Execution
+      include Concerns::StateManagement
+      include Concerns::ParentService
+
+      # @return [Collection::Base] collection of output values
+      attr_reader :outputs
+
+      # @return [Collection::Base] collection of argument values
+      attr_reader :arguments
+
+      # @return [Messages] collection of error messages
+      attr_reader :errors
+
+      # @return [Messages] collection of warning messages
+      attr_reader :warnings
+
+      # Initialize a new service instance.
+      #
+      # @param args [Hash] arguments to pass to the service
+      # @param config [Hash] runtime configuration overrides
+      # @param parent_service [Base, nil] parent service for nested calls
       def initialize(args = {}, config = {}, parent_service = nil)
         @config = Light::Services.config.merge(self.class.class_config || {}).merge(config)
         @parent_service = parent_service
 
-        @outputs = Collection::Outputs.new(self)
-        @arguments = Collection::Arguments.new(self, args.dup)
+        @outputs = Collection::Base.new(self, CollectionTypes::OUTPUTS)
+        @arguments = Collection::Base.new(self, CollectionTypes::ARGUMENTS, args.dup)
 
-        @done = false
+        @stopped = false
         @launched_steps = []
 
         initialize_errors
         initialize_warnings
       end
 
+      # Check if the service completed without errors.
+      #
+      # @return [Boolean] true if no errors were added
       def success?
         !errors?
       end
 
+      # Check if the service completed with errors.
+      #
+      # @return [Boolean] true if any errors were added
       def failed?
         errors?
       end
 
+      # Check if the service has any errors.
+      #
+      # @return [Boolean] true if errors collection is not empty
       def errors?
         @errors.any?
       end
 
+      # Check if the service has any warnings.
+      #
+      # @return [Boolean] true if warnings collection is not empty
       def warnings?
         @warnings.any?
       end
 
-      def done!
-        @done = true
+      # Stop executing remaining steps after the current step completes.
+      #
+      # @return [Boolean] true
+      def stop!
+        @stopped = true
+      end
+      alias done! stop!
+
+      # Check if the service has been stopped.
+      #
+      # @return [Boolean] true if stop! was called
+      def stopped?
+        @stopped
       end
+      alias done? stopped?
 
-      def done?
-        @done
+      # Stop execution immediately, skipping any remaining code in the current step.
+      #
+      # @raise [StopExecution] always raises to halt execution
+      # @return [void]
+      def stop_immediately!
+        @stopped = true
+        raise Light::Services::StopExecution
       end
 
+      # Execute the service steps.
+      #
+      # @return [void]
+      # @raise [StandardError] re-raises any exception after running always steps
       def call
         load_defaults_and_validate
-        log_header if benchmark? || verbose?
 
-        time = Benchmark.ms do
-          run_steps
-          run_steps_with_always
+        run_callbacks(:before_service_run, self)
 
-          copy_warnings_to_parent_service
-          copy_errors_to_parent_service
+        run_callbacks(:around_service_run, self) do
+          execute_service
         end
 
-        return unless benchmark
-
-        log "🟢 Finished #{self.class} in #{time}ms"
-        puts
+        run_service_result_callbacks
       rescue StandardError => e
         run_steps_with_always
         raise e
       end
 
       class << self
+        # @return [Hash, nil] class-level configuration options
         attr_accessor :class_config
 
+        # Set class-level configuration for this service.
+        #
+        # @param config [Hash] configuration options
+        # @return [Hash] the configuration hash
         def config(config = {})
           self.class_config = config
         end
 
+        # Run the service and return the result.
+        #
+        # @param args [Hash] arguments to pass to the service
+        # @param config [Hash] runtime configuration overrides
+        # @return [Base] the executed service instance
+        #
+        # @example
+        #   result = MyService.run(name: "test")
+        #   result.success? # => true
         def run(args = {}, config = {})
           new(args, config).tap(&:call)
         end
 
+        # Run the service and raise an error if it fails.
+        #
+        # @param args [Hash] arguments to pass to the service
+        # @param config [Hash] runtime configuration overrides
+        # @return [Base] the executed service instance
+        # @raise [Error] if the service fails
+        #
+        # @example
+        #   MyService.run!(name: "test") # raises if service fails
         def run!(args = {}, config = {})
           run(args, config.merge(raise_on_error: true))
         end
 
+        # Create a context for running the service with a parent service or config.
+        #
+        # @param service_or_config [Base, Hash] parent service or configuration hash
+        # @param config [Hash] configuration hash (when first param is a service)
+        # @return [BaseWithContext] context wrapper for running the service
+        #
+        # @example With parent service
+        #   ChildService.with(self).run(data: value)
+        #
+        # @example With configuration
+        #   MyService.with(use_transactions: false).run(name: "test")
         def with(service_or_config = {}, config = {})
           service = service_or_config.is_a?(Hash) ? nil : service_or_config
           config = service_or_config unless service
@@ -118,86 +210,6 @@ module Light
           BaseWithContext.new(self, service, config.dup)
         end
       end
-
-      # TODO: Add possibility to specify logger
-      def log(message)
-        puts "#{'  ' * deepness}→ #{message}"
-      end
-
-      private
-
-      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
-
-      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
-
-      def run_steps
-        within_transaction do
-          self.class.steps.each do |name, step|
-            @launched_steps << name if step.run(self, benchmark: benchmark)
-
-            break if @errors.break? || @warnings.break?
-          end
-        end
-      end
-
-      # Run steps with parameter `always` if they weren't launched because of errors/warnings
-      def run_steps_with_always
-        self.class.steps.each do |name, step|
-          next if !step.always || @launched_steps.include?(name)
-
-          @launched_steps << name if step.run(self)
-        end
-      end
-
-      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
-
-      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
-
-      def load_defaults_and_validate
-        @outputs.load_defaults
-        @arguments.load_defaults
-        @arguments.validate!
-      end
-
-      def log_header
-        log "🏎 Run service #{self.class}"
-      end
-
-      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

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+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,
+        :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
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods for registering callbacks.
+      #
+      # Each callback event has a corresponding class method:
+      # - {before_step_run} - before each step executes
+      # - {after_step_run} - after each step executes
+      # - {around_step_run} - wraps step execution (must yield)
+      # - {on_step_success} - when a step completes without adding errors
+      # - {on_step_failure} - when a step adds errors
+      # - {on_step_crash} - when a step raises an exception
+      # - {before_service_run} - before the service starts
+      # - {after_service_run} - after the service completes
+      # - {around_service_run} - wraps service execution (must yield)
+      # - {on_service_success} - when service completes without errors
+      # - {on_service_failure} - when service completes with errors
+      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 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
+      end
+
+      # 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)
+
+        if event.to_s.start_with?("around_")
+          run_around_callbacks(callbacks, args, &block)
+        else
+          run_simple_callbacks(callbacks, args)
+          yield if block_given?
+        end
+      end
+
+      private
+
+      def run_simple_callbacks(callbacks, args)
+        callbacks.each do |callback|
+          execute_callback(callback, args)
+        end
+      end
+
+      def run_around_callbacks(callbacks, args, &block)
+        return yield if callbacks.empty?
+
+        # Build a chain of around callbacks
+        chain = callbacks.reverse.reduce(block) do |next_block, callback|
+          proc { execute_callback(callback, args, &next_block) }
+        end
+
+        chain.call
+      end
+
+      def execute_callback(callback, args, &block)
+        case callback
+        in Symbol
+          block_given? ? send(callback, *args, &block) : send(callback, *args)
+        in Proc
+          block_given? ? instance_exec(*args, block, &callback) : instance_exec(*args, &callback)
+        else
+          raise ArgumentError, "Callback must be a Symbol or Proc, got #{callback.class}"
+        end
+      end
+    end
+  end
+end