operandi 5.0.0

data/lib/operandi/callbacks.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Provides callback hooks for service and step lifecycle events.
+  #
+  # @example Service-level callbacks
+  #   class MyService < Operandi::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 < Operandi::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 < Operandi::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
+
+    # 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, &)
+      callbacks = self.class.all_callbacks_for(event)
+
+      if event.to_s.start_with?("around_")
+        run_around_callbacks(callbacks, args, &)
+      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
+
+  # Class methods for registering callbacks.
+  # Extend this module in your service class to get callback DSL methods.
+  #
+  # @example
+  #   class MyService < Operandi::Base
+  #     before_service_run :setup
+  #     after_service_run :cleanup
+  #   end
+  module CallbackDsl
+    # Registers a callback to run before each step executes.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service, step_name] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @yieldparam step_name [Symbol] the name of the step about to run
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   before_step_run :log_step_start
+    #
+    # @example With block
+    #   before_step_run { |service, step_name| puts "Starting #{step_name}" }
+    def before_step_run(method_name = nil, &)
+      register_callback(:before_step_run, method_name, &)
+    end
+
+    # Registers a callback to run after each step executes.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service, step_name] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @yieldparam step_name [Symbol] the name of the step that just ran
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   after_step_run :log_step_complete
+    #
+    # @example With block
+    #   after_step_run { |service, step_name| puts "Finished #{step_name}" }
+    def after_step_run(method_name = nil, &)
+      register_callback(:after_step_run, method_name, &)
+    end
+
+    # Registers an around callback that wraps each step execution.
+    # The callback must yield to execute the step.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service, step_name] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @yieldparam step_name [Symbol] the name of the step being wrapped
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   around_step_run :with_step_timing
+    #
+    #   def with_step_timing(service, step_name)
+    #     start = Time.now
+    #     yield
+    #     puts "#{step_name} took #{Time.now - start}s"
+    #   end
+    def around_step_run(method_name = nil, &)
+      register_callback(:around_step_run, method_name, &)
+    end
+
+    # Registers a callback to run when a step completes successfully (without adding errors).
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service, step_name] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @yieldparam step_name [Symbol] the name of the successful step
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   on_step_success :track_step_success
+    #
+    # @example With block
+    #   on_step_success { |service, step_name| Analytics.track("step.success", step: step_name) }
+    def on_step_success(method_name = nil, &)
+      register_callback(:on_step_success, method_name, &)
+    end
+
+    # Registers a callback to run when a step fails (adds errors).
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service, step_name] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @yieldparam step_name [Symbol] the name of the failed step
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   on_step_failure :handle_step_error
+    #
+    # @example With block
+    #   on_step_failure { |service, step_name| Rails.logger.error("Step #{step_name} failed") }
+    def on_step_failure(method_name = nil, &)
+      register_callback(:on_step_failure, method_name, &)
+    end
+
+    # Registers a callback to run when a step raises an exception.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service, step_name, exception] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @yieldparam step_name [Symbol] the name of the crashed step
+    # @yieldparam exception [Exception] the exception that was raised
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   on_step_crash :report_crash
+    #
+    # @example With block
+    #   on_step_crash { |service, step_name, error| Sentry.capture_exception(error) }
+    def on_step_crash(method_name = nil, &)
+      register_callback(:on_step_crash, method_name, &)
+    end
+
+    # Registers a callback to run before the service starts executing.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   before_service_run :log_start
+    #
+    # @example With block
+    #   before_service_run { |service| Rails.logger.info("Starting #{service.class.name}") }
+    def before_service_run(method_name = nil, &)
+      register_callback(:before_service_run, method_name, &)
+    end
+
+    # Registers a callback to run after the service completes (regardless of success/failure).
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   after_service_run :cleanup
+    #
+    # @example With block
+    #   after_service_run { |service| Rails.logger.info("Done!") }
+    def after_service_run(method_name = nil, &)
+      register_callback(:after_service_run, method_name, &)
+    end
+
+    # Registers an around callback that wraps the entire service execution.
+    # The callback must yield to execute the service.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   around_service_run :with_timing
+    #
+    #   def with_timing(service)
+    #     start = Time.now
+    #     yield
+    #     puts "Took #{Time.now - start}s"
+    #   end
+    def around_service_run(method_name = nil, &)
+      register_callback(:around_service_run, method_name, &)
+    end
+
+    # Registers a callback to run when the service completes successfully (without errors).
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   on_service_success :send_notification
+    #
+    # @example With block
+    #   on_service_success { |service| NotificationMailer.success(service.user).deliver_later }
+    def on_service_success(method_name = nil, &)
+      register_callback(:on_service_success, method_name, &)
+    end
+
+    # Registers a callback to run when the service completes with errors.
+    #
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield [service] block to execute if no method name provided
+    # @yieldparam service [Operandi::Base] the service instance
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    #
+    # @example With method name
+    #   on_service_failure :log_error
+    #
+    # @example With block
+    #   on_service_failure { |service| Rails.logger.error(service.errors.full_messages) }
+    def on_service_failure(method_name = nil, &)
+      register_callback(:on_service_failure, method_name, &)
+    end
+
+    # Get callbacks defined in this class for a specific event.
+    #
+    # @param event [Symbol] the callback event name
+    # @return [Array<Symbol, Proc>] callbacks for this event
+    def callbacks_for(event)
+      @callbacks ||= {}
+      @callbacks[event] ||= []
+    end
+
+    # Get all callbacks for an event including inherited ones.
+    #
+    # @param event [Symbol] the callback event name
+    # @return [Array<Symbol, Proc>] all callbacks for this event
+    def all_callbacks_for(event)
+      if superclass.respond_to?(:all_callbacks_for)
+        inherited = superclass.all_callbacks_for(event)
+      else
+        inherited = []
+      end
+
+      inherited + callbacks_for(event)
+    end
+
+    private
+
+    # Registers a callback for a given event.
+    #
+    # @param event [Symbol] the callback event name
+    # @param method_name [Symbol, nil] name of the instance method to call
+    # @yield block to execute if no method name provided
+    # @return [void]
+    # @raise [ArgumentError] if neither method name nor block is provided
+    # @api private
+    def register_callback(event, method_name = nil, &block)
+      callback = method_name || block
+      raise ArgumentError, "#{event} requires a method name (symbol) or a block" unless callback
+
+      unless callback.is_a?(Symbol) || callback.is_a?(Proc)
+        raise ArgumentError, "#{event} callback must be a Symbol or Proc"
+      end
+
+      callbacks_for(event) << callback
+    end
+  end
+end

