simple_flow 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd0bd81d08df7f75395ab30c68637a6064c701db6ccd54f98afb05d18ebbf74d
-  data.tar.gz: c0e288adb2fba5d5101993813bf8df834fd68ee2bd7288c6c2645e3ea56b7225
+  metadata.gz: 2773d7d286318dd30f3044935fa28a7cbdae93a5452c87f47bbeba0f0e454fa9
+  data.tar.gz: da1af74a15a2ab93758ea4269c2c1b6cdc5376b543249a5f7a12d85edf8948ac
 SHA512:
-  metadata.gz: 63462e59c19f7095caa8aa2d9de89eb784f32a2e16e80d13add543fed61add8ed264e3c5aead7af24a41df66a30c1f551c4572df81fb1a3964a9f694cb2965b6
-  data.tar.gz: 7f5b5ebdd51a20b770c760de90e15ff4ccebba22f99a6af27ff45c831b5da9f0decc7e03bf84b8a51db74af245b614fc561258c38ff1dae61cd7d3a2175e34fc
+  metadata.gz: 0a63b15f0514ee9ca2cc930ac958cdb130e14d339cfddacc5b931679fb54b849f85524ab96fdd3fc3aa820c9de396bff2fa3ababa8e17b032f336316f615ea8b
+  data.tar.gz: 93966871754ccaa623431caf00a81906daaf2f7ee082fd16c56b1d6d1be96033c500dd7af88fba912882a8f910b9de0a8792b1d80dff4eed1fe674a06b541fe4

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-01-15
+
+### Added
+- Optional steps with dynamic activation via `depends_on: :optional`
+- `Result#activate(*step_names)` method for runtime step activation
+- `Result#activated_steps` attribute to track activated steps
+- `Pipeline#optional_steps` attribute returning Set of optional step names
+- Router pattern support for type-based processing paths
+- Soft failure pattern for graceful error handling with cleanup
+- Chained activation allowing optional steps to activate other optional steps
+- Example 13: Optional steps in dynamic DAG demonstration
+- Comprehensive optional steps guide in documentation
+
+### Documentation
+- Added optional steps section to README.md
+- Added optional steps guide (`docs/guides/optional-steps.md`)
+- Updated Result API documentation with `activate` method
+- Updated Pipeline API documentation with `optional_steps` attribute
+- Updated core concepts steps documentation
+- Updated examples README with example 13
+
 ## [0.2.0] - 2025-12-22
 
 ### Breaking Changes

data/README.md

@@ -242,6 +242,38 @@ result = pipeline.call_parallel(SimpleFlow::Result.new(data))
 
 **Note:** For steps with no dependencies, you can use either `depends_on: :none` (more readable) or `depends_on: []`.
 
+### Optional Steps (Dynamic DAG)
+
+Optional steps are declared with `depends_on: :optional` and only execute when explicitly activated at runtime:
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  step :router, ->(r) {
+    case r.value[:type]
+    when :pdf then r.continue(r.value).activate(:process_pdf)
+    when :image then r.continue(r.value).activate(:process_image)
+    else r.continue(r.value).activate(:process_default)
+    end
+  }, depends_on: :none
+
+  step :process_pdf, ->(r) { process_pdf(r) }, depends_on: :optional
+  step :process_image, ->(r) { process_image(r) }, depends_on: :optional
+  step :process_default, ->(r) { process_default(r) }, depends_on: :optional
+end
+
+result = pipeline.call_parallel(SimpleFlow::Result.new({ type: :pdf, data: "..." }))
+# Only :router and :process_pdf execute
+```
+
+**Key features:**
+- Declare optional steps with `depends_on: :optional`
+- Activate steps dynamically with `result.activate(:step_name)`
+- Activate multiple steps at once: `result.activate(:step_a, :step_b)`
+- Optional steps can activate other optional steps (chaining)
+- Great for routing, feature flags, and soft error handling
+
+**[Learn more →](https://madbomber.github.io/simple_flow/guides/optional-steps/)**
+
 **Execution flow:**
 
 ```mermaid
@@ -455,6 +487,7 @@ Check out the `examples/` directory for comprehensive examples:
 10. `10_concurrency_control.rb` - Per-pipeline concurrency control
 11. `11_sequential_dependencies.rb` - Sequential step dependencies and halting
 12. `12_none_constant.rb` - Using reserved dependency symbols `:none` and `:nothing`
+13. `13_optional_steps_in_dynamic_dag.rb` - Optional steps with dynamic activation
 
 ## Requirements
 

data/lib/simple_flow/pipeline.rb

@@ -39,7 +39,7 @@ module SimpleFlow
   # end
   #
   class Pipeline
-    attr_reader :steps, :middlewares, :named_steps, :step_dependencies, :concurrency, :parallel_groups
+    attr_reader :steps, :middlewares, :named_steps, :step_dependencies, :concurrency, :parallel_groups, :optional_steps
 
     # Initializes a new Pipeline object. A block can be provided to dynamically configure the pipeline,
     # allowing the addition of steps and middleware.
