simple_flow 0.1.0

data/examples/01_basic_pipeline.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Basic pipeline example demonstrating sequential step execution
+
+puts "=" * 60
+puts "Basic Pipeline Example"
+puts "=" * 60
+puts
+
+# Example 1: Simple data transformation pipeline
+puts "Example 1: Data Transformation Pipeline"
+puts "-" * 60
+
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  Step 1: Trimming whitespace"
+    result.continue(result.value.strip)
+  }
+
+  step ->(result) {
+    puts "  Step 2: Converting to uppercase"
+    result.continue(result.value.upcase)
+  }
+
+  step ->(result) {
+    puts "  Step 3: Adding greeting"
+    result.continue("Hello, #{result.value}!")
+  }
+end
+
+initial_result = SimpleFlow::Result.new("  world  ")
+final_result = pipeline.call(initial_result)
+
+puts "Input:  '#{initial_result.value}'"
+puts "Output: '#{final_result.value}'"
+puts
+
+# Example 2: Numerical computation pipeline
+puts "\nExample 2: Numerical Computation Pipeline"
+puts "-" * 60
+
+computation_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  Step 1: Add 10"
+    result.continue(result.value + 10)
+  }
+
+  step ->(result) {
+    puts "  Step 2: Multiply by 2"
+    result.continue(result.value * 2)
+  }
+
+  step ->(result) {
+    puts "  Step 3: Subtract 5"
+    result.continue(result.value - 5)
+  }
+end
+
+initial_value = SimpleFlow::Result.new(5)
+computed_result = computation_pipeline.call(initial_value)
+
+puts "Input:  #{initial_value.value}"
+puts "Output: #{computed_result.value}"
+puts "Formula: (5 + 10) * 2 - 5 = #{computed_result.value}"
+puts
+
+# Example 3: Context propagation
+puts "\nExample 3: Context Propagation"
+puts "-" * 60
+
+context_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  Step 1: Recording start time"
+    result
+      .with_context(:started_at, Time.now)
+      .continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 2: Processing data"
+    sleep 0.1  # Simulate processing
+    result
+      .with_context(:processed_at, Time.now)
+      .continue(result.value.upcase)
+  }
+
+  step ->(result) {
+    puts "  Step 3: Recording completion"
+    result
+      .with_context(:completed_at, Time.now)
+      .with_context(:steps_executed, 3)
+      .continue(result.value)
+  }
+end
+
+context_result = context_pipeline.call(SimpleFlow::Result.new("processing"))
+
+puts "Result: #{context_result.value}"
+puts "Context:"
+context_result.context.each do |key, value|
+  puts "  #{key}: #{value}"
+end
+puts
+
+puts "=" * 60
+puts "Basic pipeline examples completed!"
+puts "=" * 60

