better_service 1.0.0

data/lib/better_service/concerns/workflowable/step.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflowable
+    # Step - Represents a single step in a workflow pipeline
+    #
+    # Each step wraps a service class and defines how data flows into it,
+    # whether it's optional, conditional execution, and rollback behavior.
+    #
+    # Example:
+    #   step = Step.new(
+    #     name: :create_order,
+    #     service_class: Order::CreateService,
+    #     input: ->(ctx) { { items: ctx.cart_items } },
+    #     optional: false,
+    #     condition: ->(ctx) { ctx.cart_items.any? },
+    #     rollback: ->(ctx) { ctx.order.destroy! }
+    #   )
+    #
+    #   step.call(context, user, params)
+    class Step
+      attr_reader :name, :service_class, :input_mapper, :optional, :condition, :rollback_block
+
+      def initialize(name:, service_class:, input: nil, optional: false, condition: nil, rollback: nil)
+        @name = name
+        @service_class = service_class
+        @input_mapper = input
+        @optional = optional
+        @condition = condition
+        @rollback_block = rollback
+      end
+
+      # Execute the step
+      #
+      # @param context [Context] The workflow context
+      # @param user [Object] The current user
+      # @param params [Hash] Base params for the workflow
+      # @return [Hash] Service result
+      def call(context, user, base_params = {})
+        # Check if step should be skipped due to condition
+        if should_skip?(context)
+          return {
+            success: true,
+            skipped: true,
+            message: "Step #{name} skipped due to condition"
+          }
+        end
+
+        # Build input params for the service
+        service_params = build_params(context, base_params)
+
+        # Call the service
+        result = service_class.new(user, params: service_params).call
+
+        # Store result in context if successful
+        if result[:success]
+          store_result_in_context(context, result)
+        elsif optional
+          # If step is optional and failed, continue but log the failure
+          context.add(:"#{name}_error", result[:errors])
+          return {
+            success: true,
+            optional_failure: true,
+            message: "Optional step #{name} failed but continuing",
+            errors: result[:errors]
+          }
+        end
+
+        result
+      rescue StandardError => e
+        # If step is optional, swallow the error and continue
+        if optional
+          context.add(:"#{name}_error", e.message)
+          {
+            success: true,
+            optional_failure: true,
+            message: "Optional step #{name} raised error but continuing",
+            error: e.message
+          }
+        else
+          raise e
+        end
+      end
+
+      # Execute rollback for this step
+      #
+      # @param context [Context] The workflow context
+      # @raise [StandardError] If rollback fails (caught and wrapped by workflow)
+      def rollback(context)
+        return unless rollback_block
+
+        if rollback_block.is_a?(Proc)
+          context.instance_exec(context, &rollback_block)
+        else
+          rollback_block.call(context)
+        end
+        # Note: Exceptions are propagated to workflow which wraps them in RollbackError
+      end
+
+      private
+
+      # Check if step should be skipped
+      def should_skip?(context)
+        return false unless condition
+
+        if condition.is_a?(Proc)
+          !context.instance_exec(context, &condition)
+        else
+          !condition.call(context)
+        end
+      end
+
+      # Build params for service from context
+      def build_params(context, base_params)
+        if input_mapper
+          if input_mapper.is_a?(Proc)
+            context.instance_exec(context, &input_mapper)
+          else
+            input_mapper.call(context)
+          end
+        else
+          base_params
+        end
+      end
+
+      # Store successful result data in context
+      def store_result_in_context(context, result)
+        # Store resource if present
+        context.add(name, result[:resource]) if result.key?(:resource)
+
+        # Store items if present
+        context.add(name, result[:items]) if result.key?(:items)
+
+        # If neither resource nor items, store the whole result
+        if !result.key?(:resource) && !result.key?(:items)
+          context.add(name, result)
+        end
+      end
+    end
+  end
+end

data/lib/better_service/concerns/workflowable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    # Workflowable - Namespace for all workflow-related concerns
+    #
+    # This module groups all concerns that are specific to BetterService workflows,
+    # such as lifecycle callbacks, step execution, context management, etc.
+    module Workflowable
+    end
+  end
+end

