From a587aea9c91d068f7ee2529818d67091a2cbed31 Mon Sep 17 00:00:00 2001 From: kjg Date: Mon, 30 Mar 2026 22:25:09 +0900 Subject: [PATCH] docs: add Why section and AI-assisted development note to README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain the gap in existing JVM tools (Jakarta Validation, VAVR, Arrow-kt, Kotlin value classes) — they provide patterns but zero pre-built types. Add a short section on how typed signatures help AI code generators produce validated code by default. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index df5ec79..25a91a8 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,22 @@ Move validation into the type system. Zero runtime dependencies. Java 8+. +## Why + +Validated wrapper types are not a new idea — but existing JVM tools +only give you the **pattern**, not the types themselves. + +| Tool | What it provides | Pre-built types | +|------|-----------------|----------------| +| Jakarta Bean Validation | Annotations (`@NotNull`, `@Min`) — checked only when `validate()` is called | 0 | +| VAVR | `Validation` monad — great error accumulation, but the validated value is still just `Integer` | 0 | +| Arrow-kt | Smart-constructor pattern via `Exact` — ~10 lines of boilerplate per type | 0 | +| Kotlin value class | Language feature — you write everything yourself, Kotlin-only | 0 | + +java-refined ships **123+ ready-to-use types**. +`PositiveInt`, `NonBlankString`, `EmailString` — import and go. +Zero dependencies. Java 8+. + ## Before ```java @@ -90,6 +106,14 @@ All refined wrappers follow the same pattern: Collection refined types implement JDK interfaces directly — `NonEmptyList` is a `List`, `NonEmptyMap` is a `Map`. No unwrapping needed. +## For AI-Assisted Development + +Method signatures are contracts that AI agents cannot ignore. + +When your API accepts `PositiveInt` instead of `int`, code generators +and AI assistants are **forced** to provide validated values — +no scattered `if`-checks to forget or duplicate. + ## Installation > *"I can just implement this myself. Why add a dependency?"*