A modern programming language that makes developers happier.

kotlinlang

Hello Kotlin community!

We’re interested in learning about your experience with *immutable collections* in Kotlin projects, particularly with the `kotlinx.collections.immutable` library. Do you use immutable collections in your codebase - whether in pure Kotlin, Android, or Compose Multiplatform projects? If yes, how do you apply them in your workflow (e.g., state management, thread safety, etc.), and what use cases or patterns have you found most effective? Have you encountered any nuances, challenges, or limitations, and do you have any suggestions or feature requests for the library?

If you don’t use immutable collections, we’d love to know why - do they not match your typical scenarios, or do you find them inconvenient or unnecessary for your use cases?

Your feedback will help us understand real-world adoption and shape the evolution of Kotlin libraries. Thanks for sharing your experience!

would love a kotlin compiler flag to treat code in a module that uses regular collections _as_ immutable (by writing / replacing the used classes at compile time), sort of like how value classes box / unbox. I understand _why_ they exist (java collections are mutable) but they do add confusion and overhead

I use it quite often, both for compose and without.  Anywhere I want to be able to guarantee immutability.  The single biggest pain point is serialization, in particular how hard it is to use with kotlinx.serialization, needing type aliases everywhere in the best case.  Smaller pain points are the lack of `build*` methods and `mutate` being called mutate when not actually mutating the object.

It's hard enough to get my team to learn the existing Kotlin API (no offense to the API) without importing another library and having to teach that. Honestly, the "fake" immutable collections in the base API are good enough - I don't really care if they are truly immutable behind the scenes, just that I can know that the list won't change from my perspective.

We use them regularly for streaming minimal Map/Set events (i.e. Upsert/Remove) over network (like Kotlin RPC), and then collecting them efficiently back into `StateFlow<Map/Set>` for use in local caches of data

<https://github.com/caplin/DataSource-Extensions/blob/main/util/src/main/kotlin/com/caplin/integration/datasourcex/util/flow/SimpleMapEvent.kt#L113C1-L146C2|https://github.com/caplin/DataSource-Extensions/blob/main/util/src/main/kotlin/com/caplin/integration/datasourcex/util/flow/SimpleMapEvent.kt#L[…]C2>

I use them in Composables, so they won’t recompose on scroll. API is good enough, but it was confusing to have inconsistent terminology, e.g. `toImmutableList` conversion extension and `persistentListOf`  factory. Minor, but still

Actually one of my few issues with the library is the lack of Serializable which makes them trickier to use with Hazelcast etc. on the JVM. It's not the end of the world though.

Perhaps similar to <@U0HNMQG3V>, my most compelling use cases are flows that accumulate data in persistent collections. This can be a mind-boggling pattern in some cases.
Also great for Compose.
There are some commonly requested improvements that have been languishing as Github issues for years; it seems somewhat hypocritical to blankly ask for suggestions here.

<@U02DMT6V2JG> I understand your frustration about the long-standing GitHub issues, and you're right that it might seem contradictory to ask for feedback when existing suggestions haven't been addressed. The reason for this survey is that we're now actively prioritizing the stabilization and release of the beta version of kotlinx.collections.immutable, and we wanted to get a fresh, comprehensive view of how the library is being used in real projects today.

The feedback from GitHub issues is valuable, but this broader conversation helps us understand the current adoption patterns, pain points, and use cases across different types of projects and teams. It also helps us prioritize which of those existing issues should be addressed first as we work toward the beta release.

We're committed to addressing the most critical issues and improving the library based on both the long-standing feedback and these new insights. The stabilization effort includes reviewing and acting on those GitHub issues that have been waiting for attention.

Many people asked how the performance and efficiency of kotlinx immutable collections compares to <https://github.com/daniel-rusu/pods4k/tree/main/immutable-arrays|Immutable Arrays> so it feels like performance / efficiency is an important attribute.  My response is that kotlinx immutable collections trades element-access performance for efficient modifications due to their persistent architecture.

Perhaps the documentation of kotlinx immutable collections could be improved to better highlight its benefits along with scenarios where the persistent architecture really shines.

Thanks! We started publishing <https://kotlin.github.io/kotlinx.collections.immutable/|documentation> (on gh pages for now) and are currently working on improving it. And thanks for the tip about comparing performance with a third-party library, I think that's a good point for us.

I got the impression that most developers aren't familiar with the persistent architecture of kotlinx immutable collections.  So they're not sure if there's a penalty in memory or performance or what scenarios they're great at.

The persistent architecture makes it difficult to benchmark.  Two persistent collections with the same elements can have different memory and performance profiles depending on how they were constructed since persistent modifications wrap the prior collection.

It might be nice to have the ability to make these tradeoffs in the kotlinx library.  E.g. Persistent* would be add-optimized and Immutable* would be read-optimized.  Of course that requires breaking the current structure of persistent implementing immutable.

I'm missing buildImmutableList function. Like buildList but returning ImmutableList.

We love the persistent/immutable collection interfaces from `kotlinx.collections.immutable`, but needed different implementation performance tradeoffs for our application (the Certora Prover).  We ended up making "treap"-based persistent data structures based on the Kotlin interfaces (with extensions), which are better optimized for our use cases.  See: <https://github.com/Certora/collections|Certora/collections: Memory-effficient immutable collection types for Kotlin>

My reason to use them is to get *stable* Composables that use lists and sets.
So I only want a recompose on my wrapper around a LazyGrid if its content changes.

you can make "scaffolding" or "layouting" composables that simply take other composables as lambda parameters. if you do so you can even save them in your composables package and reuse them. and you can lift your state cleanly out of the composition in some Mediator object with flows and collect/combine/zip the state back into preciselly the smallest composable it is required in. Bipasing parents and "layouting" composables. If you are bursted data through a websocket that needs to make it to they ui. Like in a trading application with many ticking prices. Can you afford to make it immutable on and on on every frame?

I've a AppState object that contains the lazy list, so the immutable conversion doesn't happen on every frame, but only when the data changes.

I see, well I was saying above this will not always be available to you. like when data super changes over some socket.

But isn't it can be achieved with compose compiler config which marks all kotlin collections as stable?

So it's like "good enough" solution and allows complete ditch trully immutable collection

Just for context, we used Immutable collections for compose, but it was error prone (you could forget to use immutable and accidentally used normal collection), so we have to write custom Lint rules for it.

When compose compiler supported config, we marked all Kotlin collections as "stable" and we never had issues or bugs caused by this, because collection mutation is really rare in our code base and usually suspicious by itself.

So I don't see need to adopt Immutable collections just for compose. Honestly, not for compose too, until there is some very specific use case where you need to guarantee immutability and need more efficient collection copy

How do these custom rules look like?
And didn’t you still need to add the Stable annotation to every composable?

<https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration_file>

>  And didn’t you still need to add the Stable annotation to every composable?
No
You just tell compose compiler "this class is stable"

Interesting. I wasn't aware of `stability_config.conf`

But as with the `Stable` annotation you need to be careful to not mess that up and use mutable collections by accident.

Yes, it's correct, but again, we had multiple instances when people forgot ImmutableList, but never for 20 devs it happened that we got a bug because something is not recomposed because of collection was mutated, just because this code is really rare, everyone avoids mutable collections already