simple_flow 0.1.0

data/examples/05_parallel_explicit.rb

@@ -0,0 +1,279 @@
+#!/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))
+
+# Explicit parallel blocks
+#
+# 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 "Explicit Parallel Blocks"
+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 block
+puts "Example 1: Basic Parallel Block"
+puts "-" * 60
+puts
+
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  [Sequential] Pre-processing input..."
+    result.continue(result.value)
+  }
+
+  parallel do
+    step ->(result) {
+      puts "  [Parallel A] Fetching from API..."
+      sleep 0.1
+      result.with_context(:api_data, { status: "ok" }).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Parallel B] Fetching from cache..."
+      sleep 0.1
+      result.with_context(:cache_data, { cached: true }).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Parallel C] Fetching from database..."
+      sleep 0.1
+      result.with_context(:db_data, { records: 10 }).continue(result.value)
+    }
+  end
+
+  step ->(result) {
+    puts "  [Sequential] Post-processing results..."
+    merged = {
+      api: result.context[:api_data],
+      cache: result.context[:cache_data],
+      db: result.context[:db_data]
+    }
+    result.continue(merged)
+  }
+end
+
+start_time = Time.now
+result = pipeline.call(SimpleFlow::Result.new("data"))
+elapsed = Time.now - start_time
+
+puts "\nResult: #{result.value}"
+puts "Execution time: #{(elapsed * 1000).round(2)}ms"
+puts "(Should be ~100ms with parallel, ~300ms sequential)"
+puts
+
+# Example 2: Multiple parallel blocks
+puts "\nExample 2: Multiple Parallel Blocks"
+puts "-" * 60
+puts
+
+multi_parallel_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  [Step 1] Initialize"
+    result.continue(result.value)
+  }
+
+  parallel do
+    step ->(result) {
+      puts "  [Block 1.A] Validate email"
+      sleep 0.05
+      result.with_context(:email_valid, true).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Block 1.B] Validate phone"
+      sleep 0.05
+      result.with_context(:phone_valid, true).continue(result.value)
+    }
+  end
+
+  step ->(result) {
+    puts "  [Step 2] Process validations"
+    result.continue(result.value)
+  }
+
+  parallel do
+    step ->(result) {
+      puts "  [Block 2.A] Send email notification"
+      sleep 0.05
+      result.with_context(:email_sent, true).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Block 2.B] Send SMS notification"
+      sleep 0.05
+      result.with_context(:sms_sent, true).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Block 2.C] Log to database"
+      sleep 0.05
+      result.with_context(:logged, true).continue(result.value)
+    }
+  end
+
+  step ->(result) {
+    puts "  [Step 3] Finalize"
+    result.continue("All notifications sent")
+  }
+end
+
+start_time = Time.now
+result2 = multi_parallel_pipeline.call(SimpleFlow::Result.new(nil))
+elapsed2 = Time.now - start_time
+
+puts "\nResult: #{result2.value}"
+puts "Context: #{result2.context}"
+puts "Execution time: #{(elapsed2 * 1000).round(2)}ms"
+puts
+
+# Example 3: Mixing named and parallel blocks
+puts "\nExample 3: Mixed Execution Styles"
+puts "-" * 60
+puts
+
+mixed_pipeline = SimpleFlow::Pipeline.new do
+  # Traditional unnamed step
+  step ->(result) {
+    puts "  [Unnamed] Starting workflow..."
+    result.continue(result.value)
+  }
+
+  # Named steps with dependencies
+  step :fetch_config, ->(result) {
+    puts "  [Named] Fetching configuration..."
+    sleep 0.05
+    result.with_context(:config, { timeout: 30 }).continue(result.value)
+  }, depends_on: :none
+
+  # Explicit parallel block
+  parallel do
+    step ->(result) {
+      puts "  [Parallel] Processing batch 1..."
+      sleep 0.05
+      result.with_context(:batch1, :done).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Parallel] Processing batch 2..."
+      sleep 0.05
+      result.with_context(:batch2, :done).continue(result.value)
+    }
+  end
+
+  # Another unnamed step
+  step ->(result) {
+    puts "  [Unnamed] Finalizing..."
+    result.continue("Workflow complete")
+  }
+end
+
+result3 = mixed_pipeline.call(SimpleFlow::Result.new(nil))
+puts "\nResult: #{result3.value}"
+puts "Context: #{result3.context}"
+puts
+
+# Example 4: Error handling in parallel blocks
+puts "\nExample 4: Error Handling in Parallel Blocks"
+puts "-" * 60
+puts
+
+error_handling_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    puts "  [Pre] Starting operations..."
+    result.continue(result.value)
+  }
+
+  parallel do
+    step ->(result) {
+      puts "  [Parallel A] Running successfully..."
+      sleep 0.05
+      result.with_context(:task_a, :success).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Parallel B] Encountering error..."
+      sleep 0.05
+      result.halt.with_error(:task_b, "Failed to process batch")
+    }
+
+    step ->(result) {
+      puts "  [Parallel C] Running successfully..."
+      sleep 0.05
+      result.with_context(:task_c, :success).continue(result.value)
+    }
+  end
+
+  step ->(result) {
+    puts "  [Post] This should not execute when parallel block halts"
+    result.continue("Completed")
+  }
+end
+
+result4 = error_handling_pipeline.call(SimpleFlow::Result.new(nil))
+
+puts "\nResult:"
+puts "  Continue? #{result4.continue?}"
+puts "  Value: #{result4.value}"
+puts "  Errors: #{result4.errors}"
+puts "  Context: #{result4.context}"
+puts "  Note: Pipeline halted due to error in parallel block"
+puts
+
+# Example 5: Performance comparison
+puts "\nExample 5: Performance Comparison"
+puts "-" * 60
+puts
+
+# Sequential version
+sequential_pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+  step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+  step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+  step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+end
+
+# Parallel version
+parallel_pipeline = SimpleFlow::Pipeline.new do
+  parallel do
+    step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+    step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+    step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+    step ->(result) { sleep 0.1; result.continue(result.value + 1) }
+  end
+end
+
+puts "Running sequential pipeline (4 steps @ 100ms each)..."
+sequential_start = Time.now
+sequential_result = sequential_pipeline.call(SimpleFlow::Result.new(0))
+sequential_time = Time.now - sequential_start
+
+puts "Running parallel pipeline (4 steps @ 100ms each in parallel)..."
+parallel_start = Time.now
+parallel_result = parallel_pipeline.call(SimpleFlow::Result.new(0))
+parallel_time = Time.now - parallel_start
+
+puts "\nResults:"
+puts "  Sequential: #{(sequential_time * 1000).round(2)}ms (expected ~400ms)"
+puts "  Parallel:   #{(parallel_time * 1000).round(2)}ms (expected ~100ms)"
+puts "  Speedup:    #{(sequential_time / parallel_time).round(2)}x"
+
+puts "\n" + "=" * 60
+puts "Explicit parallel blocks examples completed!"
+puts "=" * 60

