better_service 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26d2fc11e6f3151030f88f3a82fbcac4e08fd056809099f82046a8e8f6a24bcd
-  data.tar.gz: eca9dd6ea5cf3bc365eb25af7a46837906cc0fe67225742ef1d6cbaada77650c
+  metadata.gz: 622ac1a705ab117672d0e9c4896e65b66585c747023d1e00b34824e9c35606a0
+  data.tar.gz: f4c6f5b6ae7baaa3f61eeb123d4a2a493a7c8acc2ff835c6891396ed543efa1c
 SHA512:
-  metadata.gz: 66f920ce24ec9b96e32a83ee4ec4a20652be82d92abd98434cfe8fce6e59017fc5192ed98ad34752af42f6465fa9e4d5aa3a5aa53195ed23307a88b915773767
-  data.tar.gz: 645b218a1fc1166f35b60b829f4c417b31c82f41710dd89aa251f28f6337956f9e35b100438819486014482f0706a7c175b398d65926c32cbe0c90393f741d77
+  metadata.gz: d4f06ae88607c9d4b6eec865811abbba0f80403914fbcac556ad3949a395ff0b43e16e6663c652959cc950fcb89d64be427eb6e8c20b19ed0aa6b1771012e7b0
+  data.tar.gz: d1a69946471e0e2f5bd7067889c4f675d0ea94a198d69f9e877283fa5166664f49283a45fd52f282288b690670a6d095f562935f3503c86dce81633d03858e74

data/LICENSE

