better_service 1.0.0

data/lib/better_service/services/base.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "dry-schema"
+require_relative "../concerns/serviceable/messageable"
+require_relative "../concerns/serviceable/validatable"
+require_relative "../concerns/serviceable/authorizable"
+require_relative "../concerns/serviceable/presentable"
+require_relative "../concerns/serviceable/cacheable"
+require_relative "../concerns/serviceable/viewable"
+require_relative "../concerns/serviceable/transactional"
+require_relative "../concerns/instrumentation"
+
+module BetterService
+  module Services
+  class Base
+    class_attribute :_allow_nil_user, default: false
+    class_attribute :_action_name, default: nil
+    class_attribute :_search_block, default: nil
+    class_attribute :_process_block, default: nil
+    class_attribute :_transform_block, default: nil
+    class_attribute :_respond_block, default: nil
+
+    include Concerns::Serviceable::Messageable
+    include Concerns::Serviceable::Validatable
+    include Concerns::Serviceable::Authorizable
+    include Concerns::Serviceable::Presentable
+    include Concerns::Serviceable::Viewable
+
+    # Prepend Transactional so it can wrap the process method
+    prepend Concerns::Serviceable::Transactional
+
+    # Default empty schema - subclasses should override
+    schema do
+      # Override in subclass with specific validations
+    end
+
+    attr_reader :user, :params
+
+    def initialize(user, params: {})
+      validate_user_presence!(user) unless self.class._allow_nil_user
+      validate_schema_presence!
+      @user = user
+      @params = safe_params_to_hash(params)
+      @validation_errors = {}
+      validate_params!
+    end
+
+    # DSL methods to define phase blocks
+    def self.search_with(&block)
+      self._search_block = block
+    end
+
+    def self.process_with(&block)
+      self._process_block = block
+    end
+
+    def self.transform_with(&block)
+      self._transform_block = block
+    end
+
+    def self.respond_with(&block)
+      self._respond_block = block
+    end
+
+    # Main entry point - executes the 5-phase flow
+    def call
+      # Validation already raises ValidationError in initialize
+      # Authorization already raises AuthorizationError
+      authorize!
+
+      data = search
+      processed = process(data)
+      transformed = transform(processed)
+      result = respond(transformed)
+
+      # Phase 5: Viewer (if enabled)
+      if respond_to?(:viewer_enabled?, true) && viewer_enabled?
+        view_config = execute_viewer(processed, transformed, result)
+        result = result.merge(view: view_config)
+      end
+
+      result
+    rescue Errors::Runtime::ValidationError, Errors::Runtime::AuthorizationError
+      # Let validation and authorization errors propagate without wrapping
+      raise
+    rescue ActiveRecord::RecordNotFound => e
+      handle_not_found_error(e)
+    rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved => e
+      handle_database_error(e)
+    rescue StandardError => e
+      handle_unexpected_error(e)
+    end
+
+    # Include Cacheable AFTER call method is defined so it can wrap it
+    # This must be before Instrumentation prepend so cache works correctly
+    include Concerns::Serviceable::Cacheable
+
+    private
+
+    # Phase 1: Search - Load raw data (override in subclass)
+    def search
+      if self.class._search_block
+        instance_exec(&self.class._search_block)
+      else
+        {}
+      end
+    end
+
+    # Phase 2: Process - Transform and aggregate data (override in subclass)
+    def process(data)
+      if self.class._process_block
+        instance_exec(data, &self.class._process_block)
+      else
+        data
+      end
+    end
+
+    # Phase 3: Transform - Handled by Presentable concern
+
+    # Phase 4: Respond - Handled by Viewable concern
+
+    # Error handlers for runtime errors
+    #
+    # These methods handle unexpected errors during service execution by raising
+    # appropriate runtime exceptions. They log the error and wrap it with service context.
+
+    # Handle resource not found errors (ActiveRecord::RecordNotFound)
+    #
+    # @param error [ActiveRecord::RecordNotFound] The original not found error
+    # @raise [Errors::Runtime::ResourceNotFoundError] Wrapped error with context
+    def handle_not_found_error(error)
+      Rails.logger.error "Resource not found in #{self.class.name}: #{error.message}" if defined?(Rails)
+
+      raise Errors::Runtime::ResourceNotFoundError.new(
+        "Resource not found: #{error.message}",
+        code: BetterService::ErrorCodes::RESOURCE_NOT_FOUND,
+        original_error: error,
+        context: { service: self.class.name, params: @params }
+      )
+    end
+
+    # Handle database errors (ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved)
+    #
+    # @param error [ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved] The original database error
+    # @raise [Errors::Runtime::DatabaseError] Wrapped error with context
+    def handle_database_error(error)
+      Rails.logger.error "Database error in #{self.class.name}: #{error.message}" if defined?(Rails)
+      Rails.logger.error error.backtrace.join("\n") if defined?(Rails)
+
+      raise Errors::Runtime::DatabaseError.new(
+        "Database error: #{error.message}",
+        code: BetterService::ErrorCodes::DATABASE_ERROR,
+        original_error: error,
+        context: { service: self.class.name, params: @params }
+      )
+    end
+
+    # Handle unexpected errors (all other StandardError)
+    #
+    # @param error [StandardError] The original unexpected error
+    # @raise [Errors::Runtime::ExecutionError] Wrapped error with context
+    def handle_unexpected_error(error)
+      Rails.logger.error "Unexpected error in #{self.class.name}: #{error.message}" if defined?(Rails)
+      Rails.logger.error error.backtrace.join("\n") if defined?(Rails)
+
+      raise Errors::Runtime::ExecutionError.new(
+        "Service execution failed: #{error.message}",
+        code: BetterService::ErrorCodes::EXECUTION_ERROR,
+        original_error: error,
+        context: { service: self.class.name, params: @params }
+      )
+    end
+
+    def validate_user_presence!(user)
+      return if user.present?
+
+      raise Errors::Configuration::NilUserError,
+            "User cannot be nil for #{self.class.name}. " \
+            "Add 'allow_nil_user true' in config block if this is intentional."
+    end
+
+    def validate_schema_presence!
+      return if self.class.schema_defined?
+
+      raise Errors::Configuration::SchemaRequiredError,
+            "#{self.class.name} must define a schema block. " \
+            "Add 'schema do ... end' to validate params."
+    end
+
+    def safe_params_to_hash(params)
+      return {} if params.nil?
+
+      # Handle ActionController::Parameters by converting to unsafe hash first
+      if params.respond_to?(:to_unsafe_h)
+        params.to_unsafe_h.deep_symbolize_keys
+      elsif params.respond_to?(:to_h)
+        params.to_h.deep_symbolize_keys
+      elsif params.is_a?(Hash)
+        params.deep_symbolize_keys
+      else
+        {}
+      end
+    rescue StandardError => e
+      Rails.logger.warn "Failed to convert params to hash: #{e.message}" if defined?(Rails)
+      {}
+    end
+
+    def success_result(message, data = {})
+      # Extract metadata if provided in data, or initialize empty
+      provided_metadata = data.delete(:metadata) || {}
+
+      # Build metadata with action if action_name is set
+      metadata = {}
+      metadata[:action] = self.class._action_name if self.class._action_name.present?
+      metadata.merge!(provided_metadata)
+
+      {
+        success: true,
+        message: message,
+        metadata: metadata,
+        **data
+      }
+    end
+
+    def failure_result(message, errors = {}, code: nil)
+      result = {
+        success: false,
+        error: message,
+        errors: errors
+      }
+      result[:code] = code if code
+      result
+    end
+
+    def error_result(message, code: nil)
+      result = {
+        success: false,
+        errors: [message]
+      }
+      result[:code] = code if code
+      result
+    end
+
+    # Prepend Instrumentation at the end, after call method is defined
+    # This wraps the entire call method (including cache logic from Cacheable)
+    prepend Concerns::Instrumentation
+  end
+  end
+end

