Skip to content

docs: add Why section and AI-assisted development note #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JunggiKim merged 1 commit into from
Apr 1, 2026
Merged

docs: add Why section and AI-assisted development note #35

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<E,A>` monad — great error accumulation, but the validated value is still just `Integer` | 0 |
| Arrow-kt | Smart-constructor pattern via `Exact<A,B>` — ~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
Expand Down Expand Up @@ -90,6 +106,14 @@ All refined wrappers follow the same pattern:

Collection refined types implement JDK interfaces directly — `NonEmptyList<T>` is a `List<T>`, `NonEmptyMap<K,V>` is a `Map<K,V>`. 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?"*
Expand Down