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 whenYou have an optional field or a lookup that may yield no result.

Avoid whenThe 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 whenAn operation can fail and the caller needs to handle the error type.

Avoid whenThe 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 whenYou are calling legacy or third-party code that throws checked/runtime exceptions.

Avoid whenYou 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 whenYou want to collect all validation errors at once (e.g. a form submission).

Avoid whenYou 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 whenYou need a branching value where neither side is inherently an error.

Avoid whenOne 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 whenYou have an expensive computation you want to defer and cache.

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

Tuple2/3/4Product types

Typed heterogeneous tuples. Named fields without a dedicated class.

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

Avoid whenThe 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 whenAn API contract requires at least one element and you want to enforce it in the type.

Avoid whenEmptiness 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 whenA registry, configuration, or lookup table that must always contain at least one entry.

Avoid whenEmptiness 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 whenSet semantics (no duplicates) with the guarantee of non-emptiness, e.g. user roles or product tags.

Avoid whenEmptiness 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 whenYou have repeated if/invalidNel validation patterns that should be defined once and composed declaratively.

Avoid whenA 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 whenYou need to bracket an operation around a resource (file, connection, lock) and want to compose multiple resources safely.

Avoid whenA 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 whenYou need to thread log entries, counters, or audit events through a pure computation chain without shared mutable state.

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

Checked interfacesInterop

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

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

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

Cross-type compositionEvery 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.

AssertJTesting

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

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

QuarkusQuarkus

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

Resilience4JResilience

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

MicrometerObservability

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

Micrometer TracingObservability

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

Micrometer ObservationObservability

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

Jakarta ValidationValidation

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

Jakarta JSON-B + JAXBSerialization

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

HTTP ClientHTTP

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

🛠Contributing & Maintainers

ContributingContributors

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

CI/CD PipelinesMaintainers

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

Release ProcessMaintainers

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

New ModuleMaintainers

Conventions and checklist for adding a new optional integration module.