data/lib/better_service/services/create_service.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module BetterService
+  module Services
+  # CreateService - Specialized service for creating new resources
+  #
+  # Returns: { resource: {}, metadata: { action: :created } }
+  #
+  # Example:
+  #   class Bookings::CreateService < BetterService::Services::CreateService
+  #     schema do
+  #       required(:title).filled(:string)
+  #       required(:date).filled(:date)
+  #     end
+  #
+  #     search_with do
+  #       {}
+  #     end
+  #
+  #     process_with do |data|
+  #       booking = user.bookings.create!(
+  #         title: params[:title],
+  #         date: params[:date]
+  #       )
+  #       { resource: booking }
+  #     end
+  #   end
+  class CreateService < Services::Base
+    # Set action_name for metadata
+    self._action_name = :created
+
+    # Enable database transactions by default for create operations
+    with_transaction true
+
+    # Default empty schema - subclasses MUST override with specific validations
+    schema do
+      # Override in subclass with required fields
+    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("Resource created successfully", data)
+      end
+
+      # Ensure resource key exists (default to nil if not provided)
+      result[:resource] ||= nil
+
+      result
+    end
+  end
+  end
+end

data/lib/better_service/services/destroy_service.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module BetterService
+  module Services
+  # DestroyService - Specialized service for deleting resources
+  #
+  # Returns: { resource: {}, metadata: { action: :deleted } }
+  #
+  # Example:
+  #   class Bookings::DestroyService < BetterService::Services::DestroyService
+  #     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.destroy!
+  #       { resource: booking }
+  #     end
+  #   end
+  class DestroyService < Services::Base
+    # Set action_name for metadata
+    self._action_name = :deleted
+
+    # Enable database transactions by default for destroy operations
+    with_transaction true
+
+    # Default schema - requires id parameter
+    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("Resource deleted successfully", data)
+      end
+
+      # Ensure resource key exists (default to nil if not provided)
+      result[:resource] ||= nil
+
+      result
+    end
+  end
+  end
+end