data/examples/06_real_world_ecommerce.rb

@@ -0,0 +1,288 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'json'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Real-world example: E-commerce order processing pipeline
+
+puts "=" * 60
+puts "Real-World Example: E-commerce Order Processing"
+puts "=" * 60
+puts
+
+# Simulate external services
+class InventoryService
+  def self.check_availability(product_id)
+    sleep 0.05  # Simulate API call
+    { product_id: product_id, available: true, quantity: 100 }
+  end
+
+  def self.reserve_items(items)
+    sleep 0.05
+    { reservation_id: "RES-#{rand(10000)}", items: items }
+  end
+end
+
+class PaymentService
+  def self.process_payment(amount, card_token)
+    sleep 0.1  # Simulate payment processing
+    if card_token.start_with?("tok_")
+      { transaction_id: "TXN-#{rand(10000)}", status: :success, amount: amount }
+    else
+      { status: :failed, reason: "Invalid card token" }
+    end
+  end
+end
+
+class ShippingService
+  def self.calculate_shipping(address, items)
+    sleep 0.05
+    { cost: 10.00, estimated_days: 3 }
+  end
+
+  def self.create_shipment(order_id, address)
+    sleep 0.05
+    { tracking_number: "TRACK-#{rand(10000)}", carrier: "FastShip" }
+  end
+end
+
+class NotificationService
+  def self.send_email(to, subject, body)
+    sleep 0.02
+    puts "    📧 Email sent to #{to}: #{subject}"
+    { sent: true, message_id: "MSG-#{rand(10000)}" }
+  end
+
+  def self.send_sms(phone, message)
+    sleep 0.02
+    puts "    📱 SMS sent to #{phone}: #{message}"
+    { sent: true }
+  end
+end
+
+# Build the order processing pipeline
+order_pipeline = SimpleFlow::Pipeline.new do
+  # Step 1: Validate order
+  step :validate_order, ->(result) {
+    puts "  ✓ Validating order..."
+    order = result.value
+
+    # Check required fields
+    errors = []
+    errors << "Missing customer email" unless order[:customer][:email]
+    errors << "No items in order" if order[:items].empty?
+    errors << "Missing payment method" unless order[:payment][:card_token]
+
+    if errors.any?
+      return result.halt.with_error(:validation, errors.join(", "))
+    end
+
+    result.with_context(:validated_at, Time.now).continue(order)
+  }, depends_on: :none
+
+  # Step 2 & 3: Run in parallel - check inventory and calculate shipping
+  step :check_inventory, ->(result) {
+    puts "  ✓ Checking inventory..."
+    order = result.value
+    inventory_results = order[:items].map do |item|
+      InventoryService.check_availability(item[:product_id])
+    end
+
+    if inventory_results.all? { |r| r[:available] }
+      result.with_context(:inventory_check, inventory_results).continue(order)
+    else
+      result.halt.with_error(:inventory, "Some items are out of stock")
+    end
+  }, depends_on: [:validate_order]
+
+  step :calculate_shipping, ->(result) {
+    puts "  ✓ Calculating shipping..."
+    order = result.value
+    shipping = ShippingService.calculate_shipping(
+      order[:shipping_address],
+      order[:items]
+    )
+    result.with_context(:shipping, shipping).continue(order)
+  }, depends_on: [:validate_order]
+
+  # Step 4: Calculate totals (waits for inventory and shipping)
+  step :calculate_totals, ->(result) {
+    puts "  ✓ Calculating totals..."
+    order = result.value
+    shipping = result.context[:shipping]
+
+    subtotal = order[:items].sum { |item| item[:price] * item[:quantity] }
+    tax = subtotal * 0.08
+    total = subtotal + tax + shipping[:cost]
+
+    result
+      .with_context(:subtotal, subtotal)
+      .with_context(:tax, tax)
+      .with_context(:total, total)
+      .continue(order)
+  }, depends_on: [:check_inventory, :calculate_shipping]
+
+  # Step 5: Process payment
+  step :process_payment, ->(result) {
+    puts "  ✓ Processing payment..."
+    order = result.value
+    total = result.context[:total]
+
+    payment_result = PaymentService.process_payment(
+      total,
+      order[:payment][:card_token]
+    )
+
+    if payment_result[:status] == :success
+      result.with_context(:payment, payment_result).continue(order)
+    else
+      result.halt.with_error(:payment, payment_result[:reason])
+    end
+  }, depends_on: [:calculate_totals]
+
+  # Step 6: Reserve inventory
+  step :reserve_inventory, ->(result) {
+    puts "  ✓ Reserving inventory..."
+    order = result.value
+    reservation = InventoryService.reserve_items(order[:items])
+    result.with_context(:reservation, reservation).continue(order)
+  }, depends_on: [:process_payment]
+
+  # Step 7: Create shipment
+  step :create_shipment, ->(result) {
+    puts "  ✓ Creating shipment..."
+    order = result.value
+    shipment = ShippingService.create_shipment(
+      order[:order_id],
+      order[:shipping_address]
+    )
+    result.with_context(:shipment, shipment).continue(order)
+  }, depends_on: [:reserve_inventory]
+
+  # Step 8 & 9: Send notifications in parallel
+  step :send_email_confirmation, ->(result) {
+    puts "  ✓ Sending email confirmation..."
+    order = result.value
+    total = result.context[:total]
+    tracking = result.context[:shipment][:tracking_number]
+
+    NotificationService.send_email(
+      order[:customer][:email],
+      "Order Confirmed",
+      "Your order ##{order[:order_id]} for $#{total.round(2)} has been confirmed. Tracking: #{tracking}"
+    )
+
+    result.continue(order)
+  }, depends_on: [:create_shipment]
+
+  step :send_sms_confirmation, ->(result) {
+    puts "  ✓ Sending SMS confirmation..."
+    order = result.value
+    tracking = result.context[:shipment][:tracking_number]
+
+    if order[:customer][:phone]
+      NotificationService.send_sms(
+        order[:customer][:phone],
+        "Order confirmed! Tracking: #{tracking}"
+      )
+    end
+
+    result.continue(order)
+  }, depends_on: [:create_shipment]
+
+  # Step 10: Finalize order
+  step :finalize_order, ->(result) {
+    puts "  ✓ Finalizing order..."
+    order = result.value
+
+    final_order = {
+      order_id: order[:order_id],
+      status: :confirmed,
+      total: result.context[:total],
+      payment_transaction: result.context[:payment][:transaction_id],
+      tracking_number: result.context[:shipment][:tracking_number],
+      estimated_delivery_days: result.context[:shipping][:estimated_days]
+    }
+
+    result.continue(final_order)
+  }, depends_on: [:send_email_confirmation, :send_sms_confirmation]
+end
+
+# Example order data
+order = {
+  order_id: "ORD-#{rand(10000)}",
+  customer: {
+    email: "customer@example.com",
+    phone: "+1-555-0123"
+  },
+  items: [
+    { product_id: 101, name: "Widget", price: 29.99, quantity: 2 },
+    { product_id: 102, name: "Gadget", price: 49.99, quantity: 1 }
+  ],
+  shipping_address: {
+    street: "123 Main St",
+    city: "Springfield",
+    state: "IL",
+    zip: "62701"
+  },
+  payment: {
+    card_token: "tok_valid_card_123"
+  }
+}
+
+puts "\nProcessing order: #{order[:order_id]}"
+puts "Items: #{order[:items].size} items totaling $#{order[:items].sum { |i| i[:price] * i[:quantity] }}"
+puts
+
+start_time = Time.now
+result = order_pipeline.call_parallel(SimpleFlow::Result.new(order))
+elapsed = Time.now - start_time
+
+puts "\n" + "=" * 60
+if result.continue?
+  puts "✅ Order processed successfully!"
+  puts "=" * 60
+  puts "\nOrder Details:"
+  puts "  Order ID: #{result.value[:order_id]}"
+  puts "  Status: #{result.value[:status]}"
+  puts "  Total: $#{result.value[:total].round(2)}"
+  puts "  Transaction: #{result.value[:payment_transaction]}"
+  puts "  Tracking: #{result.value[:tracking_number]}"
+  puts "  Estimated Delivery: #{result.value[:estimated_delivery_days]} days"
+  puts "\nProcessing time: #{(elapsed * 1000).round(2)}ms"
+else
+  puts "❌ Order processing failed"
+  puts "=" * 60
+  puts "\nErrors:"
+  result.errors.each do |category, messages|
+    puts "  #{category}: #{messages.join(', ')}"
+  end
+end
+
+# Test with invalid order
+puts "\n\n" + "=" * 60
+puts "Testing with invalid order (missing payment)..."
+puts "=" * 60
+puts
+
+invalid_order = order.dup
+invalid_order[:payment][:card_token] = "invalid_token"
+
+result2 = order_pipeline.call_parallel(SimpleFlow::Result.new(invalid_order))
+
+if result2.continue?
+  puts "✅ Order processed"
+else
+  puts "❌ Order failed (as expected)"
+  puts "\nErrors:"
+  result2.errors.each do |category, messages|
+    puts "  #{category}: #{messages.join(', ')}"
+  end
+end
+
+puts "\n" + "=" * 60
+puts "E-commerce example completed!"
+puts "=" * 60