servus 0.1.3 → 0.1.4

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

@@ -2,12 +2,33 @@
 
 module Servus
   module Generators
-    # Servus Generator
+    # Rails generator for creating Servus service objects.
+    #
+    # Generates a complete service structure including:
+    # - Service class file
+    # - RSpec test file
+    # - JSON schema files for arguments and results
+    #
+    # @example Generate a service
+    #   rails g servus:service namespace/do_something_helpful user amount
+    #
+    # @example Generated files
+    #   app/services/namespace/do_something_helpful/service.rb
+    #   spec/services/namespace/do_something_helpful/service_spec.rb
+    #   app/schemas/services/namespace/do_something_helpful/arguments.json
+    #   app/schemas/services/namespace/do_something_helpful/result.json
+    #
+    # @see https://guides.rubyonrails.org/generators.html
     class ServiceGenerator < Rails::Generators::NamedBase
       source_root File.expand_path('templates', __dir__)
 
       argument :parameters, type: :array, default: [], banner: 'parameter'
 
+      # Creates all service-related files.
+      #
+      # Generates the service class, spec file, and schema files from templates.
+      #
+      # @return [void]
       def create_service_file
         template 'service.rb.erb', service_path
         template 'service_spec.rb.erb', service_path_spec
@@ -19,40 +40,82 @@ module Servus
 
       private
 
+      # Returns the path for the service file.
+      #
+      # @return [String] service file path
+      # @api private
       def service_path
         "app/services/#{file_path}/service.rb"
       end
 
+      # Returns the path for the service spec file.
+      #
+      # @return [String] spec file path
+      # @api private
       def service_path_spec
         "spec/services/#{file_path}/service_spec.rb"
       end
 
+      # Returns the path for the result schema file.
+      #
+      # @return [String] result schema path
+      # @api private
       def service_result_schema_path
         "app/schemas/services/#{file_path}/result.json"
       end
 
+      # Returns the path for the arguments schema file.
+      #
+      # @return [String] arguments schema path
+      # @api private
       def service_arguments_shecma_path
         "app/schemas/services/#{file_path}/arguments.json"
       end
 
+      # Returns the service class name with ::Service appended.
+      #
+      # @return [String] service class name
+      # @api private
       def service_class_name
         "#{class_name}::Service"
       end
 
+      # Returns the fully-qualified service class name.
+      #
+      # @return [String] fully-qualified class name
+      # @api private
       def service_full_class_name
         service_class_name.include?('::') ? service_class_name : "::#{service_class_name}"
       end
 
+      # Generates the parameter list for the initialize method.
+      #
+      # @return [String] parameter list with keyword syntax
+      # @example
+      #   parameter_list # => "(user:, amount:)"
+      # @api private
       def parameter_list
         return '' if parameters.empty?
 
         "(#{parameters.map { |param| "#{param}:" }.join(', ')})"
       end
 
+      # Generates instance variable assignments for initialize method.
+      #
+      # @return [String] multi-line instance variable assignments
+      # @example
+      #   initialize_params # => "@user = user\n    @amount = amount"
+      # @api private
       def initialize_params
         parameters.map { |param| "@#{param} = #{param}" }.join("\n    ")
       end
 
+      # Generates attr_reader declarations for parameters.
+      #
+      # @return [String] attr_reader declaration or empty string
+      # @example
+      #   attr_readers # => "attr_reader :user, :amount"
+      # @api private
       def attr_readers
         return '' if parameters.empty?
 

data/lib/generators/servus/service/templates/service.rb.erb

@@ -1,5 +1,5 @@
 module <%= class_name %>
-  class Service < Servus::ApplicationService
+  class Service < Servus::Base
     def initialize<%= parameter_list %>
       <%= initialize_params %>
     end

data/lib/servus/base.rb

@@ -1,7 +1,50 @@
 # frozen_string_literal: true
 
 module Servus
