better_service 2.0.0 → 2.1.0

data/lib/better_service/services/base.rb

@@ -6,7 +6,6 @@ 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"
 
@@ -25,7 +24,6 @@ module BetterService
     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
@@ -65,6 +63,24 @@ module BetterService
       self._allow_nil_user = value
     end
 
+    # Configure the action name for metadata tracking
+    #
+    # @param name [Symbol, String] The action name (e.g., :publish, :approve)
+    # @return [void]
+    #
+    # @example Custom action service
+    #   class Order::ApproveService < Order::BaseService
+    #     performed_action :approve
+    #   end
+    #
+    # @example CRUD service with standard action
+    #   class Product::CreateService < Product::BaseService
+    #     performed_action :created
+    #   end
+    def self.performed_action(name)
+      self._action_name = name.to_sym
+    end
+
     def self.search_with(&block)
       self._search_block = block
     end
@@ -107,6 +123,26 @@ module BetterService
     end
 
     # Main entry point - executes the 5-phase flow
+    #
+    # @return [BetterService::Result] Result wrapper containing resource and metadata
+    #   - result.resource: The resource (single AR model, array of models, or nil on error)
+    #   - result.meta: Hash with success status, action, message, and validation errors if any
+    #   - Supports destructuring: `resource, meta = service.call`
+    #
+    # @example Success
+    #   result = ProductService.new(user, params: params).call
+    #   result.success? # => true
+    #   result.resource.persisted? # => true
+    #
+    # @example Using destructuring
+    #   product, meta = ProductService.new(user, params: params).call
+    #   meta[:success] # => true
+    #
+    # @example Validation failure (returns object with errors)
+    #   result = ProductService.new(user, params: invalid_params).call
+    #   result.failure? # => true
+    #   result.validation_errors # => { name: ["can't be blank"] }
+    #   result.resource.errors.any? # => true (object still available for form re-render)
     def call
       # Validation already raises ValidationError in initialize
       # Authorization already raises AuthorizationError
@@ -123,22 +159,26 @@ module BetterService
       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
+      # Build Result response
+      build_result_response(result)
+    rescue Errors::Runtime::ValidationError => e
+      # Schema validation errors (from initialize) - no object available
+      wrap_response(nil, validation_error_metadata(e))
+    rescue Errors::Runtime::AuthorizationError => e
+      # Authorization errors - no object available
+      wrap_response(nil, authorization_error_metadata(e))
+    rescue Errors::Runtime::ResourceNotFoundError => e
+      # Resource not found (BetterService error) - no object available
+      wrap_response(nil, resource_not_found_error_metadata(e))
     rescue ActiveRecord::RecordNotFound => e
-      handle_not_found_error(e)
+      # Resource not found (ActiveRecord error) - no object available
+      wrap_response(nil, not_found_error_metadata(e))
     rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved => e
-      handle_database_error(e)
+      # AR validation errors - return the object with errors for form re-render
+      wrap_response(e.record, ar_validation_error_metadata(e))
     rescue StandardError => e
-      handle_unexpected_error(e)
+      # Unexpected errors
+      wrap_response(nil, unexpected_error_metadata(e))
     end
 
     # Include Cacheable AFTER call method is defined so it can wrap it
@@ -181,7 +221,7 @@ module BetterService
     # Auto-invalidation happens when:
     # 1. auto_invalidate_cache is enabled (true)
     # 2. cache_contexts are defined (something to invalidate)
-    # 3. Service is a write operation (Create/Update/Destroy)
+    # 3. Service is a write operation (detected by action name or class name)
     #
     # @return [Boolean] Whether cache should be invalidated
     def should_auto_invalidate_cache?
@@ -189,62 +229,181 @@ module BetterService
       return false unless self.class.respond_to?(:_cache_contexts)
       return false unless self.class._cache_contexts.present?
 
