better_service 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c796a9b8cd27afc4ae26e29b42decb8a606d88d0fdd6158b8599766cfa33df48
-  data.tar.gz: afdee95a722f85f08c919243b5ff8da37adb211b4d7b1dd3ba7a334e97d3b2f6
+  metadata.gz: 622ac1a705ab117672d0e9c4896e65b66585c747023d1e00b34824e9c35606a0
+  data.tar.gz: f4c6f5b6ae7baaa3f61eeb123d4a2a493a7c8acc2ff835c6891396ed543efa1c
 SHA512:
-  metadata.gz: 5fb831ec7c495b453b0915c33427080012faac9aa870919d7e0e30303251fd477c9309ccfb0e8c6e257d36fe45b9c03f7af7445290641f4af898d6f62ab5c800
-  data.tar.gz: f34a008657a3f9208c220d286f3c33201daadac7a7114c729d97e3a5734574907cce3ce0fc85c6ea6964ab8339266be0b31d9c6f67a5211d0eb1c7b7ff18a176
+  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)
 
@@ -28,6 +28,7 @@ BetterService is a comprehensive Service Objects framework for Rails that brings
 - 🎨 **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
 - 🎨 **DSL-Based**: Clean, expressive DSL with `search_with`, `process_with`, `authorize_with`, etc.
@@ -1545,7 +1546,7 @@ 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,8 +2,198 @@ 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/**/*",
@@ -12,4 +202,14 @@ Rake::TestTask.new(:test) do |t|
   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/lib/better_service/version.rb

@@ -1,3 +1,3 @@
 module BetterService
-  VERSION = "1.0.1"
+  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