-  # Base class for all services
+  # Base class for all service objects in the Servus framework.
+  #
+  # This class provides the foundational functionality for implementing the Service Object pattern,
+  # including automatic validation, logging, benchmarking, and error handling.
+  #
+  # @abstract Subclass and implement initialize and call methods to create a service
+  #
+  # @example Creating a basic service
+  #   class Services::ProcessPayment::Service < Servus::Base
+  #     def initialize(user:, amount:, payment_method:)
+  #       @user = user
+  #       @amount = amount
+  #       @payment_method = payment_method
+  #     end
+  #
+  #     def call
+  #       return failure("Invalid amount") if @amount <= 0
+  #
+  #       transaction = charge_payment
+  #       success({ transaction_id: transaction.id })
+  #     end
+  #
+  #     private
+  #
+  #     def charge_payment
+  #       # Payment processing logic
+  #     end
+  #   end
+  #
+  # @example Using a service
+  #   result = Services::ProcessPayment::Service.call(
+  #     user: current_user,
+  #     amount: 100,
+  #     payment_method: "credit_card"
+  #   )
+  #
+  #   if result.success?
+  #     puts "Transaction ID: #{result.data[:transaction_id]}"
+  #   else
+  #     puts "Error: #{result.error.message}"
+  #   end
+  #
+  # @see Servus::Support::Response
+  # @see Servus::Support::Errors
   class Base
     include Servus::Support::Errors
     include Servus::Support::Rescuer
@@ -11,84 +54,242 @@ module Servus
     Response = Servus::Support::Response
     Validator = Servus::Support::Validator
 
-    # Calls the service and returns a response
-    #
-    # @param args [Hash] The arguments to pass to the service
-    # @return [Servus::Support::Response] The response
-    # @raise [StandardError] If an exception is raised
-    # @raise [Servus::Support::Errors::ValidationError] If result is invalid
-    # @raise [Servus::Support::Errors::ValidationError] If arguments are invalid
-    def self.call(**args)
-      before_call(args)
-      result = benchmark(**args) { new(**args).call }
-      after_call(result)
-
-      result
-    rescue ValidationError => e
-      Logger.log_validation_error(self, e)
-      raise e
-    rescue StandardError => e
-      Logger.log_exception(self, e)
-      raise e
-    end
-
-    # Returns a success response
+    # Creates a successful response with the provided data.
+    #
+    # Use this method to return successful results from your service's call method.
+    # The data will be validated against the RESULT_SCHEMA if one is defined.
+    #
+    # @param data [Object] the data to return in the response (typically a Hash)
+    # @return [Servus::Support::Response] response with success: true and the provided data
+    #
+    # @example Returning simple data
+    #   def call
+    #     success({ user_id: 123, status: "active" })
+    #   end
+    #
+    # @example Returning nil for operations without data
+    #   def call
+    #     perform_action
+    #     success(nil)
+    #   end
     #
-    # @param data [Object] The data to return
-    # @return [Servus::Support::Response] The success response
+    # @see #failure
+    # @see Servus::Support::Response
     def success(data)
       Response.new(true, data, nil)
     end
 
-    # Returns a failure response
+    # Creates a failure response with an error.
     #
-    # @param message [String] The error message
-    # @param type [Class] The error type
-    # @return [Servus::Support::Response] The failure response
+    # Use this method to return failure results from your service's call method.
+    # The failure is logged automatically and returns a response containing the error.
+    #
+    # @param message [String, nil] custom error message (uses error type's default if nil)
+    # @param type [Class] error class to instantiate (must inherit from ServiceError)
+    # @return [Servus::Support::Response] response with success: false and the error
+    #
+    # @example Using default error type with custom message
+    #   def call
+    #     return failure("User not found") unless user_exists?
+    #     # ...
+    #   end
+    #
+    # @example Using custom error type
+    #   def call
+    #     return failure("Invalid payment", type: Servus::Support::Errors::BadRequestError)
+    #     # ...
+    #   end
+    #
+    # @example Using error type's default message
+    #   def call
+    #     return failure(type: Servus::Support::Errors::NotFoundError)
+    #     # Uses "Not found" as the message
+    #   end
+    #
+    # @see #success
+    # @see #error!
+    # @see Servus::Support::Errors
     def failure(message = nil, type: Servus::Support::Errors::ServiceError)
       error = type.new(message)
       Response.new(false, nil, error)
     end
 
-    # Raises an error and logs it
+    # Logs an error and raises an exception, halting service execution.
+    #
+    # Use this method when you need to immediately halt execution with an exception
+    # rather than returning a failure response. The error is automatically logged before
+    # the exception is raised.
     #
-    # @param message [String] The error message
-    # @param type [Class] The error type
+    # @param message [String, nil] error message for the exception (uses default if nil)
+    # @param type [Class] error class to raise (must inherit from ServiceError)
     # @return [void]