data/examples/02_error_handling.rb

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Error handling and flow control examples
+
+puts "=" * 60
+puts "Error Handling and Flow Control"
+puts "=" * 60
+puts
+
+# Example 1: Validation with halt
+puts "Example 1: Input Validation with Halt"
+puts "-" * 60
+
+validation_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  Step 1: Validating age is numeric"
+    unless result.value.is_a?(Integer)
+      return result.halt.with_error(:validation, "Age must be a number")
+    end
+    result.continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 2: Validating age is positive"
+    if result.value < 0
+      return result.halt.with_error(:validation, "Age cannot be negative")
+    end
+    result.continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 3: Checking minimum age"
+    if result.value < 18
+      return result.halt.with_error(:validation, "Must be 18 or older")
+    end
+    result.continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 4: Processing valid age"
+    result.continue("Approved for age #{result.value}")
+  }
+end
+
+# Test with valid age
+puts "\nTest 1: Valid age (21)"
+result1 = validation_pipeline.call(SimpleFlow::Result.new(21))
+puts "Continue? #{result1.continue?}"
+puts "Result: #{result1.value}"
+puts "Errors: #{result1.errors}"
+
+# Test with invalid age (under 18)
+puts "\nTest 2: Invalid age (15)"
+result2 = validation_pipeline.call(SimpleFlow::Result.new(15))
+puts "Continue? #{result2.continue?}"
+puts "Result: #{result2.value}"
+puts "Errors: #{result2.errors}"
+
+# Test with negative age
+puts "\nTest 3: Negative age (-5)"
+result3 = validation_pipeline.call(SimpleFlow::Result.new(-5))
+puts "Continue? #{result3.continue?}"
+puts "Result: #{result3.value}"
+puts "Errors: #{result3.errors}"
+puts
+
+# Example 2: Error accumulation
+puts "\nExample 2: Error Accumulation"
+puts "-" * 60
+
+error_accumulation_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  Step 1: Checking password length"
+    if result.value[:password].length < 8
+      result = result.with_error(:password, "Password must be at least 8 characters")
+    end
+    result.continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 2: Checking for uppercase letters"
+    unless result.value[:password] =~ /[A-Z]/
+      result = result.with_error(:password, "Password must contain uppercase letters")
+    end
+    result.continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 3: Checking for numbers"
+    unless result.value[:password] =~ /[0-9]/
+      result = result.with_error(:password, "Password must contain numbers")
+    end
+    result.continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 4: Final validation"
+    if result.errors.any?
+      result.halt(result.value)
+    else
+      result.continue({ username: result.value[:username], status: "valid" })
+    end
+  }
+
+  step ->(result) {
+    puts "  Step 5: Creating account (only runs if valid)"
+    result.continue("Account created for #{result.value[:username]}")
+  }
+end
+
+# Test with weak password
+puts "\nTest 1: Weak password"
+weak_password_result = error_accumulation_pipeline.call(
+  SimpleFlow::Result.new({ username: "john", password: "weak" })
+)
+puts "Continue? #{weak_password_result.continue?}"
+puts "Result: #{weak_password_result.value}"
+puts "Errors: #{weak_password_result.errors}"
+
+# Test with strong password
+puts "\nTest 2: Strong password"
+strong_password_result = error_accumulation_pipeline.call(
+  SimpleFlow::Result.new({ username: "jane", password: "SecurePass123" })
+)
+puts "Continue? #{strong_password_result.continue?}"
+puts "Result: #{strong_password_result.value}"
+puts "Errors: #{strong_password_result.errors}"
+puts
+
+# Example 3: Conditional branching
+puts "\nExample 3: Conditional Processing"
+puts "-" * 60
+
+conditional_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  Step 1: Checking user role"
+    result.with_context(:user_role, result.value[:role]).continue(result.value)
+  }
+
+  step ->(result) {
+    puts "  Step 2: Role-based processing"
+    case result.context[:user_role]
+    when :admin
+      result.with_context(:permissions, [:read, :write, :delete]).continue(result.value)
+    when :editor
+      result.with_context(:permissions, [:read, :write]).continue(result.value)
+    when :viewer
+      result.with_context(:permissions, [:read]).continue(result.value)
+    else
+      result.halt.with_error(:auth, "Unknown role: #{result.context[:user_role]}")
+    end
+  }
+
+  step ->(result) {
+    puts "  Step 3: Generating access token"
+    permissions = result.context[:permissions]
+    result.continue("Token granted with permissions: #{permissions.join(', ')}")
+  }
+end
+
+# Test different roles
+[:admin, :editor, :viewer, :unknown].each do |role|
+  puts "\nTesting role: #{role}"
+  result = conditional_pipeline.call(SimpleFlow::Result.new({ role: role }))
+  puts "  Continue? #{result.continue?}"
+  puts "  Result: #{result.value}"
+  puts "  Errors: #{result.errors}" if result.errors.any?
+  puts "  Permissions: #{result.context[:permissions]}" if result.context[:permissions]
+end
+
+puts "\n" + "=" * 60
+puts "Error handling examples completed!"
+puts "=" * 60

data/examples/03_middleware.rb