data/lib/better_service/workflows/branch_dsl.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # DSL context for defining conditional branches
+    #
+    # This class provides the DSL methods available inside a `branch do...end` block:
+    # - `on(condition, &block)` - Defines a conditional branch
+    # - `otherwise(&block)` - Defines the default branch
+    # - `step(...)` - Adds a step to the current branch
+    # - `branch(&block)` - Allows nested branch groups
+    #
+    # @example
+    #   branch do
+    #     on ->(ctx) { ctx.user.premium? } do
+    #       step :premium_action, with: PremiumService
+    #     end
+    #
+    #     on ->(ctx) { ctx.user.basic? } do
+    #       step :basic_action, with: BasicService
+    #     end
+    #
+    #     otherwise do
+    #       step :default_action, with: DefaultService
+    #     end
+    #   end
+    class BranchDSL
+      attr_reader :branch_group
+
+      # Creates a new BranchDSL context
+      #
+      # @param branch_group [BranchGroup] The branch group being configured
+      def initialize(branch_group)
+        @branch_group = branch_group
+        @current_branch = nil
+        @branch_index = 0
+      end
+
+      # Defines a conditional branch
+      #
+      # @param condition [Proc] The condition to evaluate (receives context)
+      # @param block [Proc] The block defining steps for this branch
+      # @return [void]
+      #
+      # @example
+      #   on ->(ctx) { ctx.user.premium? } do
+      #     step :send_premium_email, with: Email::PremiumService
+      #   end
+      def on(condition, &block)
+        raise ArgumentError, "Condition must be a Proc" unless condition.is_a?(Proc)
+        raise ArgumentError, "Block required for 'on'" unless block_given?
+
+        @branch_index += 1
+        branch_name = :"on_#{@branch_index}"
+
+        @current_branch = @branch_group.add_branch(
+          condition: condition,
+          name: branch_name
+        )
+
+        # Evaluate the block in this DSL context
+        instance_eval(&block)
+
+        @current_branch = nil
+      end
+
+      # Defines the default branch (executed when no condition matches)
+      #
+      # @param block [Proc] The block defining steps for the default branch
+      # @return [void]
+      #
+      # @example
+      #   otherwise do
+      #     step :default_action, with: DefaultService
+      #   end
+      def otherwise(&block)
+        raise ArgumentError, "Block required for 'otherwise'" unless block_given?
+        raise ArgumentError, "Default branch already defined" if @branch_group.default_branch
+
+        @current_branch = @branch_group.set_default
+
+        # Evaluate the block in this DSL context
+        instance_eval(&block)
+
+        @current_branch = nil
+      end
+
+      # Adds a step to the current branch
+      #
+      # This method has the same signature as the workflow-level `step` method.
+      #
+      # @param name [Symbol] The step name
+      # @param with [Class] The service class to execute
+      # @param input [Proc, nil] Optional input mapper
+      # @param optional [Boolean] Whether the step is optional
+      # @param if [Proc, nil] Optional condition for step execution
+      # @param rollback [Proc, nil] Optional rollback handler
+      # @return [void]
+      def step(name, with:, input: nil, optional: false, **options)
+        raise "step must be called within an 'on' or 'otherwise' block" unless @current_branch
+
+        # Handle Ruby keyword 'if' gracefully
+        condition = options[:if] || options.dig(:binding)&.local_variable_get(:if) rescue nil
+
+        step_obj = Workflowable::Step.new(
+          name: name,
+          service_class: with,
+          input: input,
+          optional: optional,
+          condition: condition,
+          rollback: options[:rollback]
+        )
+
+        @current_branch.add_step(step_obj)
+      end
+
+      # Allows nested branch groups within branches
+      #
+      # @param block [Proc] The block defining the nested branch group
+      # @return [void]
+      #
+      # @example
+      #   on ->(ctx) { ctx.type == 'contract' } do
+      #     step :validate_contract, with: ValidateService
+      #
+      #     branch do
+      #       on ->(ctx) { ctx.value > 10000 } do
+      #         step :ceo_approval, with: CEOApprovalService
+      #       end
+      #       otherwise do
+      #         step :manager_approval, with: ManagerApprovalService
+      #       end
+      #     end
+      #   end
+      def branch(&block)
+        raise "branch must be called within an 'on' or 'otherwise' block" unless @current_branch
+        raise ArgumentError, "Block required for 'branch'" unless block_given?
+
+        # Create nested branch group
+        nested_group = BranchGroup.new(name: :"nested_branch_#{@branch_index}")
+        nested_dsl = BranchDSL.new(nested_group)
+
+        # Evaluate the block in the nested DSL context
+        nested_dsl.instance_eval(&block)
+
+        # Add the branch group as a "step" (it responds to call like a step)
+        @current_branch.add_step(nested_group)
+      end
+    end
+  end
+end

