Better Immutability in Kotlin -- Multi-Field Value Classes

[ice-phoenix]

We are publishing the design proposal for Multi-Field Value Classes (MFVCs) in Kotlin -- the first concrete step in our "Value Classes 2.0" story for better immutability (see KEEP-0453 for the general overview).

The core idea is simple: lift the single-property restriction on Kotlin value classes, allowing them to have multiple primary val properties. This gives us shallow immutable, identity-less types with structural equality aka "shallow immutable data classes without identity".

This looks simple, but (as usual) there are a lot of complicated interactions in the detailed design. If you're interested, go and read the proposal, and (if you want) follow the Call to Action section to give us feedback.

Read the full proposal: KEEP-0454
Related YouTrack issue: KT-77734

[kyay10]

Unlike data classes, MFVCs do not support positional-based destructuring

What about Pair and Triple? or a Point or Vector3? They seem like good reasons to have it. Can we at least define operator fun componentX() for MFVCs? I don't see why it would be prohibited.

In fact, I heavily disagree with the move to deprecate componentX() for Pair and Triple. Name based destructuring is just unnecessarily long here. I don't understand how using the names first and second is any better than just having declarations in order.

[xvbcfj]

Unlike data classes, MFVCs do not support positional-based destructuring
What about Pair and Triple? ...? They seem like good reasons to have it. Can we at least define operator fun componentX() for MFVCs? I don't see why it would be prohibited.

Tuples please :)

[serras]

I think this should not be taken as "you cannot use it", but rather "it is not available by default". So you could still use componentX for your value classes -- and we can keep it for Pair and Triple -- but they won't be automatically generated.

[kyay10]

Why have abstract value classes at all? Their restrictions sound remarkably close to an interface. What does it give you that an interface doesn't?
I can see a couple of things: constructors, and final methods. The latter, one can imagine, could be added to Kotlin eventually, so only the former matters.
Are these "advantages" of an abstract value class actually useful in real examples? I'm concerned it's just an unnecessary complication in the design.
The relevant section states:

abstract MFVCs state that they are identity-less

but I don't see why that's a useful or necessary concept. However, one cool part is that some AnyVal superclass can be added which all value classes inherit from.

You also go on to say:

Their main use-case is to represent common implementations of identity-less types aka serve as root types for value hierarchies.

but again, can't an interface do that pretty well already? final methods don't seem absolutely necessary, and neither do constructors.

[CLOVIS-AI]

I join @kyay10's feeling. We've used value classes for years now, and sealed interface hierarchies with value classes are very convenient, I don't see a need for adding yet another concept.

In general, Kotlin interfaces are much more powerful than abstract classes. For example, interface delegation is a very powerful concept. I think multi-field value classes should usable as interface delegates.

I don't think I've seen a use-case where a value class needs to implement a stateful parent. Stateless parents are interfaces, so I'd be more in favor of value interface (if there really needs to be a promise of no identity). Value classes must still be able to implement non-value interfaces.

In the code I've seen, abstract classes are always stateful (otherwise you'd use an interface, which are more versatile), so the concept of value abstract class seems strange to me.

@kyay10:
However, one cool part is that some AnyVal superclass can be added which all value classes inherit from.

I don't think that's necessary, though. Enum is not an enum class, but it's still the magic supertype that is added to all enums. Value classes could do the same; the parent is going to be magic anyway, so I don't think it has to follow all the rules.

[rnett]

One thing I could see is the ability to have copy vars of that type. I think I would still prefer value interface for that case, though.

[CLOVIS-AI]

Project Valhalla states that all fields of a value class must be initialized before the object becomes observable (i.e., before super() call where this can leak). This is more restrictive than regular class initialization today, where initializers run after the super() call and fields could be seen in a partially initialized state.

I think this is another point in favor of value interface.

The initialization order of constructors in Kotlin is already a big difficulty for learners (at least in my experience as a teacher). Having the value keyword completely reverse the order (which is not an obvious consequence of being stateless) seems to me to be a major difficulty.

However, if value class are forbidden to inherit from abstract class, and are only allowed to inherit from interface and value interface, then this entire section becomes an implementation detail that isn't visible by developers.

[rnett]

Another benefit of abstract classes that interfaces don't cover is the ability to declare inline methods. However, I'd prefer this to be handled by relaxing that restriction (KT-84151), since it doesn't seem necessary.

[CLOVIS-AI]

The new version of the proposal allows value class to implement an interface, I'm happy with that. There is no value interface, but I also don't particularly have a use-case for an interface that forces all implementations to be value class.

[kyay10]

