better_service 2.0.0 → 2.1.0

data/lib/better_service/concerns/serviceable/messageable.rb

@@ -43,7 +43,7 @@ module BetterService
         fallback_key = "better_service.services.default.#{action}"
 
         # I18n supports array of fallback keys: try each in order
-        I18n.t(full_key, default: [fallback_key.to_sym, key_path], **interpolations)
+        I18n.t(full_key, default: [ fallback_key.to_sym, key_path ], **interpolations)
       end
 
       # Extract action name from key path for fallback lookup
@@ -67,6 +67,75 @@ module BetterService
         else "action_completed"
         end
       end
+
+      # ============================================
+      # RESPONSE HELPERS FOR TUPLE FORMAT
+      # ============================================
+
+      # Build a failure response hash for validation failures
+      # Use this when using save (not save!) to handle AR validation gracefully
+      #
+      # @param record [ActiveRecord::Base] The record with validation errors
+      # @param custom_message [String, nil] Optional custom message
+      # @return [Hash] Failure response hash (for use in process_with/respond_with)
+      #
+      # @example In process_with block
+      #   process_with do |data|
+      #     product = user.products.build(params)
+      #
+      #     if product.save
+      #       { object: product }
+      #     else
+      #       failure_for(product)
+      #     end
+      #   end
+      def failure_for(record, custom_message = nil)
+        {
+          object: record,
+          success: false,
+          message: custom_message || default_failure_message(record)
+        }
+      end
+
+      # Build a success response hash
+      #
+      # @param object [Object] The object to return (AR model, array, etc.)
+      # @param custom_message [String, nil] Optional custom message
+      # @return [Hash] Success response hash (for use in respond_with)
+      #
+      # @example In respond_with block
+      #   respond_with do |data|
+      #     return data if data[:success] == false
+      #     success_for(data[:object], "Product created!")
+      #   end
+      def success_for(object, custom_message = nil)
+        {
+          object: object,
+          success: true,
+          message: custom_message || default_success_message
+        }
+      end
+
+      # Generate default failure message based on record state
+      #
+      # @param record [ActiveRecord::Base] The failed record
+      # @return [String] Failure message
+      def default_failure_message(record)
+        model_name = record.class.name.underscore.humanize.downcase
+        if record.new_record?
+          message("create.failure", default: "Failed to create #{model_name}")
+        else
+          message("update.failure", default: "Failed to update #{model_name}")
+        end
+      end
+
+      # Generate default success message based on action
+      #
+      # @return [String] Success message
+      def default_success_message
+        action = self.class._action_name || :action
+        message("#{action}.success", default: "Operation completed successfully")
+      end
     end
     end
   end

data/lib/better_service/concerns/serviceable/repository_aware.rb

@@ -10,9 +10,12 @@ module BetterService
       # separation between business logic and data access.
       #
       # @example Basic usage
-      #   class Products::CreateService < BetterService::Services::CreateService
+      #   class Products::CreateService < Products::BaseService
       #     include BetterService::Concerns::Serviceable::RepositoryAware
       #
+      #     performed_action :created
+      #     with_transaction true
+      #
       #     repository :product
       #
       #     process_with do |data|
@@ -21,7 +24,7 @@ module BetterService
       #   end
       #
       # @example With custom class name
-      #   class Bookings::AcceptService < BetterService::Services::ActionService
+      #   class Bookings::AcceptService < Bookings::BaseService
       #     include BetterService::Concerns::Serviceable::RepositoryAware
       #
       #     repository :booking, class_name: "Bookings::BookingRepository"
@@ -33,9 +36,11 @@ module BetterService
       #   end
       #
       # @example Multiple repositories shorthand
-      #   class Dashboard::IndexService < BetterService::Services::IndexService
+      #   class Dashboard::IndexService < Dashboard::BaseService
       #     include BetterService::Concerns::Serviceable::RepositoryAware
       #
+      #     performed_action :listed
+      #
       #     repositories :user, :booking, :payment
       #   end
       #

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