data/lib/better_service/workflows/branch_group.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # Represents a group of conditional branches in a workflow
+    #
+    # A BranchGroup is created by the `branch do...end` DSL block and contains:
+    # - Multiple conditional branches (from `on` blocks)
+    # - An optional default branch (from `otherwise` block)
+    #
+    # When executed, it evaluates conditions in order and executes the first matching branch.
+    # If no branch matches and there's no default, it raises an error.
+    #
+    # @example
+    #   branch_group = BranchGroup.new(name: :payment_routing)
+    #   branch_group.add_branch(condition: ->(ctx) { ctx.type == 'card' }) do
+    #     # steps...
+    #   end
+    #   branch_group.set_default do
+    #     # default steps...
+    #   end
+    #
+    #   result = branch_group.call(context, user, params)
+    class BranchGroup
+      attr_reader :branches, :default_branch, :name
+
+      # Creates a new BranchGroup
+      #
+      # @param name [Symbol, nil] Optional name for the branch group
+      def initialize(name: nil)
+        @branches = []
+        @default_branch = nil
+        @name = name
+      end
+
+      # Adds a conditional branch to this group
+      #
+      # @param condition [Proc] The condition to evaluate
+      # @param name [Symbol, nil] Optional name for the branch
+      # @return [Branch] The created branch
+      def add_branch(condition:, name: nil)
+        branch = Branch.new(condition: condition, name: name)
+        @branches << branch
+        branch
+      end
+
+      # Sets the default branch (otherwise)
+      #
+      # @param name [Symbol, nil] Optional name for the default branch
+      # @return [Branch] The created default branch
+      def set_default(name: nil)
+        @default_branch = Branch.new(condition: nil, name: name || :otherwise)
+      end
+
+      # Selects the first branch that matches the context
+      #
+      # @param context [Workflowable::Context] The workflow context
+      # @return [Branch, nil] The matching branch or nil if none match
+      def select_branch(context)
+        # Try conditional branches first (in order)
+        @branches.each do |branch|
+          return branch if branch.matches?(context)
+        end
+
+        # Fall back to default branch if present
+        @default_branch
+      end
+
+      # Executes the appropriate branch based on context
+      #
+      # This is called during workflow execution. It:
+      # 1. Selects the matching branch
+      # 2. Executes all steps in that branch
+      # 3. Returns metadata about the execution
+      #
+      # @param context [Workflowable::Context] The workflow context
+      # @param user [Object] The current user
+      # @param params [Hash] The workflow parameters
+      # @param parent_decisions [Array, nil] Parent branch decisions for nested tracking
+      # @return [Hash] Execution result with :executed_steps, :branch_taken, :branch_decisions, :skipped
+      # @raise [Errors::Configuration::InvalidConfigurationError] If no branch matches
+      def call(context, user, params, parent_decisions = nil)
+        selected_branch = select_branch(context)
+
+        if selected_branch.nil?
+          raise Errors::Configuration::InvalidConfigurationError.new(
+            "No matching branch found and no default branch defined",
+            code: ErrorCodes::CONFIGURATION_ERROR,
+            context: {
+              branch_group: @name,
+              branches_count: @branches.count,
+              has_default: !@default_branch.nil?
+            }
+          )
+        end
+
+        # Track this branch decision
+        branch_decision = "#{@name}:#{selected_branch.name}"
+        branch_decisions = [branch_decision]
+
+        # Execute the selected branch
+        executed_steps = selected_branch.execute(context, user, params, branch_decisions)
+
+        # Return execution metadata
+        {
+          executed_steps: executed_steps,
+          branch_taken: selected_branch,
+          branch_decisions: branch_decisions,
+          skipped: false
+        }
+      end
+
+      # Returns the total number of branches (including default)
+      #
+      # @return [Integer]
+      def branch_count
+        count = @branches.count
+        count += 1 if @default_branch
+        count
+      end
+
+      # Returns whether this group has a default branch
+      #
+      # @return [Boolean]
+      def has_default?
+        !@default_branch.nil?
+      end
+
+      # Returns a string representation of this branch group
+      #
+      # @return [String]
+      def inspect
+        "#<BetterService::Workflows::BranchGroup name=#{@name.inspect} " \
+          "branches=#{@branches.count} " \
+          "has_default=#{has_default?}>"
+      end
+    end
+  end
+end

data/lib/better_service/workflows/dsl.rb

@@ -42,6 +42,52 @@ module BetterService
           self._steps += [ step ]
         end
 
+        # DSL method to define conditional branches in the workflow
+        #
+        # Creates a branch group that allows multiple conditional execution paths.
+        # Only one branch will be executed based on the first matching condition.
+        #
+        # @param block [Proc] Block containing branch definitions (on/otherwise)
+        #
+        # @example Define conditional branches
+        #   branch do
+        #     on ->(ctx) { ctx.user.premium? } do
+        #       step :premium_feature, with: PremiumService
+        #     end
+        #
+        #     on ->(ctx) { ctx.user.basic? } do
+        #       step :basic_feature, with: BasicService
+        #     end
+        #
+        #     otherwise do
+        #       step :default_feature, with: DefaultService
+        #     end
+        #   end
+        def branch(&block)
+          raise ArgumentError, "Block required for 'branch'" unless block_given?
+
+          # Count existing branch groups to determine index
+          branch_count = _steps.count { |s| s.is_a?(BranchGroup) }
+
+          # Create branch group
+          branch_group = BranchGroup.new(name: :"branch_#{branch_count + 1}")
+
+          # Create DSL context and evaluate block
+          branch_dsl = BranchDSL.new(branch_group)
+          branch_dsl.instance_eval(&block)
+
+          # Validate: must have at least one branch (conditional or default)
+          if branch_group.branches.empty? && branch_group.default_branch.nil?
+            raise Errors::Configuration::InvalidConfigurationError.new(
+              "Branch group must contain at least one 'on' or 'otherwise' block",
+              code: ErrorCodes::CONFIGURATION_ERROR
+            )
+          end
+
+          # Add branch group to steps
+          self._steps += [ branch_group ]
+        end
+
         # Enable or disable database transactions for the entire workflow
         #
         # @param enabled [Boolean] Whether to use transactions

