Move validation into the type system. Zero runtime dependencies. Java 8+.
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+.
public void createUser(String name, int age, List<String> roles) { if (name == null || name.trim().isEmpty()) { throw new IllegalArgumentException("name must not be blank"); } if (age <= 0) { throw new IllegalArgumentException("age must be positive"); } if (roles == null || roles.isEmpty()) { throw new IllegalArgumentException("roles must not be empty"); } // business logic ... }
public void createUser(NonBlankString name, PositiveInt age, NonEmptyList<String> roles) { // no validation needed — the types guarantee it }
Types replace scattered if-checks. Invalid data cannot even reach your method.
// Trusted data — just unwrap PositiveInt confirmedAge = PositiveInt.unsafeOf(18); // Untrusted input — safe fallback PositiveInt safeAge = PositiveInt.ofOrElse(userInput, 1);
// Branch on success/failure EmailString.of(email).fold( error -> badRequest(error.message()), valid -> ok(register(valid)) );
Optional module with Kotlin-idiomatic extensions:
import io.github.junggikim.refined.kotlin.* val name = "Ada".toNonBlankStringOrThrow() val tags = listOf("java", "fp").toNonEmptyListOrThrow()
// Safe fallback val safeAge = PositiveInt.ofOrElse(input, 1)
// Kotlin-idiomatic nullable val age = PositiveInt.of(input).getOrNull() ?: PositiveInt.unsafeOf(1)
// Convert to kotlin.Result val result: Result<PositiveInt> = PositiveInt.of(input).toResult()
All refined wrappers follow the same pattern:
of(value)— returnsValidation<Violation, T>, never throwsunsafeOf(value)— throwsRefinementExceptionon invalid inputofOrElse(value, default)— returns validated instance or falls back todefaultofStream(stream)— collection wrappers only
Collection refined types implement JDK interfaces directly — NonEmptyList<T> is a List<T>, NonEmptyMap<K,V> is a Map<K,V>. No unwrapping needed.
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.
"I can just implement this myself. Why add a dependency?"
Totally fair! Copy the source into your project — it's MIT licensed. But if it saved you some time... give me a ⭐ 🥺
Published to Maven Central. Kotlin/JVM users can optionally add java-refined-kotlin for extension functions (adds kotlin-stdlib dependency).
dependencies {
implementation("io.github.junggikim:java-refined:1.1.0")
// optional: Kotlin extensions
// implementation("io.github.junggikim:java-refined-kotlin:1.1.0")
}<dependency> <groupId>io.github.junggikim</groupId> <artifactId>java-refined</artifactId> <version>1.1.0</version> </dependency>
| Category | Examples | Count |
|---|---|---|
| Numeric | PositiveInt, NegativeLong, NonZeroDouble, ZeroToOneFloat |
46 |
| Character | DigitChar, LetterChar, UpperCaseChar |
7 |
| String | NonBlankString, EmailString, UuidString, Ipv4String, JwtString |
48 |
| Collection | NonEmptyList, NonEmptySet, NonEmptyMap, NonEmptyDeque, NonEmptyNavigableMap, ... |
10 |
| Control | Option, Either, Try, Ior, Validated |
5 |
| Predicates | GreaterThan, LengthBetween, MatchesRegex, AllOf, ForAllElements |
55+ |
Full list: docs/type-matrix.md
CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md
MIT. See LICENSE.