Developer Guide

Deep reference for every type in dmx-fun: design rationale, every combinator, composition patterns, and pitfalls to avoid.

Start with Introduction Type composition →

⚡ Which type should I use?

Value may or may not exist? Option<T> Operation can fail with a typed reason? Result<V, E> Wraps legacy code that throws? Try<V> Collect all validation errors at once? Validated<E, A> Branch with no success/failure semantics? Either<L, R> Defer and cache an expensive computation? Lazy<T>

📦 Core types

Option<T> Nullability

A value that may or may not be present. The null-safe alternative.

Use when You have an optional field or a lookup that may yield no result.

Avoid when The absence carries meaning beyond "not found" — use Result instead.

Result<V, E> Error handling

Either a success value or a typed error. Models domain failures explicitly.

Use when An operation can fail and the caller needs to handle the error type.

Avoid when The error is always an exception message string — Try is simpler.

Try<V> Exception handling

Wraps a computation that may throw. Turns exceptions into values.

Use when You are calling legacy or third-party code that throws checked/runtime exceptions.

Avoid when You own the error type and want callers to branch on it — use Result.

Validated<E, A> Validation

Like Result but accumulates multiple errors instead of failing fast.

Use when You want to collect all validation errors at once (e.g. a form submission).

Avoid when You only care about the first failure — Result short-circuits and is simpler.

Either<L, R> Disjoint union

A neutral disjoint union with no success/failure semantics.

Use when You need a branching value where neither side is inherently an error.

Avoid when One side clearly represents failure — use Result for that semantic clarity.

Lazy<T> Deferred computation

A value computed at most once, on first access. Thread-safe memoization.

Use when You have an expensive computation you want to defer and cache.

Avoid when The value is cheap to produce — the overhead of wrapping it is not worth it.

Tuple2/3/4 Product types

Typed heterogeneous tuples. Named fields without a dedicated class.

Use when You need to return 2–4 values from a method without a dedicated record.

Avoid when The tuple has stable semantics — model it as a proper record instead.

NonEmptyList<T> Collections

A list guaranteed to have at least one element at compile time.

Use when An API contract requires at least one element and you want to enforce it in the type.

Avoid when Emptiness is a valid state — use a regular List.

NonEmptyMap<K,V> Collections

A map guaranteed to have at least one entry at compile time. Insertion order preserved.

Use when A registry, configuration, or lookup table that must always contain at least one entry.

Avoid when Emptiness is a valid state — use a regular Map.

NonEmptySet<T> Collections

A set guaranteed to have at least one element at compile time. No duplicates, insertion order preserved.

Use when Set semantics (no duplicates) with the guarantee of non-emptiness, e.g. user roles or product tags.

Avoid when Emptiness is a valid state — use a regular Set.

Guard<T> Validation

A composable, named predicate that produces a Validated result — the reusable building block for validation pipelines.

Use when You have repeated if/invalidNel validation patterns that should be defined once and composed declaratively.

Avoid when A single ad-hoc check is simpler — Guard shines when rules are reused or composed.

Resource<T> Resource management

A composable managed resource: acquire, use, and release with a guaranteed cleanup.

Use when You need to bracket an operation around a resource (file, connection, lock) and want to compose multiple resources safely.

Avoid when A simple try-with-resources block suffices and no composition is needed.

Accumulator<E,A> Tracing

A value paired with a side-channel accumulation (log, metrics, audit trail). The functional alternative to mutable shared state.

Use when You need to thread log entries, counters, or audit events through a pure computation chain without shared mutable state.

Avoid when A step can fail — use Result for error handling, or Validated to accumulate validation errors.

Checked interfaces Interop

Checked variants of Function, Supplier, Consumer, Runnable, plus TriFunction/QuadFunction.

Use when You need to pass lambdas that throw checked exceptions to higher-order functions.

Avoid when The lambda does not throw — use the standard java.util.function types.

Cross-type composition Every type converts to the others. The Combining Types page covers the full conversion matrix, railway-oriented pipelines, and parallel validation patterns.

🔌 Integration modules

Optional artifacts — add only what you need. Each module declares its peer dependency as compileOnly so it never pulls in transitive dependencies unexpectedly.

Serializers and deserializers for all dmx-fun types via the optional fun-jackson module.

AssertJ Testing

Fluent AssertJ custom assertions for Option, Result, Try, Validated, and Tuple types.

Spring Spring

TxResult and TxTry: programmatic transaction support that rolls back when Result.isError() or Try.isFailure(), without relying on exceptions.

Quarkus Quarkus

TxResult and TxTry: CDI transaction support that rolls back when Result.isError() or Try.isFailure(). Declarative @TransactionalResult and @TransactionalTry via a CDI interceptor.

Resilience4J Resilience

Adapters for Retry, CircuitBreaker, RateLimiter, and Bulkhead that return Try or Result instead of throwing exceptions.

Micrometer Observability

Automatic counters, timers, and failure metrics for Try and Result executions via DmxMicrometer.

Micrometer Tracing Observability

Automatic distributed tracing spans for Try and Result executions via DmxTracing.

Micrometer Observation Observability

Metrics and distributed tracing spans for Try and Result executions — both signals from a single DmxObservation call.

Jakarta Validation Validation

DmxValidator bridges Jakarta Bean Validation with Validated<NonEmptyList<E>, A> so all constraint violations accumulate without throwing ConstraintViolationException.

Jakarta JSON-B + JAXB Serialization

JsonbAdapter and XmlAdapter implementations for all dmx-fun types via the optional fun-jakarta-jaxb module.

HTTP Client HTTP

Wraps java.net.http.HttpClient so every call returns Result<T, HttpError> with typed variants for 4xx, 5xx, timeouts, and network failures.

🛠 Contributing & Maintainers

Contributing Contributors

Prerequisites, local build, code conventions, and how to open a PR.

CI/CD Pipelines Maintainers

All six GitHub Actions workflows: triggers, secrets, local equivalents.

Release Process Maintainers

Step-by-step guide for cutting a stable release.

New Module Maintainers

Conventions and checklist for adding a new optional integration module.