data/lib/better_service/workflows/execution.rb

@@ -22,16 +22,39 @@ module BetterService
         steps_executed = []
         steps_skipped = []
 
-        self.class._steps.each do |step|
-          # Execute step with around_step callbacks
+        self.class._steps.each do |step_or_branch|
+          # Handle BranchGroup (conditional branching)
+          if step_or_branch.is_a?(BranchGroup)
+            branch_result = nil
+            run_around_step_callbacks(step_or_branch, @context) do
+              branch_result = step_or_branch.call(@context, @user, @params)
+            end
+
+            # Track branch decisions (including nested)
+            if branch_result[:branch_decisions]
+              @branch_decisions.concat(branch_result[:branch_decisions])
+            end
+
+            # Track executed steps from the branch
+            if branch_result[:executed_steps]
+              branch_result[:executed_steps].each do |executed_step|
+                @executed_steps << executed_step
+                steps_executed << executed_step.name
+              end
+            end
+
+            next
+          end
+
+          # Handle regular Step
           result = nil
-          run_around_step_callbacks(step, @context) do
-            result = step.call(@context, @user, @params)
+          run_around_step_callbacks(step_or_branch, @context) do
+            result = step_or_branch.call(@context, @user, @params)
           end
 
           # Track skipped steps
           if result[:skipped]
-            steps_skipped << step.name
+            steps_skipped << step_or_branch.name
             next
           end
 
