Effect Path API

"A map is not the territory it represents, but, if correct, it has a similar structure to the territory, which accounts for its usefulness."

-- Alfred Korzybski, Science and Sanity

Every Java application navigates territory that doesn't appear on any class diagram: the landscape of what might go wrong. A database connection that refuses to connect. A user ID that points to nobody. A file that was there yesterday. A validation rule that nobody told you about.

Traditional Java handles this territory with a patchwork of approaches: nulls here, exceptions there, Optional when someone remembered, raw booleans when they didn't. Each approach speaks a different dialect. None compose cleanly with the others.

The Effect Path API provides a unified map for this territory.

Rather than learning separate idioms for absence (Optional), failure (try-catch), typed errors (Either), and deferred effects (CompletableFuture), you work with Path types: thin, composable wrappers that share a common vocabulary. The same map, via, and recover operations work regardless of what kind of effect you're handling. The underlying complexity remains (it must), but the Path contains it.

If you've used the Focus DSL from the optics chapters, the patterns will feel familiar. Where FocusPath navigates through data structures, EffectPath navigates through computational effects. Both use via for composition. Both provide fluent, chainable operations. The territory differs; the cartography rhymes. And when you need to cross between territories, extracting structured data into effect pipelines or drilling into effect results with optics, the bridge API connects both worlds seamlessly.

In This Chapter

Quickstart -- Three runnable examples showing MaybePath, EitherPath, and ForPath in about 150 lines. The fastest path from zero to working code.

Core Paths -- The everyday API for Effect Path adopters:

  • Core Paths Overview -- The problem that Path types solve, the railway model of effect composition, and your first taste of the API.
  • Migration Cookbook -- Pattern-by-pattern translations from imperative Java to Effect Path. Recipes for try/catch, nullable lookups, CompletableFuture, validation, and nested record updates.
  • Path Types Overview -- A decision tree across the six core path types, with a short primer on when to reach for each.
  • MaybePath, EitherPath, TryPath, ValidationPath, IOPath, VTaskPath -- One page per path type: operators, idioms, and worked examples.
  • Composition Patterns -- Sequential chains, independent combination, parallel execution, debugging with peek.
  • ForPath Comprehension (with Examples) -- The for-comprehension designed specifically for Path types. Parallel and Traverse variants live under Advanced Paths.

Optics Integration -- Bridging Effect Paths with the Optics chapter:

  • Focus-Effect Integration -- Converting between FocusPath / AffinePath / TraversalPath and Effect Path types; using focus() to navigate within effect contexts.
  • Capstone: Effects Meet Optics -- A complete before/after example combining effects and optics in a single pipeline.

Advanced Paths -- Free monads, algebraic effects, streaming, and resilience:

  • Advanced Paths Overview -- Stack-safe recursion, DSL building with Free structures, resource management, parallel execution.
  • IdPath, OptionalPath, GenericPath, TrampolinePath, FreePath, FreeApPath, VStreamPath -- Advanced and specialised path types.
  • ForPath Parallel Composition and ForPath Traverse -- Concurrency primitives and typeclass-level traversal for ForPath comprehensions.
  • Advanced Effects -- Reader, State, and Writer paths for environment access, stateful computation, and logging accumulation.
  • Effect Contexts -- Context-scoped effects including ErrorContext, ConfigContext, RequestContext, and SecurityContext.
  • Effect Handlers -- Algebraic-effect-style programming via Free monads and interpreters.
  • Patterns and Recipes -- Real-world patterns distilled from production code: validation pipelines, service orchestration, fallback chains, resilience with retry.
  • Resilience Patterns -- Retry, circuit breaker, bulkhead, saga, and the ResilienceBuilder.

Reference -- Lookup material:

  • Capability Interfaces -- The hierarchy of powers that Path types possess: Composable, Combinable, Chainable, Recoverable, Effectful, and Accumulating.
  • Type Conversions -- Moving between Path types as your needs change.
  • Common Compiler Errors -- The five most common compiler errors with full messages, minimal triggers, and fixes.
  • Production Readiness -- Stack traces, allocation overhead, and stack safety. Honest answers for senior engineers.

Compile-Time Safety

The HKJ Gradle plugin can detect Path type mismatches at compile time, catching errors that would otherwise surface as runtime exceptions. See Compile-Time Checks for setup.

See Example Code

Core Paths:

Advanced Paths:

Reference:

Hands-On Tutorial

For a guided, exercise-driven walkthrough of the Effect Path API, see the Effect API Tutorial. Each section pairs a chapter concept with a runnable Java exercise and a worked solution.

Chapter Contents

  1. Quickstart - Your first three runnable Effect Path examples
  2. Core Paths - The six everyday path types, composition, and basic ForPath comprehensions
  3. Optics Integration - Bridging the Effect Path API with the Optics chapter
  4. Advanced Paths - Free monads, effect handlers, contexts, parallel/traverse ForPath, and resilience
  5. Reference - Capability typeclasses, type conversions, compiler errors, and production readiness

Next: Quickstart