aalsanie/codes

Source: https://github.com/aalsanie/codes

Codes

Java 17+. Zero runtime dependencies.

Codes provides stable application outcome identities and explicit boundary mappings for JVM applications. Applications keep their own domain result or error model and use Codes where multiple parts of a system need to agree on outcome meaning without coupling that meaning to HTTP, gRPC, serialization, or a framework.

A domain outcome can keep the same identity across boundaries:

com.example.payments:PAYMENT_DECLINED
                    |
                    +-- HTTP 422
                    +-- gRPC FAILED_PRECONDITION
                    +-- logs/metrics keep PAYMENT_DECLINED

Install

Gradle:

dependencies {
    implementation("io.github.aalsanie:codes:0.3.1")
}

Maven:

<dependency>
    <groupId>io.github.aalsanie</groupId>
    <artifactId>codes</artifactId>
    <version>0.3.1</version>
</dependency>

Java 17+. Zero runtime dependencies. Kotlin applications consume the same Java API with JSpecify nullability metadata.

Custom outcomes

OutcomeDefinition paymentDeclined = OutcomeDefinition.custom(
    "com.example.payments",
    "PAYMENT_DECLINED",
    OutcomeState.FAILED,
    "The payment was declined."
);

Outcome outcome = Outcome.of(paymentDeclined);

HttpOutcomeMapper http = HttpOutcomeMapper.standard()
    .withMapping(paymentDeclined, HttpStatusCode.of(422));

GrpcOutcomeMapper grpc = GrpcOutcomeMapper.standard()
    .withMapping(paymentDeclined, GrpcStatusCode.FAILED_PRECONDITION);

OutcomeCode is the stable machine identity. Protocol mappings do not change that identity.

Standard outcomes

OK

INVALID_ARGUMENT
UNAUTHENTICATED
PERMISSION_DENIED
NOT_FOUND
ALREADY_EXISTS
FAILED_PRECONDITION
OUT_OF_RANGE
RATE_LIMITED
CANCELLED
DEADLINE_EXCEEDED
ABORTED
UNIMPLEMENTED
UNAVAILABLE
INTERNAL
DATA_LOSS
RESOURCE_EXHAUSTED

OK is the standard successful outcome. Applications define domain-specific success, pending, and failure outcomes when the standard catalog does not match the operation.

Runtime occurrences

Outcome outcome = Outcome.of(
    StandardOutcomes.NOT_FOUND,
    "customerId=123"
);

System.out.println(outcome.getCode());
System.out.println(outcome.getMessage());
System.out.println(outcome.getDetail());

message comes from the reusable definition. detail belongs to one occurrence.

Structured issues

ValidationResult validation = ValidationResult.invalid(
    Issue.at("email", "Invalid email address.")
);

Outcome outcome = validation.toOutcome(StandardOutcomes.INVALID_ARGUMENT);

ValidationResult is a small convenience for aggregating issues. It is not intended to replace an application’s result, validation, or functional programming model.

HTTP

HttpStatusCode status = HttpOutcomeMapper.standard()
    .map(StandardOutcomes.NOT_FOUND)
    .orNull();

assert status == HttpStatusCode.NOT_FOUND;

Some standard outcomes are intentionally left unmapped for HTTP when the correct status depends on the application.

gRPC

GrpcStatusCode status = GrpcOutcomeMapper.standard()
    .map(StandardOutcomes.NOT_FOUND)
    .orNull();

assert status == GrpcStatusCode.NOT_FOUND;

The standard gRPC mapper covers all standard outcomes.

Kotlin

Java getters and static factories are directly usable as Kotlin properties and calls:

val outcome = Outcome.of(StandardOutcomes.NOT_FOUND, "customerId=123")
val status = HttpOutcomeMapper.standard().map(outcome).orNull()

check(outcome.code == StandardOutcomes.NOT_FOUND.code)
check(status?.value == 404)

Reference

• Semantic contract
• HTTP and gRPC mappings
• Compatibility policy

License

Apache License 2.0.