better_service 1.0.0 → 1.0.1

data/lib/better_service/services/base.rb

@@ -19,6 +19,7 @@ module BetterService
     class_attribute :_process_block, default: nil
     class_attribute :_transform_block, default: nil
     class_attribute :_respond_block, default: nil
+    class_attribute :_auto_invalidate_cache, default: false
 
     include Concerns::Serviceable::Messageable
     include Concerns::Serviceable::Validatable
@@ -41,11 +42,29 @@ module BetterService
       validate_schema_presence!
       @user = user
       @params = safe_params_to_hash(params)
-      @validation_errors = {}
       validate_params!
     end
 
     # DSL methods to define phase blocks
+
+    # Configure whether this service allows nil user
+    #
+    # @param value [Boolean] Whether to allow nil user (default: true)
+    # @return [void]
+    #
+    # @example Allow nil user
+    #   class PublicService < BetterService::Services::Base
+    #     allow_nil_user true
+    #   end
+    #
+    # @example Require user (default)
+    #   class PrivateService < BetterService::Services::Base
+    #     allow_nil_user false
+    #   end
+    def self.allow_nil_user(value = true)
+      self._allow_nil_user = value
+    end
+
     def self.search_with(&block)
       self._search_block = block
     end
@@ -62,6 +81,31 @@ module BetterService
       self._respond_block = block
     end
 
+    # Configure automatic cache invalidation after write operations
+    #
+    # @param enabled [Boolean] Whether to automatically invalidate cache (default: true)
+    # @return [void]
+    #
+    # @example Enable automatic cache invalidation (default for Create/Update/Destroy)
+    #   class Products::CreateService < CreateService
+    #     cache_contexts :products, :category_products
+    #     # Cache is automatically invalidated after successful create
+    #   end
+    #
+    # @example Disable automatic cache invalidation
+    #   class Products::CreateService < CreateService
+    #     auto_invalidate_cache false
+    #
+    #     process_with do |data|
+    #       product = Product.create!(params)
+    #       invalidate_cache_for(user) if should_invalidate?  # Manual control
+    #       { resource: product }
+    #     end
+    #   end
+    def self.auto_invalidate_cache(enabled = true)
+      self._auto_invalidate_cache = enabled
+    end
+
     # Main entry point - executes the 5-phase flow
     def call
       # Validation already raises ValidationError in initialize
@@ -70,6 +114,12 @@ module BetterService
 
       data = search
       processed = process(data)
+
+      # Auto-invalidate cache after write operations if configured
+      if should_auto_invalidate_cache?
+        invalidate_cache_for(user)
+      end
+
       transformed = transform(processed)
       result = respond(transformed)
 
@@ -117,7 +167,33 @@ module BetterService
 
     # Phase 3: Transform - Handled by Presentable concern
 
-    # Phase 4: Respond - Handled by Viewable concern
+    # Phase 4: Respond - Format response (override in service types or with respond_with block)
+    def respond(data)
+      if self.class._respond_block
+        instance_exec(data, &self.class._respond_block)
+      else
+        success_result("Operation completed successfully", data)
+      end
+    end
+
+    # Check if cache should be automatically invalidated
+    #
+    # 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)
+    #
+    # @return [Boolean] Whether cache should be invalidated
+    def should_auto_invalidate_cache?
+      return false unless self.class._auto_invalidate_cache
+      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)
+    end
 
     # Error handlers for runtime errors
     #
@@ -222,25 +298,6 @@ module BetterService
       }
     end
 
-    def failure_result(message, errors = {}, code: nil)
-      result = {
-        success: false,
-        error: message,
-        errors: errors
-      }
-      result[:code] = code if code
-      result
-    end
-
-    def error_result(message, code: nil)
-      result = {
-        success: false,
-        errors: [message]
-      }
-      result[:code] = code if code
-      result
-    end
-
     # Prepend Instrumentation at the end, after call method is defined
     # This wraps the entire call method (including cache logic from Cacheable)
     prepend Concerns::Instrumentation

data/lib/better_service/services/create_service.rb

@@ -34,6 +34,9 @@ module BetterService
     # Enable database transactions by default for create operations
     with_transaction true
 