data/lib/better_service/configuration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module BetterService
+  # Configuration - Centralized configuration for BetterService
+  #
+  # Provides configuration options for various BetterService features.
+  #
+  # @example Configure in initializer
+  #   # config/initializers/better_service.rb
+  #   BetterService.configure do |config|
+  #     config.instrumentation_enabled = true
+  #     config.instrumentation_include_args = false
+  #     config.instrumentation_excluded_services = ["HealthCheckService"]
+  #   end
+  class Configuration
+    # Enable/disable instrumentation globally
+    #
+    # When disabled, no events will be published for any service.
+    #
+    # @return [Boolean] Default: true
+    attr_accessor :instrumentation_enabled
+
+    # Include service arguments in event payloads
+    #
+    # When enabled, args and kwargs are included in event payloads.
+    # Disable if arguments contain sensitive data (passwords, tokens, etc.)
+    #
+    # @return [Boolean] Default: true
+    attr_accessor :instrumentation_include_args
+
+    # Include service result in event payloads
+    #
+    # When enabled, the service result is included in completion events.
+    # Disable to reduce payload size or protect sensitive return values.
+    #
+    # @return [Boolean] Default: false
+    attr_accessor :instrumentation_include_result
+
+    # List of service class names to exclude from instrumentation
+    #
+    # Services in this list will not publish any events.
+    # Useful for high-frequency services that would generate too many events.
+    #
+    # @return [Array<String>] Default: []
+    attr_accessor :instrumentation_excluded_services
+
+    # Enable/disable built-in log subscriber
+    #
+    # When enabled, all service events are logged to Rails.logger.
+    #
+    # @return [Boolean] Default: false
+    attr_accessor :log_subscriber_enabled
+
+    # Log level for built-in log subscriber
+    #
+    # Valid values: :debug, :info, :warn, :error
+    #
+    # @return [Symbol] Default: :info
+    attr_accessor :log_subscriber_level
+
+    # Enable/disable built-in stats subscriber
+    #
+    # When enabled, statistics are collected for all service executions.
+    #
+    # @return [Boolean] Default: false
+    attr_accessor :stats_subscriber_enabled
+
+    def initialize
+      # Instrumentation defaults
+      @instrumentation_enabled = true
+      @instrumentation_include_args = true
+      @instrumentation_include_result = false
+      @instrumentation_excluded_services = []
+
+      # Built-in subscribers defaults
+      @log_subscriber_enabled = false
+      @log_subscriber_level = :info
+      @stats_subscriber_enabled = false
+    end
+  end
+
+  class << self
+    # Get the global configuration object
+    #
+    # @return [BetterService::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure BetterService
+    #
+    # @yield [Configuration] Configuration object
+    # @return [void]
+    #
+    # @example
+    #   BetterService.configure do |config|
+    #     config.instrumentation_enabled = true
+    #     config.log_subscriber_enabled = true
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults
+    #
+    # Useful for testing.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/better_service/errors/better_service_error.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module BetterService
+  # Base exception class for all BetterService errors
+  #
+  # This class provides rich error information including error codes, context,
+  # original errors, and structured metadata for debugging and logging.
+  #
+  # @example Basic usage
+  #   raise BetterServiceError.new(
+  #     "Something went wrong",
+  #     code: :custom_error,
+  #     context: { user_id: 123, action: "create" }
+  #   )
+  #
+  # @example With original error
+  #   begin
+  #     dangerous_operation
+  #   rescue StandardError => e
+  #     raise BetterServiceError.new(
+  #       "Operation failed",
+  #       code: :operation_failed,
+  #       original_error: e,
+  #       context: { operation: "dangerous_operation" }
+  #     )
+  #   end
+  #
+  # @example Accessing error information
+  #   begin
+  #     service.call
+  #   rescue BetterServiceError => e
+  #     logger.error e.to_h
+  #     # => {
+  #     #   error_class: "BetterService::Errors::Runtime::ValidationError",
+  #     #   message: "Validation failed",
+  #     #   code: :validation_failed,
+  #     #   timestamp: "2025-11-09T10:30:00Z",
+  #     #   context: { service: "UserService", validation_errors: {...} },
+  #     #   original_error: nil,
+  #     #   backtrace: [...]
+  #     # }
+  #   end
+  class BetterServiceError < StandardError
+    # @return [Symbol, nil] Error code for programmatic handling
+    attr_reader :code
+
+    # @return [Exception, nil] Original exception that caused this error
+    attr_reader :original_error
+
+    # @return [Hash] Additional context about the error
+    attr_reader :context
+
+    # @return [Time] When the error was raised
+    attr_reader :timestamp
+
+    # Initialize a new BetterService error
+    #
+    # @param message [String, nil] Human-readable error message
+    # @param code [Symbol, nil] Error code for programmatic handling
+    # @param original_error [Exception, nil] Original exception that caused this error
+    # @param context [Hash] Additional context about the error (service name, params, etc.)
+    def initialize(message = nil, code: nil, original_error: nil, context: {})
+      super(message)
+      @code = code
+      @original_error = original_error
+      @context = context || {}
+      @timestamp = Time.current
+    end
+
+    # Convert error to a structured hash
+    #
+    # @return [Hash] Hash representation with all error information
+    def to_h
+      {
+        error_class: self.class.name,
+        message: message,
+        code: code,
+        timestamp: timestamp.iso8601,
+        context: context,
+        original_error: original_error_info,
+        backtrace: backtrace&.first(10) || []
+      }
+    end
+
+    # Get detailed error message with context
+    #
+    # @return [String] Detailed message including context
+    def detailed_message
+      parts = [ message ]
+      parts << "Code: #{code}" if code
+      parts << "Context: #{context.inspect}" if context.any?
+      parts << "Original: #{original_error.class.name}: #{original_error.message}" if original_error
+      parts.join(" | ")
+    end
+
+    # Enhanced inspect for debugging
+    #
+    # @return [String] Detailed string representation
+    def inspect
+      "#<#{self.class.name}: #{detailed_message}>"
+    end
+
+    # Override backtrace to include original error's backtrace
+    #
+    # @return [Array<String>] Combined backtrace
+    def backtrace
+      trace = super || []
+
+      if original_error && original_error.backtrace
+        trace + [ "--- Original Error Backtrace ---" ] + original_error.backtrace
+      else
+        trace
+      end
+    end
+
+    private
+
+    # Get original error information as hash
+    #
+    # @return [Hash, nil] Original error details or nil
+    def original_error_info
+      return nil unless original_error
+
+      {
+        class: original_error.class.name,
+        message: original_error.message,
+        backtrace: original_error.backtrace&.first(5) || []
+      }
+    end
+  end
+
+  # Standard error codes used in BetterService responses
+  #
+  # These codes are used for both hash responses and exception codes,
+  # providing consistent error identification across the system.
+  #
+  # @example Using error codes in exceptions
+  #   raise Errors::Runtime::ValidationError.new(
+  #     "Validation failed",
+  #     code: ErrorCodes::VALIDATION_FAILED,
+  #     context: { validation_errors: {...} }
+  #   )
+  #
+  # @example Handling errors by code
+  #   begin
+  #     service.call
+  #   rescue BetterServiceError => e
+  #     case e.code
+  #     when ErrorCodes::VALIDATION_FAILED
+  #       render json: { errors: e.context[:validation_errors] }, status: :unprocessable_entity
+  #     when ErrorCodes::UNAUTHORIZED
+  #       render json: { error: e.message }, status: :forbidden
+  #     end
+  #   end
+  module ErrorCodes
+    # ============================================
+    # BUSINESS LOGIC ERROR CODES
+    # ============================================
+
+    # Validation failed - input parameters are invalid
+    #
+    # Used when Dry::Schema validation fails.
+    # The error will include validation details in context.
+    #
+    # @example
+    #   raise Errors::Runtime::ValidationError.new(
+    #     "Validation failed",
+    #     code: :validation_failed,
+    #     context: {
+    #       validation_errors: { email: ["is invalid"], age: ["must be greater than 18"] }
+    #     }
+    #   )
+    VALIDATION_FAILED = :validation_failed
+
+    # Authorization failed - user doesn't have permission
+    #
+    # Used when the authorize_with block returns false.
+    #
+    # @example
+    #   raise Errors::Runtime::AuthorizationError.new(
+    #     "Not authorized to perform this action",
+    #     code: :unauthorized,
+    #     context: { user_id: 123, action: "destroy" }
+    #   )
+    UNAUTHORIZED = :unauthorized
+
+    # ============================================
+    # PROGRAMMING ERROR CODES
+    # ============================================
+
+    # Schema is missing or invalid
+    SCHEMA_REQUIRED = :schema_required
+
+    # Service configuration is invalid
+    CONFIGURATION_ERROR = :configuration_error
+
+    # ============================================
+    # RUNTIME ERROR CODES
+    # ============================================
+
+    # Unexpected error during service execution
+    EXECUTION_ERROR = :execution_error
+
+    # Required resource was not found
+    RESOURCE_NOT_FOUND = :resource_not_found
+
+    # Database transaction failed
+    TRANSACTION_ERROR = :transaction_error
+
+    # Database operation failed (validation errors, save failures)
+    DATABASE_ERROR = :database_error
+
+    # Workflow execution failed
+    WORKFLOW_FAILED = :workflow_failed
+
+    # Workflow step failed
+    STEP_FAILED = :step_failed
+
+    # Workflow rollback failed
+    ROLLBACK_FAILED = :rollback_failed
+  end
+end
+
+# Require all error classes
+require_relative "configuration/configuration_error"
+require_relative "configuration/schema_required_error"
+require_relative "configuration/invalid_schema_error"
+require_relative "configuration/invalid_configuration_error"
+require_relative "configuration/nil_user_error"
+
+require_relative "runtime/runtime_error"
+require_relative "runtime/execution_error"
+require_relative "runtime/transaction_error"
+require_relative "runtime/resource_not_found_error"
+require_relative "runtime/database_error"
+require_relative "runtime/validation_error"
+require_relative "runtime/authorization_error"
+
+require_relative "workflowable/configuration/workflow_configuration_error"
+require_relative "workflowable/configuration/step_not_found_error"
+require_relative "workflowable/configuration/invalid_step_error"
+require_relative "workflowable/configuration/duplicate_step_error"
+
+require_relative "workflowable/runtime/workflow_runtime_error"
+require_relative "workflowable/runtime/workflow_execution_error"
+require_relative "workflowable/runtime/step_execution_error"
+require_relative "workflowable/runtime/rollback_error"
+
+# Namespace for all BetterService errors
+module BetterService
+  module Errors
+    # Namespace for configuration/programming errors
+    module Configuration
+    end
+
+    # Namespace for runtime errors
+    module Runtime
+    end
+
+    # Namespace for workflow-related errors
+    module Workflowable
+      # Namespace for workflow configuration errors
+      module Configuration
+      end
+
+      # Namespace for workflow runtime errors
+      module Runtime
+      end
+    end
+  end
+end