@@ -53,6 +53,7 @@ module SimpleFlow
       @named_steps = {}
       @step_dependencies = {}
       @parallel_groups = {}
+      @optional_steps = Set.new
       @concurrency = concurrency
 
       validate_concurrency!
@@ -92,7 +93,7 @@ module SimpleFlow
         callable ||= block
 
         # Validate step name
-        if [:none, :nothing].include?(name)
+        if [:none, :nothing, :optional].include?(name)
           raise ArgumentError, "Step name '#{name}' is reserved. Please use a different name."
         end
 
@@ -100,8 +101,16 @@ module SimpleFlow
 
         callable = apply_middleware(callable)
         @named_steps[name] = callable
-        # Filter out reserved dependency symbols :none and :nothing, and expand parallel group names
-        @step_dependencies[name] = expand_dependencies(Array(depends_on).reject { |dep| [:none, :nothing].include?(dep) })
+
+        # Check if this is an optional step
+        if depends_on == :optional
+          @optional_steps << name
+          @step_dependencies[name] = []
+        else
+          # Filter out reserved dependency symbols :none and :nothing, and expand parallel group names
+          @step_dependencies[name] = expand_dependencies(Array(depends_on).reject { |dep| [:none, :nothing].include?(dep) })
+        end
+
         @steps << { name: name, callable: callable, type: :named }
       else
         # Unnamed step: step ->(result) { ... } or step { |result| ... }
@@ -312,31 +321,49 @@ module SimpleFlow
     def execute_with_dependency_graph(result)
       require_relative 'dependency_graph'
 
-      graph = DependencyGraph.new(@step_dependencies)
-      parallel_groups = graph.parallel_order
-
       current_result = result
-      step_results = {}
+      executed_steps = Set.new
+      activated_steps = Set.new
 
-      parallel_groups.each do |group|
-        if group.size == 1
+      loop do
+        # Build active dependencies: all non-optional steps + activated optional steps
+        active_dependencies = build_active_dependencies(activated_steps, executed_steps)
+
+        # Find the next group of steps that can be executed
+        next_group = find_next_executable_group(active_dependencies, executed_steps)
+        break if next_group.empty?
+
+        if next_group.size == 1
           # Single step, execute sequentially
-          step_name = group.first
+          step_name = next_group.first
           current_result = @named_steps[step_name].call(current_result)
-          step_results[step_name] = current_result
+          executed_steps << step_name
+
+          # Process any newly activated steps
+          process_activations(current_result, step_name, activated_steps)
+
           return current_result if current_result.respond_to?(:continue?) && !current_result.continue?
         else
           # Multiple steps, execute in parallel
-          callables = group.map { |name| @named_steps[name] }
+          callables = next_group.map { |name| @named_steps[name] }
           results = ParallelExecutor.execute_parallel(callables, current_result, concurrency: @concurrency)
 
           # Check if any step halted
           halted_result = results.find { |r| r.respond_to?(:continue?) && !r.continue? }
           return halted_result if halted_result
 
-          # Merge contexts and errors from all parallel results
+          # Mark all steps as executed
+          next_group.each { |name| executed_steps << name }
+
+          # Process activations from all results
+          next_group.each_with_index do |name, idx|
+            process_activations(results[idx], name, activated_steps)
+          end
+
+          # Merge contexts, errors, and activated_steps from all parallel results
           merged_context = {}
           merged_errors = {}
+          merged_activated = []
           results.each do |r|
             merged_context.merge!(r.context) if r.respond_to?(:context)
             if r.respond_to?(:errors)
@@ -345,19 +372,16 @@ module SimpleFlow
                 merged_errors[key].concat(messages)
               end
             end
+            merged_activated.concat(r.activated_steps) if r.respond_to?(:activated_steps)
           end
 
-          # Store results and create merged result
-          group.each_with_index do |name, idx|
-            step_results[name] = results[idx]
-          end
-
-          # Use the last result's value but with merged context/errors
+          # Use the last result's value but with merged context/errors/activated_steps
           last_result = results.last
           current_result = Result.new(
             last_result.value,
             context: merged_context,
-            errors: merged_errors
+            errors: merged_errors,
+            activated_steps: merged_activated.uniq
           )
         end
       end
@@ -365,6 +389,65 @@ module SimpleFlow
       current_result
     end
 