+    # @raise [Servus::Support::Errors::ServiceError] the specified error type
+    #
+    # @example Raising an error with custom message
+    #   def call
+    #     error!("Critical system failure") if system_down?
+    #   end
+    #
+    # @example Raising with specific error type
+    #   def call
+    #     error!("Unauthorized access", type: Servus::Support::Errors::UnauthorizedError)
+    #   end
+    #
+    # @note Prefer {#failure} for expected error conditions. Use this for exceptional cases.
+    # @see #failure
     def error!(message = nil, type: Servus::Support::Errors::ServiceError)
       Logger.log_exception(self.class, type.new(message))
       raise type, message
     end
 
-    # Runs call setup before call
-    #
-    # @param args [Hash] The arguments to pass to the service
-    # @return [Object] The result of the call
-    def self.before_call(args)
-      Logger.log_call(self, args)
-      Validator.validate_arguments!(self, args)
-    end
+    class << self
+      # Executes the service with automatic validation, logging, and benchmarking.
+      #
+      # This is the primary entry point for executing services. It handles the complete
+      # service lifecycle including:
+      # - Input argument validation against schema
+      # - Service instantiation
+      # - Execution timing/benchmarking
+      # - Result validation against schema
+      # - Automatic logging of calls, results, and errors
+      #
+      # @param args [Hash] keyword arguments passed to the service's initialize method
+      # @return [Servus::Support::Response] response object with success status and data or error
+      #
+      # @raise [Servus::Support::Errors::ValidationError] if input arguments fail schema validation
+      # @raise [Servus::Support::Errors::ValidationError] if result data fails schema validation
+      # @raise [StandardError] if an uncaught exception occurs during execution
+      #
+      # @example Successful execution
+      #   result = MyService.call(user_id: 123, amount: 50)
+      #   result.success? # => true
+      #   result.data # => { transaction_id: "abc123" }
+      #
+      # @example Failed execution
+      #   result = MyService.call(user_id: 123, amount: -10)
+      #   result.success? # => false
+      #   result.error.message # => "Amount must be positive"
+      #
+      # @see #initialize
+      # @see #call
+      def call(**args)
+        before_call(args)
+        result = benchmark(**args) { new(**args).call }
+        after_call(result)
 
-    # Runs after call
-    #
-    # @param args [Hash] The arguments to pass to the service
-    # @return [Object] The result of the call
-    def self.after_call(args)
-      Validator.validate_result!(self, args)
-    end
+        result
+      rescue Servus::Support::Errors::ValidationError => e
+        Logger.log_validation_error(self, e)
+        raise e
+      rescue StandardError => e
+        Logger.log_exception(self, e)
+        raise e
+      end
+
+      # Defines schema validation rules for the service's arguments and/or result.
+      #
+      # This method provides a clean DSL for specifying JSON schemas that will be used
+      # to validate service inputs and outputs. Schemas defined via this method take
+      # precedence over ARGUMENTS_SCHEMA and RESULT_SCHEMA constants. The next major
+      # version will deprecate those constants in favor of this DSL.
+      #
+      # @param arguments [Hash, nil] JSON schema for validating service arguments
+      # @param result [Hash, nil] JSON schema for validating service result data
+      # @return [void]
+      #
+      # @example Defining both arguments and result schemas
+      #   class ProcessPayment::Service < Servus::Base
+      #     schema(
+      #       arguments: {
+      #         type: 'object',
+      #         required: ['user_id', 'amount'],
+      #         properties: {
+      #           user_id: { type: 'integer' },
+      #           amount: { type: 'number', minimum: 0.01 }
+      #         }
+      #       },
+      #       result: {
+      #         type: 'object',
+      #         required: ['transaction_id'],
+      #         properties: {
+      #           transaction_id: { type: 'string' }
+      #         }
+      #       }
+      #     )
+      #   end
+      #
+      # @example Defining only arguments schema
+      #   class SendEmail::Service < Servus::Base
+      #     schema arguments: { type: 'object', required: ['email', 'subject'] }
+      #   end
+      #
+      # @see Servus::Support::Validator
+      def schema(arguments: nil, result: nil)
+        @arguments_schema = arguments.with_indifferent_access if arguments
+        @result_schema    = result.with_indifferent_access    if result
+      end
+
+      # Returns the arguments schema defined via the schema DSL method.
+      #
+      # @return [Hash, nil] the arguments schema or nil if not defined
+      # @api private
+      attr_reader :arguments_schema
+
+      # Returns the result schema defined via the schema DSL method.
+      #
+      # @return [Hash, nil] the result schema or nil if not defined
+      # @api private
+      attr_reader :result_schema
+
+      # Executes pre-call hooks including logging and argument validation.
+      #
+      # This method is automatically called before service execution and handles:
+      # - Logging the service call with arguments
+      # - Validating arguments against ARGUMENTS_SCHEMA (if defined)
+      #
+      # @param args [Hash] keyword arguments being passed to the service
+      # @return [void]
+      # @raise [Servus::Support::Errors::ValidationError] if arguments fail validation
+      #
+      # @api private
+      def before_call(args)
+        Logger.log_call(self, args)
+        Validator.validate_arguments!(self, args)
+      end
+
+      # Executes post-call hooks including result validation.
+      #
+      # This method is automatically called after service execution completes and handles:
+      # - Validating the result data against RESULT_SCHEMA (if defined)
+      #
+      # @param result [Servus::Support::Response] the response returned from the service
+      # @return [void]
+      # @raise [Servus::Support::Errors::ValidationError] if result data fails validation
+      #
+      # @api private
+      def after_call(result)
+        Validator.validate_result!(self, result)
+      end
 