data/lib/better_service/services/index_service.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module BetterService
+  module Services
+  # IndexService - Specialized service for list/collection endpoints
+  #
+  # Returns: { items: [], metadata: { action: :index, stats: {}, pagination: {} } }
+  #
+  # Example:
+  #   class Bookings::IndexService < BetterService::Services::IndexService
+  #     search_with do
+  #       { items: user.bookings.to_a }
+  #     end
+  #
+  #     process_with do |data|
+  #       {
+  #         items: data[:items],
+  #         metadata: {
+  #           stats: { total: data[:items].count },
+  #           pagination: { page: params[:page] || 1 }
+  #         }
+  #       }
+  #     end
+  #   end
+  class IndexService < Services::Base
+    # Set action_name for metadata
+    self._action_name = :index
+
+    # Default schema - can be overridden in subclasses
+    schema do
+      optional(:page).filled(:integer, gteq?: 1)
+      optional(:per_page).filled(:integer, gteq?: 1, lteq?: 100)
+      optional(:search).maybe(:string)
+    end
+
+    private
+
+    # Override respond to ensure items 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("Operation completed successfully", data)
+      end
+
+      # Ensure items key exists (default to empty array if not provided)
+      result[:items] ||= []
+
+      result
+    end
+  end
+  end
+end

data/lib/better_service/services/show_service.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module BetterService
+  module Services
+  # ShowService - Specialized service for single resource detail endpoints
+  #
+  # Returns: { resource: {}, metadata: { action: :show } }
+  #
+  # Example:
+  #   class Bookings::ShowService < BetterService::Services::ShowService
+  #     search_with do
+  #       { resource: user.bookings.find(params[:id]) }
+  #     end
+  #   end
+  class ShowService < Services::Base
+    # Set action_name for metadata
+    self._action_name = :show
+
+    # Default schema - requires id parameter
+    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("Operation completed successfully", data)
+      end
+
+      # Ensure resource key exists (default to nil if not provided)
+      result[:resource] ||= nil
+
+      result
+    end
+  end
+  end
+end