Can you elaborate further on value objects? It seems rather unnecessary to me. I'd much rather just blanket prohibit === comparisons on data objects instead.
The only use I can see for them is with abstract value classes, but (as I commented above), that doesn't seem necessary either. Thus, I don't really see why preserving identity for data objects is necessary.

[rnett]

As an alternative way to represent the feature, do you think allowing value classes with zero properties would be better?

Interesting idea, and after thinking about it some, I think so? It seems to me like most of the value in value object is coming from use as a sentinel or the like, i.e. as an instance, not as a namespace. Where the 0-cost namespacing is better handled by companion (or actual namespaces). So using 0-arg value classes deconflicts the usage scenarios a bit and makes "which one should I use" confusion less likely.

[CLOVIS-AI]

That is a good idea, but it fails encounter with reality on several fronts. As data objects still (inherently) have identity and it cannot be dropped from them (as they allow for properties with backing fields, and these fields need a place to be stored), prohibiting === does not really solve anything.

I don't understand this point. Of course there is actually an instance in the end. But since there is only one, === on an object can never return anything other than true, so it doesn't have any usage. The only situation where === can return false is when comparing to a completely different type (there's a warning at compilation already) or when weird deserialization is done and duplicates the object. I would argue that this is always a bug, and there is no legitimate reason to do this. If it's not valid code, forbidding it isn't a breaking change.

they are completely outside our control, and we cannot say "well you used a bad-bad thing, joke's on you, Kotlin will work incorrectly now".

That is what we are doing though. The compiled code will be compiled-as-specified, but if there is any state in the object, it is not duplicated and will drift away. I have never seen user code that takes this possibility into account, and I'm fairly certain that, if it were to happen, most codebases I've ever worked on would be utterly broken.

I would file this in the "the code you wrote is so utterly weird that it's not on us what happens". The same way that you can use reflection to rewrite the JVM's integer cache, which will make all math operations give incorrect results.

From a "regular developer" point of view, the only difference between object and data object right now is that data object has the toString representation that we all expected object to have. In a way, object is a dead feature now, there isn't really a reason to use it instead of data object; data object could be the default. I see value object as a new iteration of the same thing, which will lead us to two different object variants that have no use.

value objects are about not having identity at all, meaning you don't really care about how many instances there is.

This implies that value object must always be deeply immutable, right? Otherwise, this is very dangerous. Also, this means that

value object {
    val foo = 2
}

is the same as

object {
    const val foo = 2
} 

(although the second still creates an instance, that isn't used at runtime because foo is inlined at callsites).

As an alternative way to represent the feature, do you think allowing value classes with zero properties would be better?

IMO, it depends what the use-case is. If the use-case is "group multiple fields semantically together without an instance that contains them", then I think xxx object makes more sense than class, because class inherently means "instance".

If that's the use-case, note that this feature is identical (at least from what I can see) to the namespace feature requested in the companion blocks KEEP, and thus would imply that companion {} becomes syntax sugar for companion value object {}, and they are both strictly the same feature. I like that this is tying the different KEEPs together.

[ice-phoenix]

@CLOVIS-AI

This implies that value object must always be deeply immutable, right?

Ah, I see where the KEEP should be improved. As value classes cannot have stored state besides their primary properties, and value objects have 0 primary properties, they cannot have any stored state at all. They are exactly (almost) zero-cost type tokens and/or behavior carriers (but not state carriers).

If it's not valid code, forbidding it isn't a breaking change.

About the other mentioned issue, let's agree to disagree on what we consider (in)valid code here. I do understand your PoV and I would love to have the freedom to follow it. Unfortunately, in practice people do use each and every possible combination of language features, and sometimes it happens outside of the user's direct control.

Which means we cannot really guarantee a single instance and cannot rely on it, e.g., in the equals implementation for an object / data object. And we cannot say it's not our problem.

At the same time, I see some potential for your "prohibit === for data objects" idea, most probably as a warning to discourage people from this suspicious code pattern. I'll think about that.

companion {} becomes syntax sugar for companion value object {}

That is a possible view on these two features, which requires a very particular relaxation of what value means when combined with companion (to allow basically companion stored properties in a companion value object). We could do that, but I don't really see any benefits in doing so.

[CLOVIS-AI]

Ah, I see where the KEEP should be improved. As value classes cannot have stored state besides their primary properties, and value objects have 0 primary properties, they cannot have any stored state at all.

I see. I don't really understand what feature they provide, then. The top-level of a file is already a thing that has no identity, but it can hold state, which makes it more useful I think?

At the same time, I see some potential for your "prohibit === for data objects" idea, most probably as a warning to discourage people from this suspicious code pattern. I'll think about that.

Please do. At least, it can start as a warning, that should at least give information on how many people complain about it.

That is a possible view on these two features, which requires a very particular relaxation of what value means when combined with companion (to allow basically companion stored properties in a companion value object).

When reading the KEEP I didn't get that value objects are not allowed to have properties. Indeed, since that's the case, I agree companion blocks and value object are different things.

I do think there is value for an identity-less singleton data holder though: this is what a companion block or a top-level file are, and it'd be great to have a keyword that creates that by itself. Maybe just a top-level package {} block. But off-topic for this KEEP.

[zhelenskiy]

I would suggest allowing both data and value classes with zero parameters without declaring value object. data class with zero parameters is not equivalent to data object, as data classes can have many instances with their own backing field instances, etc. Moreover, they are supported in Java records this way. The solution is both consistent and does not mix incompatible features.

[kyay10]

Unlike current (@JvmInline) inline value classes, MFVCs are not inlined by the Kotlin compiler. They are designed to work as shallow immutable value-based types first and foremost, with no immediate performance guarantees. Thus, their underlying representation will depend on the platform.

Conceivably, could they be optimized eventually? Especially on non-JVM platforms, where Valhalla doesn't affect things. This proposal doesn't rule that out in the future, right?

[ice-phoenix]

Yes, that's exactly our plan. On the JVM we are bound by what is and isn't available on the platform: doing value-specific optimizations in user space is fragile and murders the interop story. On most other platforms (Wasm, Native) we have full control and more possibilities for optimizations. On some platforms (JS) we do not have a good solution atm.

[kyay10]

While MFVC ergonomic update is being designed, and even after it's added, I think having a copy method would still be useful. Have you explored simply generating copy methods for all MFVCs?

[ice-phoenix]

We are aiming to support both step-by-step / implicit style of updates (copy vars or smth) and all-at-once / explicit style of updates (copy fun or smth), in one way or another. We hope to achieve that without the need to generate copy method for value classes, but it's still an open question whether it is achievable.

[rnett]

(for abstract value classs)

This means they also cannot have delegated properties (as they need a backing field to store the delegate).

This is generally but not always true. If the delegate is already a property, is stateless, or the delegate can be inlined, no additional field is needed. That said, I can't come up with any convincing use-cases where using such delegates would be important, so maybe it's not important.

[kyay10]

I think such delegated properties can be added as extension properties, so it's fine.

[rnett]

The particular case I was thinking of was something like:

value class Foo(private val _bar: MutableState<Int>, private val _baz: Lazy<String>) {
  var bar by _bar
  val baz by _baz
}

You could implement them as extensions which call the getValue/setValue functions directly, but it's not pretty.

[ice-phoenix]

Two thoughts.

• Yes, this use-case looks very niche atm, and we won't be supporting it in the first version of the design. But it is also smth we could allow later if we see enough reasons to do so.
• To my mind, your particular case looks more about "How to make already existing value-like things (e.g., Compose's MutableState) look like (copy) vars", similar to what you suggested in KT-77734. I feel there should be a better (less boilerplate-y) solution to this, and we are working on finding it.

[rnett]

(for migration)

To understand if we actually need this, we need to discuss whether this migration has important use-cases. We currently believe that in most cases @JvmInline value classes are used for their performance optimizations first, and for their immutability second. This means that the migration from (0) to (1) is not a very immediate problem.

In my experience and my own use, most @JvmInline value classes are used as a low cost abstraction first, for code clarity and type safety, with performance being a "don't make things that much worse" consideration. That said, I don't see a whole lot of need to migrate from state 1 to 2, other than wanting to introduce another constructor property, which is a breaking change. The primary reasons for me would be to get rid of the @JvmInline clutter, and better java interop.

[ice-phoenix]

About that, what do you think about the migration plan for @JvmInline we outlined in the KEEP, based on @JvmExposeBoxed? Would that be enough?

[rnett]

That makes sense, it does seem feasible.

[rnett]

I think it's necessary to have a way of defining "requires identity" for user code, and ideally making it type checked. For example, for a parameter that will be synchronized on later. Or a parameter that will be used to create a cleaner or weak ref. Currently, there's no way to enforce this at compile time, so presumably it would be a runtime error, or worse, unexpected undefined behavior depending on the auto-boxing strategy used. Which would be unfortunate, because there would be no way to know that the method you're calling is safe to use with a value object or not.

This is all assuming that value classes extend Any, otherwise it could be used as a bound. An introduction of an synthetic HasIdentity interface (that all non-value types extend) could serve as a solution to this problem, although the ergonomics of using it with interface-typed parameters aren't very good.

[kyay10]

the ergonomics of using it with interface-typed parameters aren't very good.

Intersection types would fix this...

More seriously, it's okay if this isn't super ergonomic, since defining an identity-required function is niche and likely something libraries do, while using such a function is much more likely (but it won't be cluttered on the user side). The way to do it is to use a type parameter with multiple bounds, which is already supported in the language, so it's not crazy to do

[rnett]

That's true, using where would work, as long as there's an upper bound that represents "has identity".

[ice-phoenix]

Noted, thanks for highlighting this issue to us. At the moment we will almost definitely have smth like fun Any?.isValue() / Any?.hasIdentity() for dynamic checks. As for how the solution looks like for static checks, we are not 100% definite.

[kyay10]

@ice-phoenix does this mean that Error <: Any?? Or is that just temporarily the case for this prototype

[rnett]

Noted, thanks for highlighting this issue to us. At the moment we will almost definitely have smth like fun Any?.isValue() / Any?.hasIdentity() for dynamic checks. As for how the solution looks like for static checks, we are not 100% definite.

That's certainly better than nothing. I honestly don't care much what the solution for static checks looks like, I just wanted to emphasize the importance of some form of it, otherwise you'll end up with a lot of code with "Do not pass value classes here" KDocs and nothing more.

[CLOVIS-AI]

(on the section "MFVC and ===")

However, things get trickier once an MFVC value is passed as a generic type, as Any or as an interface it implements. In that case, you can observe that the runtime may allocate two distinct boxes for what is semantically "the same" value.

I think this is acceptable. It is already a common behavior in the JVM world: java.lang.String, java.lang.Integer etc already behave like this.

[CLOVIS-AI]

With regards to performance: I expect === on value classes via an interface will only ever be called as an early-discriminator (e.g. in equals implementation of other types, especially when they have a parent ancestor that is a key in a Map), which tend to be performance-sensitive places.

I would therefore be in favor of:

• Keep the runtime behavior as simple as possible (e.g. just use the box's identity)
• Have the compiler & IDE attempt to discover these situations (e.g. through data-flow analysis)

[CLOVIS-AI]

Given the properties of MFVCs, Compose can analyze fun UserView and record that it needs restarting only when either user.name or user.nickname are updated. This fundamentally means that we get more fine-grained state change tracking for MFVC parameters of composable functions, without the need for manual boilerplate.

If this is possible, I think this will be a massive improvement in developer experience with using Compose. That by itself makes MFVC very compelling for UI development.

[rnett]

I really like the idea of separating the data class method generation from the semantics, like the @GenerateDataClassMethods methods.

[JakeWharton]

Can a section be added which details the process for adding a property to an existing value class in a binary-compatible manner? Is it merely providing the constructor overload? Presumably @IntroducedAt will also work?

[ice-phoenix]

Yes, adding a property to an MFVC should be binary-compatible, and it works the same as for other kinds of classes. So both manual ctor overload and one generated from @IntroducedAt should work.

There are some wrinkles around potential interop (export) on value-type-aware platforms, e.g., if we at some point decide to export them as value types (structs) and there is a dynamic (no recompilation needed) Kotlin-unaware consumer, it might break there. But atm we consider this as a very narrow corner case.

[ice-phoenix]

Hi mates, just a small update that we have not forgotten about your feedback, I just need more time to go through, merge related things together and answer them.

Thank you for all your comments, and for your patience ❤️

[ice-phoenix]

We’ve updated the KEEP-0454 to clarify the scope of the first experimental phase of MFVCs planned for Kotlin 2.5.

The update talks in more detail on the design around abstract value classes, value objects, and other cases where you asked for refinement. It also talks a bit more on the migration stories and explicitly moves non-phase-I ideas -- such as stable delegation, runtime identity checks, and changes to identity equality -- into a dedicated "Possible Extensions" section. We will be working on bringing some of those to 2.5.20 and 2.6.

We will soon also share the KEEP for the second part of the story -- ergonomic updates via copy vars -- currently planned for experimental release in Kotlin 2.6. Once again thank you all for your patience 🤟

[rnett]

Thanks for the updates, the abstract value class rationale makes sense to me. I can see why you would want to deal with objects as proposed for now, but I don't think having all of data, value, and normal objects (plus statics and companion blocks) is a good final state, there are too many ways to do what is essentially the same thing. It's another issue but I think it deserves some looking into.