-      # Only auto-invalidate for write operations
-      is_a?(Services::CreateService) ||
-        is_a?(Services::UpdateService) ||
-        is_a?(Services::DestroyService)
+      # Detect write operations by action name or class name pattern
+      write_actions = %i[created updated destroyed]
+      action_name = self.class._action_name
+      return true if write_actions.include?(action_name)
+
+      # Also check class name pattern as fallback
+      class_name = self.class.name.to_s
+      class_name.end_with?("CreateService", "UpdateService", "DestroyService")
+    end
+
+    # ============================================
+    # RESULT RESPONSE BUILDERS
+    # ============================================
+
+    # Build response from service result hash
+    #
+    # @param result [Hash] The result from respond phase
+    # @return [BetterService::Result, Array] Result wrapper or [object, metadata] tuple
+    def build_result_response(result)
+      object = extract_object(result)
+      metadata = build_success_metadata(result)
+
+      wrap_response(object, metadata)
+    end
+
+    # Wrap object and metadata in configured format
+    #
+    # @param object [Object] The resource object
+    # @param metadata [Hash] The metadata hash
+    # @return [BetterService::Result] Result wrapper
+    def wrap_response(object, metadata)
+      Result.new(object, meta: metadata)
+    end
+
+    # Extract the object from result hash
+    # Supports :object, :resource, and :items keys
+    #
+    # @param result [Hash] Result hash from respond phase
+    # @return [Object, Array, nil] The extracted object
+    def extract_object(result)
+      result[:object] || result[:resource] || result[:items]
+    end
+
+    # Build metadata hash for successful responses
+    #
+    # @param result [Hash] Result hash from respond phase
+    # @return [Hash] Metadata hash
+    def build_success_metadata(result)
+      # Check if respond phase already signaled failure
+      success = result.fetch(:success, true)
+
+      metadata = {
+        success: success,
+        action: self.class._action_name,
+        message: result[:message]
+      }
+
+      # Merge any additional metadata provided
+      if result[:metadata].is_a?(Hash)
+        metadata.merge!(result[:metadata])
+      end
+
+      # Add validation errors if this is a failure response from process_with
+      if !success && result[:object].respond_to?(:errors) && result[:object].errors.any?
+        metadata[:validation_errors] = result[:object].errors.messages
+        metadata[:full_messages] = result[:object].errors.full_messages
+      end
+
+      metadata
+    end
+
+    # ============================================
+    # ERROR METADATA BUILDERS
+    # ============================================
+
+    # Build metadata for schema validation errors (from Dry::Schema)
+    #
+    # @param error [Errors::Runtime::ValidationError] The validation error
+    # @return [Hash] Error metadata
+    def validation_error_metadata(error)
+      Rails.logger.error "Validation error in #{self.class.name}: #{error.message}" if defined?(Rails)
+
+      {
+        success: false,
+        action: self.class._action_name,
+        message: error.message,
+        error_code: error.code,
+        validation_errors: error.context[:validation_errors] || {}
+      }
     end
 
-    # Error handlers for runtime errors
+    # Build metadata for authorization errors
     #
-    # These methods handle unexpected errors during service execution by raising
-    # appropriate runtime exceptions. They log the error and wrap it with service context.
+    # @param error [Errors::Runtime::AuthorizationError] The authorization error
+    # @return [Hash] Error metadata
+    def authorization_error_metadata(error)
+      Rails.logger.error "Authorization error in #{self.class.name}: #{error.message}" if defined?(Rails)
+
+      {
+        success: false,
+        action: self.class._action_name,
+        message: error.message,
+        error_code: error.code
+      }
+    end
+
+    # Build metadata for BetterService resource not found errors
+    #
+    # @param error [Errors::Runtime::ResourceNotFoundError] The BetterService not found error
+    # @return [Hash] Error metadata
+    def resource_not_found_error_metadata(error)
+      Rails.logger.error "Resource not found in #{self.class.name}: #{error.message}" if defined?(Rails)
 
-    # Handle resource not found errors (ActiveRecord::RecordNotFound)
+      {
+        success: false,
+        action: self.class._action_name,
+        message: error.message,
+        error_code: error.code
+      }
+    end
+
+    # Build metadata for ActiveRecord not found errors
     #
-    # @param error [ActiveRecord::RecordNotFound] The original not found error
-    # @raise [Errors::Runtime::ResourceNotFoundError] Wrapped error with context
-    def handle_not_found_error(error)
+    # @param error [ActiveRecord::RecordNotFound] The not found error
+    # @return [Hash] Error metadata
+    def not_found_error_metadata(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 }
-      )
+      {
+        success: false,
+        action: self.class._action_name,
+        message: "Resource not found: #{error.message}",
+        error_code: BetterService::ErrorCodes::RESOURCE_NOT_FOUND
+      }
     end
 