+    # Build the active step dependencies, excluding optional steps that haven't been activated
+    def build_active_dependencies(activated_steps, executed_steps)
+      active_deps = {}
+      @step_dependencies.each do |step_name, deps|
+        # Skip optional steps that haven't been activated
+        next if @optional_steps.include?(step_name) && !activated_steps.include?(step_name)
+
+        # Check if any dependency is an optional step that hasn't been activated
+        has_unactivated_optional_dep = deps.any? do |dep|
+          @optional_steps.include?(dep) && !activated_steps.include?(dep)
+        end
+
+        # If this step depends on an optional step that hasn't been activated, skip it
+        # (it can only run if/when that optional dependency gets activated)
+        next if has_unactivated_optional_dep
+
+        # Filter dependencies to only include steps that will actually run
+        # (non-optional steps and activated optional steps)
+        filtered_deps = deps.select do |dep|
+          !@optional_steps.include?(dep) || activated_steps.include?(dep)
+        end
+
+        active_deps[step_name] = filtered_deps
+      end
+      active_deps
+    end
+
+    # Find the next group of steps that can be executed
+    def find_next_executable_group(active_dependencies, executed_steps)
+      # Find steps whose dependencies have all been executed
+      ready_steps = active_dependencies.keys.select do |step_name|
+        next false if executed_steps.include?(step_name)
+
+        deps = active_dependencies[step_name]
+        deps.all? { |dep| executed_steps.include?(dep) }
+      end
+
+      ready_steps
+    end
+
+    # Process activated steps from a result, validating each
+    def process_activations(result, current_step, activated_steps)
+      return unless result.respond_to?(:activated_steps)
+
+      result.activated_steps.each do |step_name|
+        next if activated_steps.include?(step_name) # Idempotent
+
+        unless @named_steps.key?(step_name)
+          raise ArgumentError, "Step :#{current_step} attempted to activate unknown step :#{step_name}"
+        end
+
+        unless @optional_steps.include?(step_name)
+          raise ArgumentError, "Step :#{current_step} attempted to activate non-optional step :#{step_name}. Only steps declared with depends_on: :optional can be activated."
+        end
+
+        activated_steps << step_name
+      end
+    end
+
     def execute_with_explicit_parallelism(result)
       steps.reduce(result) do |res, step_def|
         return res if res.respond_to?(:continue?) && !res.continue?

data/lib/simple_flow/result.rb

@@ -20,14 +20,19 @@ module SimpleFlow
     # Errors occurred during the operation.
     attr_reader :errors
 
+    # Steps that have been activated for dynamic execution.
+    attr_reader :activated_steps
+
     # Initializes a new Result instance.
     # @param value [Object] the outcome of the operation.
     # @param context [Hash, optional] contextual data related to the operation.
     # @param errors [Hash, optional] errors occurred during the operation.
-    def initialize(value, context: {}, errors: {})
+    # @param activated_steps [Array<Symbol>, optional] steps activated for dynamic execution.
+    def initialize(value, context: {}, errors: {}, activated_steps: [])
       @value = value
       @context = context
       @errors = errors
+      @activated_steps = activated_steps
       @continue = true
     end
 
@@ -36,7 +41,7 @@ module SimpleFlow
     # @param value [Object] the value to store.
     # @return [Result] a new Result instance with updated context.
     def with_context(key, value)
-      result = self.class.new(@value, context: @context.merge(key => value), errors: @errors)
+      result = self.class.new(@value, context: @context.merge(key => value), errors: @errors, activated_steps: @activated_steps)
       result.instance_variable_set(:@continue, @continue)
       result
     end
@@ -47,7 +52,7 @@ module SimpleFlow
     # @param message [String] the error message.
     # @return [Result] a new Result instance with updated errors.
     def with_error(key, message)
-      result = self.class.new(@value, context: @context, errors: @errors.merge(key => [*@errors[key], message]))
+      result = self.class.new(@value, context: @context, errors: @errors.merge(key => [*@errors[key], message]), activated_steps: @activated_steps)
       result.instance_variable_set(:@continue, @continue)
       result
     end
@@ -56,7 +61,7 @@ module SimpleFlow
     # @param new_value [Object, nil] the new value to set, if any.
     # @return [Result] a new Result instance with continue set to false.
     def halt(new_value = nil)
-      result = new_value ? with_value(new_value) : self.class.new(@value, context: @context, errors: @errors)
+      result = new_value ? with_value(new_value) : self.class.new(@value, context: @context, errors: @errors, activated_steps: @activated_steps)
       result.instance_variable_set(:@continue, false)
       result
     end
@@ -74,13 +79,23 @@ module SimpleFlow
       @continue
     end
 
+    # Activates optional steps for dynamic execution.
+    # @param step_names [Symbol, Array<Symbol>] one or more step names to activate.
+    # @return [Result] a new Result instance with the steps added to activated_steps.
+    def activate(*step_names)
+      new_activated = @activated_steps + step_names.flatten
+      result = self.class.new(@value, context: @context, errors: @errors, activated_steps: new_activated)
+      result.instance_variable_set(:@continue, @continue)
+      result
+    end
+
     private
 
     # Creates a new Result instance with updated value.
     # @param new_value [Object] the new value for the result.
     # @return [Result] a new Result instance.
     def with_value(new_value)
-      result = self.class.new(new_value, context: @context, errors: @errors)
+      result = self.class.new(new_value, context: @context, errors: @errors, activated_steps: @activated_steps)
       result.instance_variable_set(:@continue, @continue)
       result
     end

data/lib/simple_flow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleFlow
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_flow
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -54,7 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.4
 specification_version: 4
 summary: A lightweight, modular Ruby framework for building composable data processing
   pipelines