better_service 1.0.0

data/lib/better_service/errors/runtime/authorization_error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Raised when user is not authorized to perform the action
+      #
+      # This error is raised when the authorize_with block returns false.
+      # Authorization checks happen before the service execution begins.
+      #
+      # @example Authorization failure
+      #   class Post::DestroyService < BetterService::Services::DestroyService
+      #     model_class Post
+      #
+      #     schema do
+      #       required(:id).filled(:integer)
+      #     end
+      #
+      #     authorize_with do
+      #       resource.user_id == user.id  # Only owner can delete
+      #     end
+      #   end
+      #
+      #   # User tries to delete someone else's post
+      #   Post::DestroyService.new(current_user, params: { id: other_users_post_id }).call
+      #   # => raises AuthorizationError
+      #
+      # @example Handling authorization errors
+      #   begin
+      #     MyService.new(user, params: params).call
+      #   rescue BetterService::Errors::Runtime::AuthorizationError => e
+      #     render json: { error: e.message }, status: :forbidden
+      #   end
+      class AuthorizationError < RuntimeError
+      end
+    end
+  end
+end

data/lib/better_service/errors/runtime/database_error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Raised when a database operation fails
+      #
+      # This error wraps ActiveRecord database errors such as RecordInvalid,
+      # RecordNotSaved, constraint violations, and other database-level failures.
+      #
+      # @example Record validation fails
+      #   class UserCreateService < BetterService::Services::CreateService
+      #     model_class User
+      #
+      #     schema do
+      #       required(:email).filled(:string)
+      #     end
+      #   end
+      #
+      #   UserCreateService.new(user, params: { email: "invalid" }).call
+      #   # => raises DatabaseError wrapping ActiveRecord::RecordInvalid
+      #
+      # @example Constraint violation
+      #   class MyService < BetterService::Services::Base
+      #     schema { required(:user_id).filled(:integer) }
+      #
+      #     process_with do |data|
+      #       User.create!(email: "duplicate@example.com")  # Unique constraint fails
+      #     end
+      #   end
+      #
+      #   MyService.new(user, params: { user_id: 1 }).call
+      #   # => raises DatabaseError
+      class DatabaseError < RuntimeError
+      end
+    end
+  end
+end

data/lib/better_service/errors/runtime/execution_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Raised when unexpected error occurs during service execution
+      #
+      # This error wraps unexpected StandardError exceptions that occur during
+      # the service's search, process, transform, or respond phases.
+      #
+      # @example Unexpected error in service
+      #   class MyService < BetterService::Services::Base
+      #     schema { }
+      #
+      #     process_with do |data|
+      #       # Some operation that fails unexpectedly
+      #       third_party_api.call  # raises SocketError
+      #     end
+      #   end
+      #
+      #   MyService.new(user, params: {}).call
+      #   # => raises ExecutionError wrapping SocketError
+      class ExecutionError < RuntimeError
+      end
+    end
+  end
+end

data/lib/better_service/errors/runtime/resource_not_found_error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Raised when a required resource is not found
+      #
+      # This error wraps ActiveRecord::RecordNotFound exceptions raised during
+      # service execution (usually in the search phase).
+      #
+      # @example Resource not found
+      #   class UserShowService < BetterService::Services::ShowService
+      #     model_class User
+      #
+      #     schema do
+      #       required(:id).filled(:integer)
+      #     end
+      #   end
+      #
+      #   UserShowService.new(user, params: { id: 99999 }).call
+      #   # => raises ResourceNotFoundError wrapping ActiveRecord::RecordNotFound
+      #
+      # @example In custom service
+      #   class MyService < BetterService::Services::Base
+      #     schema { required(:user_id).filled(:integer) }
+      #
+      #     search_with do
+      #       User.find(params[:user_id])  # Raises RecordNotFound if not exists
+      #     end
+      #   end
+      #
+      #   MyService.new(user, params: { user_id: 99999 }).call
+      #   # => raises ResourceNotFoundError
+      class ResourceNotFoundError < RuntimeError
+      end
+    end
+  end
+end

data/lib/better_service/errors/runtime/runtime_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Base class for all runtime errors in BetterService
+      #
+      # Runtime errors are raised when something goes wrong during service execution
+      # due to external factors (database, network, invalid data, etc.).
+      # These are not programming errors.
+      #
+      # @example
+      #   raise BetterService::Errors::Runtime::RuntimeError.new(
+      #     "Runtime error occurred",
+      #     code: :runtime_error,
+      #     context: { service: "MyService", operation: "fetch_data" }
+      #   )
+      class RuntimeError < BetterServiceError
+      end
+    end
+  end
+end

