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.

Review procedure

1. Find single-property wrappers, primitive-heavy APIs, and @Immutable wrappers in UI state.
2. Decide whether the single value is a real domain distinction. If not, keep the primitive or use a typealias.
3. Check whether replacing the type changes equality, serialization, Java interop, or hot-path boxing.
4. Convert only when the domain meaning is clear and the contract changes are acceptable.
5. Re-run the affected compiler/tests; for Compose performance work, re-check compiler reports or recomposition evidence.

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 beyond the wrapped value	Data class (value classes delegate to the underlying type)
Used as a generic type argument or nullable in a proven hot path	Data class or primitive

// 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 domain field
data class UserId(val value: String)

// 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 procedure

When a Compose report points at a single-field wrapper:

1. Confirm the underlying type is stable (String, primitives, or another stable type).
2. Prefer a value class over @Immutable on a wrapper whose only job is type distinction.
3. Do not change public serialization/API contracts just to silence a report.