-    # Handle database errors (ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved)
+    # Build metadata for ActiveRecord validation errors
+    # Returns the record so it can be used to re-render forms
     #
-    # @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)
+    # @param error [ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved] The AR error
+    # @return [Hash] Error metadata with validation details
+    def ar_validation_error_metadata(error)
+      Rails.logger.error "AR validation error in #{self.class.name}: #{error.message}" 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 }
-      )
+      metadata = {
+        success: false,
+        action: self.class._action_name,
+        message: "Validation failed: #{error.message}",
+        error_code: BetterService::ErrorCodes::DATABASE_ERROR
+      }
+
+      # Extract validation errors from the record if available
+      if error.respond_to?(:record) && error.record
+        metadata[:validation_errors] = error.record.errors.messages
+        metadata[:full_messages] = error.record.errors.full_messages
+      end
+
+      metadata
     end
 
-    # Handle unexpected errors (all other StandardError)
+    # Build metadata for unexpected errors
     #
-    # @param error [StandardError] The original unexpected error
-    # @raise [Errors::Runtime::ExecutionError] Wrapped error with context
-    def handle_unexpected_error(error)
+    # @param error [StandardError] The unexpected error
+    # @return [Hash] Error metadata
+    def unexpected_error_metadata(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 }
-      )
+      Rails.logger.error error.backtrace.join("\n") if defined?(Rails) && error.backtrace
+
+      {
+        success: false,
+        action: self.class._action_name,
+        message: "Service execution failed: #{error.message}",
+        error_code: BetterService::ErrorCodes::EXECUTION_ERROR,
+        error_class: error.class.name
+      }
     end
 
     def validate_user_presence!(user)

data/lib/better_service/version.rb

@@ -1,3 +1,3 @@
 module BetterService
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/lib/better_service/workflows/branch_group.rb

@@ -96,7 +96,7 @@ module BetterService
 
         # Track this branch decision
         branch_decision = "#{@name}:#{selected_branch.name}"
-        branch_decisions = [branch_decision]
+        branch_decisions = [ branch_decision ]
 
         # Execute the selected branch
         executed_steps = selected_branch.execute(context, user, params, branch_decisions)

data/lib/better_service.rb

@@ -2,6 +2,7 @@ require "better_service/version"
 require "better_service/railtie"
 require "better_service/configuration"
 require "better_service/errors/better_service_error"
+require "better_service/result"
 require "better_service/cache_service"
 require "better_service/presenter"
 require "better_service/repository/base_repository"
@@ -10,12 +11,6 @@ require "better_service/concerns/instrumentation"
 require "better_service/subscribers/log_subscriber"
 require "better_service/subscribers/stats_subscriber"
 require "better_service/services/base"
-require "better_service/services/index_service"
-require "better_service/services/show_service"
-require "better_service/services/create_service"
-require "better_service/services/update_service"
-require "better_service/services/destroy_service"
-require "better_service/services/action_service"
 require "better_service/concerns/workflowable/context"
 require "better_service/concerns/workflowable/step"
 require "better_service/concerns/workflowable/callbacks"

data/lib/generators/serviceable/action_generator.rb

@@ -11,6 +11,9 @@ module Serviceable
 
       desc "Generate an Action service for custom state transitions"
 
+      class_option :base_class, type: :string, default: nil,
+                   desc: "Custom base class to inherit from (e.g., Articles::BaseService)"
+
       def create_service_file
         template "action_service.rb.tt", File.join("app/services", class_path, "#{file_name}/#{action_name}_service.rb")
       end
@@ -24,6 +27,14 @@ module Serviceable
       def service_class_name
         "#{class_name}::#{action_name.camelize}Service"
       end
+
+      def parent_class
+        options[:base_class] || "BetterService::Services::Base"
+      end
+
+      def using_base_service?
+        options[:base_class].present?
+      end
     end
   end
 end