data/lib/better_service/errors/runtime/transaction_error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Raised when a database transaction fails
+      #
+      # This error is raised when ActiveRecord transaction operations fail,
+      # such as deadlocks, serialization errors, or constraint violations.
+      #
+      # @example Transaction failure
+      #   class MyService < BetterService::Services::Base
+      #     config do
+      #       use_transaction true
+      #     end
+      #
+      #     schema { }
+      #
+      #     process_with do |data|
+      #       # Database operation that causes deadlock
+      #       User.transaction do
+      #         user.lock!
+      #         other_user.lock!  # Deadlock!
+      #       end
+      #     end
+      #   end
+      #
+      #   MyService.new(user, params: {}).call
+      #   # => raises TransactionError
+      class TransactionError < RuntimeError
+      end
+    end
+  end
+end

data/lib/better_service/errors/runtime/validation_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # Raised when parameter validation fails
+      #
+      # This error is raised during service initialization when Dry::Schema
+      # validation fails. The validation errors are available in the context.
+      #
+      # @example Validation failure
+      #   class MyService < BetterService::Services::Base
+      #     schema do
+      #       required(:email).filled(:string)
+      #       required(:age).filled(:integer, gt?: 18)
+      #     end
+      #   end
+      #
+      #   MyService.new(user, params: { email: "", age: 15 }).call
+      #   # => raises ValidationError with context:
+      #   # {
+      #   #   service: "MyService",
+      #   #   validation_errors: {
+      #   #     email: ["must be filled"],
+      #   #     age: ["must be greater than 18"]
+      #   #   }
+      #   # }
+      #
+      # @example Handling validation errors
+      #   begin
+      #     MyService.new(user, params: invalid_params).call
+      #   rescue BetterService::Errors::Runtime::ValidationError => e
+      #     render json: {
+      #       error: e.message,
+      #       validation_errors: e.context[:validation_errors]
+      #     }, status: :unprocessable_entity
+      #   end
+      class ValidationError < RuntimeError
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/configuration/duplicate_step_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Configuration
+        # Raised when a workflow has duplicate step names
+        #
+        # Each step in a workflow must have a unique name. This error is raised
+        # if you try to define multiple steps with the same name.
+        #
+        # @example Duplicate step names
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :create_user,
+        #          with: User::CreateService
+        #
+        #     step :create_user,  # Duplicate name!
+        #          with: Profile::CreateService
+        #   end
+        #
+        #   # => raises DuplicateStepError during class definition
+        class DuplicateStepError < WorkflowConfigurationError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/configuration/invalid_step_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Configuration
+        class InvalidStepError < WorkflowConfigurationError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/configuration/step_not_found_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Configuration
+        # Raised when a referenced workflow step is not found
+        #
+        # This error is raised when trying to access a step that doesn't exist
+        # in the workflow definition, such as in dependencies or conditionals.
+        #
+        # @example Step not found
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :first_step,
+        #          with: FirstService
+        #
+        #     step :second_step,
+        #          with: SecondService,
+        #          if: ->(ctx) { ctx.non_existent_step.success? }  # Step doesn't exist
+        #   end
+        #
+        #   MyWorkflow.new(user, params: {}).call
+        #   # => raises StepNotFoundError
+        class StepNotFoundError < WorkflowConfigurationError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/configuration/workflow_configuration_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Configuration
+        # Base class for workflow configuration errors
+        #
+        # Raised when a workflow is incorrectly configured, such as invalid steps,
+        # missing service classes, or conflicting configurations.
+        #
+        # @example Invalid workflow configuration
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :invalid,
+        #          with: nil  # Missing service class
+        #   end
+        #
+        #   # => raises WorkflowConfigurationError during class definition
+        class WorkflowConfigurationError < BetterService::Errors::Configuration::ConfigurationError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/runtime/rollback_error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Runtime
+        # Raised when workflow rollback fails
+        #
+        # This error is raised when a step's rollback block fails during workflow rollback.
+        # Rollback failures are serious as they may leave the system in an inconsistent state.
+        #
+        # @example Rollback failure
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :create_user,
+        #          with: User::CreateService,
+        #          rollback: ->(ctx) { ctx.user.destroy! }
+        #
+        #     step :charge_payment,
+        #          with: Payment::ChargeService,
+        #          rollback: ->(ctx) {
+        #            # Rollback fails - payment gateway is down
+        #            PaymentGateway.refund(ctx.charge.id)  # raises error
+        #          }
+        #
+        #     step :send_email,
+        #          with: Email::WelcomeService  # This step fails
+        #   end
+        #
+        #   MyWorkflow.new(user, params: {}).call
+        #   # => send_email fails, triggers rollback
+        #   # => charge_payment rollback fails
+        #   # => raises RollbackError with context:
+        #   # {
+        #   #   workflow: "MyWorkflow",
+        #   #   step: :charge_payment,
+        #   #   executed_steps: [:create_user, :charge_payment]
+        #   # }
+        #
+        # @note Rollback errors indicate potential data inconsistency and should be
+        #   monitored and handled carefully in production systems.
+        class RollbackError < WorkflowRuntimeError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/runtime/step_execution_error.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Runtime
+        # Raised when a workflow step execution fails
+        #
+        # This error is raised when a step in the workflow fails and the step is not optional.
+        # The error includes context about which step failed and what steps were executed.
+        #
+        # @example Step execution failure
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :create_user,
+        #          with: User::CreateService
+        #
+        #     step :charge_payment,
+        #          with: Payment::ChargeService  # This step fails
+        #
+        #     step :send_email,
+        #          with: Email::WelcomeService  # This step never executes
+        #   end
+        #
+        #   MyWorkflow.new(user, params: {}).call
+        #   # => raises StepExecutionError with context:
+        #   # {
+        #   #   workflow: "MyWorkflow",
+        #   #   step: :charge_payment,
+        #   #   steps_executed: [:create_user],
+        #   #   errors: { ... }
+        #   # }
+        #
+        # @example Optional step failures don't raise
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :create_user,
+        #          with: User::CreateService
+        #
+        #     step :send_email,
+        #          with: Email::WelcomeService,
+        #          optional: true  # Failure won't raise StepExecutionError
+        #   end
+        class StepExecutionError < WorkflowRuntimeError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/runtime/workflow_execution_error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Runtime
+        # Raised when workflow execution fails
+        #
+        # This error is raised when unexpected errors occur during workflow execution,
+        # wrapping the original exception with workflow context.
+        #
+        # @example Workflow execution failure
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :create_user,
+        #          with: User::CreateService
+        #
+        #     step :send_email,
+        #          with: Email::WelcomeService
+        #   end
+        #
+        #   MyWorkflow.new(user, params: {}).call
+        #   # If unexpected error occurs => raises WorkflowExecutionError
+        #
+        # @example Error context
+        #   begin
+        #     MyWorkflow.new(user, params: params).call
+        #   rescue BetterService::Errors::Workflowable::Runtime::WorkflowExecutionError => e
+        #     e.context
+        #     # => {
+        #     #   workflow: "MyWorkflow",
+        #     #   steps_executed: [:create_user],
+        #     #   steps_skipped: []
+        #     # }
+        #   end
+        class WorkflowExecutionError < WorkflowRuntimeError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/errors/workflowable/runtime/workflow_runtime_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Workflowable
+      module Runtime
+        # Base class for workflow runtime errors
+        #
+        # Raised when errors occur during workflow execution, such as step failures,
+        # rollback failures, or workflow execution errors.
+        #
+        # @example Workflow runtime error
+        #   class MyWorkflow < BetterService::Workflow
+        #     step :first_step,
+        #          with: FirstService
+        #   end
+        #
+        #   MyWorkflow.new(user, params: {}).call
+        #   # If FirstService fails => raises WorkflowRuntimeError (or subclass)
+        class WorkflowRuntimeError < BetterService::Errors::Runtime::RuntimeError
+        end
+      end
+    end
+  end
+end