-    # Benchmarks the call
-    #
-    # @param args [Hash] The arguments to pass to the service
-    # @return [Object] The result of the call
-    def self.benchmark(**_args)
-      start_time = Time.now.utc
-      result = yield
-      duration = Time.now.utc - start_time
+      # Measures service execution time and logs the result.
+      #
+      # This method wraps the service execution to capture timing metrics.
+      # The duration is logged along with the success/failure status of the service.
+      #
+      # @param _args [Hash] keyword arguments (unused, kept for method signature compatibility)
+      # @yieldreturn [Servus::Support::Response] the result from executing the service
+      # @return [Servus::Support::Response] the service execution result
+      #
+      # @api private
+      def benchmark(**_args)
+        start_time = Time.now.utc
+        result = yield
+        duration = Time.now.utc - start_time
 
-      Logger.log_result(self, result, duration)
+        Logger.log_result(self, result, duration)
 
-      result
+        result
+      end
     end
   end
 end

data/lib/servus/config.rb

@@ -2,38 +2,69 @@
 
 # Servus namespace
 module Servus
-  # Configuration class for Servus
+  # Configuration settings for the Servus gem.
+  #
+  # Manages global configuration options including schema file locations.
+  # Access the configuration via {Servus.config} or modify via {Servus.configure}.
+  #
+  # @example Customizing schema location
+  #   Servus.configure do |config|
+  #     config.schema_root = Rails.root.join('lib/schemas')
+  #   end
+  #
+  # @see Servus.config
+  # @see Servus.configure
   class Config
-    # The directory where schemas are loaded from, can be set by the user
+    # The root directory where schema files are located.
+    #
+    # Defaults to `Rails.root/app/schemas/services` in Rails applications,
+    # or a relative path from the gem installation otherwise.
+    #
+    # @return [String] the schema root directory path
     attr_reader :schema_root
 
+    # Initializes a new configuration with default values.
+    #
+    # @api private
     def initialize
       # Default to Rails.root if available, otherwise use current working directory
       @schema_root = File.join(root_path, 'app/schemas/services')
     end
 
-    # Returns the path for a specific service's schema
+    # Returns the full path to a service's schema file.
     #
-    # @param service_namespace [String] the namespace of the service
-    # @param type [String] the type of the schema (e.g., "arguments", "result")
-    # @return [String] the path for the service's schema type
+    # Constructs the path by combining {#schema_root} with the service namespace
+    # and schema type.
+    #
+    # @param service_namespace [String] underscored service namespace (e.g., "process_payment")
+    # @param type [String] schema type ("arguments" or "result")
+    # @return [String] full path to the schema JSON file
+    #
+    # @example
+    #   config.schema_path_for("process_payment", "arguments")
+    #   # => "/app/app/schemas/services/process_payment/arguments.json"
     def schema_path_for(service_namespace, type)
       File.join(schema_root.to_s, service_namespace, "#{type}.json")
     end
 
-    # Returns the directory for a specific service
+    # Returns the directory containing a service's schema files.
+    #
+    # @param service_namespace [String] underscored service namespace
+    # @return [String] directory path for the service's schemas
     #
-    # @param service_namespace [String] the namespace of the service
-    # @return [String] the directory for the service's schemas
+    # @example
+    #   config.schema_dir_for("process_payment")
+    #   # => "/app/app/schemas/services/process_payment"
     def schema_dir_for(service_namespace)
       File.join(schema_root.to_s, service_namespace)
     end
 
     private
 