data/lib/better_service/errors/configuration/configuration_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Configuration
+      # Base class for all configuration/programming errors in BetterService
+      #
+      # Configuration errors are raised when a service is incorrectly configured or used.
+      # These are programming errors that should be fixed during development.
+      #
+      # @example
+      #   raise BetterService::Errors::Configuration::ConfigurationError.new(
+      #     "Invalid service configuration",
+      #     code: :configuration_error,
+      #     context: { service: "MyService", issue: "missing required config" }
+      #   )
+      class ConfigurationError < BetterServiceError
+      end
+    end
+  end
+end

data/lib/better_service/errors/configuration/invalid_configuration_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Configuration
+      # Raised when a service has invalid configuration settings
+      #
+      # This error is raised when configuration options are invalid or conflicting,
+      # such as invalid cache settings, presenter configurations, or workflow definitions.
+      #
+      # @example Invalid cache configuration
+      #   class MyService < BetterService::Services::Base
+      #     config do
+      #       cache enabled: true, expires_in: "invalid"  # Should be integer
+      #     end
+      #   end
+      #
+      # @example Invalid workflow step
+      #   class MyWorkflow < BetterService::Workflow
+      #     step :invalid,
+      #          with: nil,  # Missing service class
+      #          input: -> (ctx) { ctx.data }
+      #   end
+      class InvalidConfigurationError < ConfigurationError
+      end
+    end
+  end
+end