@@ -0,0 +1,13 @@
+DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                Version 2, December 2004
+
+Copyright (C) 2025 alessiobussolari <alessio@cosmic.tech>
+
+Everyone is permitted to copy and distribute verbatim or modified
+copies of this license document, and changing it is allowed as long
+as the name is changed.
+
+        DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -5,7 +5,7 @@
 ### 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-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![License](https://img.shields.io/badge/license-WTFPL-blue.svg)](http://www.wtfpl.net/about/)
 
 [Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Usage](#-usage) • [Error Handling](#%EF%B8%8F-error-handling) • [Examples](#-examples)
 
@@ -23,9 +23,13 @@ BetterService is a comprehensive Service Objects framework for Rails that brings
 - 🔐 **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
 - 💾 **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
-- 🏗️ **Powerful Generators**: 8 generators for rapid scaffolding (scaffold, index, show, create, update, destroy, action, workflow)
+- 🌲 **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
 - 🎨 **DSL-Based**: Clean, expressive DSL with `search_with`, `process_with`, `authorize_with`, etc.
 
@@ -95,9 +99,9 @@ Comprehensive guides and examples are available in the `/docs` directory:
 
 ### 🎓 Guides
 
-- **[Getting Started](docs/getting-started.md)** - Installation, core concepts, your first service
-- **[Service Types](docs/service-types.md)** - Deep dive into all 6 service types (Index, Show, Create, Update, Destroy, Action)
-- **[Concerns Reference](docs/concerns-reference.md)** - Complete reference for all 8 concerns (Validatable, Authorizable, Cacheable, etc.)
+- **[Getting Started](docs/start/getting-started.md)** - Installation, core concepts, your first service
+- **[Service Types](docs/services/01_services_structure.md)** - Deep dive into all 6 service types (Index, Show, Create, Update, Destroy, Action)
+- **[Concerns Reference](docs/concerns-reference.md)** - Complete reference for all 7 concerns (Validatable, Authorizable, Cacheable, etc.)
 
 ### 💡 Examples
 
@@ -105,7 +109,7 @@ Comprehensive guides and examples are available in the `/docs` directory:
 
 ### 🔧 Configuration
 
-See `config/initializers/better_service.rb` for all configuration options including:
+See **[Configuration Guide](docs/start/configuration.md)** for all options including:
 - Instrumentation & Observability
 - Built-in LogSubscriber and StatsSubscriber
 - Cache configuration
@@ -868,9 +872,241 @@ The CacheService works with any Rails cache store, but pattern-based deletion (`
 
 ---
 
+## 🔄 Auto-Invalidation Cache
+
+Write operations (Create/Update/Destroy) can automatically invalidate cache after successful execution.
+
+### How It Works
+
+Auto-invalidation is **enabled by default** for Create, Update, and Destroy services when cache contexts are defined:
+
+```ruby
+class Products::CreateService < BetterService::Services::CreateService
+  cache_contexts :products, :homepage
+
+  # Cache is automatically invalidated for these contexts after create!
+  # No need to call invalidate_cache_for manually
+end
+```
+
+When the service completes successfully:
+1. The product is created/updated/deleted
+2. Cache is automatically invalidated for all defined contexts
+3. All cache keys matching the patterns are cleared
+
+### Disabling Auto-Invalidation
+
+Control auto-invalidation with the `auto_invalidate_cache` DSL:
+
+```ruby
+class Products::CreateService < BetterService::Services::CreateService
+  cache_contexts :products
+  auto_invalidate_cache false  # Disable automatic invalidation
+
+  process_with do |data|
+    product = user.products.create!(params)
+
+    # Manual control: only invalidate for featured products
+    invalidate_cache_for(user) if product.featured?
+
+    { resource: product }
+  end
+end
+```
+
+### Async Invalidation
+
+Combine with async option for non-blocking cache invalidation:
+
+```ruby
+class Products::CreateService < BetterService::Services::CreateService
+  cache_contexts :products, :homepage
+
+  # Auto-invalidation happens async via ActiveJob
+  cache_async true
+end
+```
+
+**Note**: Auto-invalidation only applies to Create, Update, and Destroy services. Index and Show services don't trigger cache invalidation since they're read-only operations.
+
+---
+
+## 🌍 Internationalization (I18n)
+
+BetterService includes built-in I18n support for service messages with automatic fallback.
+
+### Using the message() Helper
+
+All service templates use the `message()` helper for response messages:
+
+```ruby
+class Products::CreateService < BetterService::Services::CreateService
+  respond_with do |data|
+    success_result(message("create.success"), data)
+  end
+end
+```
+
+### Default Messages
+
+BetterService ships with English defaults in `config/locales/better_service.en.yml`:
+
+```yaml
+en:
+  better_service:
+    services:
+      default:
+        created: "Resource created successfully"
+        updated: "Resource updated successfully"
+        deleted: "Resource deleted successfully"
+        listed: "Resources retrieved successfully"
+        shown: "Resource retrieved successfully"
+```
+
+### Custom Messages
+
+Generate custom locale files for your services:
+
+```bash
+rails generate better_service:locale products
+```
+
+This creates `config/locales/products_services.en.yml`:
+
+```yaml
+en:
+  products:
+    services:
+      create:
+        success: "Product created and added to inventory"
+      update:
+        success: "Product updated successfully"
+      destroy:
+        success: "Product removed from catalog"
+```
+
+Then configure the namespace in your service:
+
+```ruby
+class Products::CreateService < BetterService::Services::CreateService
+  messages_namespace :products
+
+  respond_with do |data|
+    # Uses products.services.create.success
+    success_result(message("create.success"), data)
+  end
+end
+```
+
+### Fallback Chain
+
+Messages follow a 3-level fallback:
+1. Custom namespace (e.g., `products.services.create.success`)
+2. BetterService defaults (e.g., `better_service.services.default.created`)
+3. Key itself (e.g., `"create.success"`)
+
+### Message Interpolations
+
+Pass dynamic values to messages:
+
+```ruby
+respond_with do |data|
+  success_result(
+    message("create.success", product_name: data[:resource].name),
+    data
+  )
+end
+```
+
+**Locale file:**
+```yaml
+en:
+  products:
+    services:
+      create:
+        success: "Product '%{product_name}' created successfully"
+```
+
+---
+
+## 🎨 Presenter System
+
+BetterService includes an optional presenter layer for formatting data for API/view consumption.
+
+### Creating Presenters
+
+Generate a presenter class:
+
+```bash
+rails generate better_service:presenter Product
+```
+
+This creates:
+- `app/presenters/product_presenter.rb`
+- `test/presenters/product_presenter_test.rb`
+
+```ruby
+class ProductPresenter < BetterService::Presenter
+  def as_json(opts = {})
+    {
+      id: object.id,
+      name: object.name,
+      price: object.price,
+      display_name: "#{object.name} - $#{object.price}",
+
+      # Conditional fields based on user permissions
+      **(admin_fields if current_user&.admin?)
+    }
+  end
+
+  private
+
+  def admin_fields
+    {
+      cost: object.cost,
+      margin: object.price - object.cost
+    }
+  end
+end
+```
+
+### Using Presenters in Services
+
+Configure presenters via the `presenter` DSL:
+
+```ruby
+class Products::IndexService < BetterService::Services::IndexService
+  presenter ProductPresenter
+
+  presenter_options do
+    { current_user: user }
+  end
+
+  # Items are automatically formatted via ProductPresenter#as_json
+end
+```
+
+### Presenter Features
+
+**Available Methods:**
+- `object` - The resource being presented
+- `options` - Options hash passed via `presenter_options`
+- `current_user` - Shortcut for `options[:current_user]`
+- `as_json(opts)` - Format object as JSON
+- `to_json(opts)` - Serialize to JSON string
+- `to_h` - Alias for `as_json`
+
+**Example with scaffold:**
+```bash
+# Generate services + presenter in one command
+rails generate serviceable:scaffold Product --presenter
+```
+
+---
+
 ## 🏗️ Generators
 
-BetterService includes 8 powerful generators:
+BetterService includes 10 powerful generators:
 
 ### Scaffold Generator
 
@@ -878,6 +1114,9 @@ Generates all 5 CRUD services at once:
 
 ```bash
 rails generate serviceable:scaffold Product
+
+# With presenter
+rails generate serviceable:scaffold Product --presenter
 ```
 
 Creates:
@@ -886,23 +1125,16 @@ Creates:
 - `app/services/product/create_service.rb`
 - `app/services/product/update_service.rb`
 - `app/services/product/destroy_service.rb`
+- (Optional) `app/presenters/product_presenter.rb` with `--presenter`
 
 ### Individual Generators
 
 ```bash
-# Index service
+# CRUD Services
 rails generate serviceable:index Product
-
-# Show service
 rails generate serviceable:show Product
-
-# Create service
 rails generate serviceable:create Product
-
-# Update service
 rails generate serviceable:update Product
-
-# Destroy service
 rails generate serviceable:destroy Product
 
 # Custom action service
@@ -910,6 +1142,12 @@ rails generate serviceable:action Product publish
 
 # Workflow for composing services
 rails generate serviceable:workflow OrderPurchase --steps create_order charge_payment
+
+# Presenter for data transformation
+rails generate better_service:presenter Product
+
+# Custom locale file for I18n messages
+rails generate better_service:locale products
 ```
 
 ---
@@ -1302,13 +1540,13 @@ ActiveSupport::Notifications.subscribe("service.completed") do |name, start, fin
 end
 ```
 
-See [Configuration](docs/getting-started.md#configuration) for more details.
+See [Configuration Guide](docs/start/configuration.md) for more details.
 
 ---
 
 ## 📄 License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [WTFPL License](http://www.wtfpl.net/about/).
 
 ---
 

data/Rakefile

@@ -2,14 +2,214 @@ require "bundler/setup"
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "fileutils"
 
-Rake::TestTask.new(:test) do |t|
+# 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/**/*"
+    "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
+end
+
 task default: :test

data/config/locales/better_service.en.yml

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# BetterService Default Locale File (English)
+#
+# This file contains default messages for BetterService operations.
+# These messages are used as fallbacks when services don't define
+# their own custom messages via the message() helper.
+#
+# To override messages for a specific namespace:
+# 1. Define a namespace with messages_namespace in your service
+# 2. Create locale entries under that namespace
+#
+# Example:
+#   products:
+#     services:
+#       create:
+#         success: "Product created successfully"
+
+en:
+  better_service:
+    services:
+      # Default success messages for standard CRUD operations
+      default:
+        created: "Resource created successfully"
+        updated: "Resource updated successfully"
+        deleted: "Resource deleted successfully"
+        listed: "Resources retrieved successfully"
+        shown: "Resource retrieved successfully"
+        action_completed: "Action completed successfully"
+
+      # Default error messages
+      errors:
+        validation_failed: "Validation failed"
+        unauthorized: "You are not authorized to perform this action"
+        not_found: "Resource not found"
+        database_error: "A database error occurred"
+        execution_error: "An error occurred while processing your request"

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

@@ -18,11 +18,54 @@ module BetterService
 
       private
 
+      # Get translated message with fallback support
+      #
+      # Lookup order:
+      # 1. Custom namespace: "#{namespace}.services.#{key_path}"
+      # 2. Default namespace: "better_service.services.default.#{action}"
+      # 3. Key itself as final fallback
+      #
+      # @param key_path [String] Message key path (e.g., "create.success")
+      # @param interpolations [Hash] Variables to interpolate
+      # @return [String] Translated message
       def message(key_path, interpolations = {})
-        return key_path if self.class._messages_namespace.nil?
+        # If no namespace defined, use default BetterService messages
+        if self.class._messages_namespace.nil?
+          # Extract action from key_path (e.g., "create.success" -> "created")
+          action = extract_action_from_key(key_path)
+          default_key = "better_service.services.default.#{action}"
+          return I18n.t(default_key, default: key_path, **interpolations)
+        end
 
+        # Try custom namespace first, fallback to default, then to key itself
         full_key = "#{self.class._messages_namespace}.services.#{key_path}"
-        I18n.t(full_key, **interpolations)
+        action = extract_action_from_key(key_path)
+        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)
+      end
+
+      # Extract action name from key path for fallback lookup
+      #
+      # Examples:
+      #   "create.success" -> "created"
+      #   "update.success" -> "updated"
+      #   "destroy.success" -> "deleted"
+      #   "custom_action" -> "action_completed"
+      #
+      # @param key_path [String] Full key path
+      # @return [String] Action name for default messages
+      def extract_action_from_key(key_path)
+        # Handle common patterns
+        case key_path
+        when /create/i then "created"
+        when /update/i then "updated"
+        when /destroy|delete/i then "deleted"
+        when /index|list/i then "listed"
+        when /show/i then "shown"
+        else "action_completed"
+        end
       end
     end
     end