-    # Sets the schema root directory
+    # Determines the application root path.
     #
-    # @param path [String] the new schema root directory
+    # @return [String] Rails.root in Rails apps, or gem's root directory otherwise
+    # @api private
     def root_path
       if defined?(Rails) && Rails.respond_to?(:root)
         Rails.root
@@ -43,11 +74,26 @@ module Servus
     end
   end
 
-  # Singleton config instance
+  # Returns the singleton configuration instance.
+  #
+  # @return [Servus::Config] the global configuration object
+  #
+  # @example
+  #   Servus.config.schema_root
+  #   # => "/app/app/schemas/services"
   def self.config
     @config ||= Config.new
   end
 
+  # Yields the configuration for modification.
+  #
+  # @yieldparam config [Servus::Config] the configuration object to modify
+  # @return [void]
+  #
+  # @example
+  #   Servus.configure do |config|
+  #     config.schema_root = Rails.root.join('custom/schemas')
+  #   end
   def self.configure
     yield(config)
   end

data/lib/servus/extensions/async/call.rb

@@ -3,28 +3,60 @@
 module Servus
   module Extensions
     module Async
-      # Calls the service asynchronously using AsyncCallerJob.
+      # Provides asynchronous service execution via ActiveJob.
       #
-      # Supports all standard ActiveJob scheduling and routing options:
-      #   - wait:        <ActiveSupport::Duration>   (e.g., 5.minutes)
-      #   - wait_until:  <Time>                      (e.g., 2.hours.from_now)
-      #   - queue:       <Symbol/String>             (e.g., :critical, 'low_priority')
-      #   - priority:    <Integer>                   (depends on adapter support)
-      #   - retry:       <Boolean>                   (custom control for job retry)
-      #   - job_options: <Hash>                      (extra options, merged in)
-      #
-      # Example:
-      #   call_async(
-      #     wait: 10.minutes,
-      #     queue: :low_priority,
-      #     priority: 20,
-      #     job_options: { tags: ['user_graduation'] },
-      #     user_id: current_user.id
-      #   )
+      # This module extends {Servus::Base} with the {#call_async} method, enabling
+      # services to be executed in background jobs. Requires ActiveJob to be loaded.
       #
+      # @see Call#call_async
       module Call
-        # @param args [Hash] The arguments to pass to the service and job options.
+        # Enqueues the service for asynchronous execution via ActiveJob.
+        #
+        # This method schedules the service to run in a background job, supporting
+        # all standard ActiveJob options for scheduling, queue routing, and priority.
+        #
+        # Service arguments are passed as keyword arguments alongside job configuration.
+        # Job-specific options are extracted and the remaining arguments are passed
+        # to the service's initialize method.
+        #
+        # @param args [Hash] combined service arguments and job configuration options
+        # @option args [ActiveSupport::Duration] :wait delay before execution (e.g., 5.minutes)
+        # @option args [Time] :wait_until specific time to execute (e.g., 2.hours.from_now)
+        # @option args [Symbol, String] :queue queue name (e.g., :low_priority)
+        # @option args [Integer] :priority job priority (adapter-dependent)
+        # @option args [Hash] :job_options additional ActiveJob options
+        #
         # @return [void]
+        # @raise [Servus::Extensions::Async::Errors::JobEnqueueError] if job enqueueing fails
+        #
+        # @example Basic async execution
+        #   Services::SendEmail::Service.call_async(
+        #     user_id: 123,
+        #     template: :welcome
+        #   )
+        #
+        # @example With delay
+        #   Services::SendReminder::Service.call_async(
+        #     wait: 1.day,
+        #     user_id: 123
+        #   )
+        #
+        # @example With queue and priority
+        #   Services::ProcessPayment::Service.call_async(
+        #     queue: :critical,
+        #     priority: 10,
+        #     order_id: 456
+        #   )
+        #
+        # @example With custom job options
+        #   Services::GenerateReport::Service.call_async(
+        #     wait_until: Date.tomorrow.beginning_of_day,
+        #     job_options: { tags: ['reports', 'daily'] },
+        #     report_type: :sales
+        #   )
+        #
+        # @note Only available when ActiveJob is loaded (typically in Rails applications)
+        # @see Servus::Base.call
         def call_async(**args)
           # Extract ActiveJob configuration options
           job_options = args.slice(:wait, :wait_until, :queue, :priority)