@@ -41,11 +64,11 @@ module BetterService
             rollback_steps
 
             raise Errors::Workflowable::Runtime::StepExecutionError.new(
-              "Step #{step.name} failed: #{result[:error] || result[:message]}",
+              "Step #{step_or_branch.name} failed: #{result[:error] || result[:message]}",
               code: ErrorCodes::STEP_FAILED,
               context: {
                 workflow: self.class.name,
-                step: step.name,
+                step: step_or_branch.name,
                 steps_executed: steps_executed,
                 errors: result[:errors] || {}
               }
@@ -53,8 +76,8 @@ module BetterService
           end
 
           # Track successful execution
-          @executed_steps << step
-          steps_executed << step.name
+          @executed_steps << step_or_branch
+          steps_executed << step_or_branch.name
         end
 
         # All steps succeeded
@@ -66,6 +89,9 @@ module BetterService
       rescue Errors::Workflowable::Runtime::StepExecutionError
         # Step error already raised, just re-raise
         raise
+      rescue Errors::Configuration::InvalidConfigurationError
+        # Configuration error (e.g., no matching branch), just re-raise
+        raise
       rescue StandardError => e
         # Unexpected error during workflow execution
         rollback_steps

data/lib/better_service/workflows/result_builder.rb

@@ -15,16 +15,21 @@ module BetterService
       # @param steps_skipped [Array<Symbol>] Names of steps that were skipped
       # @return [Hash] Success result with context and metadata
       def build_success_result(steps_executed: [], steps_skipped: [])
+        metadata = {
+          workflow: self.class.name,
+          steps_executed: steps_executed,
+          steps_skipped: steps_skipped,
+          duration_ms: duration_ms
+        }
+
+        # Include branch decisions if any branches were taken
+        metadata[:branches_taken] = @branch_decisions if @branch_decisions.any?
+
         {
           success: true,
           message: "Workflow completed successfully",
           context: @context,
-          metadata: {
-            workflow: self.class.name,
-            steps_executed: steps_executed,
-            steps_skipped: steps_skipped,
-            duration_ms: duration_ms
-          }
+          metadata: metadata
         }
       end
 
@@ -37,22 +42,26 @@ module BetterService
       # @param steps_skipped [Array<Symbol>] Names of steps that were skipped
       # @return [Hash] Failure result with error details and metadata
       def build_failure_result(message: nil, errors: {}, failed_step: nil, steps_executed: [], steps_skipped: [])
-        result = {
+        metadata = {
+          workflow: self.class.name,
+          failed_step: failed_step,
+          steps_executed: steps_executed,
+          steps_skipped: steps_skipped,
+          duration_ms: duration_ms
+        }
+
+        # Include branch decisions if any branches were taken before failure
+        metadata[:branches_taken] = @branch_decisions if @branch_decisions.any?
+
+        metadata.delete(:failed_step) if failed_step.nil?
+
+        {
           success: false,
           error: message || @context.errors[:message] || "Workflow failed",
           errors: errors.any? ? errors : @context.errors,
           context: @context,
-          metadata: {
-            workflow: self.class.name,
-            failed_step: failed_step,
-            steps_executed: steps_executed,
-            steps_skipped: steps_skipped,
-            duration_ms: duration_ms
-          }
+          metadata: metadata
         }
-
-        result[:metadata].delete(:failed_step) if failed_step.nil?
-        result
       end
 
       # Calculate duration in milliseconds

data/lib/better_service.rb

@@ -20,6 +20,9 @@ require "better_service/concerns/workflowable/callbacks"
 require "better_service/workflows/result_builder"
 require "better_service/workflows/rollback_support"
 require "better_service/workflows/transaction_support"
+require "better_service/workflows/branch"
+require "better_service/workflows/branch_group"
+require "better_service/workflows/branch_dsl"
 require "better_service/workflows/dsl"
 require "better_service/workflows/execution"
 require "better_service/workflows/base"

data/lib/generators/workflowable/templates/workflow.rb.tt

@@ -48,6 +48,28 @@ class <%= workflow_class_name %> < BetterService::Workflow
   #      input: ->(ctx) { { resource_id: ctx.resource.id } },
   #      optional: true,
   #      if: ->(ctx) { ctx.user.notifications_enabled? }
+  #
+  # Conditional branching (NEW):
+  #
+  # branch do
+  #   on ->(ctx) { ctx.user.premium? } do
+  #     step :premium_feature,
+  #          with: <%= class_name %>::PremiumService,
+  #          input: ->(ctx) { { resource: ctx.resource } }
+  #   end
+  #
+  #   on ->(ctx) { ctx.user.basic? } do
+  #     step :basic_feature,
+  #          with: <%= class_name %>::BasicService,
+  #          input: ->(ctx) { { resource: ctx.resource } }
+  #   end
+  #
+  #   otherwise do
+  #     step :default_feature,
+  #          with: <%= class_name %>::DefaultService,
+  #          input: ->(ctx) { { resource: ctx.resource } }
+  #   end
+  # end
 
 <% end -%>
   private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_service
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-11 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -74,7 +74,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - config/locales/better_service.en.yml
@@ -128,6 +128,9 @@ files:
 - lib/better_service/subscribers/stats_subscriber.rb
 - lib/better_service/version.rb
 - lib/better_service/workflows/base.rb
+- lib/better_service/workflows/branch.rb
+- lib/better_service/workflows/branch_dsl.rb
+- lib/better_service/workflows/branch_group.rb
 - lib/better_service/workflows/dsl.rb
 - lib/better_service/workflows/execution.rb
 - lib/better_service/workflows/result_builder.rb
@@ -161,7 +164,7 @@ files:
 - lib/tasks/better_service_tasks.rake
 homepage: https://github.com/alessiobussolari/better_service
 licenses:
-- MIT
+- WTFPL
 metadata:
   homepage_uri: https://github.com/alessiobussolari/better_service
   source_code_uri: https://github.com/alessiobussolari/better_service

data/MIT-LICENSE

@@ -1,20 +0,0 @@
-Copyright alessiobussolari
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.