+    # Enable automatic cache invalidation for create operations
+    self._auto_invalidate_cache = true
+
     # Default empty schema - subclasses MUST override with specific validations
     schema do
       # Override in subclass with required fields

data/lib/better_service/services/destroy_service.rb

@@ -31,6 +31,9 @@ module BetterService
     # Enable database transactions by default for destroy operations
     with_transaction true
 
+    # Enable automatic cache invalidation for destroy operations
+    self._auto_invalidate_cache = true
+
     # Default schema - requires id parameter
     schema do
       required(:id).filled

data/lib/better_service/services/update_service.rb

@@ -32,6 +32,9 @@ module BetterService
     # Enable database transactions by default for update operations
     with_transaction true
 
+    # Enable automatic cache invalidation for update operations
+    self._auto_invalidate_cache = true
+
     # Default schema - requires id parameter
     schema do
       required(:id).filled

data/lib/better_service/subscribers/log_subscriber.rb

@@ -14,6 +14,11 @@ module BetterService
     #   end
     class LogSubscriber
       class << self
+        # Storage for ActiveSupport::Notifications subscriptions
+        #
+        # @return [Array<ActiveSupport::Notifications::Fanout::Subscriber>]
+        attr_reader :subscriptions
+
         # Attach the subscriber to ActiveSupport::Notifications
         #
         # This method is called automatically when subscriber is enabled.
@@ -21,25 +26,40 @@ module BetterService
         #
         # @return [void]
         def attach
+          @subscriptions ||= []
           subscribe_to_service_events
           subscribe_to_cache_events
         end
 
+        # Detach the subscriber from ActiveSupport::Notifications
+        #
+        # Removes all subscriptions. Useful for testing.
+        #
+        # @return [void]
+        def detach
+          if @subscriptions
+            @subscriptions.each do |subscription|
+              ActiveSupport::Notifications.unsubscribe(subscription)
+            end
+          end
+          @subscriptions = []
+        end
+
         private
 
         # Subscribe to service lifecycle events
         #
         # @return [void]
         def subscribe_to_service_events
-          ActiveSupport::Notifications.subscribe("service.started") do |name, start, finish, id, payload|
+          @subscriptions << ActiveSupport::Notifications.subscribe("service.started") do |name, start, finish, id, payload|
             log_service_started(payload)
           end
 
-          ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
+          @subscriptions << ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
             log_service_completed(payload)
           end
 
-          ActiveSupport::Notifications.subscribe("service.failed") do |name, start, finish, id, payload|
+          @subscriptions << ActiveSupport::Notifications.subscribe("service.failed") do |name, start, finish, id, payload|
             log_service_failed(payload)
           end
         end
@@ -48,11 +68,11 @@ module BetterService
         #
         # @return [void]
         def subscribe_to_cache_events
-          ActiveSupport::Notifications.subscribe("cache.hit") do |name, start, finish, id, payload|
+          @subscriptions << ActiveSupport::Notifications.subscribe("cache.hit") do |name, start, finish, id, payload|
             log_cache_hit(payload)
           end
 
-          ActiveSupport::Notifications.subscribe("cache.miss") do |name, start, finish, id, payload|
+          @subscriptions << ActiveSupport::Notifications.subscribe("cache.miss") do |name, start, finish, id, payload|
             log_cache_miss(payload)
           end
         end

data/lib/better_service/version.rb

@@ -1,3 +1,3 @@
 module BetterService
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/lib/better_service.rb

@@ -3,6 +3,7 @@ require "better_service/railtie"
 require "better_service/configuration"
 require "better_service/errors/better_service_error"
 require "better_service/cache_service"
+require "better_service/presenter"
 require "better_service/concerns/instrumentation"
 require "better_service/subscribers/log_subscriber"
 require "better_service/subscribers/stats_subscriber"