@@ -4,33 +4,33 @@ module BetterService
   module Concerns
     module Workflowable
       # Callbacks - Adds lifecycle callbacks to workflows
-    #
-    # Provides before_workflow, after_workflow, and around_step hooks
-    # that allow executing custom logic at different stages of the workflow.
-    #
-    # Example:
-    #   class OrderWorkflow < BetterService::Workflow
-    #     before_workflow :validate_prerequisites
-    #     after_workflow :cleanup_resources
-    #     around_step :log_step_execution
-    #
-    #     private
-    #
-    #     def validate_prerequisites(context)
-    #       context.fail!("Cart is empty") if context.cart_items.empty?
-    #     end
-    #
-    #     def cleanup_resources(context)
-    #       context.user.clear_cart! if context.success?
-    #     end
-    #
-    #     def log_step_execution(step, context)
-    #       start_time = Time.current
-    #       yield # Execute the step
-    #       duration = Time.current - start_time
-    #       Rails.logger.info "Step #{step.name} completed in #{duration}s"
-    #     end
-    #   end
+      #
+      # Provides before_workflow, after_workflow, and around_step hooks
+      # that allow executing custom logic at different stages of the workflow.
+      #
+      # Example:
+      #   class OrderWorkflow < BetterService::Workflow
+      #     before_workflow :validate_prerequisites
+      #     after_workflow :cleanup_resources
+      #     around_step :log_step_execution
+      #
+      #     private
+      #
+      #     def validate_prerequisites(context)
+      #       context.fail!("Cart is empty") if context.cart_items.empty?
+      #     end
+      #
+      #     def cleanup_resources(context)
+      #       context.user.clear_cart! if context.success?
+      #     end
+      #
+      #     def log_step_execution(step, context)
+      #       start_time = Time.current
+      #       yield # Execute the step
+      #       duration = Time.current - start_time
+      #       Rails.logger.info "Step #{step.name} completed in #{duration}s"
+      #     end
+      #   end
       module Callbacks
         extend ActiveSupport::Concern
 

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

@@ -35,7 +35,7 @@ module BetterService
       # @param context [Context] The workflow context
       # @param user [Object] The current user
       # @param params [Hash] Base params for the workflow
-      # @return [Hash] Service result
+      # @return [Hash] Service result (normalized to hash format for workflow compatibility)
       def call(context, user, base_params = {})
         # Check if step should be skipped due to condition
         if should_skip?(context)
@@ -49,20 +49,23 @@ module BetterService
         # 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
+        # Call the service - returns [object, metadata] tuple
+        service_result = service_class.new(user, params: service_params).call
+
+        # Normalize result to hash format (services now return [object, metadata] tuple)
+        result = normalize_service_result(service_result)
 
         # 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])
+          context.add(:"#{name}_error", result[:errors] || result[:validation_errors])
           return {
             success: true,
             optional_failure: true,
             message: "Optional step #{name} failed but continuing",
-            errors: result[:errors]
+            errors: result[:errors] || result[:validation_errors]
           }
         end
 
@@ -123,6 +126,37 @@ module BetterService
         end
       end
 
+      # Normalize service result from Result format to hash format
+      # Services return BetterService::Result but workflows expect hash with :success, :resource, etc.
+      #
+      # @param service_result [BetterService::Result] The service result
+      # @return [Hash] Normalized result hash
+      # @raise [BetterService::Errors::Runtime::InvalidResultError] If result is not a BetterService::Result
+      def normalize_service_result(service_result)
+        unless service_result.is_a?(BetterService::Result)
+          raise BetterService::Errors::Runtime::InvalidResultError.new(
+            "Step #{name} service must return BetterService::Result, got #{service_result.class}",
+            context: { step: name, service: service_class.name, result_class: service_result.class.name }
+          )
+        end
+
+        object = service_result.resource
+        metadata = service_result.meta
+
+        # Build normalized hash result
+        result = metadata.dup
+        result[:success] = metadata[:success] if metadata.key?(:success)
+
+        # Store object appropriately based on type
+        if object.is_a?(Array)
+          result[:items] = object
+        elsif object.present?
+          result[:resource] = object
+        end
+
+        result
+      end
+
       # Store successful result data in context
       def store_result_in_context(context, result)
         # Store resource if present