@@ -0,0 +1,186 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Middleware examples showing logging, instrumentation, and custom middleware
+
+puts "=" * 60
+puts "Middleware Examples"
+puts "=" * 60
+puts
+
+# Example 1: Logging middleware
+puts "Example 1: Logging Middleware"
+puts "-" * 60
+
+pipeline_with_logging = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Logging
+
+  step ->(result) {
+    result.continue(result.value * 2)
+  }
+
+  step ->(result) {
+    result.continue(result.value + 10)
+  }
+end
+
+puts "Executing pipeline with logging middleware:"
+result1 = pipeline_with_logging.call(SimpleFlow::Result.new(5))
+puts "Final result: #{result1.value}"
+puts
+
+# Example 2: Instrumentation middleware
+puts "\nExample 2: Instrumentation Middleware"
+puts "-" * 60
+
+pipeline_with_instrumentation = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Instrumentation, api_key: 'demo-key-123'
+
+  step ->(result) {
+    sleep 0.01  # Simulate work
+    result.continue(result.value.upcase)
+  }
+
+  step ->(result) {
+    sleep 0.02  # Simulate more work
+    result.continue("Processed: #{result.value}")
+  }
+end
+
+puts "Executing pipeline with instrumentation middleware:"
+result2 = pipeline_with_instrumentation.call(SimpleFlow::Result.new("data"))
+puts "Final result: #{result2.value}"
+puts
+
+# Example 3: Multiple middleware (stacked)
+puts "\nExample 3: Stacked Middleware"
+puts "-" * 60
+
+pipeline_with_multiple = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Instrumentation, api_key: 'stacked-demo'
+  use_middleware SimpleFlow::MiddleWare::Logging
+
+  step ->(result) {
+    result.continue(result.value + 5)
+  }
+
+  step ->(result) {
+    result.continue(result.value * 3)
+  }
+end
+
+puts "Executing pipeline with multiple middleware:"
+result3 = pipeline_with_multiple.call(SimpleFlow::Result.new(10))
+puts "Final result: #{result3.value}"
+puts
+
+# Example 4: Custom middleware - retry logic
+puts "\nExample 4: Custom Retry Middleware"
+puts "-" * 60
+
+class RetryMiddleware
+  def initialize(callable, max_retries: 3)
+    @callable = callable
+    @max_retries = max_retries
+  end
+
+  def call(result)
+    attempts = 0
+    begin
+      attempts += 1
+      puts "    Attempt #{attempts} of #{@max_retries}"
+      @callable.call(result)
+    rescue StandardError => e
+      if attempts < @max_retries
+        puts "    Failed (#{e.message}), retrying..."
+        retry
+      else
+        puts "    Failed after #{@max_retries} attempts"
+        result.halt.with_error(:retry, "Failed after #{@max_retries} attempts: #{e.message}")
+      end
+    end
+  end
+end
+
+# Simulated flaky operation
+attempt_count = 0
+flaky_operation = ->(result) {
+  attempt_count += 1
+  if attempt_count < 2
+    raise StandardError, "Temporary failure"
+  end
+  result.continue("Success on attempt #{attempt_count}")
+}
+
+retry_pipeline = SimpleFlow::Pipeline.new do
+  use_middleware RetryMiddleware, max_retries: 3
+  step flaky_operation
+end
+
+puts "Executing pipeline with retry middleware:"
+result4 = retry_pipeline.call(SimpleFlow::Result.new(nil))
+puts "Final result: #{result4.value}"
+puts
+
+# Example 5: Custom middleware - authentication
+puts "\nExample 5: Custom Authentication Middleware"
+puts "-" * 60
+
+class AuthMiddleware
+  def initialize(callable, required_role:)
+    @callable = callable
+    @required_role = required_role
+  end
+
+  def call(result)
+    user_role = result.context[:user_role]
+
+    unless user_role == @required_role
+      puts "    Access denied: requires #{@required_role}, got #{user_role}"
+      return result.halt.with_error(:auth, "Unauthorized: requires #{@required_role} role")
+    end
+
+    puts "    Access granted for #{@required_role}"
+    @callable.call(result)
+  end
+end
+
+auth_pipeline = SimpleFlow::Pipeline.new do
+  # First step sets the user role in context
+  step ->(result) {
+    result.with_context(:user_role, result.value[:role]).continue(result.value)
+  }
+
+  # Protected step - requires admin role
+  use_middleware AuthMiddleware, required_role: :admin
+
+  step ->(result) {
+    result.continue("Sensitive admin operation completed")
+  }
+end
+
+# Test with admin role
+puts "\nTest 1: Admin user"
+admin_result = auth_pipeline.call(
+  SimpleFlow::Result.new({ role: :admin })
+)
+puts "Continue? #{admin_result.continue?}"
+puts "Result: #{admin_result.value}"
+puts "Errors: #{admin_result.errors}"
+
+# Test with regular user
+puts "\nTest 2: Regular user"
+user_result = auth_pipeline.call(
+  SimpleFlow::Result.new({ role: :user })
+)
+puts "Continue? #{user_result.continue?}"
+puts "Result: #{user_result.value}"
+puts "Errors: #{user_result.errors}"
+
+puts "\n" + "=" * 60
+puts "Middleware examples completed!"
+puts "=" * 60

