Inline Classes in Kotlin: Why, Where, and How to Use Them

Inline classes in Kotlin allow you to wrap a single value with a custom type to improve code safety and readability. Unlike regular classes, inline classes do not add runtime overhead since they get "inlined" by the compiler—meaning no actual object is created at runtime. This article explores why and where to use inline classes, how they differ from typealias, and includes examples.

Why Use Inline Classes?

1. Type Safety: Inline classes help prevent accidental usage of similar data types. For example, a UserId and a ProductId may both be represented as Strings, but they are not interchangeable concepts. Inline classes ensure that they remain distinct types at compile time.

2. Runtime Performance: With inline classes, Kotlin removes the need to create wrapper objects by inlining the wrapped value wherever possible. This makes them more efficient for performance that often pass around small values like IDs, codes, or identifiers.

3. Readable Code: Inline classes give meaningful names to otherwise generic values, making code more self-explanatory and easier to understand.

Defining an Inline Class

To define an inline class in Kotlin, use the @JvmInline annotation along with value class, and ensure it contains only one val property:

@JvmInline
value class UserId(val id: String)
@JvmInline
value class ProductId(val id: String)

fun fetchUser(userId: UserId) {
    println("Fetching user with ID: ${userId.id}")
}

fun main() {
    fetchUser(UserId("1")) // OK
    fetchUser(ProductId("1")) // NOT OK. Even though inlined type is String
}

In the above example, UserId and ProductId are inline classes that wrap String. Even though they have the same underlying type (String), Kotlin treats them as distinct types, preventing accidental mix-ups.

When and Where to Use Inline Classes

Inline classes are especially useful when you need to:

1. Wrap Identifiers or Codes: When you have unique IDs or codes (e.g., UserId, ProductId) and want to avoid the risk of accidentally swapping them.
2. Reduce Overhead in High-Frequency Calls: For functions or APIs where performance matters, inline classes avoid the cost of additional object creation.
3. Encapsulate Domain-Specific Types: They’re great for representing domain-specific types, such as currency, weight, or distance, without the need for full-fledged classes.

Comparison with typealias

typealias in Kotlin is another way to add meaning to a type without creating a new one. However, unlike inline classes, typealias only creates an alias without actual type safety at compile time:

typealias UserId = String
typealias ProductId = String

fun printProductId(id: ProductId) {
    println("Product ID: $id")
}

// The following would compile, even though it's an incorrect usage.
val userId: UserId = "user_id"
printProductId(userId) // Will print Product ID: user_id

With typealias, UserId and ProductId are just aliases of String, so Kotlin treats them as interchangeable, which risks accidental misuse. Inline classes avoid this issue by creating distinct types for UserId and ProductId at compile time.

Conclusion

Inline classes in Kotlin provide a robust way to add type safety, improve code readability, and optimize performance for lightweight wrappers around values. They are particularly useful for identifiers or small values that would otherwise create unnecessary object allocation. By using inline classes, you get the best of both worlds: compile-time safety without runtime overhead.