data/lib/generators/better_service/install_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterService
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate BetterService initializer with configuration options"
+
+      def create_initializer_file
+        template "better_service_initializer.rb.tt", "config/initializers/better_service.rb"
+      end
+
+      def copy_locale_file
+        # Copy from gem's config/locales to Rails app's config/locales
+        locale_source = File.expand_path("../../../config/locales/better_service.en.yml", __dir__)
+        copy_file locale_source, "config/locales/better_service.en.yml"
+      end
+
+      def display_readme
+        say
+        say "BetterService initializer created!", :green
+        say
+        say "Next steps:", :yellow
+        say "  1. Review config/initializers/better_service.rb"
+        say "  2. Enable instrumentation if needed"
+        say "  3. Configure logging and stats subscribers"
+        say
+        say "Documentation:", :cyan
+        say "  Getting Started: docs/start/getting-started.md"
+        say "  Configuration:   docs/start/configuration.md"
+        say
+      end
+    end
+  end
+end

data/lib/generators/better_service/locale_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module BetterService
+  module Generators
+    # LocaleGenerator - Generate I18n locale files for BetterService
+    #
+    # Usage:
+    #   rails generate better_service:locale products
+    #   rails generate better_service:locale bookings
+    #
+    # This generates config/locales/products_services.en.yml with scaffolded
+    # translations for common service actions (create, update, destroy, etc.)
+    class LocaleGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate I18n locale file for BetterService messages"
+
+      # Optional: specify which actions to include
+      class_option :actions,
+                   type: :array,
+                   default: %w[create update destroy index show],
+                   desc: "Actions to include in locale file"
+
+      def create_locale_file
+        template "locale.en.yml.tt", "config/locales/#{file_name.pluralize}_services.en.yml"
+      end
+
+      def display_info
+        say
+        say "Locale file created: config/locales/#{file_name.pluralize}_services.en.yml", :green
+        say
+        say "Usage in services:", :yellow
+        say "  class #{class_name.pluralize}::CreateService < CreateService"
+        say "    messages_namespace :#{file_name.pluralize}"
+        say "  end"
+        say
+        say "Then customize the messages in the locale file to your needs.", :cyan
+        say
+      end
+
+      private
+
+      def plural_name
+        file_name.pluralize
+      end
+
+      def actions_list
+        options[:actions]
+      end
+    end
+  end
+end

data/lib/generators/better_service/presenter_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module BetterService
+  module Generators
+    # PresenterGenerator - Generate presenter classes for BetterService
+    #
+    # Usage:
+    #   rails generate better_service:presenter Product
+    #   rails generate better_service:presenter Product name:string price:decimal
+    #
+    # This generates:
+    #   - app/presenters/product_presenter.rb
+    #   - test/presenters/product_presenter_test.rb
+    class PresenterGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a presenter class for BetterService"
+
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      def create_presenter_file
+        template "presenter.rb.tt", File.join("app/presenters", class_path, "#{file_name}_presenter.rb")
+      end
+
+      def create_test_file
+        template "presenter_test.rb.tt", File.join("test/presenters", class_path, "#{file_name}_presenter_test.rb")
+      end
+
+      def display_info
+        say
+        say "Presenter created: app/presenters/#{file_name}_presenter.rb", :green
+        say "Test created: test/presenters/#{file_name}_presenter_test.rb", :green
+        say
+        say "Usage in services:", :yellow
+        say "  class #{class_name.pluralize}::IndexService < IndexService"
+        say "    presenter #{class_name}Presenter"
+        say
+        say "    presenter_options do"
+        say "      { current_user: user }"
+        say "    end"
+        say "  end"
+        say
+        say "Customize the as_json method in the presenter to format your data.", :cyan
+        say
+      end
+
+      private
+
+      def presenter_class_name
+        "#{class_name}Presenter"
+      end
+
+      def attributes_list
+        attributes.map(&:name)
+      end
+    end
+  end
+end