data/lib/better_service/errors/configuration/invalid_schema_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Configuration
+      # Raised when a service schema definition is invalid
+      #
+      # This error is raised when the Dry::Schema definition contains syntax errors
+      # or invalid validation rules.
+      #
+      # @example Invalid schema definition
+      #   class MyService < BetterService::Services::Base
+      #     schema do
+      #       required(:email).filled(:invalid_type)  # Invalid type
+      #     end
+      #   end
+      #
+      # @example Schema with syntax error
+      #   class MyService < BetterService::Services::Base
+      #     schema do
+      #       required(:name)  # Missing predicate
+      #     end
+      #   end
+      class InvalidSchemaError < ConfigurationError
+      end
+    end
+  end
+end

data/lib/better_service/errors/configuration/nil_user_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Configuration
+      # Raised when a service is initialized with nil user when user is required
+      #
+      # By default, all BetterService services require a user object. This error is raised
+      # during initialization if user is nil and `allow_nil_user` is not configured.
+      #
+      # @example Service called with nil user (will raise error)
+      #   class MyService < BetterService::Services::Base
+      #     schema do
+      #       required(:name).filled(:string)
+      #     end
+      #   end
+      #
+      #   MyService.new(nil, params: { name: "test" })
+      #   # => raises NilUserError
+      #
+      # @example Allowing nil user
+      #   class MyService < BetterService::Services::Base
+      #     config do
+      #       allow_nil_user true
+      #     end
+      #
+      #     schema do
+      #       required(:name).filled(:string)
+      #     end
+      #   end
+      #
+      #   MyService.new(nil, params: { name: "test" })  # OK
+      class NilUserError < ConfigurationError
+      end
+    end
+  end
+end

data/lib/better_service/errors/configuration/schema_required_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Configuration
+      # Raised when a service is missing a required schema definition
+      #
+      # All BetterService services must define a schema block for parameter validation.
+      # This error is raised during service initialization if no schema is defined.
+      #
+      # @example Service without schema (will raise error)
+      #   class MyService < BetterService::Services::Base
+      #     # Missing: schema do ... end
+      #   end
+      #
+      #   MyService.new(user, params: {})
+      #   # => raises SchemaRequiredError
+      #
+      # @example Correct usage with schema
+      #   class MyService < BetterService::Services::Base
+      #     schema do
+      #       required(:name).filled(:string)
+      #     end
+      #   end
+      class SchemaRequiredError < ConfigurationError
+      end
+    end
+  end
+end