kotlin-types-value-class

Kotlin value class vs data class

Core principle

Prefer @JvmInline value class for single-field types that carry domain meaning. Data classes are for aggregating multiple fields. A value class gives you type safety (you can't mix up UserId and String) without the allocation overhead of a data class.

When to use this skill

• Writing a new Kotlin type that wraps a single value
• Reviewing a data class that has only one property
• Seeing primitive types (String, Long, Int, etc.) used where a domain type would prevent misuse
• Compose compiler reports showing unstable parameters that could be value classes

Decision flow

Situation	Prefer
Single field + domain-meaningful (UserId, EmailAddress, Percentage)	@JvmInline value class
Single field + no domain meaning (just grouping)	Type alias or keep the primitive
Multiple fields	Data class
Needs custom equals/hashCode/toString beyond the wrapped value	Data class (value classes delegate to the underlying type)
Used as a generic type argument or nullable in hot paths	Data class or primitive (autoboxing cost)

// GOOD: domain-meaningful single field
@JvmInline value class UserId(val value: String)
@JvmInline value class EmailAddress(val value: String)
@JvmInline value class Percentage(val value: Float)

// BAD: data class wrapping a single field
data class UserId(val value: String) // unnecessary allocation
data class EmailAddress(val value: String) // type safety without the overhead is available

// BAD: value class with no domain meaning
@JvmInline value class Wrapper(val value: String) // just use the String, or a type alias

// BAD: value class needing custom equality
@JvmInline value class CaseInsensitiveString(val value: String)
// value class equals delegates to String equals, which IS case-sensitive
// Use a data class if you need different equality semantics

Compose stability

@JvmInline value class is treated as Stable by the Compose compiler when its underlying type is stable (primitives, String, and other stable types). This means: