Order Workflow: A Practical Guide to Effect Composition

"The major difference between a thing that might go wrong and a thing that cannot possibly go wrong is that when a thing that cannot possibly go wrong goes wrong, it usually turns out to be impossible to get at or repair."

— Douglas Adams, Mostly Harmless

Enterprise software can be like this. Consider order processing. Every step can fail. Every failure has a type. Every type demands a different response. And when you have nested enough try-catch blocks inside enough null checks inside enough if statements, the thing that cannot possibly go wrong becomes the thing you cannot possibly debug.

This walkthrough demonstrates how to build a robust, multi-step order workflow using the Effect Path API and Focus DSL. You will see how typed errors, composable operations, and functional patterns transform the pyramid of doom into a railway of clarity.

What You'll Learn

Composing multi-step workflows with EitherPath and via() chains
Modelling domain errors with sealed interfaces for exhaustive handling
Using ForPath comprehensions for readable sequential composition
Implementing resilience patterns: retry policies, timeouts, and recovery
Scaling with structured concurrency, resource management, and virtual threads
Adapting these patterns to your own domain

In This Chapter

Effect Composition – The core patterns for building workflows: sealed error hierarchies for type-safe error handling, via() chains for sequential composition, ForPath comprehensions for readable syntax, and recovery patterns for graceful degradation.
Production Patterns – Making workflows production-ready: retry policies with exponential backoff, timeouts for external services, Focus DSL for immutable state updates, feature flags for configuration, and code generation to eliminate boilerplate.
Concurrency and Scale – Patterns for high-throughput systems: context propagation with ScopedValue for cross-cutting concerns, structured concurrency with Scope for parallel operations, resource management with the bracket pattern, and virtual thread execution for massive scale.

See Example Code

OrderWorkflow.java - Main workflow implementation
ConfigurableOrderWorkflow.java - Feature flags and resilience
EnhancedOrderWorkflow.java - Concurrency patterns
OrderError.java - Sealed error hierarchy

The Territory: Why Order Workflows Are Hard

Consider a typical e-commerce order flow:

┌─────────────────────────────────────────────────────────────────────────┐
│                        ORDER PROCESSING PIPELINE                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   Request ──▶ Validate ──▶ Customer ──▶ Inventory ──▶ Discount          │
│                  │            │            │            │               │
│                  ▼            ▼            ▼            ▼               │
│              Address?     Exists?      In Stock?    Valid Code?         │
│              Postcode?    Eligible?    Reserved?    Loyalty Tier?       │
│                                                                         │
│   ──▶ Payment ──▶ Shipment ──▶ Notification ──▶ Result                  │
│          │           │             │                                    │
│          ▼           ▼             ▼                                    │
│       Approved?   Created?     Sent?                                    │
│       Funds?      Carrier?     (non-critical)                           │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Each step can fail for specific, typed reasons. Traditional Java handles this with a patchwork of approaches:

// The pyramid of doom
public OrderResult processOrder(OrderRequest request) {
    if (request == null) {
        return OrderResult.error("Request is null");
    }
    try {
        var address = validateAddress(request.address());
        if (address == null) {
            return OrderResult.error("Invalid address");
        }
        var customer = customerService.find(request.customerId());
        if (customer == null) {
            return OrderResult.error("Customer not found");
        }
        try {
            var inventory = inventoryService.reserve(request.items());
            if (!inventory.isSuccess()) {
                return OrderResult.error(inventory.getReason());
            }
            // ... and so on, ever deeper
        } catch (InventoryException e) {
            return OrderResult.error("Inventory error: " + e.getMessage());
        }
    } catch (ValidationException e) {
        return OrderResult.error("Validation error: " + e.getMessage());
    }
}

The problems multiply:

Issue	Consequence
Mixed idioms	Nulls, exceptions, and booleans do not compose
Nested structure	Business logic buried under error handling
String errors	No type safety, no exhaustive matching
Repeated patterns	Each step reinvents error propagation