data/lib/generators/serviceable/base_generator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Serviceable
+  module Generators
+    # BaseGenerator - Generate a base service class for a resource namespace
+    #
+    # Creates a ResourceBaseService that centralizes:
+    # - Repository initialization via RepositoryAware concern
+    # - Cache configuration
+    # - Messages namespace (I18n)
+    # - Presenter configuration
+    #
+    # Usage:
+    #   rails generate serviceable:base Articles
+    #   rails generate serviceable:base Admin::Articles
+    #   rails generate serviceable:base Articles --skip_repository
+    #   rails generate serviceable:base Articles --skip_locale
+    #
+    # This generates:
+    #   app/services/articles/base_service.rb
+    #   app/repositories/articles_repository.rb
+    #   config/locales/articles_services.en.yml
+    #   test/services/articles/base_service_test.rb
+    #   test/repositories/articles_repository_test.rb
+    class BaseGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a base service with repository, cache, and I18n configuration"
+
+      class_option :skip_repository, type: :boolean, default: false,
+                   desc: "Skip repository generation"
+      class_option :skip_locale, type: :boolean, default: false,
+                   desc: "Skip locale file generation"
+      class_option :skip_presenter, type: :boolean, default: false,
+                   desc: "Skip presenter configuration in base service"
+      class_option :skip_test, type: :boolean, default: false,
+                   desc: "Skip test file generation"
+
+      def create_base_service
+        template "base_service.rb.tt",
+                 File.join("app/services", class_path, file_name, "base_service.rb")
+      end
+
+      def create_repository
+        return if options[:skip_repository]
+
+        template "repository.rb.tt",
+                 File.join("app/repositories", class_path, "#{file_name}_repository.rb")
+      end
+
+      def create_locale
+        return if options[:skip_locale]
+
+        template "base_locale.en.yml.tt",
+                 File.join("config/locales", "#{file_name}_services.en.yml")
+      end
+
+      def create_base_service_test
+        return if options[:skip_test]
+
+        template "base_service_test.rb.tt",
+                 File.join("test/services", class_path, file_name, "base_service_test.rb")
+      end
+
+      def create_repository_test
+        return if options[:skip_test] || options[:skip_repository]
+
+        template "repository_test.rb.tt",
+                 File.join("test/repositories", class_path, "#{file_name}_repository_test.rb")
+      end
+
+      def show_completion_message
+        say "\n" + "=" * 80
+        say "Base service generation completed! 🎉", :green
+        say "=" * 80
+        say "\nGenerated files:"
+        say "  - #{class_name}::BaseService (app/services/#{file_path}/base_service.rb)"
+        say "  - #{class_name}Repository (app/repositories/#{file_path}_repository.rb)" unless options[:skip_repository]
+        say "  - I18n locale (config/locales/#{file_name}_services.en.yml)" unless options[:skip_locale]
+        say "\nNext steps:"
+        say "  1. Customize the base service with resource-specific methods"
+        say "  2. Add custom repository methods for your queries"
+        say "  3. Generate CRUD services that inherit from BaseService:"
+        say "     rails generate serviceable:scaffold #{name} --base"
+        say "\nServices will inherit like: #{class_name}::IndexService < #{class_name}::BaseService\n\n"
+      end
+
+      private
+
+      def file_path
+        File.join(class_path, file_name)
+      end
+
+      def repository_class_name
+        "#{class_name}Repository"
+      end
+
+      def presenter_class_name
+        "#{class_name}Presenter"
+      end
+
+      def base_service_class_name
+        "#{class_name}::BaseService"
+      end
+    end
+  end
+end

data/lib/generators/serviceable/create_generator.rb

@@ -9,6 +9,9 @@ module Serviceable
 
       desc "Generate a Create service for creating new resources"
 
+      class_option :base_class, type: :string, default: nil,
+                   desc: "Custom base class to inherit from (e.g., Articles::BaseService)"
+
       def create_service_file
         template "create_service.rb.tt", File.join("app/services", class_path, "#{file_name}/create_service.rb")
       end
@@ -22,6 +25,14 @@ module Serviceable
       def service_class_name
         "#{class_name}::CreateService"
       end
+
+      def parent_class
+        options[:base_class] || "BetterService::Services::Base"
+      end
+
+      def using_base_service?
+        options[:base_class].present?
+      end
     end
   end
 end

data/lib/generators/serviceable/destroy_generator.rb

@@ -9,6 +9,9 @@ module Serviceable
 
       desc "Generate a Destroy service for deleting resources"
 
+      class_option :base_class, type: :string, default: nil,
+                   desc: "Custom base class to inherit from (e.g., Articles::BaseService)"
+
       def create_service_file
         template "destroy_service.rb.tt", File.join("app/services", class_path, "#{file_name}/destroy_service.rb")
       end
@@ -22,6 +25,14 @@ module Serviceable
       def service_class_name
         "#{class_name}::DestroyService"
       end