data/lib/better_service/railtie.rb

@@ -0,0 +1,6 @@
+if defined?(Rails)
+  module BetterService
+    class Railtie < ::Rails::Railtie
+    end
+  end
+end

data/lib/better_service/services/action_service.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module BetterService
+  module Services
+  # ActionService - Specialized service for custom actions/transitions
+  #
+  # Returns: { resource: {}, metadata: { action: :custom_action_name } }
+  #
+  # Example:
+  #   class Bookings::AcceptService < BetterService::Services::ActionService
+  #     action_name :accepted  # Sets metadata action
+  #
+  #     schema do
+  #       required(:id).filled(:integer)
+  #     end
+  #
+  #     search_with do
+  #       { resource: user.bookings.find(params[:id]) }
+  #     end
+  #
+  #     process_with do |data|
+  #       booking = data[:resource]
+  #       booking.update!(status: 'accepted', accepted_at: Time.current)
+  #       { resource: booking }
+  #     end
+  #   end
+  class ActionService < Services::Base
+    # Default action_name to nil - subclasses MUST set it
+    self._action_name = nil
+
+    def self.action_name(name)
+      self._action_name = name.to_sym
+    end
+
+    # Default schema - requires id parameter for actions
+    schema do
+      required(:id).filled
+    end
+
+    private
+
+    # Override respond to ensure resource key is present
+    def respond(data)
+      # Get base result (from custom respond_with block or default)
+      if self.class._respond_block
+        result = instance_exec(data, &self.class._respond_block)
+      else
+        result = success_result("Action completed successfully", data)
+      end
+
+      # Ensure resource key exists (default to nil if not provided)
+      result[:resource] ||= nil
+
+      result
+    end
+  end
+  end
+end