simple_flow 0.1.0

data/docs/core-concepts/middleware.md

@@ -0,0 +1,389 @@
+# Middleware
+
+Middleware provides a way to add cross-cutting concerns to your pipeline without modifying individual steps.
+
+## Overview
+
+Middleware wraps steps using the decorator pattern, allowing you to:
+
+- Log step execution
+- Measure performance
+- Add authentication/authorization
+- Handle retries
+- Cache results
+- Track metrics
+
+## Built-in Middleware
+
+### Logging Middleware
+
+Logs before and after each step execution:
+
+```ruby
+require 'simple_flow'
+
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Logging
+
+  step ->(result) { result.continue(process_data(result.value)) }
+  step ->(result) { result.continue(validate_data(result.value)) }
+end
+```
+
+Output:
+```
+[SimpleFlow] Before step: #<Proc:0x00007f8b1c0b4f00>
+[SimpleFlow] After step: #<Proc:0x00007f8b1c0b4f00>
+[SimpleFlow] Before step: #<Proc:0x00007f8b1c0b5200>
+[SimpleFlow] After step: #<Proc:0x00007f8b1c0b5200>
+```
+
+### Instrumentation Middleware
+
+Measures execution time and tracks API usage:
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Instrumentation, api_key: 'my-app-key'
+
+  step ->(result) { result.continue(fetch_data(result.value)) }
+  step ->(result) { result.continue(process_data(result.value)) }
+end
+```
+
+Output:
+```
+Instrumentation: my-app-key took 0.0423s
+Instrumentation: my-app-key took 0.0156s
+```
+
+## Creating Custom Middleware
+
+Middleware is any class that:
+
+1. Accepts a `callable` and optional `options` in its initializer
+2. Implements a `call(result)` method
+3. Calls `@callable.call(result)` to execute the wrapped step
+
+### Basic Template
+
+```ruby
+class MyMiddleware
+  def initialize(callable, **options)
+    @callable = callable
+    @options = options
+  end
+
+  def call(result)
+    # Before logic
+    puts "Before step with options: #{@options.inspect}"
+
+    # Execute the step
+    result = @callable.call(result)
+
+    # After logic
+    puts "After step, value: #{result.value.inspect}"
+
+    result
+  end
+end
+```
+
+### Example: Retry Middleware
+
+```ruby
+class RetryMiddleware
+  def initialize(callable, max_retries: 3, backoff: 1.0)
+    @callable = callable
+    @max_retries = max_retries
+    @backoff = backoff
+  end
+
+  def call(result)
+    attempts = 0
+
+    begin
+      @callable.call(result)
+    rescue StandardError => e
+      attempts += 1
+
+      if attempts < @max_retries
+        sleep(@backoff * attempts)
+        retry
+      else
+        result.with_error(:retry_exhausted, e.message).halt
+      end
+    end
+  end
+end
+
+# Usage
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware RetryMiddleware, max_retries: 5, backoff: 2.0
+
+  step ->(result) {
+    # This will be retried up to 5 times
+    data = unreliable_api_call(result.value)
+    result.continue(data)
+  }
+end
+```
+
+### Example: Authentication Middleware
+
+```ruby
+class AuthenticationMiddleware
+  def initialize(callable, required_role: nil)
+    @callable = callable
+    @required_role = required_role
+  end
+
+  def call(result)
+    user = result.context[:current_user]
+
+    unless user
+      return result
+        .with_error(:authentication, 'User not authenticated')
+        .halt
+    end
+
+    if @required_role && !user.has_role?(@required_role)
+      return result
+        .with_error(:authorization, "Requires #{@required_role} role")
+        .halt
+    end
+
+    @callable.call(result)
+  end
+end
+
+# Usage
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware AuthenticationMiddleware, required_role: :admin
+
+  step ->(result) {
+    # This only runs if user is authenticated and has admin role
+    result.continue(sensitive_operation(result.value))
+  }
+end
+```
+
+### Example: Caching Middleware
+
+```ruby
+class CachingMiddleware
+  def initialize(callable, cache:, ttl: 3600)
+    @callable = callable
+    @cache = cache
+    @ttl = ttl
+  end
+
+  def call(result)
+    cache_key = generate_cache_key(result)
+
+    # Try cache first
+    if cached = @cache.get(cache_key)
+      return result
+        .continue(cached)
+        .with_context(:cache_hit, true)
+    end
+
+    # Execute step
+    result = @callable.call(result)
+
+    # Cache the result
+    @cache.set(cache_key, result.value, ttl: @ttl) if result.continue?
+
+    result.with_context(:cache_hit, false)
+  end
+
+  private
+
+  def generate_cache_key(result)
+    Digest::MD5.hexdigest(result.value.to_json)
+  end
+end
+
+# Usage
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware CachingMiddleware, cache: Redis.new, ttl: 1800
+
+  step ->(result) {
+    # Expensive operation that will be cached
+    data = expensive_database_query(result.value)
+    result.continue(data)
+  }
+end
+```
+
+## Middleware Order
+
+Middleware is applied in reverse order (last declared = innermost wrapper):
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware MiddlewareA  # Applied third (outermost)
+  use_middleware MiddlewareB  # Applied second
+  use_middleware MiddlewareC  # Applied first (innermost)
+
+  step ->(result) { result.continue('data') }
+end
+```
+
+Execution order:
+```
+MiddlewareA before
+  MiddlewareB before
+    MiddlewareC before
+      Step executes
+    MiddlewareC after
+  MiddlewareB after
+MiddlewareA after
+```
+
+## Combining Multiple Middleware
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  # Logging (outermost)
+  use_middleware SimpleFlow::MiddleWare::Logging
+
+  # Authentication
+  use_middleware AuthenticationMiddleware, required_role: :user
+
+  # Caching
+  use_middleware CachingMiddleware, cache: Rails.cache
+
+  # Retry logic
+  use_middleware RetryMiddleware, max_retries: 3
+
+  # Instrumentation (innermost)
+  use_middleware SimpleFlow::MiddleWare::Instrumentation, api_key: 'app'
+
+  step ->(result) { result.continue(process(result.value)) }
+end
+```
+
+## Conditional Middleware
+
+Apply middleware based on conditions:
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Logging if ENV['DEBUG']
+  use_middleware CachingMiddleware, cache: cache if Rails.env.production?
+
+  step ->(result) { result.continue(process(result.value)) }
+end
+```
+
+## Testing Middleware
+
+```ruby
+require 'minitest/autorun'
+
+class MyMiddlewareTest < Minitest::Test
+  def test_middleware_execution
+    step = ->(result) { result.continue('processed') }
+    middleware = MyMiddleware.new(step, option: 'value')
+
+    input = SimpleFlow::Result.new('input')
+    output = middleware.call(input)
+
+    assert_equal 'processed', output.value
+  end
+
+  def test_middleware_adds_context
+    step = ->(result) { result.continue(result.value) }
+    middleware = TimingMiddleware.new(step)
+
+    input = SimpleFlow::Result.new('data')
+    output = middleware.call(input)
+
+    assert output.context[:execution_time]
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep middleware focused**: Each middleware should handle one concern
+2. **Preserve the result**: Always call `@callable.call(result)`
+3. **Don't swallow errors**: Let exceptions propagate unless you're handling retries
+4. **Use context for metadata**: Add timing, cache hits, etc. to context
+5. **Make options explicit**: Use keyword arguments for clarity
+6. **Test in isolation**: Middleware should be independently testable
+7. **Document side effects**: Clearly document any state changes
+
+## Common Use Cases
+
+### Performance Monitoring
+
+```ruby
+class PerformanceMiddleware
+  def initialize(callable, threshold: 1.0)
+    @callable = callable
+    @threshold = threshold
+  end
+
+  def call(result)
+    start_time = Time.now
+    result = @callable.call(result)
+    duration = Time.now - start_time
+
+    if duration > @threshold
+      warn "Slow step: #{duration}s (threshold: #{@threshold}s)"
+    end
+
+    result.with_context(:duration, duration)
+  end
+end
+```
+
+### Error Enrichment
+
+```ruby
+class ErrorEnrichmentMiddleware
+  def initialize(callable)
+    @callable = callable
+  end
+
+  def call(result)
+    @callable.call(result)
+  rescue StandardError => e
+    result
+      .with_error(:exception, e.message)
+      .with_context(:exception_class, e.class.name)
+      .with_context(:backtrace, e.backtrace.first(5))
+      .halt
+  end
+end
+```
+
+### Request ID Tracking
+
+```ruby
+class RequestIDMiddleware
+  def initialize(callable)
+    @callable = callable
+  end
+
+  def call(result)
+    request_id = result.context[:request_id] || SecureRandom.uuid
+
+    result_with_id = result.with_context(:request_id, request_id)
+
+    Thread.current[:request_id] = request_id
+    result = @callable.call(result_with_id)
+    Thread.current[:request_id] = nil
+
+    result
+  end
+end
+```
+
+## Next Steps
+
+- [Pipeline](pipeline.md) - Learn how middleware integrates with pipelines
+- [Flow Control](flow-control.md) - Controlling execution flow
+- [Error Handling Guide](../guides/error-handling.md) - Comprehensive error strategies

data/docs/core-concepts/overview.md

@@ -0,0 +1,219 @@
+# Core Concepts
+
+Understanding SimpleFlow's fundamental concepts will help you build robust pipelines.
+
+## Architecture
+
+SimpleFlow is built on four core components:
+
+```mermaid
+graph TD
+    A[Result] -->|passed to| B[Step]
+    B -->|transformed by| C[Middleware]
+    C -->|orchestrated by| D[Pipeline]
+    D -->|produces| A
+```
+
+### 1. Result
+
+An **immutable value object** that carries:
+- **Value**: The data being processed
+- **Context**: Metadata accumulated during processing
+- **Errors**: Validation or processing errors
+- **Continue Flag**: Whether to continue pipeline execution
+
+[Learn more about Results](result.md)
+
+### 2. Step
+
+A **callable object** (usually a lambda) that:
+- Receives a Result
+- Performs some operation
+- Returns a new Result
+
+[Learn more about Steps](steps.md)
+
+### 3. Pipeline
+
+An **orchestrator** that:
+- Holds a sequence of steps
+- Applies middleware to steps
+- Executes steps in order
+- Short-circuits on halt
+
+[Learn more about Pipelines](pipeline.md)
+
+### 4. Middleware
+
+A **decorator** that:
+- Wraps steps with additional behavior
+- Adds cross-cutting concerns (logging, timing, etc.)
+- Applied in reverse order to all steps
+
+[Learn more about Middleware](middleware.md)
+
+## Data Flow
+
+Here's how data flows through a pipeline:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Pipeline
+    participant Middleware
+    participant Step
+    participant Result
+
+    Client->>Pipeline: call(initial_result)
+    Pipeline->>Middleware: wrap steps
+    loop Each Step
+        Pipeline->>Step: call(result)
+        Step->>Result: transform
+        Result-->>Step: new result
+        Step-->>Pipeline: new result
+        alt continue?
+            Pipeline->>Pipeline: next step
+        else halted
+            Pipeline-->>Client: final result
+        end
+    end
+    Pipeline-->>Client: final result
+```
+
+## Key Principles
+
+### Immutability
+
+Results are **never modified**, only **copied with changes**:
+
+```ruby
+original = SimpleFlow::Result.new(42)
+updated = original.continue(43)
+
+original.value  # => 42 (unchanged)
+updated.value   # => 43 (new object)
+```
+
+This makes pipelines thread-safe and easier to reason about.
+
+### Composability
+
+Steps are **simple, reusable functions**:
+
+```ruby
+# Define reusable steps
+validate_email = ->(result) { ... }
+validate_age = ->(result) { ... }
+validate_password = ->(result) { ... }
+
+# Compose into pipelines
+pipeline1 = SimpleFlow::Pipeline.new do
+  step validate_email
+  step validate_age
+end
+
+pipeline2 = SimpleFlow::Pipeline.new do
+  step validate_email
+  step validate_password
+end
+```
+
+### Flow Control
+
+Steps decide whether the pipeline should **continue or halt**:
+
+```ruby
+step ->(result) {
+  if condition_met?
+    result.continue(new_value)  # Continue to next step
+  else
+    result.halt(value).with_error(:key, "message")  # Stop pipeline
+  end
+}
+```
+
+### Context Accumulation
+
+Metadata accumulates across steps:
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) { result.with_context(:step1, "data").continue(result.value) }
+  step ->(result) { result.with_context(:step2, "more").continue(result.value) }
+end
+
+result = pipeline.call(SimpleFlow::Result.new(42))
+result.context  # => {:step1=>"data", :step2=>"more"}
+```
+
+## Design Patterns
+
+SimpleFlow implements several design patterns:
+
+### Pipeline Pattern
+Sequential processing with short-circuit capability.
+
+### Decorator Pattern
+Middleware wraps steps to add behavior without modifying them.
+
+### Immutable Value Object
+Results are never modified, preventing side effects.
+
+### Builder Pattern
+DSL for intuitive pipeline configuration.
+
+### Chain of Responsibility
+Each step can handle or pass along the result.
+
+## Common Patterns
+
+### Validation Pipeline
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) { validate_required_fields(result) }
+  step ->(result) { validate_format(result) }
+  step ->(result) { validate_business_rules(result) }
+
+  step ->(result) {
+    # Halt if any errors accumulated
+    result.errors.any? ? result.halt : result.continue(result.value)
+  }
+end
+```
+
+### Data Transformation Pipeline
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) { parse_input(result) }
+  step ->(result) { transform_data(result) }
+  step ->(result) { format_output(result) }
+end
+```
+
+### Enrichment Pipeline
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) { fetch_base_data(result) }
+
+  parallel do
+    step ->(result) { enrich_with_user_data(result) }
+    step ->(result) { enrich_with_order_data(result) }
+    step ->(result) { enrich_with_analytics(result) }
+  end
+
+  step ->(result) { aggregate_enrichments(result) }
+end
+```
+
+## Next Steps
+
+Explore each component in detail:
+
+- [Result API](result.md) - Immutable value objects
+- [Pipeline API](pipeline.md) - Orchestrating steps
+- [Steps Guide](steps.md) - Writing effective steps
+- [Middleware Guide](middleware.md) - Cross-cutting concerns
+- [Flow Control](flow-control.md) - Halting and continuing