better_service 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ce89074c072a76a05a669dc079d3d4fbf1ba99a7f758f4ae45c9640b335c4c4
-  data.tar.gz: 34bcc32228b8c358f21f4713e783ef3f17e7e38047ab0116abad5a6e0d2a1aec
+  metadata.gz: a03149390ed14f18e00211a28f8549497048245e592f598a41612789a80b0889
+  data.tar.gz: f97b2063a3c2652942957b120a227b29cd92fb4b22a70b0162772c61125dee9e
 SHA512:
-  metadata.gz: 1479b3e94a12463614adb2022aa8a8d725939224715c5f5ae876be036f96da3c3a63171d6ca1cda4dc10ac3c6e97f98a615a45b952a9441066f24f064161521d
-  data.tar.gz: 2a985c1abfdbb8dc352fdc34351439f35bf0f09ed8784593e04e113a3bd2a38c1d172a3fb1f69836ab24cfd25881b59b52a5c54e5a4a3a6c8b8eacb1fcdb31f8
+  metadata.gz: d157b4542bd163145c2a3db7eae5cc0154c40f412ba32287ebbbbe1c535b4ebf386763115d463104ad0816bde0fc218382a1382bfa981e839a538e7791d033c5
+  data.tar.gz: ad3756e28b89045810aee2e7014c483f821d7d0df396d967536f8f9e07f48f33235847e36d05439cd99022755d5860f62af44399d40346c4d74a7864949ca6d3

data/LICENSE

@@ -11,3 +11,5 @@ as the name is changed.
 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
 0. You just DO WHAT THE FUCK YOU WANT TO.
+
+"public_key": "pk_B9nH6LdAbbONpo8kXlCON",

data/README.md

@@ -1,11 +1,21 @@
 <div align="center">
 