The Map: Effect Path Tames Complexity

The Effect Path API provides a unified approach. Here is the same workflow:

public EitherPath<OrderError, OrderResult> process(OrderRequest request) {
    return validateShippingAddress(request.shippingAddress())
        .via(validAddress ->
            lookupAndValidateCustomer(request.customerId())
                .via(customer ->
                    buildValidatedOrder(request, customer, validAddress)
                        .via(order -> processOrderCore(order, customer))));
}

The transformation is dramatic:

Flat structure: Each step chains to the next with via()
Typed errors: OrderError is a sealed interface; the compiler ensures exhaustive handling
Automatic propagation: Failures short-circuit; no explicit checks required
Composable: Each step returns EitherPath<OrderError, T>, so they combine naturally

Workflow Architecture

Order Workflow Architecture

Notice how errors branch off at each decision point, while success flows forward. This is the railway model in action: success stays on the main track; errors switch to the failure track and propagate to the end.

Complexity Tamed by Simple Building Blocks

Step back and consider what this example builds. An order workflow with eight distinct steps, seven potential error types, recovery logic, retry policies, feature flags, immutable state updates, and concurrent execution. In traditional Java, this would likely span hundreds of lines of nested conditionals, try-catch blocks, and defensive null checks.

Instead, the core workflow fits in a single method:

return validateShippingAddress(request.shippingAddress())
    .via(validAddress -> lookupAndValidateCustomer(request.customerId())
        .via(customer -> buildValidatedOrder(request, customer, validAddress)
            .via(order -> processOrderCore(order, customer))));

This is not magic. It is the result of combining a small number of simple, composable building blocks:

Building Block	What It Does
`Either<E, A>`	Represents success or typed failure
`EitherPath<E, A>`	Wraps `Either` with chainable operations
`via(f)`	Sequences operations, propagating errors
`map(f)`	Transforms success values
`recoverWith(f)`	Handles failures with fallbacks
Sealed interfaces	Enables exhaustive error handling
Records	Provides immutable data with minimal syntax
Annotations	Generates lenses, prisms, and bridges

None of these concepts is particularly complex. Either is just a container with two cases. via is just flatMap with a friendlier name. Sealed interfaces are just sum types. Records are just product types. Lenses are just pairs of getter and setter functions.

The power comes from composition. Each building block does one thing well, and they combine without friction. Error propagation is automatic. State updates are immutable. Pattern matching is exhaustive. Code generation eliminates boilerplate.

"Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new features."

— Doug McIlroy, Unix Philosophy

This is the Unix philosophy applied to data and control flow. Small, focused tools, combined freely. The result is code that is:

Readable: The workflow reads like a specification
Testable: Each step is a pure function
Maintainable: Changes are localised; the compiler catches missing cases
Resilient: Error handling is consistent and explicit

The pyramid of doom we started with was not a failure of Java. It was a failure to find the right abstractions. Effect Path, sealed types, and code generation provide those abstractions. The complexity has not disappeared, but it is now managed rather than sprawling.

Chapter Contents

Effect Composition - Sealed errors, via() chains, ForPath, recovery patterns
Production Patterns - Retry, timeout, Focus DSL, feature flags, code generation
Concurrency and Scale - Context propagation, Scope, Resource, VTaskPath

Key Takeaways

Sealed error hierarchies enable exhaustive pattern matching and type-safe error handling
via() chains compose sequential operations with automatic error propagation
ForPath comprehensions provide readable syntax for simple sequences
Recovery patterns handle non-fatal errors gracefully
Resilience utilities add retry and timeout behaviour without cluttering business logic
Focus DSL complements Effect Path for immutable state updates
Context propagation enables implicit trace IDs, tenant isolation, and deadlines
Structured concurrency provides parallel operations with proper cancellation
Resource management ensures cleanup via the bracket pattern
Virtual threads enable scaling to millions of concurrent operations
Composition of simple building blocks tames complexity without hiding it