GitHub - aalsanie/codes: lightweight jvm library for stable application outcomes, structured issues, and explicit protocol mappings for Kotlin and Java.

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.