data/lib/generators/better_service/templates/better_service_initializer.rb.tt

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# BetterService Configuration
+#
+# This file contains all available configuration options for BetterService.
+# Uncomment and modify the options you want to change from their defaults.
+#
+# For detailed documentation, see: docs/start/configuration.md
+
+BetterService.configure do |config|
+  # === Instrumentation Settings ===
+  #
+  # Enable/disable ActiveSupport::Notifications instrumentation globally.
+  # When disabled, no events will be published for any service.
+  #
+  # Default: true
+  # config.instrumentation_enabled = true
+
+  # Include service arguments in event payloads.
+  # Disable if arguments contain sensitive data (passwords, tokens, etc.)
+  #
+  # Default: true
+  # config.instrumentation_include_args = true
+
+  # Include service result in event payloads.
+  # Disable to reduce payload size or protect sensitive return values.
+  #
+  # Default: false
+  # config.instrumentation_include_result = false
+
+  # List of service class names to exclude from instrumentation.
+  # Useful for high-frequency services that would generate too many events.
+  #
+  # Default: []
+  # config.instrumentation_excluded_services = ["HealthCheckService", "MetricsService"]
+
+  # === Built-in Subscribers ===
+  #
+  # Enable the built-in log subscriber.
+  # When enabled, all service events are logged to Rails.logger.
+  #
+  # Default: false
+  # config.log_subscriber_enabled = true
+
+  # Log level for the built-in log subscriber.
+  # Valid values: :debug, :info, :warn, :error
+  #
+  # Default: :info
+  # config.log_subscriber_level = :info
+
+  # Enable the built-in stats subscriber.
+  # When enabled, statistics are collected for all service executions.
+  # Access stats with: BetterService::Subscribers::StatsSubscriber.stats
+  #
+  # Default: false
+  # config.stats_subscriber_enabled = true
+end
+
+# === Custom Subscribers ===
+#
+# You can subscribe to BetterService events for custom integrations:
+#
+# # DataDog integration
+# ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
+#   duration_ms = payload[:duration]
+#   service_name = payload[:service]
+#
+#   StatsD.increment("better_service.calls", tags: ["service:#{service_name}"])
+#   StatsD.histogram("better_service.duration", duration_ms, tags: ["service:#{service_name}"])
+# end
+#
+# # New Relic integration
+# ActiveSupport::Notifications.subscribe("service.failed") do |name, start, finish, id, payload|
+#   NewRelic::Agent.notice_error(
+#     payload[:error],
+#     custom_params: {
+#       service: payload[:service],
+#       duration: payload[:duration]
+#     }
+#   )
+# end
+#
+# Available events:
+# - service.started     - Service execution started
+# - service.completed   - Service completed successfully
+# - service.failed      - Service raised an exception
+# - cache.hit           - Cache hit for cacheable service
+# - cache.miss          - Cache miss for cacheable service
+#
+# See docs/advanced/instrumentation.md for detailed event payloads and examples.

data/lib/generators/better_service/templates/locale.en.yml.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# I18n translations for <%= class_name %> services
+#
+# These messages are used when services define:
+#   messages_namespace :<%= plural_name %>
+#
+# Fallback chain:
+#   1. <%= plural_name %>.services.{action}.{key}
+#   2. better_service.services.default.{action}
+#   3. Key itself
+
+en:
+  <%= plural_name %>:
+    services:
+<% actions_list.each do |action| -%>
+      <%= action %>:
+        success: "<%= class_name %> <%= action %>d successfully"
+        failure: "Failed to <%= action %> <%= human_name.downcase %>"
+<% end -%>
+
+      # Custom messages
+      # Add your own message keys here
+      # Example:
+      # published:
+      #   success: "<%= class_name %> published and customers notified"
+      #   failure: "Failed to publish <%= human_name.downcase %>"

data/lib/generators/better_service/templates/presenter.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+# <%= presenter_class_name %> - Formats <%= class_name %> data for API/view consumption
+#
+# Usage in services:
+#   class <%= class_name.pluralize %>::IndexService < IndexService
+#     presenter <%= presenter_class_name %>
+#
+#     presenter_options do
+#       { current_user: user }
+#     end
+#   end
+class <%= presenter_class_name %> < BetterService::Presenter
+  # Define JSON representation
+  #
+  # @param opts [Hash] JSON serialization options
+  # @return [Hash] Formatted hash representation
+  def as_json(opts = {})
+    {
+      id: object.id,
+<% attributes_list.each do |attr| -%>
+      <%= attr %>: object.<%= attr %>,
+<% end -%>
+      # Add computed fields
+      # display_name: "#{object.first_name} #{object.last_name}",
+
+      # Add timestamps if needed
+      # created_at: object.created_at,
+      # updated_at: object.updated_at,
+
+      # Add conditional fields based on user permissions
+      # **(admin_fields if current_user&.admin?)
+    }
+  end
+
+  private
+
+  # Example: Include admin-only fields
+  # def admin_fields
+  #   {
+  #     internal_notes: object.internal_notes,
+  #     cost: object.cost
+  #   }
+  # end
+
+  # Example: Check if user has specific permission
+  # def user_can_edit?
+  #   return false unless current_user
+  #   current_user.id == object.user_id || current_user.admin?
+  # end
+end
+<% end -%>

