better_service 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26d2fc11e6f3151030f88f3a82fbcac4e08fd056809099f82046a8e8f6a24bcd
-  data.tar.gz: eca9dd6ea5cf3bc365eb25af7a46837906cc0fe67225742ef1d6cbaada77650c
+  metadata.gz: c796a9b8cd27afc4ae26e29b42decb8a606d88d0fdd6158b8599766cfa33df48
+  data.tar.gz: afdee95a722f85f08c919243b5ff8da37adb211b4d7b1dd3ba7a334e97d3b2f6
 SHA512:
-  metadata.gz: 66f920ce24ec9b96e32a83ee4ec4a20652be82d92abd98434cfe8fce6e59017fc5192ed98ad34752af42f6465fa9e4d5aa3a5aa53195ed23307a88b915773767
-  data.tar.gz: 645b218a1fc1166f35b60b829f4c417b31c82f41710dd89aa251f28f6337956f9e35b100438819486014482f0706a7c175b398d65926c32cbe0c90393f741d77
+  metadata.gz: 5fb831ec7c495b453b0915c33427080012faac9aa870919d7e0e30303251fd477c9309ccfb0e8c6e257d36fe45b9c03f7af7445290641f4af898d6f62ab5c800
+  data.tar.gz: f34a008657a3f9208c220d286f3c33201daadac7a7114c729d97e3a5734574907cce3ce0fc85c6ea6964ab8339266be0b31d9c6f67a5211d0eb1c7b7ff18a176

data/README.md

@@ -23,9 +23,12 @@ 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)
+- 🏗️ **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 +98,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 +108,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 +871,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 +1113,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 +1124,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 +1141,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,7 +1539,7 @@ 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.
 
 ---
 

data/Rakefile

@@ -7,7 +7,7 @@ Rake::TestTask.new(:test) 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

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

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

@@ -10,7 +10,6 @@ module BetterService
 
         included do
           class_attribute :_schema, default: nil
-          attr_reader :validation_errors
         end
 
         class_methods do
@@ -23,10 +22,6 @@ module BetterService
           end
         end
 
-        def valid?
-          @validation_errors.empty?
-        end
-
         private
 
         def validate_params!

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

@@ -20,22 +20,6 @@ module BetterService
 
       private
 
-      # Override respond to add viewer phase
-      def respond(data)
-        # Get base result from parent respond
-        if self.class._respond_block
-          result = instance_exec(data, &self.class._respond_block)
-        else
-          result = success_result("Operation completed successfully", data)
-        end
-
-        # Add viewer if enabled
-        return result unless viewer_enabled?
-
-        view_config = execute_viewer(data, data, result)
-        result.merge(view: view_config)
-      end
-
       def viewer_enabled?
         self.class._viewer_enabled && self.class._viewer_block.present?
       end

data/lib/better_service/presenter.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module BetterService
+  # Presenter - Base class for presenting service data
+  #
+  # Presenters transform raw model data into view-friendly formats.
+  # They are typically used with the Presentable concern's presenter DSL.
+  #
+  # Example:
+  #   class ProductPresenter < BetterService::Presenter
+  #     def as_json(opts = {})
+  #       {
+  #         id: object.id,
+  #         name: object.name,
+  #         price_formatted: "$#{object.price}",
+  #         available: object.stock > 0,
+  #         # Conditional fields based on current user
+  #         **(admin_fields if current_user&.admin?)
+  #       }
+  #     end
+  #
+  #     private
+  #
+  #     def admin_fields
+  #       {
+  #         cost: object.cost,
+  #         margin: object.price - object.cost
+  #       }
+  #     end
+  #   end
+  #
+  # Usage with services:
+  #   class Products::IndexService < IndexService
+  #     presenter ProductPresenter
+  #
+  #     presenter_options do
+  #       { current_user: user }
+  #     end
+  #
+  #     search_with do
+  #       { items: Product.all.to_a }
+  #     end
+  #   end
+  class Presenter
+    attr_reader :object, :options
+
+    # Initialize presenter
+    #
+    # @param object [Object] The object to present (e.g., ActiveRecord model)
+    # @param options [Hash] Additional options (e.g., current_user, permissions)
+    def initialize(object, **options)
+      @object = object
+      @options = options
+    end
+
+    # Override in subclass to define JSON representation
+    #
+    # @param opts [Hash] JSON serialization options
+    # @return [Hash] Hash representation of the object
+    def as_json(opts = {})
+      # Default implementation delegates to object
+      if object.respond_to?(:as_json)
+        object.as_json(opts)
+      else
+        { data: object }
+      end
+    end
+
+    # JSON string representation
+    #
+    # @param opts [Hash] JSON serialization options
+    # @return [String] JSON string
+    def to_json(opts = {})
+      as_json(opts).to_json
+    end
+
+    # Hash representation (alias for as_json)
+    #
+    # @return [Hash] Hash representation
+    def to_h
+      as_json
+    end
+
+    private
+
+    # Get current user from options
+    #
+    # @return [Object, nil] Current user if provided in options
+    def current_user
+      options[:current_user]
+    end
+
+    # Check if a field should be included based on options
+    #
+    # Useful for selective field rendering based on client requests.
+    #
+    # @param field [Symbol, String] Field name to check
+    # @return [Boolean] Whether field should be included
+    #
+    # @example
+    #   # In service:
+    #   presenter_options do
+    #     { fields: params[:fields]&.split(',')&.map(&:to_sym) }
+    #   end
+    #
+    #   # In presenter:
+    #   def as_json(opts = {})
+    #     {
+    #       id: object.id,
+    #       name: object.name,
+    #       **(expensive_data if include_field?(:details))
+    #     }
+    #   end
+    def include_field?(field)
+      return true unless options[:fields]
+
+      options[:fields].include?(field.to_sym)
+    end
+
+    # Check if current user has a specific role/permission
+    #
+    # @param role [Symbol, String] Role to check
+    # @return [Boolean] Whether user has the role
+    def user_can?(role)
+      return false unless current_user
+      return false unless current_user.respond_to?(:has_role?)
+
+      current_user.has_role?(role)
+    end
+  end
+end

data/lib/better_service/railtie.rb

@@ -1,6 +1,23 @@
 if defined?(Rails)
   module BetterService
     class Railtie < ::Rails::Railtie
+      # Initialize subscribers after Rails boots
+      #
+      # This hook runs after all initializers have been executed,
+      # ensuring BetterService.configuration is fully loaded.
+      config.after_initialize do
+        # Attach LogSubscriber if enabled in configuration
+        if BetterService.configuration.log_subscriber_enabled
+          BetterService::Subscribers::LogSubscriber.attach
+          Rails.logger.info "[BetterService] LogSubscriber attached" if Rails.logger
+        end
+
+        # Attach StatsSubscriber if enabled in configuration
+        if BetterService.configuration.stats_subscriber_enabled
+          BetterService::Subscribers::StatsSubscriber.attach
+          Rails.logger.info "[BetterService] StatsSubscriber attached" if Rails.logger
+        end
+      end
     end
   end
 end