ddn.result

ddn.result — value-based success/failure results.

This module provides Success, the empty payload for operations that succeed without returning a value, and Result, a thin wrapper around ddn_types, Either, ddn.types.Either representing "either a recoverable error or a successful outcome".

Results are ordinary values. Construction, copying and inspection are allocation-free and non-throwing when the relevant payload operations are; attributes are inferred from those operations. This suits low-level @nogc nothrow APIs as well as general application code.

Semantics:

• The success value is the first type argument and the recoverable

  error is the second, following the conventional Result!(Value, Error) order.

• Payload types equal after Unqual normalization are rejected.

  Use distinct role wrappers for qualifier-distinguished types.

• Construction accepts exactly one of the payload types; implicit

  conversions match neither constructor and must be made explicit by the caller.

• A default-constructed Result holds E.init, so ok() is false.

  There is no separate unset alternative: this is indistinguishable from explicitly storing E.init, which may not be a meaningful domain error.

• Accessing the inactive payload (value() on an error state, or

  error() on a success state) is a programming error. It terminates the process with a diagnostic on stderr — even in release builds — without allocating or throwing. Recoverable failures are represented by result values, never by this path.

• ok() reports which alternative is active. It never inspects error

  codes, null references or payload contents to guess success.

The branch-based accessors (ok, value, error) are the primary ergonomic API while D lacks native pattern matching; exhaustive handling remains available through match. With selective imports, import match explicitly and name the result before matching. Should language-level matching arrive, removing the accessors would still be an explicit, compatibility-reviewed deprecation — not an automatic cleanup.

Example:

import ddn.result : Result, Status, Success;

struct ParseError { string msg; size_t offset; }
struct Config { int value; }
struct UpdateError { enum Reason { NOT_FOUND, LOCKED } Reason reason; }

alias ParseResult = Result!(Config, ParseError);
alias UpdateStatus = Status!UpdateError;

ParseResult parseConfig(scope const(char)[] text) @safe pure nothrow @nogc {
   if (text.length == 0)
      return ParseResult(ParseError("empty input", 0));
   return ParseResult(Config(1));
}

// Caller-side handling:
auto result = parseConfig("");
if (result.ok()) {
   auto config = result.value();
} else {
   auto failure = result.error();
}

Design record: doc/DDN-RESULT.md in the repository documents the validated decisions behind this module.