better_service 1.0.0 → 1.1.0

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

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.1.0"
 end

data/lib/better_service/workflows/base.rb

@@ -66,6 +66,7 @@ module BetterService
       @params = params
       @context = Workflowable::Context.new(user, **params)
       @executed_steps = []
+      @branch_decisions = []
       @start_time = nil
       @end_time = nil
     end

data/lib/better_service/workflows/branch.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # Represents a single conditional branch within a workflow
+    #
+    # A Branch contains:
+    # - A condition (Proc) that determines if the branch should execute
+    # - An array of steps to execute if the condition is true
+    # - An optional name for identification
+    #
+    # @example
+    #   branch = Branch.new(
+    #     condition: ->(ctx) { ctx.user.premium? },
+    #     name: :premium_path
+    #   )
+    #   branch.add_step(step1)
+    #   branch.add_step(step2)
+    #
+    #   if branch.matches?(context)
+    #     branch.execute(context, user, params)
+    #   end
+    class Branch
+      attr_reader :condition, :steps, :name
+
+      # Creates a new Branch
+      #
+      # @param condition [Proc, nil] The condition to evaluate (nil for default/otherwise branch)
+      # @param name [Symbol, nil] Optional name for the branch
+      def initialize(condition: nil, name: nil)
+        @condition = condition
+        @steps = []
+        @name = name
+      end
+
+      # Checks if this branch's condition matches the given context
+      #
+      # @param context [Workflowable::Context] The workflow context
+      # @return [Boolean] true if condition matches or is nil (default branch)
+      def matches?(context)
+        return true if condition.nil? # Default branch always matches
+
+        if condition.is_a?(Proc)
+          context.instance_exec(context, &condition)
+        else
+          condition.call(context)
+        end
+      rescue StandardError => e
+        Rails.logger.error "Branch condition evaluation failed: #{e.message}"
+        false
+      end
+
+      # Adds a step to this branch
+      #
+      # @param step [Workflowable::Step] The step to add
+      # @return [Array] The updated steps array
+      def add_step(step)
+        @steps << step
+      end
+
+      # Executes all steps in this branch
+      #
+      # @param context [Workflowable::Context] The workflow context
+      # @param user [Object] The current user
+      # @param params [Hash] The workflow parameters
+      # @param branch_decisions [Array, nil] Array to track branch decisions for nested branches
+      # @return [Array<Workflowable::Step>] Array of successfully executed steps
+      # @raise [Errors::Workflowable::Runtime::StepExecutionError] If a required step fails
+      def execute(context, user, params, branch_decisions = nil)
+        executed_steps = []
+
+        @steps.each do |step_or_branch_group|
+          # Handle nested BranchGroup
+          if step_or_branch_group.is_a?(BranchGroup)
+            branch_result = step_or_branch_group.call(context, user, params)
+
+            # Add executed steps from nested branch
+            if branch_result[:executed_steps]
+              executed_steps.concat(branch_result[:executed_steps])
+            end
+
+            # Track nested branch decisions
+            if branch_decisions && branch_result[:branch_decisions]
+              branch_decisions.concat(branch_result[:branch_decisions])
+            end
+
+            next
+          end
+
+          # Handle regular Step
+          result = step_or_branch_group.call(context, user, params)
+
+          # Skip if step was skipped
+          next if result[:skipped]
+
+          # Handle step failure
+          if result[:success] == false && !result[:optional_failure]
+            raise Errors::Workflowable::Runtime::StepExecutionError.new(
+              "Step #{step_or_branch_group.name} failed in branch",
+              code: ErrorCodes::STEP_EXECUTION_FAILED,
+              context: {
+                step: step_or_branch_group.name,
+                branch: @name,
+                errors: result[:errors]
+              }
+            )
+          end
+
+          # Track successfully executed steps
+          executed_steps << step_or_branch_group unless result[:optional_failure]
+        end
+
+        executed_steps
+      end
+
+      # Returns whether this is a default branch (no condition)
+      #
+      # @return [Boolean]
+      def default?
+        condition.nil?
+      end
+
+      # Returns a string representation of this branch
+      #
+      # @return [String]
+      def inspect
+        "#<BetterService::Workflows::Branch name=#{@name.inspect} " \
+          "condition=#{@condition.present? ? 'present' : 'nil'} " \
+          "steps=#{@steps.count}>"
+      end
+    end
+  end
+end