data/examples/04_parallel_automatic.rb

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Automatic parallel discovery using dependency graphs
+#
+# NOTE: You can control which concurrency model is used with the concurrency parameter:
+#   pipeline = SimpleFlow::Pipeline.new(concurrency: :threads) do ... end  # Force threads
+#   pipeline = SimpleFlow::Pipeline.new(concurrency: :async) do ... end    # Force async
+#   pipeline = SimpleFlow::Pipeline.new(concurrency: :auto) do ... end     # Auto-detect (default)
+#
+# See examples/10_concurrency_control.rb for detailed examples
+
+puts "=" * 60
+puts "Automatic Parallel Discovery"
+puts "=" * 60
+puts
+
+# Check if async is available
+if SimpleFlow::Pipeline.new.async_available?
+  puts "✓ Async gem is available - will use fiber-based concurrency"
+else
+  puts "⚠ Async gem not available - will use thread-based parallelism"
+end
+puts
+
+# Example 1: Basic parallel discovery
+puts "Example 1: Basic Parallel Execution"
+puts "-" * 60
+puts
+
+pipeline = SimpleFlow::Pipeline.new do
+  # This step has no dependencies - runs first
+  step :fetch_user, ->(result) {
+    puts "  [#{Time.now.strftime('%H:%M:%S.%L')}] Fetching user..."
+    sleep 0.1  # Simulate API call
+    result.with_context(:user, { id: result.value, name: "John Doe" }).continue(result.value)
+  }, depends_on: :none
+
+  # These two steps both depend on :fetch_user, so they can run in parallel
+  step :fetch_orders, ->(result) {
+    puts "  [#{Time.now.strftime('%H:%M:%S.%L')}] Fetching orders..."
+    sleep 0.1  # Simulate API call
+    result.with_context(:orders, [1, 2, 3]).continue(result.value)
+  }, depends_on: [:fetch_user]
+
+  step :fetch_products, ->(result) {
+    puts "  [#{Time.now.strftime('%H:%M:%S.%L')}] Fetching products..."
+    sleep 0.1  # Simulate API call
+    result.with_context(:products, [:a, :b, :c]).continue(result.value)
+  }, depends_on: [:fetch_user]
+
+  # This step depends on both parallel steps - runs last
+  step :calculate_total, ->(result) {
+    puts "  [#{Time.now.strftime('%H:%M:%S.%L')}] Calculating total..."
+    orders = result.context[:orders]
+    products = result.context[:products]
+    result.continue("Total: #{orders.size} orders, #{products.size} products")
+  }, depends_on: [:fetch_orders, :fetch_products]
+end
+
+start_time = Time.now
+result = pipeline.call_parallel(SimpleFlow::Result.new(123))
+elapsed = Time.now - start_time
+
+puts "\nResult: #{result.value}"
+puts "User: #{result.context[:user]}"
+puts "Orders: #{result.context[:orders]}"
+puts "Products: #{result.context[:products]}"
+puts "Execution time: #{(elapsed * 1000).round(2)}ms"
+puts "(Should be ~200ms with parallel, ~400ms sequential)"
+puts
+
+# Example 2: Complex dependency graph
+puts "\nExample 2: Complex Dependency Graph"
+puts "-" * 60
+puts
+
+complex_pipeline = SimpleFlow::Pipeline.new do
+  # Level 1: No dependencies
+  step :validate_input, ->(result) {
+    puts "  [Level 1] Validating input..."
+    sleep 0.05
+    result.with_context(:validated, true).continue(result.value)
+  }, depends_on: :none
+
+  # Level 2: Depends on validation (can run in parallel with each other)
+  step :check_inventory, ->(result) {
+    puts "  [Level 2] Checking inventory..."
+    sleep 0.05
+    result.with_context(:inventory, :available).continue(result.value)
+  }, depends_on: [:validate_input]
+
+  step :check_pricing, ->(result) {
+    puts "  [Level 2] Checking pricing..."
+    sleep 0.05
+    result.with_context(:price, 100).continue(result.value)
+  }, depends_on: [:validate_input]
+
+  step :check_shipping, ->(result) {
+    puts "  [Level 2] Checking shipping..."
+    sleep 0.05
+    result.with_context(:shipping, 10).continue(result.value)
+  }, depends_on: [:validate_input]
+
+  # Level 3: Depends on inventory and pricing (runs after level 2)
+  step :calculate_discount, ->(result) {
+    puts "  [Level 3] Calculating discount..."
+    sleep 0.05
+    price = result.context[:price]
+    result.with_context(:discount, price * 0.1).continue(result.value)
+  }, depends_on: [:check_inventory, :check_pricing]
+
+  # Level 4: Final step (depends on everything)
+  step :finalize_order, ->(result) {
+    puts "  [Level 4] Finalizing order..."
+    price = result.context[:price]
+    shipping = result.context[:shipping]
+    discount = result.context[:discount]
+    total = price + shipping - discount
+    result.continue("Order total: $#{total}")
+  }, depends_on: [:calculate_discount, :check_shipping]
+end
+
+puts "Dependency graph structure:"
+puts "  Level 1: validate_input"
+puts "  Level 2: check_inventory, check_pricing, check_shipping (parallel)"
+puts "  Level 3: calculate_discount"
+puts "  Level 4: finalize_order"
+puts
+
+start_time = Time.now
+result2 = complex_pipeline.call_parallel(SimpleFlow::Result.new({ product_id: 456 }))
+elapsed2 = Time.now - start_time
+
+puts "\nResult: #{result2.value}"
+puts "Context: #{result2.context}"
+puts "Execution time: #{(elapsed2 * 1000).round(2)}ms"
+puts
+
+# Example 3: Visualizing the dependency graph
+puts "\nExample 3: Dependency Graph Analysis"
+puts "-" * 60
+puts
+
+# Create a graph manually to show analysis
+graph = SimpleFlow::DependencyGraph.new(
+  fetch_user: [],
+  fetch_orders: [:fetch_user],
+  fetch_products: [:fetch_user],
+  fetch_reviews: [:fetch_user],
+  calculate_stats: [:fetch_orders, :fetch_products],
+  generate_report: [:calculate_stats, :fetch_reviews]
+)
+
+puts "Dependencies:"
+graph.dependencies.each do |step, deps|
+  deps_str = deps.empty? ? "(none)" : deps.join(", ")
+  puts "  #{step}: #{deps_str}"
+end
+
+puts "\nSequential order:"
+puts "  #{graph.order.join(' → ')}"
+
+puts "\nParallel execution groups:"
+graph.parallel_order.each_with_index do |group, index|
+  puts "  Group #{index + 1}: #{group.join(', ')}"
+end
+
+puts "\nExecution strategy:"
+puts "  • fetch_user runs first (no dependencies)"
+puts "  • fetch_orders, fetch_products, fetch_reviews run in parallel"
+puts "  • calculate_stats waits for orders and products"
+puts "  • generate_report waits for stats and reviews"
+puts
+
+# Example 4: Error handling in parallel steps
+puts "\nExample 4: Error Handling in Parallel Execution"
+puts "-" * 60
+puts
+
+error_pipeline = SimpleFlow::Pipeline.new do
+  step :task_a, ->(result) {
+    puts "  Task A: Processing..."
+    sleep 0.05
+    result.with_context(:task_a, :success).continue(result.value)
+  }, depends_on: :none
+
+  step :task_b, ->(result) {
+    puts "  Task B: Processing..."
+    sleep 0.05
+    # Simulate a failure
+    result.halt.with_error(:task_b, "Task B encountered an error")
+  }, depends_on: :none
+
+  step :task_c, ->(result) {
+    puts "  Task C: Processing..."
+    sleep 0.05
+    result.with_context(:task_c, :success).continue(result.value)
+  }, depends_on: :none
+
+  step :final_step, ->(result) {
+    puts "  Final step: This should not execute"
+    result.continue("Completed")
+  }, depends_on: [:task_a, :task_b, :task_c]
+end
+
+result3 = error_pipeline.call_parallel(SimpleFlow::Result.new(nil))
+
+puts "\nResult:"
+puts "  Continue? #{result3.continue?}"
+puts "  Errors: #{result3.errors}"
+puts "  Context: #{result3.context}"
+puts "  Note: Pipeline halted when task_b failed, preventing final_step"
+
+puts "\n" + "=" * 60
+puts "Automatic parallel discovery examples completed!"
+puts "=" * 60