data/lib/generators/better_service/templates/presenter_test.rb.tt

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+<% module_namespacing do -%>
+class <%= presenter_class_name %>Test < ActiveSupport::TestCase
+  setup do
+    @<%= file_name %> = <%= class_name %>.new(
+      id: 1<%= attributes_list.map { |attr| ",\n      #{attr}: \"test_#{attr}\"" }.join %>
+    )
+    @presenter = <%= presenter_class_name %>.new(@<%= file_name %>)
+  end
+
+  test "presents <%= file_name %> as json" do
+    json = @presenter.as_json
+
+    assert_equal @<%= file_name %>.id, json[:id]
+<% attributes_list.each do |attr| -%>
+    assert_equal @<%= file_name %>.<%= attr %>, json[:<%= attr %>]
+<% end -%>
+  end
+
+  test "accepts options" do
+    presenter = <%= presenter_class_name %>.new(@<%= file_name %>, custom: "value")
+
+    assert_equal "value", presenter.options[:custom]
+  end
+
+  test "provides access to current_user from options" do
+    user = OpenStruct.new(id: 123, admin?: true)
+    presenter = <%= presenter_class_name %>.new(@<%= file_name %>, current_user: user)
+
+    assert_equal user, presenter.send(:current_user)
+  end
+
+  test "responds to to_h" do
+    assert_respond_to @presenter, :to_h
+    assert_kind_of Hash, @presenter.to_h
+  end
+
+  test "responds to to_json" do
+    assert_respond_to @presenter, :to_json
+    assert_kind_of String, @presenter.to_json
+  end
+end
+<% end -%>

data/lib/generators/serviceable/scaffold_generator.rb

@@ -12,6 +12,7 @@ module Serviceable
       class_option :skip_create, type: :boolean, default: false, desc: "Skip Create service generation"
       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"
 
       desc "Generate all CRUD services (Index, Show, Create, Update, Destroy)"
 
@@ -50,6 +51,13 @@ module Serviceable
         generate "serviceable:destroy", name
       end
 
+      def generate_presenter
+        return unless options[:presenter]
+
+        say "Generating Presenter...", :green
+        generate "better_service:presenter", name
+      end
+
       def show_completion_message
         say "\n" + "=" * 80
         say "Scaffold generation completed! 🎉", :green
@@ -60,6 +68,7 @@ module Serviceable
         say "  - #{class_name}::CreateService" unless options[:skip_create]
         say "  - #{class_name}::UpdateService" unless options[:skip_update]
         say "  - #{class_name}::DestroyService" unless options[:skip_destroy]
+        say "  - #{class_name}Presenter (app/presenters)" if options[:presenter]
         say "\nNext steps:"
         say "  1. Review and customize the generated services"
         say "  2. Update schemas with your specific validations"

data/lib/generators/serviceable/templates/create_service.rb.tt

@@ -26,8 +26,18 @@ class <%= class_name %>::CreateService < BetterService::Services::CreateService
   end
 
   # Phase 4: Respond - Format response (optional override)
+  # Uses I18n message helper with fallback to default messages
+  #
+  # To customize messages, create config/locales/<%= plural_table_name %>_services.en.yml:
+  #   en:
+  #     <%= plural_table_name %>:
+  #       services:
+  #         create:
+  #           success: "<%= human_name %> created successfully!"
+  #
+  # Then configure namespace: messages_namespace :<%= plural_table_name %>
   respond_with do |data|
-    success_result("<%= human_name %> created successfully", data)
+    success_result(message("create.success"), data)
   end
 end
 <% end -%>