data/lib/operandi/collection.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Operandi
+  # Collection module for storing argument and output values.
+  module Collection
+    # Storage for service arguments or outputs with type validation.
+    #
+    # @example Accessing values
+    #   service.arg[:name]     # => "John"
+    #   service.output[: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)
+
+        message = "#{instance.class} - #{collection_type} must be a Hash"
+        raise Operandi::ArgTypeError.new(message, service_class: instance.class)
+      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 validated value
+          validated_value = field.validate_type!(get(name))
+
+          # Store the validated value back
+          set(name, validated_value) if validated_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
+
+      # Access a value using method call syntax.
+      #
+      # @param method_name [Symbol] the method name (used as key)
+      # @param args [Array] method arguments (must be empty)
+      # @return [Object, nil] the stored value or nil
+      # @raise [NoMethodError] if the key doesn't exist
+      def method_missing(method_name, *args, &)
+        return super unless respond_to_missing?(method_name, false)
+
+        get(method_name)
+      end
+
+      # Check if a method name corresponds to a stored key.
+      #
+      # @param method_name [Symbol] the method name to check
+      # @param include_private [Boolean] whether to include private methods
+      # @return [Boolean] true if the key exists
+      def respond_to_missing?(method_name, include_private = false)
+        key?(method_name) || settings_collection.key?(method_name) || super
+      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

data/lib/operandi/concerns/execution.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Operandi
+  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
+        @output.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 Operandi::StopExecution
+          # Gracefully handle stop_immediately! inside transaction to prevent rollback
+          @stopped = true
+        end
+      rescue Operandi::FailExecution
+        # FailExecution bubbles out of transaction (causing rollback) but is caught here
+        nil
+      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
+        @output.load_defaults
+        @arg.load_defaults
+        @arg.validate!
+      end
+
+      # Execute block within transaction if configured
+      def within_transaction(&)
+        if @config[:use_transactions] && defined?(ActiveRecord::Base)
+          ActiveRecord::Base.transaction(requires_new: true, &)
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/operandi/concerns/parent_service.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Operandi
+  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

data/lib/operandi/concerns/state_management.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Operandi
+  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],
+          },
+          service: self,
+        )
+      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],
+          },
+          service: self,
+        )
+      end
+    end
+  end
+end