data/lib/better_service/errors/better_service_error.rb

@@ -218,6 +218,9 @@ module BetterService
 
     # Workflow rollback failed
     ROLLBACK_FAILED = :rollback_failed
+
+    # Service returned invalid result type (not BetterService::Result)
+    INVALID_RESULT = :invalid_result
   end
 end
 
@@ -235,6 +238,7 @@ require_relative "runtime/resource_not_found_error"
 require_relative "runtime/database_error"
 require_relative "runtime/validation_error"
 require_relative "runtime/authorization_error"
+require_relative "runtime/invalid_result_error"
 
 require_relative "workflowable/configuration/workflow_configuration_error"
 require_relative "workflowable/configuration/step_not_found_error"

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

@@ -31,7 +31,10 @@ module BetterService
       #   rescue BetterService::Errors::Runtime::AuthorizationError => e
       #     render json: { error: e.message }, status: :forbidden
       #   end
-      class AuthorizationError < RuntimeError
+      class AuthorizationError < BetterService::Errors::Runtime::RuntimeError
+        def initialize(message = "Not authorized", code: :unauthorized, context: {}, original_error: nil)
+          super(message, code: code, context: context, original_error: original_error)
+        end
       end
     end
   end

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

@@ -31,7 +31,10 @@ module BetterService
       #
       #   MyService.new(user, params: { user_id: 1 }).call
       #   # => raises DatabaseError
-      class DatabaseError < RuntimeError
+      class DatabaseError < BetterService::Errors::Runtime::RuntimeError
+        def initialize(message = "Database error", code: :database_error, context: {}, original_error: nil)
+          super(message, code: code, context: context, original_error: original_error)
+        end
       end
     end
   end

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

@@ -20,7 +20,10 @@ module BetterService
       #
       #   MyService.new(user, params: {}).call
       #   # => raises ExecutionError wrapping SocketError
-      class ExecutionError < RuntimeError
+      class ExecutionError < BetterService::Errors::Runtime::RuntimeError
+        def initialize(message = "Execution failed", code: :execution_error, context: {}, original_error: nil)
+          super(message, code: code, context: context, original_error: original_error)
+        end
       end
     end
   end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Errors