-# 💎 BetterService
+# BetterService
 
 ### Clean, powerful Service Objects for Rails
 
 [![Gem Version](https://badge.fury.io/rb/better_service.svg)](https://badge.fury.io/rb/better_service)
-[![License](https://img.shields.io/badge/license-WTFPL-blue.svg)](http://www.wtfpl.net/about/)
+[![CI](https://github.com/alessiobussolari/better_service/actions/workflows/ci.yml/badge.svg)](https://github.com/alessiobussolari/better_service/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/alessiobussolari/better_service/branch/main/graph/badge.svg)](https://codecov.io/gh/alessiobussolari/better_service)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-CC0000.svg)](https://rubyonrails.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[![Downloads](https://img.shields.io/gem/dt/better_service.svg)](https://rubygems.org/gems/better_service)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/better_service)
+[![GitHub issues](https://img.shields.io/github/issues/alessiobussolari/better_service.svg)](https://github.com/alessiobussolari/better_service/issues)
+[![GitHub stars](https://img.shields.io/github/stars/alessiobussolari/better_service.svg)](https://github.com/alessiobussolari/better_service/stargazers)
+[![Contributors](https://img.shields.io/github/contributors/alessiobussolari/better_service.svg)](https://github.com/alessiobussolari/better_service/graphs/contributors)
 
 [Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Usage](#-usage) • [Error Handling](#%EF%B8%8F-error-handling) • [Examples](#-examples)
 
@@ -15,22 +25,30 @@
 
 ## ✨ Features
 
-BetterService is a comprehensive Service Objects framework for Rails that brings clean architecture and powerful features to your business logic layer:
+BetterService is a comprehensive Service Objects framework for Rails that brings clean architecture and powerful features to your business logic layer.
 
-- 🎯 **5-Phase Flow Architecture**: Structured flow with search → process → transform → respond → viewer phases
+**Version 2.1.0** • 1,000+ tests passing (812 gem + 275 rails_app)
+
+### Core Features
+
+- 🎯 **4-Phase Flow Architecture**: Structured flow with validation → authorization → search → process → respond
+- 📦 **Result Wrapper**: `BetterService::Result` with `.success?`, `.resource`, `.meta`, `.message` and destructuring support
+- 🏛️ **Repository Pattern**: Clean data access with `RepositoryAware` concern and `repository :model_name` DSL
 - ✅ **Mandatory Schema Validation**: Built-in [Dry::Schema](https://dry-rb.org/gems/dry-schema/) validation for all params
 - 🔄 **Transaction Support**: Automatic database transaction wrapping with rollback
 - 🔐 **Flexible Authorization**: `authorize_with` DSL that works with any auth system (Pundit, CanCanCan, custom)
 - ⚠️ **Rich Error Handling**: Pure Exception Pattern with hierarchical errors, rich context, and detailed debugging info
+
+### Advanced Features
+
 - 💾 **Cache Management**: Built-in `CacheService` for invalidating cache by context, user, or globally with async support
 - 🔄 **Auto-Invalidation**: Write operations (Create/Update/Destroy) automatically invalidate cache when configured
 - 🌍 **I18n Support**: Built-in internationalization with `message()` helper, custom namespaces, and fallback chain
 - 🎨 **Presenter System**: Optional data transformation layer with `BetterService::Presenter` base class
 - 📊 **Metadata Tracking**: Automatic action metadata in all service responses
 - 🔗 **Workflow Composition**: Chain multiple services into pipelines with conditional steps, rollback support, and lifecycle hooks
-- 🌲 **Conditional Branching** (v1.1.0+): Multi-path workflow execution with `branch`/`on`/`otherwise` DSL for clean conditional logic
-- 🏗️ **Powerful Generators**: 10 generators for rapid scaffolding (scaffold, CRUD services, action, workflow, locale, presenter)
-- 📦 **6 Service Types**: Specialized services for different use cases
+- 🌲 **Conditional Branching**: Multi-path workflow execution with `branch`/`on`/`otherwise` DSL for clean conditional logic
+- 🏗️ **Powerful Generators**: 11 generators for rapid scaffolding (base, scaffold, CRUD services, action, workflow, locale, presenter)
 - 🎨 **DSL-Based**: Clean, expressive DSL with `search_with`, `process_with`, `authorize_with`, etc.
 
 ---
@@ -59,19 +77,21 @@ gem install better_service
 
 ## 🚀 Quick Start
 
-### 1. Generate a Service
+### 1. Generate Services
 
 ```bash
-# Generate a complete CRUD scaffold
-rails generate serviceable:scaffold Product
+# Generate BaseService + Repository + locale file
+rails generate serviceable:base Product
+
+# Generate all CRUD services inheriting from BaseService
+rails generate serviceable:scaffold Product --base
 
 # Or generate individual services
-rails generate serviceable:create Product
-rails generate serviceable:update Product
+rails generate serviceable:create Product --base_class=Product::BaseService
 rails generate serviceable:action Product publish
 ```
 
-### 2. Use the Service
+### 2. Use the Service with Result Wrapper
 
 ```ruby
 # Create a product
@@ -80,15 +100,19 @@ result = Product::CreateService.new(current_user, params: {
   price: 2499.99
 }).call
 
-if result[:success]
-  product = result[:resource]
-  # => Product object
-  action = result[:metadata][:action]
-  # => :created
+# Check success with Result wrapper
+if result.success?
+  product = result.resource   # => Product object
+  message = result.message    # => "Product created successfully"
+  action = result.meta[:action]  # => :created
 else
-  errors = result[:errors]
-  # => { name: ["can't be blank"], price: ["must be greater than 0"] }
+  error_code = result.meta[:error_code]  # => :unauthorized
+  message = result.message  # => "Not authorized"
 end
+
+# Or use destructuring
+product, meta = result
+redirect_to product if meta[:success]
 ```
 
 ---
@@ -118,37 +142,57 @@ See **[Configuration Guide](docs/start/configuration.md)** for all options inclu
 
 ## 📚 Usage
 
-### Service Structure
+### Service Architecture
 
-All services follow a 5-phase flow:
+All services inherit from `BetterService::Services::Base` via a resource-specific BaseService:
 
 ```ruby
-class Product::CreateService < BetterService::Services::CreateService
-  # 1. Schema Validation (mandatory)
+# 1. BaseService with Repository (generated with `rails g serviceable:base Product`)
+class Product::BaseService < BetterService::Services::Base
+  include BetterService::Concerns::Serviceable::RepositoryAware
+
+  messages_namespace :products
+  cache_contexts [:products]
+  repository :product  # Injects product_repository method
+end
+
+# 2. All services inherit from BaseService
+class Product::CreateService < Product::BaseService
+  performed_action :created
+  with_transaction true
+  auto_invalidate_cache true
+
+  # Schema Validation (mandatory)
   schema do
-    required(:name).filled(:string)
+    required(:name).filled(:string, min_size?: 2)
     required(:price).filled(:decimal, gt?: 0)
   end
 
-  # 2. Authorization (optional)
+  # Authorization - IMPORTANT: use `next` not `return`
   authorize_with do
-    user.admin? || user.can_create_products?
+    next true if user.admin?  # Admin bypass
+    user.seller?
   end
 
-  # 3. Search Phase - Load data
+  # Search Phase - Load data
   search_with do
-    { category: Category.find_by(id: params[:category_id]) }
+    {}  # No data to load for create
   end
 
-  # 4. Process Phase - Business logic
-  process_with do |data|
-    product = user.products.create!(params)
+  # Process Phase - Business logic
+  process_with do |_data|
+    product = product_repository.create!(
+      name: params[:name],
+      price: params[:price],
+      user: user
+    )
+    # IMPORTANT: Return { resource: ... } for proper extraction
     { resource: product }
   end
 
-  # 5. Respond Phase - Format response
+  # Respond Phase - Format response with Result wrapper
   respond_with do |data|
-    success_result("Product created successfully", data)
+    success_result(message("create.success", name: data[:resource].name), data)
   end
 end
 ```
@@ -282,11 +326,12 @@ class Product::DestroyService < BetterService::Services::DestroyService
 end
 ```
 
-#### 6. ⚡ ActionService - Custom Actions
+#### 6. ⚡ Custom Action Services
 
 ```ruby
-class Product::PublishService < BetterService::Services::ActionService
-  action_name :publish
+class Product::PublishService < Product::BaseService
+  # Action name for metadata
+  performed_action :publish
 
   schema do
     required(:id).filled(:integer)
@@ -297,7 +342,7 @@ class Product::PublishService < BetterService::Services::ActionService
   end
 
   search_with do
-    { resource: user.products.find(params[:id]) }
+    { resource: product_repository.find(params[:id]) }
   end
 
   process_with do |data|
@@ -321,19 +366,27 @@ BetterService provides a flexible `authorize_with` DSL that works with **any** a
 ### Simple Role-Based Authorization
 
 ```ruby
-class Product::CreateService < BetterService::Services::CreateService
+class Product::CreateService < Product::BaseService
   authorize_with do
-    user.admin?
+    # IMPORTANT: Use `next` not `return` (return causes LocalJumpError)
+    next true if user.admin?
+    user.seller?
   end
 end
 ```
 
-### Resource Ownership Check
+### Resource Ownership Check (Admin Bypass Pattern)
 
 ```ruby
-class Product::UpdateService < BetterService::Services::UpdateService
+class Product::UpdateService < Product::BaseService
   authorize_with do
-    product = Product.find(params[:id])
+    # Admin can update any product (even non-existent - will get "not found" error)
+    next true if user.admin?
+
+    # For non-admin, check resource ownership
+    product = Product.find_by(id: params[:id])
+    next false unless product  # Return unauthorized if product doesn't exist
+
     product.user_id == user.id
   end
 end
@@ -1481,7 +1534,7 @@ BetterService includes comprehensive test coverage. Run tests with:
 bundle exec rake
 
 # Or
-bundle exec rake test
+bundle exec rspec
 ```
 
 ### Manual Testing
@@ -1489,7 +1542,7 @@ bundle exec rake test
 A manual test script is included for hands-on verification:
 
 ```bash
-cd test/dummy
+cd spec/rails_app
 rails console
 load '../../manual_test.rb'
 ```

data/Rakefile

@@ -1,215 +1,13 @@
 require "bundler/setup"
 
 require "bundler/gem_tasks"
-require "rake/testtask"
-require "fileutils"
+require "rspec/core/rake_task"
 
-# Track files created during test setup
-CREATED_FILES_MARKER = ".test_created_files"
-PRODUCT_SERVICES_DIR = "test/dummy/app/services/product"
-
-# Service file templates
-SERVICE_TEMPLATES = {
-  "create_service.rb" => <<~RUBY,
-    # frozen_string_literal: true
-
-    class Product::CreateService < BetterService::Services::CreateService
-      # Schema for validating params
-      schema do
-        required(:name).filled(:string)
-        required(:price).filled(:decimal, gt?: 0)
-        optional(:published).filled(:bool)
-      end
-
-      # Phase 1: Search - Prepare dependencies (optional)
-      search_with do
-        {}
-      end
-
-      # Phase 2: Process - Create the resource
-      process_with do |data|
-        product = user.products.create!(params)
-        { resource: product }
-      end
-
-      # Phase 4: Respond - Format response (optional override)
-      respond_with do |data|
-        success_result("Product created successfully", data)
-      end
-    end
-  RUBY
-  "index_service.rb" => <<~RUBY,
-    # frozen_string_literal: true
-
-    class Product::IndexService < BetterService::Services::IndexService
-      # Schema for validating params
-      schema do
-        optional(:page).filled(:integer, gteq?: 1)
-        optional(:per_page).filled(:integer, gteq?: 1, lteq?: 100)
-        optional(:search).maybe(:string)
-      end
-
-      # Phase 1: Search - Load raw data
-      search_with do
-        products = user.products
-        products = products.where("name LIKE ?", "%\#{params[:search]}%") if params[:search].present?
-
-        { items: products.to_a }
-      end
-
-      # Phase 2: Process - Transform and aggregate data
-      process_with do |data|
-        {
-          items: data[:items],
-          metadata: {
-            stats: {
-              total: data[:items].count
-            },
-            pagination: {
-              page: params[:page] || 1,
-              per_page: params[:per_page] || 25
-            }
-          }
-        }
-      end
-
-      # Phase 4: Respond - Format response (optional override)
-      respond_with do |data|
-        success_result("Products loaded successfully", data)
-      end
-    end
-  RUBY
-  "show_service.rb" => <<~RUBY,
-    # frozen_string_literal: true
-
-    class Product::ShowService < BetterService::Services::ShowService
-      # Schema for validating params
-      schema do
-        required(:id).filled
-      end
-
-      # Phase 1: Search - Load the resource
-      search_with do
-        { resource: user.products.find(params[:id]) }
-      end
-
-      # Phase 4: Respond - Format response (optional override)
-      respond_with do |data|
-        success_result("Product loaded successfully", data)
-      end
-    end
-  RUBY
-  "update_service.rb" => <<~RUBY,
-    # frozen_string_literal: true
-
-    class Product::UpdateService < BetterService::Services::UpdateService
-      # Schema for validating params
-      schema do
-        required(:id).filled
-      end
-
-      # Phase 1: Search - Load the resource
-      search_with do
-        { resource: user.products.find(params[:id]) }
-      end
-
-      # Phase 2: Process - Update the resource
-      process_with do |data|
-        product = data[:resource]
-        product.update!(params.except(:id))
-        { resource: product }
-      end
-
-      # Phase 4: Respond - Format response (optional override)
-      respond_with do |data|
-        success_result("Product updated successfully", data)
-      end
-    end
-  RUBY
-  "destroy_service.rb" => <<~RUBY
-    # frozen_string_literal: true
-
-    class Product::DestroyService < BetterService::Services::DestroyService
-      # Schema for validating params
-      schema do
-        required(:id).filled
-      end
-
-      # Phase 1: Search - Load the resource
-      search_with do
-        { resource: user.products.find(params[:id]) }
-      end
-
-      # Phase 2: Process - Delete the resource
-      process_with do |data|
-        product = data[:resource]
-        product.destroy!
-        { resource: product }
-      end
-
-      # Phase 4: Respond - Format response (optional override)
-      respond_with do |data|
-        success_result("Product deleted successfully", data)
-      end
-    end
-  RUBY
-}
-
-namespace :test do
-  desc "Setup test environment - create missing Product service files"
-  task :setup do
-    created_files = []
-
-    SERVICE_TEMPLATES.each do |filename, content|
-      filepath = File.join(PRODUCT_SERVICES_DIR, filename)
-
-      unless File.exist?(filepath)
-        puts "Creating temporary test file: #{filepath}"
-        File.write(filepath, content)
-        created_files << filepath
-      end
-    end
-
-    # Save list of created files
-    File.write(CREATED_FILES_MARKER, created_files.join("\n")) if created_files.any?
-    puts "Test setup complete (#{created_files.size} files created)" if created_files.any?
-  end
-
-  desc "Cleanup test environment - remove temporary Product service files"
-  task :cleanup do
-    if File.exist?(CREATED_FILES_MARKER)
-      created_files = File.read(CREATED_FILES_MARKER).split("\n")
-
-      created_files.each do |filepath|
-        if File.exist?(filepath)
-          puts "Removing temporary test file: #{filepath}"
-          File.delete(filepath)
-        end
-      end
-
-      File.delete(CREATED_FILES_MARKER)
-      puts "Test cleanup complete (#{created_files.size} files removed)" if created_files.any?
-    end
-  end
-end
-
-Rake::TestTask.new(:test_only) do |t|
-  t.libs << "test"
-  t.test_files = FileList["test/**/*_test.rb"].exclude(
-    "test/dummy/**/*",
-    "test/generators/**/*"  # Generator tests require Rails context - run manually with: bundle exec ruby -Itest test/generators/*_test.rb
-  )
-  t.verbose = false
-end
-
-# Main test task with automatic setup and cleanup
-task :test do
-  begin
-    Rake::Task["test:setup"].invoke
-    Rake::Task["test_only"].invoke
-  ensure
-    Rake::Task["test:cleanup"].invoke
-  end
+# Default task runs RSpec
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.exclude_pattern = "spec/rails_app/**/*"
 end
 
-task default: :test
+task default: :spec
+task test: :spec

data/config/locales/better_service.en.yml

@@ -21,6 +21,7 @@ en:
     services:
       # Default success messages for standard CRUD operations
       default:
+        # Success messages
         created: "Resource created successfully"
         updated: "Resource updated successfully"
         deleted: "Resource deleted successfully"
@@ -28,6 +29,20 @@ en:
         shown: "Resource retrieved successfully"
         action_completed: "Action completed successfully"
 
+        # Structured success messages for new tuple format
+        index:
+          success: "Resources retrieved successfully"
+        show:
+          success: "Resource retrieved successfully"
+        create:
+          success: "Resource created successfully"
+          failure: "Failed to create resource"
+        update:
+          success: "Resource updated successfully"
+          failure: "Failed to update resource"
+        destroy:
+          success: "Resource deleted successfully"
+
       # Default error messages
       errors:
         validation_failed: "Validation failed"

data/lib/better_service/cache_service.rb

@@ -89,7 +89,7 @@ module BetterService
       #   contexts_for('unknown')   # => ['unknown']
       def contexts_to_invalidate(context)
         context_str = context.to_s
-        (@invalidation_map || {})[context_str] || [context_str]
+        (@invalidation_map || {})[context_str] || [ context_str ]
       end
 
       # Invalidate cache for a specific context and user
@@ -121,7 +121,7 @@ module BetterService
         return 0 unless user && context && !context.to_s.strip.empty?
 
         # Get all contexts to invalidate (cascading or single)
-        contexts = cascade ? contexts_to_invalidate(context) : [context.to_s]
+        contexts = cascade ? contexts_to_invalidate(context) : [ context.to_s ]
         total_deleted = 0
 
         contexts.each do |ctx|
@@ -164,7 +164,7 @@ module BetterService
         return 0 unless context && !context.to_s.strip.empty?
 
         # Get all contexts to invalidate (cascading or single)
-        contexts = cascade ? contexts_to_invalidate(context) : [context.to_s]
+        contexts = cascade ? contexts_to_invalidate(context) : [ context.to_s ]
         total_deleted = 0
 
         contexts.each do |ctx|
@@ -352,7 +352,7 @@ module BetterService
         # Escape special regex characters except *
         escaped = Regexp.escape(pattern.to_s)
         # Replace escaped \* with .* for regex matching
-        regex_string = escaped.gsub('\*', '.*')
+        regex_string = escaped.gsub('\*', ".*")
         Regexp.new(regex_string)
       end
 

data/lib/better_service/concerns/instrumentation.rb

@@ -55,11 +55,27 @@ module BetterService
                 result = call_without_instrumentation
                 duration = ((Time.current - start_time) * 1000).round(2) # milliseconds
 
-                # Publish service.completed event
-                completion_payload = build_completion_payload(
-                  service_name, user_id, result, duration
-                )
-                ActiveSupport::Notifications.instrument("service.completed", completion_payload)
+                # Validate that result is a BetterService::Result object
+                unless result.is_a?(BetterService::Result)
+                  raise BetterService::Errors::Runtime::InvalidResultError.new(
+                    "Service #{service_name} must return BetterService::Result, got #{result.class}",
+                    context: { service: service_name, result_class: result.class.name }
+                  )
+                end
+
+                if result.failure?
+                  # Publish service.failed event for Result failures
+                  failure_payload = build_result_failure_payload(
+                    service_name, user_id, result, duration
+                  )
+                  ActiveSupport::Notifications.instrument("service.failed", failure_payload)
+                else
+                  # Publish service.completed event
+                  completion_payload = build_completion_payload(
+                    service_name, user_id, result, duration
+                  )
+                  ActiveSupport::Notifications.instrument("service.completed", completion_payload)
+                end
 
                 result
               rescue => error
@@ -130,7 +146,7 @@ module BetterService
       #
       # @param service_name [String] Name of service class
       # @param user_id [Integer, String, nil] User ID
-      # @param result [Object] Service result
+      # @param result [BetterService::Result] Service result
       # @param duration [Float] Execution duration in milliseconds
       # @return [Hash] Event payload
       def build_completion_payload(service_name, user_id, result, duration)
@@ -152,14 +168,43 @@ module BetterService
           payload[:result] = result
         end
 
-        # Include cache metadata if available
-        if result.is_a?(Hash)
-          if result.key?(:cache_hit)
-            payload[:cache_hit] = result[:cache_hit]
-          end
-          if result.key?(:cache_key)
-            payload[:cache_key] = result[:cache_key]
-          end
+        # Include cache metadata if available from Result meta
+        if result.meta[:cache_hit]
+          payload[:cache_hit] = result.meta[:cache_hit]
+        end
+        if result.meta[:cache_key]
+          payload[:cache_key] = result.meta[:cache_key]
+        end
+
+        payload
+      end
+
+      # Build payload for service.failed event from Result object
+      #
+      # @param service_name [String] Name of service class
+      # @param user_id [Integer, String, nil] User ID
+      # @param result [BetterService::Result] Result object with failure
+      # @param duration [Float] Execution duration in milliseconds
+      # @return [Hash] Event payload
+      def build_result_failure_payload(service_name, user_id, result, duration)
+        payload = {
+          service_name: service_name,
+          user_id: user_id,
+          duration: duration,
+          timestamp: Time.current.iso8601,
+          success: false,
+          error_class: result.meta[:error_code]&.to_s || "UnknownError",
+          error_message: result.message || "Service failed"
+        }
+
+        # Include params if configured and available
+        if BetterService.configuration.instrumentation_include_args && respond_to?(:params, true)
+          payload[:params] = send(:params)
+        end
+
+        # Include validation errors if present
+        if result.validation_errors
+          payload[:validation_errors] = result.validation_errors
         end
 
         payload

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

@@ -3,7 +3,7 @@
 module BetterService
   module Concerns
     module Serviceable
-      # Authorizable adds authorization support to services.
+    # Authorizable adds authorization support to services.
     #
     # Use the `authorize_with` DSL to define authorization logic that runs
     # BEFORE the search phase (fail fast principle).