data/lib/better_service/services/update_service.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module BetterService
+  module Services
+  # UpdateService - Specialized service for updating existing resources
+  #
+  # Returns: { resource: {}, metadata: { action: :updated } }
+  #
+  # Example:
+  #   class Bookings::UpdateService < BetterService::Services::UpdateService
+  #     schema do
+  #       required(:id).filled(:integer)
+  #       optional(:title).filled(:string)
+  #     end
+  #
+  #     search_with do
+  #       { resource: user.bookings.find(params[:id]) }
+  #     end
+  #
+  #     process_with do |data|
+  #       booking = data[:resource]
+  #       booking.update!(params.except(:id))
+  #       { resource: booking }
+  #     end
+  #   end
+  class UpdateService < Services::Base
+    # Set action_name for metadata
+    self._action_name = :updated
+
+    # Enable database transactions by default for update operations
+    with_transaction true
+
+    # Default schema - requires id parameter
+    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("Resource updated successfully", data)
+      end
+
+      # Ensure resource key exists (default to nil if not provided)
+      result[:resource] ||= nil
+
+      result
+    end
+  end
+  end
+end

data/lib/better_service/subscribers/log_subscriber.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Subscribers
+    # LogSubscriber - Built-in subscriber that logs service events
+    #
+    # This subscriber logs all service events to Rails.logger.
+    # Enable it in configuration to get automatic logging for all services.
+    #
+    # @example Enable in initializer
+    #   BetterService.configure do |config|
+    #     config.log_subscriber_enabled = true
+    #     config.log_subscriber_level = :info
+    #   end
+    class LogSubscriber
+      class << self
+        # Attach the subscriber to ActiveSupport::Notifications
+        #
+        # This method is called automatically when subscriber is enabled.
+        # It subscribes to all service.* events.
+        #
+        # @return [void]
+        def attach
+          subscribe_to_service_events
+          subscribe_to_cache_events
+        end
+
+        private
+
+        # Subscribe to service lifecycle events
+        #
+        # @return [void]
+        def subscribe_to_service_events
+          ActiveSupport::Notifications.subscribe("service.started") do |name, start, finish, id, payload|
+            log_service_started(payload)
+          end
+
+          ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
+            log_service_completed(payload)
+          end
+
+          ActiveSupport::Notifications.subscribe("service.failed") do |name, start, finish, id, payload|
+            log_service_failed(payload)
+          end
+        end
+
+        # Subscribe to cache events
+        #
+        # @return [void]
+        def subscribe_to_cache_events
+          ActiveSupport::Notifications.subscribe("cache.hit") do |name, start, finish, id, payload|
+            log_cache_hit(payload)
+          end
+
+          ActiveSupport::Notifications.subscribe("cache.miss") do |name, start, finish, id, payload|
+            log_cache_miss(payload)
+          end
+        end
+
+        # Log service started event
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def log_service_started(payload)
+          message = "[BetterService] #{payload[:service_name]} started"
+          message += " (user: #{payload[:user_id]})" if payload[:user_id]
+
+          log(message)
+        end
+
+        # Log service completed event
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def log_service_completed(payload)
+          message = "[BetterService] #{payload[:service_name]} completed in #{payload[:duration]}ms"
+          message += " (user: #{payload[:user_id]})" if payload[:user_id]
+          message += " [CACHED]" if payload[:cache_hit]
+
+          log(message)
+        end
+
+        # Log service failed event
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def log_service_failed(payload)
+          message = "[BetterService] #{payload[:service_name]} failed after #{payload[:duration]}ms"
+          message += " (user: #{payload[:user_id]})" if payload[:user_id]
+          message += " - #{payload[:error_class]}: #{payload[:error_message]}"
+
+          log(message, :error)
+        end
+
+        # Log cache hit event
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def log_cache_hit(payload)
+          message = "[BetterService::Cache] HIT - #{payload[:service_name]}"
+          message += " (context: #{payload[:context]})" if payload[:context]
+
+          log(message, :debug)
+        end
+
+        # Log cache miss event
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def log_cache_miss(payload)
+          message = "[BetterService::Cache] MISS - #{payload[:service_name]}"
+          message += " (context: #{payload[:context]})" if payload[:context]
+
+          log(message, :debug)
+        end
+
+        # Write to Rails logger
+        #
+        # @param message [String] Log message
+        # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+        # @return [void]
+        def log(message, level = nil)
+          return unless defined?(Rails) && Rails.logger
+
+          level ||= BetterService.configuration.log_subscriber_level
+          Rails.logger.send(level, message)
+        end
+      end
+    end
+  end
+end