+
+      def parent_class
+        options[:base_class] || "BetterService::Services::Base"
+      end
+
+      def using_base_service?
+        options[:base_class].present?
+      end
     end
   end
 end

data/lib/generators/serviceable/index_generator.rb

@@ -9,6 +9,9 @@ module Serviceable
 
       desc "Generate an Index service for listing resources"
 
+      class_option :base_class, type: :string, default: nil,
+                   desc: "Custom base class to inherit from (e.g., Articles::BaseService)"
+
       def create_service_file
         template "index_service.rb.tt", File.join("app/services", class_path, "#{file_name}/index_service.rb")
       end
@@ -22,6 +25,14 @@ module Serviceable
       def service_class_name
         "#{class_name}::IndexService"
       end
+
+      def parent_class
+        options[:base_class] || "BetterService::Services::Base"
+      end
+
+      def using_base_service?
+        options[:base_class].present?
+      end
     end
   end
 end

data/lib/generators/serviceable/scaffold_generator.rb

@@ -13,42 +13,52 @@ module Serviceable
       class_option :skip_update, type: :boolean, default: false, desc: "Skip Update service generation"
       class_option :skip_destroy, type: :boolean, default: false, desc: "Skip Destroy service generation"
       class_option :presenter, type: :boolean, default: false, desc: "Generate presenter class"
+      class_option :skip_repository, type: :boolean, default: false, desc: "Skip repository generation"
+      class_option :skip_locale, type: :boolean, default: false, desc: "Skip locale file generation"
 
-      desc "Generate all CRUD services (Index, Show, Create, Update, Destroy)"
+      desc "Generate all CRUD services (Index, Show, Create, Update, Destroy) with BaseService"
+
+      def generate_base_service
+        say "Generating BaseService, Repository and Locale...", :green
+        args = [ name ]
+        args << "--skip_repository" if options[:skip_repository]
+        args << "--skip_locale" if options[:skip_locale]
+        generate "serviceable:base", *args
+      end
 
       def generate_index_service
         return if options[:skip_index]
 
         say "Generating Index service...", :green
-        generate "serviceable:index", name
+        generate "serviceable:index", *service_generator_args
       end
 
       def generate_show_service
         return if options[:skip_show]
 
         say "Generating Show service...", :green
-        generate "serviceable:show", name
+        generate "serviceable:show", *service_generator_args
       end
 
       def generate_create_service
         return if options[:skip_create]
 
         say "Generating Create service...", :green
-        generate "serviceable:create", name
+        generate "serviceable:create", *service_generator_args
       end
 
       def generate_update_service
         return if options[:skip_update]
 
         say "Generating Update service...", :green
-        generate "serviceable:update", name
+        generate "serviceable:update", *service_generator_args
       end
 
       def generate_destroy_service
         return if options[:skip_destroy]
 
         say "Generating Destroy service...", :green
-        generate "serviceable:destroy", name
+        generate "serviceable:destroy", *service_generator_args
       end
 
       def generate_presenter
@@ -62,7 +72,11 @@ module Serviceable
         say "\n" + "=" * 80
         say "Scaffold generation completed! 🎉", :green
         say "=" * 80
-        say "\nGenerated services:"
+        say "\nGenerated base infrastructure:"
+        say "  - #{class_name}::BaseService (app/services/#{file_name}/base_service.rb)"
+        say "  - #{class_name}Repository (app/repositories/#{file_name}_repository.rb)" unless options[:skip_repository]
+        say "  - I18n locale (config/locales/#{file_name}_services.en.yml)" unless options[:skip_locale]
+        say "\nGenerated services (inheriting from #{class_name}::BaseService):"
         say "  - #{class_name}::IndexService" unless options[:skip_index]
         say "  - #{class_name}::ShowService" unless options[:skip_show]
         say "  - #{class_name}::CreateService" unless options[:skip_create]
@@ -74,6 +88,14 @@ module Serviceable
         say "  2. Update schemas with your specific validations"
         say "  3. Run the tests: rails test test/services/#{file_name}\n\n"
       end
+
+      private
+
+      # Build arguments array for CRUD service generators
+      # Always includes --base_class since BaseService is always generated
+      def service_generator_args
+        [ name, "--base_class=#{class_name}::BaseService" ]
+      end
     end
   end
 end