+    module Runtime
+      # InvalidResultError - Raised when a service does not return BetterService::Result
+      #
+      # All services MUST return a BetterService::Result object. This error is raised
+      # when a service returns a Hash, Array (tuple), or any other type instead.
+      #
+      # @example
+      #   raise BetterService::Errors::Runtime::InvalidResultError.new(
+      #     "Service MyService must return BetterService::Result, got Hash",
+      #     context: { service: "MyService", result_class: "Hash" }
+      #   )
+      class InvalidResultError < RuntimeError
+        def initialize(message = nil, code: :invalid_result, context: {}, original_error: nil)
+          super(
+            message || "Service must return BetterService::Result",
+            code: code,
+            context: context,
+            original_error: original_error
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -31,7 +31,10 @@ module BetterService
       #
       #   MyService.new(user, params: { user_id: 99999 }).call
       #   # => raises ResourceNotFoundError
-      class ResourceNotFoundError < RuntimeError
+      class ResourceNotFoundError < BetterService::Errors::Runtime::RuntimeError
+        def initialize(message = "Resource not found", code: :resource_not_found, context: {}, original_error: nil)
+          super(message, code: code, context: context, original_error: original_error)
+        end
       end
     end
   end

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

@@ -35,7 +35,10 @@ module BetterService
       #       validation_errors: e.context[:validation_errors]
       #     }, status: :unprocessable_entity
       #   end
-      class ValidationError < RuntimeError
+      class ValidationError < BetterService::Errors::Runtime::RuntimeError
+        def initialize(message = "Validation failed", code: :validation_failed, context: {}, original_error: nil)
+          super(message, code: code, context: context, original_error: original_error)
+        end
       end
     end
   end

data/lib/better_service/repository/base_repository.rb

@@ -249,7 +249,7 @@ module BetterService
       # @param per_page [Integer] Records per page
       # @return [ActiveRecord::Relation] Paginated scope
       def paginate(scope, page:, per_page:)
-        offset_value = ([page.to_i, 1].max - 1) * per_page.to_i
+        offset_value = ([ page.to_i, 1 ].max - 1) * per_page.to_i
         scope.offset(offset_value).limit(per_page)
       end
     end

data/lib/better_service/result.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module BetterService
+  # Result wrapper per le risposte dei service
+  #
+  # Fornisce un modo standardizzato per restituire sia la risorsa che i metadata.
+  # BetterController può automaticamente unwrappare gli oggetti Result.
+  #
+  # @example Caso di successo
+  #   BetterService::Result.new(user, meta: { message: "Created" })
+  #
+  # @example Caso di fallimento
+  #   BetterService::Result.new(user, meta: { success: false, message: "Validation failed" })
+  #
+  class Result
+    attr_reader :resource, :meta
+
+    # @param resource [Object] L'oggetto risorsa (model, collection, etc.)
+    # @param meta [Hash] Hash di metadata, deve contenere :success key (default: true)
+    def initialize(resource, meta: {})
+      @resource = resource
+      @meta     = meta.is_a?(Hash) ? meta.reverse_merge(success: true) : { success: true }
+    end
+
+    # @return [Boolean] true se l'operazione è riuscita
+    def success?
+      meta[:success] == true
+    end
+
+    # @return [Boolean] true se l'operazione è fallita
+    def failure?
+      !success?
+    end
+
+    # @return [String, nil] Il messaggio dal meta
+    def message
+      meta[:message]
+    end
+
+    # @return [Symbol, nil] L'azione eseguita
+    def action
+      meta[:action]
+    end
+
+    # @return [Hash, nil] Gli errori di validazione
+    def validation_errors
+      meta[:validation_errors]
+    end
+
+    # @return [Array<String>, nil] I messaggi di errore completi
+    def full_messages
+      meta[:full_messages]
+    end
+
+    # @return [ActiveModel::Errors, nil] Errori dalla risorsa se disponibili
+    def errors
+      resource.respond_to?(:errors) ? resource.errors : nil
+    end
+
+    # Supporta destructuring: resource, meta = result
+    # @return [Array] [resource, meta]
+    def to_ary
+      [ resource, meta ]
+    end
+
+    # Alias per compatibilità con destructuring
+    alias_method :deconstruct, :to_ary
+
+    # @return [Hash] Rappresentazione completa
+    def to_h
+      { resource: resource, meta: meta }
+    end
+
+    # Accesso Hash-like per compatibilità con BetterController
+    # @param key [Symbol] La chiave da accedere
+    # @return [Object, nil] Il valore associato alla chiave
+    def [](key)
+      case key
+      when :resource then resource
+      when :meta then meta
+      when :success then success?
+      when :message then message
+      when :action then action
+      else
+        meta[key]
+      end
+    end
+
+    # Accesso nested Hash-like (dig)
+    # @param keys [Array<Symbol>] Le chiavi per l'accesso nested
+    # @return [Object, nil] Il valore nested
+    def dig(*keys)
+      return nil if keys.empty?
+
+      value = self[keys.first]
+      return value if keys.size == 1
+      return nil unless value.respond_to?(:dig)
+
+      value.dig(*keys[1..])
+    end
+
+    # Verifica esistenza chiave
+    # @param key [Symbol] La chiave da verificare
+    # @return [Boolean]
+    def key?(key)
+      %i[resource meta success message action].include?(key) || meta.key?(key)
+    end
+    alias_method :has_key?, :key?
+  end
+end