docs(skills): vendor 10 Compose/Kotlin technique-layer skills
Adds technique-oriented Compose and Kotlin skills from chrisbanes/skills to complement the existing codebase-oriented skills. Codebase skills cover "where is X in Amethyst"; these cover "what is the correct Compose/Kotlin design". Descriptions tagged as technique-layer and cross-links trimmed to the vendored subset. CLAUDE.md skill table updated with a dedicated section. https://claude.ai/code/session_01QE8CjoJXUt7RKtwGgzeMrb
This commit is contained in:
Claude
@@ -0,0 +1,333 @@
|
||||
---
|
||||
name: compose-modifier-and-layout-style
|
||||
description: Use when writing or reviewing Jetpack Compose layout APIs, modifier parameters, modifier chain construction, hardcoded root layout decisions, or layout wrappers around a single conditional. Technique-layer skill — complements the codebase-specific compose-expert.
|
||||
---
|
||||
|
||||
# Compose modifier and layout style
|
||||
|
||||
## Core principle
|
||||
|
||||
A composable that emits layout is a leaf the *parent* places — the parent decides position, size, alignment, padding. The composable's job is structure (what's inside), not placement (where it goes). Three rules follow:
|
||||
|
||||
- **Declare a `modifier` parameter and apply it to the root**, so the parent can actually do its job. Hardcoding `.fillMaxWidth()` on a composable's root takes that decision away from every future caller.
|
||||
- **Construct modifier chains as one fluent expression**, not stepwise reassignments. Both compile to the same thing, but the chain *reads* as intent in one pass.
|
||||
- **Conditional rendering belongs where the condition applies.** A layout call whose only content is one `if` exists solely to hold the condition — push the `if` outside instead.
|
||||
|
||||
These travel together because the same composable usually triggers all three: you declare its parameters (rule 1), the caller constructs a chain to position it (rules 2), and the body has a conditional you might be tempted to wrap (rule 3).
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- You're writing a `@Composable fun` that calls a layout (`Box`, `Column`, `Row`, `LazyColumn`, `Text`, `Image`, `Surface`, `Card`, `Layout { … }`, anything from `compose.foundation.layout` or `compose.material*`) and its signature has no `modifier` parameter, or has one that isn't applied to the root, or has a hardcoded `.fillMaxWidth()`/`.padding(...)` on the root.
|
||||
- You see `var m = Modifier` followed by `m = m.padding(…)`, `m = m.background(…)`, etc.
|
||||
- A `modifier = …` argument has three or more chained calls on a single line.
|
||||
- A composable's body is `Layout { if (cond) Content() }` — one conditional, nothing else.
|
||||
|
||||
## 1. Declare a `modifier` parameter
|
||||
|
||||
For composables that emit layout, prefer a `modifier` parameter after required parameters and before content/lambda parameters, with a default of `Modifier`. The name is exactly `modifier` — not `mod`, not `m`, not `wrapperModifier`.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — no modifier param; caller can't position, size, or constrain this
|
||||
@Composable
|
||||
fun HomeScreenHeader(title: String, subtitle: String) {
|
||||
Column(
|
||||
modifier = Modifier
|
||||
.fillMaxWidth()
|
||||
.padding(horizontal = 16.dp),
|
||||
verticalArrangement = Arrangement.spacedBy(4.dp),
|
||||
) {
|
||||
Text(title, style = MaterialTheme.typography.headlineLarge)
|
||||
Text(subtitle, style = MaterialTheme.typography.bodyMedium)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — parent decides width and padding; the composable describes structure only
|
||||
@Composable
|
||||
fun HomeScreenHeader(
|
||||
title: String,
|
||||
subtitle: String,
|
||||
modifier: Modifier = Modifier,
|
||||
) {
|
||||
Column(
|
||||
modifier = modifier,
|
||||
verticalArrangement = Arrangement.spacedBy(4.dp),
|
||||
) {
|
||||
Text(title, style = MaterialTheme.typography.headlineLarge)
|
||||
Text(subtitle, style = MaterialTheme.typography.bodyMedium)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The caller now writes `HomeScreenHeader(title, subtitle, Modifier.fillMaxWidth().padding(horizontal = 16.dp))` once, at the home screen — the only place that knows the layout actually wants those.
|
||||
|
||||
## 2. Apply the caller's modifier to the root, and apply it first
|
||||
|
||||
When the root layout already takes other arguments (alignment, arrangement, padding *that's intrinsic to the composable*), the caller-provided modifier still goes on the root layout's `modifier` parameter — and the composable's local chain is appended after.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — modifier accepted but never applied
|
||||
@Composable
|
||||
fun Avatar(url: String, modifier: Modifier = Modifier) {
|
||||
Image(painter = rememberAsyncImagePainter(url), contentDescription = null)
|
||||
}
|
||||
|
||||
// ❌ BAD — applied to a child, not the root; caller's size/position changes don't take
|
||||
@Composable
|
||||
fun Avatar(url: String, modifier: Modifier = Modifier) {
|
||||
Box {
|
||||
Image(
|
||||
painter = rememberAsyncImagePainter(url),
|
||||
contentDescription = null,
|
||||
modifier = modifier,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ BAD — caller's modifier ends up last, so the composable's own size wins
|
||||
@Composable
|
||||
fun Avatar(url: String, modifier: Modifier = Modifier) {
|
||||
Image(
|
||||
painter = rememberAsyncImagePainter(url),
|
||||
contentDescription = null,
|
||||
modifier = Modifier
|
||||
.clip(CircleShape)
|
||||
.size(48.dp)
|
||||
.then(modifier),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — caller's modifier first, then the composable's intrinsic chain
|
||||
@Composable
|
||||
fun Avatar(url: String, modifier: Modifier = Modifier) {
|
||||
Image(
|
||||
painter = rememberAsyncImagePainter(url),
|
||||
contentDescription = null,
|
||||
modifier = modifier
|
||||
.clip(CircleShape)
|
||||
.size(48.dp),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Order matters: in a modifier chain, the *earlier* segment is the outer wrapper. The caller's modifier should be the outermost so caller-provided `.size(...)` or `.padding(...)` can override the composable's defaults rather than being overridden by them.
|
||||
|
||||
## 3. Don't hardcode layout decisions on the root
|
||||
|
||||
If the composable's root has `.fillMaxWidth()`, `.padding(horizontal = 16.dp)`, `.height(56.dp)`, etc., the caller can't *not* have them. Those are layout choices the parent should own.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — every caller now fills max width whether they want to or not
|
||||
@Composable
|
||||
fun PrimaryButton(text: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
|
||||
Button(
|
||||
onClick = onClick,
|
||||
modifier = modifier.fillMaxWidth(), // ← hardcoded
|
||||
) { Text(text) }
|
||||
}
|
||||
|
||||
// ✅ GOOD — caller adds .fillMaxWidth() if (and only if) they want it
|
||||
@Composable
|
||||
fun PrimaryButton(text: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
|
||||
Button(onClick = onClick, modifier = modifier) { Text(text) }
|
||||
}
|
||||
```
|
||||
|
||||
The carve-out is for modifiers that are part of the **identity** of the composable — what makes an `Avatar` an avatar (the `.clip(CircleShape)` and a default `.size(48.dp)`), not where it sits on the screen. Test: can you imagine a caller wanting a version of this composable *without* that modifier? If yes, push it out. If no (an avatar without `clip(CircleShape)` isn't an avatar), keep it — but put it *after* the caller's modifier in the chain (see §2).
|
||||
|
||||
## 4. Construct modifier chains as one fluent expression
|
||||
|
||||
Recomposition re-runs the composable body — every modifier expression is re-evaluated. Reassigning `var modifier =` step-by-step looks plausible but breaks the visual flow, invites further mutation, and produces nothing a chain doesn't.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — visual flow broken into reassignments; `var` invites more mutation
|
||||
@Composable
|
||||
fun Demo() {
|
||||
var m = Modifier
|
||||
m = m.padding(16.dp)
|
||||
m = m.fillMaxSize()
|
||||
Box(m) { }
|
||||
}
|
||||
|
||||
// ❌ ALSO BAD — same shape, dressed up with .then()
|
||||
@Composable
|
||||
fun Demo() {
|
||||
var m = Modifier
|
||||
m = m.padding(16.dp)
|
||||
m = m.then(Modifier.fillMaxSize())
|
||||
Box(m) { }
|
||||
}
|
||||
```
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD
|
||||
@Composable
|
||||
fun Demo() {
|
||||
val m = Modifier
|
||||
.padding(16.dp)
|
||||
.fillMaxSize()
|
||||
Box(m) { }
|
||||
}
|
||||
```
|
||||
|
||||
`val`, not `var`: once the chain is built, nothing should re-bind it. The reassignment shape is what makes `var` look necessary; the chain shape doesn't need it.
|
||||
|
||||
### Inline at the call site is fine for short chains
|
||||
|
||||
For one or two calls, build the modifier inline. The "extract to a `val`" rule only earns its keep when the chain is long enough to be worth naming, or when the same chain repeats.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — short chain inline
|
||||
Box(modifier = Modifier.fillMaxWidth()) { … }
|
||||
Box(modifier = Modifier.padding(8.dp).background(Color.Red)) { … }
|
||||
```
|
||||
|
||||
### Conditional segments stay on the chain
|
||||
|
||||
A common reason to reach for `var` is "the modifier depends on a condition." It doesn't — splice the condition inline:
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — conditional inside the chain, still one expression
|
||||
Box(
|
||||
modifier = Modifier
|
||||
.fillMaxWidth()
|
||||
.then(if (selected) Modifier.background(Color.Red) else Modifier),
|
||||
)
|
||||
```
|
||||
|
||||
`Modifier` (the empty modifier) is the identity element for `.then` — it lets you keep the chain shape when one branch contributes nothing.
|
||||
|
||||
## 5. Multiline formatting at the call site
|
||||
|
||||
When a `modifier` argument's chain has **three or more** calls, format multiline with one call per line. Indent the chain so the dotted calls align beneath the value.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — three+ calls on one line; hard to scan
|
||||
Box(
|
||||
modifier = modifier.fillMaxSize().padding(16.dp).weight(1f),
|
||||
)
|
||||
|
||||
// ✅ GOOD
|
||||
Box(
|
||||
modifier = modifier
|
||||
.fillMaxSize()
|
||||
.padding(16.dp)
|
||||
.weight(1f),
|
||||
)
|
||||
```
|
||||
|
||||
One or two calls stay on a single line — the threshold is the call count, not the character count. If a single call has very long arguments, that's a different problem (extract a `val`, or shorten the arguments).
|
||||
|
||||
This applies *only* to a parameter named `modifier`. Other fluent-style arguments aren't covered here.
|
||||
|
||||
## 6. Hoist single conditionals out of the layout
|
||||
|
||||
When a layout's *only* content is one `if`, the layout exists solely to "hold" the conditional. Move the `if` outside — the layout will only exist when it has something to show.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — Column always emitted; only its inner content is conditional
|
||||
@Composable
|
||||
fun A() {
|
||||
Column {
|
||||
if (showHeader) {
|
||||
Text("Title")
|
||||
Text("Subtitle")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ GOOD — Column only exists when it has content
|
||||
@Composable
|
||||
fun A() {
|
||||
if (showHeader) {
|
||||
Column {
|
||||
Text("Title")
|
||||
Text("Subtitle")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The benefit isn't a performance win — the runtime handles both fine — it's that the second form *reads* as "header section, conditionally." The first reads as "always-on column that may or may not have content."
|
||||
|
||||
### The carve-outs (and why)
|
||||
|
||||
- **Layout carries visual semantics that aren't conditional.** When the layout call passes `modifier`, `contentAlignment`, `horizontalArrangement`, or `verticalAlignment`, those arguments describe the *container*, not the content. Hoisting the conditional either loses those (the container collapses with the content) or duplicates them into both branches. Leave it.
|
||||
|
||||
```kotlin
|
||||
// ✅ KEEP AS-IS — modifier on the container is doing visible work
|
||||
@Composable
|
||||
fun A(modifier: Modifier = Modifier) {
|
||||
Box(modifier = modifier) {
|
||||
if (something) {
|
||||
Text("Bleh1")
|
||||
Text("Bleh2")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **There are siblings to the `if`.** The layout has other content; the `if` is just one piece. Hoisting either pulls the siblings out (changing the layout) or leaves a different shape behind. Leave it.
|
||||
|
||||
- **`if … else …` with both branches contributing composables.** Both branches do work; nothing to hoist; the layout *is* the shared container.
|
||||
|
||||
```kotlin
|
||||
// ✅ KEEP AS-IS — both branches contribute to the layout
|
||||
Box {
|
||||
if (something) Text("Hint") else innerTextField()
|
||||
}
|
||||
```
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Symptom | Diagnosis | Fix |
|
||||
|---|---|---|
|
||||
| `@Composable fun Foo(text: String)` with `Column`/`Box`/`Text` in body | No `modifier` param (§1) | Add `modifier: Modifier = Modifier`; pass to root |
|
||||
| `modifier: Modifier = Modifier` declared but never referenced | Param ignored (§2) | Apply to root layout's `modifier` arg |
|
||||
| `modifier` passed to a child, not the root | Wrong target (§2) | Move to the outermost layout's `modifier` |
|
||||
| `modifier = Modifier.x().y().then(modifier)` | Caller's modifier last (§2) | Reorder: `modifier = modifier.x().y()` |
|
||||
| `modifier = modifier.fillMaxWidth().padding(...)` on a general-purpose component | Layout hardcoded (§3) | Remove the hardcoded calls; let callers add them |
|
||||
| Sibling composables in the file don't have `modifier` either | Spreading anti-pattern | Fix this one; fix siblings opportunistically |
|
||||
| `mod: Modifier = Modifier` or `wrapperModifier: Modifier = Modifier` | Wrong name (§1) | Rename to exactly `modifier` |
|
||||
| `var m = Modifier` followed by `m = m.xxx()` reassignments | Stepwise modifier construction (§4) | One fluent chain on a `val`, or build inline |
|
||||
| `var m = Modifier; m = m.then(Modifier.xxx())` | Same shape via `.then` (§4) | Collapse `.then(Modifier.x())` to `.x()` in the chain |
|
||||
| Modifier branch needs a condition | Reaching for `var` (§4) | `.then(if (c) Modifier.x() else Modifier)` inside the chain |
|
||||
| `modifier = modifier.a().b().c()` on one line | Long chain not formatted (§5) | One call per line, indented under the value |
|
||||
| `Layout { if (cond) X() }` with no other content and no layout-tuning args | Hoist (§6) | Move the `if` outside the layout |
|
||||
| `Box(modifier = …) { if (cond) X() }` | Layout carries semantics — leave (§6 carve-out) | Keep as-is |
|
||||
| `Box { if (cond) X() else Y() }` | Both branches contribute — leave (§6 carve-out) | Keep as-is |
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- **Composables that don't emit layout.** A `@Composable fun computeColor(): Color` or a `@Composable @ReadOnlyComposable` accessor doesn't emit a layout node. No `modifier` parameter needed (and a `@ReadOnlyComposable` couldn't accept one anyway).
|
||||
- **`@Preview` functions.** Previews are throwaway entry points; the framework calls them with no caller. A `modifier` parameter would be unused dead weight.
|
||||
- **Test-only composables** inside `*Test` sources whose only caller is `composeTestRule.setContent { … }`. Same reasoning as previews.
|
||||
- **Internal layout primitives that take a `modifier` as their *first required* parameter** (very rare; framework-level). The rule is "first *optional* param"; some private utilities legitimately have `modifier` upfront as required.
|
||||
- **Modifier assembled imperatively from animation state.** A modifier built by appending values from `Animatable` or other procedural sources may legitimately need intermediate variables. The chain isn't the goal; readability is. If the chain becomes a worse expression, write the imperative form.
|
||||
- **Slot APIs that store modifiers** in a data class or builder (rare; usually framework-level code). The fluent-chain idea is about user-site construction.
|
||||
- **Test composables** pinning specific recomposition shapes — usually fine either way; don't refactor test composables purely for style.
|
||||
|
||||
The declaration-side rules (§1–§3) should not be skipped merely because "this composable is internal", "only used in one place", "I'd rather not have the extra parameter on the signature", or "we know all the callers already". Those are exactly the rationalisations that produce composables that become single-use the day someone wants to call them twice.
|
||||
|
||||
## Red flags during review
|
||||
|
||||
| Thought | Reality |
|
||||
|---|---|
|
||||
| "This composable is internal-only — adding `modifier` is over-engineering" | The parameter is eight characters and a default. It's not over-engineering; it's the convention. Skipping it is the over-engineering — it's a custom decision against the grain of every Compose API. |
|
||||
| "It's only used in one place, so I know the layout requirements" | "Only used in one place" describes today. The cost of the parameter is paid once; the cost of refactoring callers when the second use site appears is paid per caller. |
|
||||
| "The sibling composables in this file don't have `modifier` either, so I'm matching style" | Spreading an anti-pattern isn't matching style. Fix this one. Fix the siblings opportunistically. |
|
||||
| "The parent always wants `.fillMaxWidth()` here" | Then the parent passes `.fillMaxWidth()`. The composable doesn't decide that for callers it hasn't met yet. |
|
||||
| "I'll add it when someone needs it" | You're someone. You need it now (for the convention). The next caller won't add it either — they'll work around its absence. |
|
||||
| "It's a tiny composable — the modifier param is noise" | The param is eight characters at the declaration and zero characters at any call site that doesn't need it. The "noise" is imagined. |
|
||||
| "I added `modifier` but kept `.fillMaxWidth()` on the root so the home screen doesn't have to" | Then the *not*-home-screen caller can't unset it. Move the `.fillMaxWidth()` to the caller. |
|
||||
| "I need `var` for the modifier because the chain depends on a condition" | A conditional segment is `.then(if (c) Modifier.x() else Modifier)`, still on one chain. No `var` needed. |
|
||||
| "Three lines is too few to make multiline" | Three chained calls *is* the threshold. Below three, one line. At or above three, multiline. |
|
||||
| "The Column adds nothing but I'll keep it for symmetry" | Then hoist the conditional and keep the Column inside the consequent — symmetry preserved, no always-on container. |
|
||||
| "I'll put the `if` inside because the layout already exists" | "Already exists" is the bug. The layout shouldn't exist when the condition is false. |
|
||||
|
||||
## Related
|
||||
|
||||
- [`compose-slot-api-pattern`](../compose-slot-api-pattern/SKILL.md) — the other half of declaring a reusable composable's public API: take `@Composable () -> Unit` slots for variable content. A reusable component takes both a `modifier` parameter *and* slots — caller owns placement *and* what to place.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: compose-recomposition-performance
|
||||
description: Use when investigating Jetpack Compose recomposition performance, skippable/restartable composables, composables.txt or compiler reports, Layout Inspector recomposition counts, or frame-rate State reads in composition vs layout/draw, and it is not yet clear whether the cause is parameter stability or deferred reads. Technique-layer skill — complements the codebase-specific compose-expert.
|
||||
---
|
||||
|
||||
# Compose recomposition performance
|
||||
|
||||
Router only — deep fixes live in [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) and [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md).
|
||||
|
||||
## Two axes
|
||||
|
||||
1. **Parameter stability / skipping** — can Compose skip this restartable composable; are arguments stable and comparable?
|
||||
2. **Where `State` is read** — is frame-rate `State` read during composition vs layout/draw?
|
||||
|
||||
Either axis can dominate; they combine independently.
|
||||
|
||||
## Route here → focused skill
|
||||
|
||||
| Primary suspicion | Next skill |
|
||||
|---|---|
|
||||
| Skipping, unstable params, compiler/`composables.txt` churn | [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) |
|
||||
| Frame-rate `State` read phase (composition vs layout/draw) | [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) |
|
||||
| Evidence for both | Apply both skills in parallel |
|
||||
|
||||
## Review order
|
||||
|
||||
1. Decide which axis fits the evidence; open the matching skill.
|
||||
2. If unclear, sample both — stability churn vs composition-phase reads of fast `State`.
|
||||
3. Re-measure after changes.
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- Recomposition tracks real data changes, or the bug is correctness not cost.
|
||||
- No profiler / compiler signal suggests a problem.
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: compose-side-effects
|
||||
description: Use when writing or reviewing Jetpack Compose code with LaunchedEffect, DisposableEffect, SideEffect, rememberCoroutineScope, rememberUpdatedState, snapshotFlow, snackbar, navigation, focus requests, analytics, or event Flow collection. Technique-layer skill — complements the codebase-specific compose-expert.
|
||||
---
|
||||
|
||||
# Compose: side effects
|
||||
|
||||
## Core principle
|
||||
|
||||
Composable bodies describe UI. They can be recomposed, skipped, or abandoned. Work that changes the outside world belongs in an effect API whose lifecycle matches the work.
|
||||
|
||||
## Pick the smallest effect
|
||||
|
||||
| Need | API |
|
||||
|---|---|
|
||||
| Publish Compose state to non-Compose code after every successful recomposition | `SideEffect` |
|
||||
| Register/unregister a listener, callback, observer, or resource | `DisposableEffect(keys...)` |
|
||||
| Run suspending, deferred, or keyed one-shot work | `LaunchedEffect(keys...)` |
|
||||
| Launch suspending work from a user event callback | `rememberCoroutineScope()` |
|
||||
| Convert Compose snapshot reads into a Flow inside a coroutine | `snapshotFlow { ... }` inside `LaunchedEffect` |
|
||||
|
||||
## Effect keys
|
||||
|
||||
Keys define restart identity. When any key changes, the old effect is cancelled/disposed and a new one starts.
|
||||
|
||||
```kotlin
|
||||
// ✅ Restart collection when userId changes
|
||||
LaunchedEffect(userId) {
|
||||
repository.events(userId).collect { event -> handle(event) }
|
||||
}
|
||||
|
||||
// ❌ Unit hides a changing input; collection keeps using the first userId
|
||||
LaunchedEffect(Unit) {
|
||||
repository.events(userId).collect { event -> handle(event) }
|
||||
}
|
||||
```
|
||||
|
||||
Use stable, semantic keys:
|
||||
|
||||
- Use the thing whose lifecycle the effect follows: `userId`, `screenId`, `lifecycleOwner`, `focusRequester`.
|
||||
- Do not use broad objects (`state`, `viewModel`) when only one property matters.
|
||||
- Do not add changing lambdas as keys unless you really want restarts on every lambda change.
|
||||
|
||||
## Avoid stale captures
|
||||
|
||||
For long-running effects that should not restart but need the latest callback or value, use `rememberUpdatedState`.
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
fun Timeout(onTimeout: () -> Unit) {
|
||||
val latestOnTimeout by rememberUpdatedState(onTimeout)
|
||||
|
||||
LaunchedEffect(Unit) {
|
||||
delay(1_000)
|
||||
latestOnTimeout()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use this when the lifecycle is "start once" but the invoked lambda should stay fresh. Common cases:
|
||||
|
||||
- A timeout or splash effect should not restart when `onTimeout` changes, but it should call the latest callback.
|
||||
- A lifecycle observer should stay registered to the same owner, but invoke the latest `onStart` / `onStop` lambdas.
|
||||
- A long-running collector should keep its collection lifecycle, but call the latest event handler.
|
||||
|
||||
Do not use `rememberUpdatedState` to avoid choosing proper keys. If the changed value should restart the work, make it a key instead:
|
||||
|
||||
```kotlin
|
||||
// BAD: userId changes should restart the collection, not update a captured value.
|
||||
val latestUserId by rememberUpdatedState(userId)
|
||||
LaunchedEffect(Unit) {
|
||||
repository.events(latestUserId).collect { event -> handle(event) }
|
||||
}
|
||||
|
||||
// GOOD: the collection lifecycle follows userId.
|
||||
LaunchedEffect(userId) {
|
||||
repository.events(userId).collect { event -> handle(event) }
|
||||
}
|
||||
```
|
||||
|
||||
`rememberUpdatedState` also does not make render state "non-recomposing." If the UI needs to display a changing value, read normal `State` in composition or use the deferred-read patterns in [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) for frame-rate values.
|
||||
|
||||
## Collecting Flow
|
||||
|
||||
Use `LaunchedEffect` for **side-effect/event flows**: snackbars, navigation events, analytics events, focus commands, or other streams where each emission triggers imperative work.
|
||||
|
||||
```kotlin
|
||||
LaunchedEffect(events) {
|
||||
events.collect { event ->
|
||||
snackbarHostState.showSnackbar(event.message)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not collect render state imperatively just to mutate local state. For UI state, collect near the state holder and pass plain values into the UI composable—the **state-holder vs UI split**, `collectAsStateWithLifecycle()` / `collectAsState()`, and preview-friendly wiring are covered in [`compose-state-holder-ui-split`](../compose-state-holder-ui-split/SKILL.md). Do not duplicate that architecture here.
|
||||
|
||||
On Android, prefer lifecycle-aware collection where available; use `collectAsState()` on targets without lifecycle-aware APIs.
|
||||
|
||||
For Compose state reads, use `snapshotFlow`:
|
||||
|
||||
```kotlin
|
||||
LaunchedEffect(listState) {
|
||||
snapshotFlow { listState.firstVisibleItemIndex }
|
||||
.distinctUntilChanged()
|
||||
.collect { index -> analytics.visibleIndex(index) }
|
||||
}
|
||||
```
|
||||
|
||||
`snapshotFlow { ... }.map { ... }` without a terminal `collect` does nothing.
|
||||
|
||||
## User events
|
||||
|
||||
Use `rememberCoroutineScope()` when a click or gesture starts suspending work:
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
fun SaveButton(snackbarHostState: SnackbarHostState) {
|
||||
val scope = rememberCoroutineScope()
|
||||
|
||||
Button(
|
||||
onClick = {
|
||||
scope.launch {
|
||||
snackbarHostState.showSnackbar("Saved")
|
||||
}
|
||||
},
|
||||
) {
|
||||
Text("Save")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Avoid "event flag" state just to trigger a `LaunchedEffect`. The click already is the event.
|
||||
|
||||
## Registration and cleanup
|
||||
|
||||
Use `DisposableEffect` for paired setup/teardown:
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
fun ObserveLifecycle(owner: LifecycleOwner, observer: LifecycleObserver) {
|
||||
DisposableEffect(owner, observer) {
|
||||
owner.lifecycle.addObserver(observer)
|
||||
onDispose {
|
||||
owner.lifecycle.removeObserver(observer)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Every registration path should have a matching `onDispose` cleanup path.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| Network request directly in the composable body | Usually move to a ViewModel/state holder; use `LaunchedEffect` only for UI-owned keyed work |
|
||||
| Analytics property written from the composable body | Use `SideEffect` when it should publish after every successful recomposition |
|
||||
| Impression/event logged from the composable body | Use `LaunchedEffect(key)` when it should run once for that key |
|
||||
| `LaunchedEffect(Unit)` captures changing `id` | Key by `id`, or use `rememberUpdatedState` if it must not restart |
|
||||
| `rememberUpdatedState(id)` used so `LaunchedEffect(Unit)` keeps running after `id` changes | Hidden lifecycle bug | Key the effect by `id` |
|
||||
| Long-lived effect invokes an old callback after recomposition | Stale capture | Wrap the callback with `rememberUpdatedState` and call the wrapper inside the effect |
|
||||
| `LaunchedEffect(state) { ... }` restarts too often | Key by the specific property |
|
||||
| `LaunchedEffect(...) { nonSuspendSetter() }` | Usually `SideEffect`; keep `LaunchedEffect` only for keyed one-shot/deferred work |
|
||||
| Listener added in `LaunchedEffect` with no cleanup | Use `DisposableEffect` |
|
||||
| Launching from click by setting `shouldShowSnackbar = true` | Use `rememberCoroutineScope()` in the click callback |
|
||||
|
||||
## Red flags during review
|
||||
|
||||
- "This only runs once" about code in a composable body.
|
||||
- `LaunchedEffect(Unit)` in a function with changing parameters.
|
||||
- A flow chain inside an effect with no terminal collection.
|
||||
- Effects whose keys are chosen to silence lint instead of model lifecycle.
|
||||
- Callback lambdas used from long-lived effects without either a key or `rememberUpdatedState`.
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: compose-slot-api-pattern
|
||||
description: Use when designing or reviewing a reusable Jetpack Compose component whose visual regions vary by caller, or when primitive content parameters and boolean shape flags are accumulating. Technique-layer skill — complements the codebase-specific compose-expert.
|
||||
---
|
||||
|
||||
# Compose: slot API pattern
|
||||
|
||||
## Core principle
|
||||
|
||||
A reusable Compose component's job is to lay things out, not to enumerate what it lays out. The moment you write `title: String, subtitle: String?, leadingIcon: ImageVector?, trailingIcon: ImageVector?, trailingText: String?, showSwitch: Boolean, switchValue: Boolean, onSwitchChange: (Boolean) -> Unit?, badge: String?, …`, the component has stopped describing a layout and started enumerating call sites — and the next call site will need a parameter the component doesn't have.
|
||||
|
||||
The fix is to **delegate content to the caller** via `@Composable` lambda parameters. The component contributes structure (where the leading bit, headline, supporting bit, trailing bit go). The caller contributes everything that goes *in* those slots.
|
||||
|
||||
Material 3's `ListItem` is the canonical example: every visual piece is a slot (`headlineContent`, `supportingContent`, `leadingContent`, `trailingContent`, `overlineContent`), not a primitive. That's not over-engineering — it's the design that scales to every list-item shape the design system needs without ever editing `ListItem` again.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
You're designing or reviewing a Compose component intended for reuse (more than one call site, now or planned), its visual content varies by caller, and any of these is true:
|
||||
|
||||
- Its signature has `title: String`, `icon: ImageVector`, `actionText: String?`, etc. — primitive types describing *content*.
|
||||
- It has multiple optional-content parameters that vary by call site (`subtitle: String?`, `leadingIcon: ImageVector?`, `trailingText: String?`).
|
||||
- It has boolean flags whose only purpose is to switch between content shapes (`showChevron: Boolean`, `showSwitch: Boolean`, `mode: Mode.Text | Mode.Switch | …`).
|
||||
- It accepts a `String` parameter where one caller would want a `Text` with custom style, a second caller a `Text` with a `Badge`, a third caller a row of icons.
|
||||
- It already has *one* slot (often `trailing` or `content`) and the rest of the parameters are still primitives.
|
||||
|
||||
## 1. Replace primitive content with `@Composable` slots
|
||||
|
||||
Where the component asks for caller-controlled *content*, prefer a `@Composable () -> Unit` slot. Where the slot is structurally required, leave it non-nullable with no default. Where it's optional, make it nullable with a `null` default.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — primitive parameters; trailing area is the only slot; everything else is locked
|
||||
@Composable
|
||||
fun SettingsRow(
|
||||
title: String,
|
||||
onClick: () -> Unit,
|
||||
modifier: Modifier = Modifier,
|
||||
subtitle: String? = null,
|
||||
leadingIcon: ImageVector? = null,
|
||||
trailing: (@Composable () -> Unit)? = null,
|
||||
) { … }
|
||||
```
|
||||
|
||||
This shape *seems* fine because the call sites today fit (`title` is always single-line text, `leadingIcon` is always an `ImageVector`). The problem is the *next* call site: a row with a `Badge` next to the title, a leading slot that's a circular avatar (not an `ImageVector`), a subtitle that's a row of chips. Each forces either a new parameter, a new flag, or a workaround.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — every visual region is a slot; the row describes structure, not content
|
||||
@Composable
|
||||
fun SettingsRow(
|
||||
headlineContent: @Composable () -> Unit,
|
||||
onClick: () -> Unit,
|
||||
modifier: Modifier = Modifier,
|
||||
supportingContent: (@Composable () -> Unit)? = null,
|
||||
leadingContent: (@Composable () -> Unit)? = null,
|
||||
trailingContent: (@Composable () -> Unit)? = null,
|
||||
) { … }
|
||||
```
|
||||
|
||||
Call sites stay short because the typical content is a one-liner:
|
||||
|
||||
```kotlin
|
||||
SettingsRow(
|
||||
headlineContent = { Text("Account") },
|
||||
leadingContent = { Icon(Icons.Default.Person, contentDescription = null) },
|
||||
trailingContent = { SettingsRowDefaults.Chevron() },
|
||||
onClick = { … },
|
||||
)
|
||||
```
|
||||
|
||||
And the awkward cases that *would* have required new primitive parameters now don't:
|
||||
|
||||
```kotlin
|
||||
SettingsRow(
|
||||
headlineContent = {
|
||||
Row(verticalAlignment = Alignment.CenterVertically) {
|
||||
Text("Inbox")
|
||||
Spacer(Modifier.width(8.dp))
|
||||
Badge { Text("3") }
|
||||
}
|
||||
},
|
||||
onClick = { … },
|
||||
)
|
||||
```
|
||||
|
||||
### Slot naming
|
||||
|
||||
- Use `xxxContent` for free-form `@Composable () -> Unit` slots (`headlineContent`, `supportingContent`, `trailingContent`) — matches Material 3.
|
||||
- Use a singular noun (`title`, `icon`, `actions`) when the slot is semantically constrained and the component name disambiguates (`Scaffold(topBar = { … }, bottomBar = { … }, floatingActionButton = { … })`).
|
||||
- Don't use `content` *and* other `xxxContent` slots together — pick one convention per component.
|
||||
|
||||
## 2. Scope receivers when the slot emits into a layout
|
||||
|
||||
If the slot's content will sit inside a `Row`/`Column`/`Box` whose layout features (`Modifier.weight`, `BoxScope.matchParentSize`, alignment) should be available to the caller, declare the slot as a receiver lambda: `@Composable RowScope.() -> Unit`.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — actions render inside a Row, but callers can't use RowScope.weight()
|
||||
@Composable
|
||||
fun MyTopBar(
|
||||
title: @Composable () -> Unit,
|
||||
actions: @Composable () -> Unit = {}, // ← caller has no Row scope
|
||||
)
|
||||
```
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — caller gets RowScope; .weight() and alignment-by works inside
|
||||
@Composable
|
||||
fun MyTopBar(
|
||||
title: @Composable () -> Unit,
|
||||
actions: @Composable RowScope.() -> Unit = {},
|
||||
)
|
||||
```
|
||||
|
||||
This is what makes `TopAppBar(actions = { IconButton(…); IconButton(…) })` work — the caller is implicitly inside a `RowScope`.
|
||||
|
||||
Don't bolt a scope receiver onto every slot reflexively. The receiver should match the actual parent layout the slot emits into. If the slot is rendered inside a `Box`, use `BoxScope`. If it's inside a `Column`, use `ColumnScope`. If the parent is not a standard layout (or none of its scope APIs are useful in slot content), no receiver.
|
||||
|
||||
## 3. Optional slots — nullable with `null` default
|
||||
|
||||
For slots that may be absent, prefer `(@Composable () -> Unit)? = null` over `@Composable () -> Unit = {}`:
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — empty default; "no leading content" is the empty lambda
|
||||
leadingContent: @Composable () -> Unit = {}
|
||||
|
||||
// ✅ GOOD — null means "no slot"; the component can omit space/padding when absent
|
||||
leadingContent: (@Composable () -> Unit)? = null
|
||||
```
|
||||
|
||||
Why: with a nullable slot, the *component* can branch on `leadingContent != null` and skip the slot's container, spacing, padding entirely. With an empty default, the layout still allocates the slot — sometimes you see a stray padding or spacer around content that turned out to be nothing. The nullable form makes the "absent" case structurally distinct, which is almost always what you want.
|
||||
|
||||
The trade-off: callers who pass an explicit empty `{}` to silence a slot now have to pass `null` or omit the argument. That's the right answer either way — they shouldn't be passing `{}`.
|
||||
|
||||
## 4. Defaults live in `XxxDefaults`
|
||||
|
||||
When you find yourself documenting "the trailing slot should usually be a chevron" or "pass `MaterialTheme.colorScheme.surface` for the default background", co-locate the helpers in a `XxxDefaults` object next to the component:
|
||||
|
||||
```kotlin
|
||||
object SettingsRowDefaults {
|
||||
@Composable
|
||||
fun Chevron() = Icon(
|
||||
imageVector = Icons.AutoMirrored.Filled.KeyboardArrowRight,
|
||||
contentDescription = null,
|
||||
)
|
||||
|
||||
@Composable
|
||||
fun TrailingValue(text: String) = Text(
|
||||
text = text,
|
||||
style = MaterialTheme.typography.bodyMedium,
|
||||
color = MaterialTheme.colorScheme.onSurfaceVariant,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Call sites stay declarative for the common cases and the slot is still fully open for one-offs:
|
||||
|
||||
```kotlin
|
||||
SettingsRow(
|
||||
headlineContent = { Text("Notifications") },
|
||||
trailingContent = { SettingsRowDefaults.Chevron() },
|
||||
onClick = { … },
|
||||
)
|
||||
```
|
||||
|
||||
This matches Material 3's `ButtonDefaults`, `TopAppBarDefaults`, etc. — defaults that are themselves composable belong here, not as new component parameters with `MaterialTheme.x.y` defaults expanded inline.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Symptom | Diagnosis | Fix |
|
||||
|---|---|---|
|
||||
| `title: String, subtitle: String?, leadingIcon: ImageVector?` on a reusable component | Primitive content params (§1) | Convert to `xxxContent: (@Composable () -> Unit)?` slots |
|
||||
| Multiple boolean flags (`showChevron`, `showSwitch`) selecting trailing shapes | Enumerating shapes (§1) | One `trailingContent: (@Composable () -> Unit)?` slot |
|
||||
| A `mode: Mode.Sealed` parameter listing variants | Same as flag soup (§1) | Slot it |
|
||||
| `actions: @Composable () -> Unit = {}` inside a `Row` body | Missing scope receiver (§2) | `actions: @Composable RowScope.() -> Unit = {}` |
|
||||
| `slot: @Composable () -> Unit = {}` for an optional area | Empty-lambda default (§3) | `slot: (@Composable () -> Unit)? = null` and branch on it |
|
||||
| Component param `defaultColor: Color = MaterialTheme.colorScheme.surface` | Defaults inlined (§4) | Move to `XxxDefaults.color` and reference it |
|
||||
| Common trailing content repeats at every call site | Missing default helper (§4) | Add `XxxDefaults.Chevron()` etc. |
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- **Single-use components.** A composable used in exactly one place, with no plan to reuse, doesn't benefit from slot flexibility — and the slot indirection makes the code harder to read for the one reader. Primitive params + inline content is fine. (As soon as a second call site appears, slot it.)
|
||||
- **Design-system primitives where every caller must look identical.** A `Heading2(text: String)` exists *because* you want every H2 to look the same; making it `headlineContent: @Composable () -> Unit` invites callers to break the rule. Keep it primitive. (Conversely: if `Heading2` ever needs a badge inline, slot it.)
|
||||
- **Semantic parameters the component intentionally owns.** If the component owns typography, iconography, accessibility wording, or product consistency, a primitive parameter may be the constraint you want.
|
||||
- **Constrained-type parameters that genuinely are constrained.** A `Switch(checked: Boolean, onCheckedChange: ...)` doesn't need its checked indicator to be a slot. Booleans-with-callbacks are not "content."
|
||||
- **Performance-critical fast paths** (rare in app code; common in framework primitives). A slot is an allocated lambda. In the deepest LazyList item layer, sometimes primitives win. If you're not writing the framework, this doesn't apply.
|
||||
|
||||
## Red flags during review
|
||||
|
||||
| Thought | Reality |
|
||||
|---|---|
|
||||
| "Title is *always* a String — making it a slot is over-engineering" | "Always today" is the trap. Material's `ListItem.headlineContent` exists because tomorrow someone wants a `Text + Badge`. The slot is `8` characters of extra wrapping at every call site (`{ Text(…) }`); the refactor to add a slot later edits every existing call site. |
|
||||
| "Lambdas are heavier than strings" | At the scale of typical Compose UI, this isn't measurable — and the framework's own components (`Button`, `ListItem`, `TopAppBar`, `Scaffold`) all slot. If your component is in the hottest of hot paths, see "When NOT to apply." |
|
||||
| "I'll add a slot later if someone asks" | The slot turns one parameter into two parameters (the slot itself + maybe an internal flag) and edits every call site. The shape change isn't a "later" change. |
|
||||
| "I'll model the variants with a sealed `Trailing` type instead" | Sealed enumeration is bounded; slots are unbounded. A sealed type works *until* the day someone needs a variant you didn't anticipate — at which point you're back to editing the component. The slot avoids the cycle. |
|
||||
| "The leading area is *always* an icon, the trailing area varies — I'll slot only the trailing" | This is the partial-slot trap. The "always-an-icon" assumption breaks the first time a row needs an avatar or a flag emoji or a coloured shape. Slot leading too. |
|
||||
| "There's only one call site today" | If there's only one call site, you're probably not designing a reusable component yet. See "When NOT to apply" — primitives are fine for a true single-use. The moment you copy-paste it, slot it. |
|
||||
|
||||
## Related
|
||||
|
||||
- [`compose-modifier-and-layout-style`](../compose-modifier-and-layout-style/SKILL.md) — the modifier-parameter rule (§1–§3 there) travels with slot APIs. A reusable component takes a `modifier` parameter *and* slots its content; the caller owns both placement and what to place.
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: compose-stability-diagnostics
|
||||
description: Use when writing or reviewing Jetpack Compose parameter stability, compiler reports, skippability, unstable UI state classes, collection parameters, or Kotlin 2.0+ strong skipping behavior. Technique-layer skill — complements the codebase-specific compose-expert and kotlin-expert.
|
||||
---
|
||||
|
||||
# Compose stability diagnostics
|
||||
|
||||
## Core principle
|
||||
|
||||
Compose performance problems from parameters are about **whether inputs compare cheaply and predictably across recompositions**. With Kotlin 2.0.20+ strong skipping is enabled by default, so unstable parameters no longer automatically make restartable composables non-skippable. That does not make stability irrelevant: unstable parameters are compared by instance identity (`===`), stable parameters by equality (`equals`), and churny instances can still defeat skipping.
|
||||
|
||||
First identify the compiler mode you are on, then read reports in that context.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- A composable or screen recomposes more than expected and parameter churn is suspected.
|
||||
- A UI-state/model class is passed to composables and contains `List`, `Set`, `Map`, ranges, Java time/money types, or third-party types.
|
||||
- `composables.txt` / `classes.txt` shows unstable parameters or non-skippable composables.
|
||||
- A project uses Kotlin < 2.0.20, disables strong skipping, or has old Compose compiler report guidance.
|
||||
|
||||
## 1. Start with strong skipping
|
||||
|
||||
On Kotlin 2.0.20+, strong skipping is enabled by default. In that mode:
|
||||
|
||||
- Restartable composables are skippable even when parameters are unstable, unless explicitly opted out.
|
||||
- Stable parameters compare with `equals`.
|
||||
- Unstable parameters compare with instance equality (`===`).
|
||||
- Lambdas inside composables are automatically remembered based on captures.
|
||||
|
||||
That means the question changes from "is this composable skippable at all?" to "will these parameters compare the way I expect, and are callers creating new unstable instances every frame?"
|
||||
|
||||
For older compiler setups or strong skipping disabled, the legacy rule still matters: a restartable composable with unstable parameters may be restartable but not skippable.
|
||||
|
||||
## 2. Generate compiler reports
|
||||
|
||||
With Kotlin 2.0+ the Compose Compiler is configured through the Kotlin Gradle plugin:
|
||||
|
||||
```kotlin
|
||||
plugins {
|
||||
alias(libs.plugins.android.application) // or android.library / jvm
|
||||
alias(libs.plugins.kotlin.android) // or kotlin.multiplatform / kotlin.jvm
|
||||
alias(libs.plugins.compose.compiler)
|
||||
}
|
||||
|
||||
if (providers.gradleProperty("composeReports").orNull == "true") {
|
||||
composeCompiler {
|
||||
reportsDestination = layout.buildDirectory.dir("compose_compiler")
|
||||
metricsDestination = layout.buildDirectory.dir("compose_compiler")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then build the variant whose compiler configuration you care about, for example:
|
||||
|
||||
```bash
|
||||
./gradlew :app:assembleRelease -PcomposeReports=true
|
||||
```
|
||||
|
||||
Use release/non-debuggable builds for runtime profiling. Compiler reports are build-time outputs, so the important thing is matching the variant and compiler flags you ship.
|
||||
|
||||
Key files:
|
||||
|
||||
| File | What it tells you |
|
||||
|---|---|
|
||||
| `<module>-classes.txt` | Stability of classes and properties |
|
||||
| `<module>-composables.txt` | Restartable/skippable status and parameter stability |
|
||||
| `<module>-composables.csv` | Same data in sortable form |
|
||||
| `<module>-module.json` | Aggregate metrics |
|
||||
|
||||
## 3. Fix stability where semantics need it
|
||||
|
||||
Pick the lightest fix that makes the type's immutability or equality semantics true.
|
||||
|
||||
### Immutable collections
|
||||
|
||||
`kotlin.collections.List` is an interface; Compose cannot know the runtime implementation is immutable. Prefer `kotlinx.collections.immutable` at UI-state boundaries:
|
||||
|
||||
```kotlin
|
||||
// Before: unstable collection interfaces
|
||||
data class UiState(val items: List<Item>, val tags: Set<String>)
|
||||
|
||||
// After: immutable collection contracts
|
||||
import kotlinx.collections.immutable.ImmutableList
|
||||
import kotlinx.collections.immutable.ImmutableSet
|
||||
|
||||
data class UiState(val items: ImmutableList<Item>, val tags: ImmutableSet<String>)
|
||||
```
|
||||
|
||||
Producers convert once at the boundary with `.toImmutableList()` / `.toImmutableSet()`.
|
||||
|
||||
### `@Immutable` / `@Stable`
|
||||
|
||||
- Use `@Immutable` when every property is effectively immutable and equality describes all observable state.
|
||||
- Use `@Stable` for types whose mutable state is observable by Compose, typically via `MutableState`.
|
||||
|
||||
Do not annotate to silence a report. A false stability promise can produce stale UI.
|
||||
|
||||
### Third-party immutable types
|
||||
|
||||
For types you cannot annotate, use `stabilityConfigurationFiles`:
|
||||
|
||||
```kotlin
|
||||
composeCompiler {
|
||||
stabilityConfigurationFiles.add(
|
||||
rootProject.layout.projectDirectory.file("compose_stability.conf"),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```text
|
||||
java.math.BigDecimal
|
||||
java.math.BigInteger
|
||||
java.time.*
|
||||
kotlinx.datetime.*
|
||||
```
|
||||
|
||||
Only list types you are willing to promise are immutable. Do not list mutable types such as `java.util.Date`.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Symptom | Diagnosis | Fix |
|
||||
|---|---|---|
|
||||
| Kotlin 2.0.20+ but old docs say unstable means non-skippable | Strong skipping changed the default | Check comparison semantics and instance churn instead |
|
||||
| `unstable val items: List<Item>` | Interface collection | Use `ImmutableList<Item>` or another true immutable wrapper |
|
||||
| `unstable val price: BigDecimal` | External immutable type | Add to stability config |
|
||||
| `@Immutable` on a type with mutable internals | False promise | Fix the model or remove the annotation |
|
||||
| Composable skips poorly despite strong skipping | New unstable instance each recomposition | Remember, hoist, or make the type stable/equality-based |
|
||||
| Reports not generated | Compose compiler plugin missing or flag not set | Apply `org.jetbrains.kotlin.plugin.compose` and enable destinations |
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- The issue is a fast-changing `State` read in composition, such as scroll or animation. Use `compose-state-deferred-reads`.
|
||||
- The recomposition count matches real data changes.
|
||||
- The bug is wrong data or stale state, not excess work.
|
||||
- The code is test-only and readability is more important than report cleanliness.
|
||||
|
||||
## Related
|
||||
|
||||
- [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) - frame-rate state should often be read in layout/draw rather than composition.
|
||||
- [`compose-recomposition-performance`](../compose-recomposition-performance/SKILL.md) - entry point when you are not sure which recomposition axis is involved.
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
name: compose-state-deferred-reads
|
||||
description: Use when Jetpack Compose code reads scroll, animation, gesture, or other frame-rate State in composition, passes changing values across composable boundaries, or uses value-form layout/draw modifiers. Technique-layer skill — complements the codebase-specific compose-expert.
|
||||
---
|
||||
|
||||
# Compose state deferred reads
|
||||
|
||||
## Core principle
|
||||
|
||||
State reads invalidate the phase that reads them. If a `State<T>` is read in a composable body, changes invalidate composition. If it is read in layout or draw, changes can invalidate only layout or draw. Frame-rate state such as scroll offsets, animations, and drag positions usually belongs in layout/draw, not composition.
|
||||
|
||||
The fix is structural: keep the `State<T>` or a provider lambda, and read the value inside a layout/draw callback.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- `val x by animate*AsState(...)` is passed to `Modifier.offset(x = ...)`, `Modifier.size(...)`, `Modifier.graphicsLayer(...)`, or another value-form modifier.
|
||||
- `LazyListState.firstVisibleItemScrollOffset`, `ScrollState.value`, `Animatable.value`, or gesture state is read in a composable body.
|
||||
- A composable takes `scrollOffset: Int`, `progress: Float`, `dragOffset: Offset`, or similar frame-rate values.
|
||||
- Recomposition counters climb during scroll, animation, or gestures even when data is stable.
|
||||
|
||||
## 1. Prefer block-form modifiers
|
||||
|
||||
Several modifiers have value forms and block forms. The value form receives values already read in composition; the block form can read during layout or draw.
|
||||
|
||||
```kotlin
|
||||
// Before: animated value read in composition by the `by` delegate
|
||||
@Composable
|
||||
fun SelectionPill(selectedIndex: Int) {
|
||||
val offsetX by animateDpAsState(120.dp * selectedIndex)
|
||||
Box(Modifier.offset(x = offsetX))
|
||||
}
|
||||
|
||||
// After: State is kept, value is read in the layout-phase offset block
|
||||
@Composable
|
||||
fun SelectionPill(selectedIndex: Int) {
|
||||
val offsetX = animateDpAsState(120.dp * selectedIndex)
|
||||
Box(
|
||||
Modifier.offset {
|
||||
IntOffset(offsetX.value.roundToPx(), 0)
|
||||
},
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Common replacements:
|
||||
|
||||
| Composition read | Deferred read |
|
||||
|---|---|
|
||||
| `Modifier.offset(x = animatedX)` | `Modifier.offset { IntOffset(animatedX.value.roundToPx(), 0) }` |
|
||||
| `Modifier.graphicsLayer(translationY = y)` | `Modifier.graphicsLayer { translationY = yProvider() }` |
|
||||
| `val radius by animateFloatAsState(...); drawBehind { drawCircle(radius = radius) }` | `val radius = animateFloatAsState(...); drawBehind { drawCircle(radius = radius.value) }` |
|
||||
|
||||
The `drawBehind` block is already draw-phase; the important part is that the `State.value` read also happens inside that block.
|
||||
|
||||
## 2. Pass providers across composable boundaries
|
||||
|
||||
If the fast-changing value would cross a composable boundary, pass a provider lambda instead of a snapshot value:
|
||||
|
||||
```kotlin
|
||||
// Before: HomeScreen reads scroll offset in composition and passes the value down
|
||||
@Composable
|
||||
fun HomeScreen() {
|
||||
val listState = rememberLazyListState()
|
||||
LazyColumn(state = listState) {
|
||||
item { HeroImage(scrollOffset = listState.firstVisibleItemScrollOffset) }
|
||||
}
|
||||
}
|
||||
|
||||
@Composable
|
||||
fun HeroImage(scrollOffset: Int, modifier: Modifier = Modifier) {
|
||||
AsyncImage(
|
||||
model = "...",
|
||||
modifier = modifier.graphicsLayer(translationY = -scrollOffset / 2f),
|
||||
)
|
||||
}
|
||||
|
||||
// After: the only read happens inside graphicsLayer
|
||||
@Composable
|
||||
fun HomeScreen() {
|
||||
val listState = rememberLazyListState()
|
||||
LazyColumn(state = listState) {
|
||||
item {
|
||||
HeroImage(
|
||||
scrollOffsetProvider = {
|
||||
if (listState.firstVisibleItemIndex == 0) {
|
||||
listState.firstVisibleItemScrollOffset
|
||||
} else {
|
||||
0
|
||||
}
|
||||
},
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@Composable
|
||||
fun HeroImage(scrollOffsetProvider: () -> Int, modifier: Modifier = Modifier) {
|
||||
AsyncImage(
|
||||
model = "...",
|
||||
modifier = modifier.graphicsLayer {
|
||||
translationY = -scrollOffsetProvider() / 2f
|
||||
},
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Suffix provider parameters with `Provider` when that clarifies the deferred-read contract.
|
||||
|
||||
## 3. Other layout/draw read sites
|
||||
|
||||
State reads can also be deferred inside:
|
||||
|
||||
- `Modifier.layout { measurable, constraints -> ... }`
|
||||
- Custom `Alignment.align(...)`
|
||||
- `drawWithContent`, `drawBehind`, and other draw modifiers
|
||||
- Block-form layer/layout modifiers such as `graphicsLayer { ... }` and `offset { ... }`
|
||||
|
||||
Use these when the state changes where something is placed or painted. If the state decides *which composables exist*, it belongs in composition.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Symptom | Diagnosis | Fix |
|
||||
|---|---|---|
|
||||
| `val x by animateFloatAsState(...)` then `Modifier.offset(...)` | `by` reads in composition | Keep `State<Float>` and read `.value` in `offset {}` |
|
||||
| `Modifier.graphicsLayer(translationY = animatedY)` | Property-argument form uses composition values | Use `graphicsLayer { translationY = ... }` |
|
||||
| `Child(scrollOffset = listState.firstVisibleItemScrollOffset)` | Fast-changing value crosses boundary | `Child(scrollOffsetProvider = { ... })` |
|
||||
| Draw block still recomposes every frame | Value was read before draw block | Move the `State.value` read inside the draw block |
|
||||
| State chooses between different UI branches | Composition decision | Keep the read in composition |
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- The state controls which composables are emitted.
|
||||
- The animation is one-shot, cheap, and clarity wins.
|
||||
- You are writing tests where direct value assertions are simpler.
|
||||
- Runtime evidence shows recomposition is not the bottleneck.
|
||||
|
||||
## Related
|
||||
|
||||
- [`compose-state-holder-ui-split`](../compose-state-holder-ui-split/SKILL.md) - where state-holder vs plain UI split applies when passing providers/lambdas across boundaries.
|
||||
- [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) - parameter stability and compiler reports.
|
||||
- [`compose-modifier-and-layout-style`](../compose-modifier-and-layout-style/SKILL.md) - child composables need a normal `modifier` parameter before callers can move visual reads into modifiers.
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
name: compose-state-holder-ui-split
|
||||
description: Use when a Jetpack Compose screen-level composable takes a ViewModel/component/controller, collects state or effects, handles navigation/snackbars, or wires callbacks while also rendering layout. Technique-layer skill — complements the codebase-specific compose-expert and feed-patterns.
|
||||
---
|
||||
|
||||
# Compose: state holder/UI split
|
||||
|
||||
## Core principle
|
||||
|
||||
Separate state-holder wiring from UI rendering. The state-holder composable talks to ViewModels, components, flows, navigation, and side effects. The UI composable takes plain immutable UI state plus callbacks and describes layout.
|
||||
|
||||
This keeps screens previewable, testable, and easier to reuse across Android, Desktop, TV, and KMP/CMP targets.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
Use this when a Compose screen:
|
||||
|
||||
- Takes a ViewModel, component, controller, navigator, repository, or service directly.
|
||||
- Collects app/business state or side effects in the same function that lays out most UI.
|
||||
- Passes a whole state holder into child composables instead of explicit state and callbacks.
|
||||
- Is hard to preview because it needs dependency injection, navigation, lifecycle, or fake services.
|
||||
- Has UI tests that must construct a full app stack to verify a simple layout branch.
|
||||
|
||||
## The pattern
|
||||
|
||||
Use a small public state-holder composable:
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
fun ProfileScreen(component: ProfileComponent, modifier: Modifier = Modifier) {
|
||||
val state by component.state.collectAsStateWithLifecycle()
|
||||
|
||||
ProfileScreen(
|
||||
state = state,
|
||||
onNameChange = component::onNameChange,
|
||||
onSaveClick = component::save,
|
||||
onBackClick = component::back,
|
||||
modifier = modifier,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Then put UI in a plain composable that knows nothing about the state holder:
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
fun ProfileScreen(
|
||||
state: ProfileUiState,
|
||||
onNameChange: (String) -> Unit,
|
||||
onSaveClick: () -> Unit,
|
||||
onBackClick: () -> Unit,
|
||||
modifier: Modifier = Modifier,
|
||||
) {
|
||||
ProfileContent(
|
||||
name = state.name,
|
||||
isSaving = state.isSaving,
|
||||
canSave = state.canSave,
|
||||
onNameChange = onNameChange,
|
||||
onSaveClick = onSaveClick,
|
||||
onBackClick = onBackClick,
|
||||
modifier = modifier,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Private content functions can break up layout:
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
private fun ProfileContent(
|
||||
name: String,
|
||||
isSaving: Boolean,
|
||||
canSave: Boolean,
|
||||
onNameChange: (String) -> Unit,
|
||||
onSaveClick: () -> Unit,
|
||||
onBackClick: () -> Unit,
|
||||
modifier: Modifier = Modifier,
|
||||
) {
|
||||
// Layout only.
|
||||
}
|
||||
```
|
||||
|
||||
## Rules of thumb
|
||||
|
||||
| Concern | State-holder composable | UI composable |
|
||||
|---|---|---|
|
||||
| Collect ViewModel/component state | Yes | No |
|
||||
| Collect one-shot effects | Yes, or a tiny sibling effect handler | Usually no |
|
||||
| Hold dependency-injected objects | Yes | No |
|
||||
| Accept immutable UI state | Usually passes it through | Yes |
|
||||
| Accept lambdas for user events | Wires them | Calls them |
|
||||
| Own layout, modifiers, semantics, test tags | No/minimal | Yes |
|
||||
| Own UI-local state like scroll, focus, text input, animation, interaction | Sometimes seeds it | Yes |
|
||||
| Preview/screenshot friendly | Not necessarily | Yes |
|
||||
|
||||
The "no collection in UI composables" rule is about app/business state and side-effect streams. Plain UI composables can still own UI-local framework state: `rememberScrollState`, `rememberLazyListState`, `FocusRequester`, focus state, animation state, `TextFieldState`, `MutableInteractionSource.collectIsPressedAsState()`, and similar behavior that belongs to the rendered widget.
|
||||
|
||||
If that UI-local state grows into coordinated behavior with multiple related fields and operations, consult `compose-expert` (state hoisting section) to decide whether it should become a plain state holder class remembered in composition.
|
||||
|
||||
## What to pass
|
||||
|
||||
Pass the smallest useful UI contract:
|
||||
|
||||
- Prefer a dedicated `UiState`/`State` object over many unrelated primitives when the screen has real state.
|
||||
- Prefer explicit lambdas (`onRetryClick`, `onItemSelected`) over passing a whole component.
|
||||
- Keep domain models out of the UI composable if they force business rules into UI. Map to UI models when the UI needs a different shape.
|
||||
- Keep navigation as callbacks. The UI composable says "user clicked back", not "navigate to route X".
|
||||
- Frame-rate or UI-local values that should not force whole-tree recomposition when they change: prefer provider lambdas and deferred reads per [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md).
|
||||
|
||||
## Side effects
|
||||
|
||||
[`compose-side-effects`](../compose-side-effects/SKILL.md) covers effect APIs (`LaunchedEffect`, `DisposableEffect`, `SideEffect`), keys, cleanup, and `rememberUpdatedState`.
|
||||
|
||||
Handle effects near the state holder, where the effect source and imperative target are both available:
|
||||
|
||||
```kotlin
|
||||
@Composable
|
||||
fun ProfileScreen(component: ProfileComponent, snackbarHostState: SnackbarHostState) {
|
||||
val state by component.state.collectAsStateWithLifecycle()
|
||||
|
||||
LaunchedEffect(component) {
|
||||
component.effects.collect { effect ->
|
||||
when (effect) {
|
||||
ProfileEffect.Saved -> snackbarHostState.showSnackbar("Saved")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
ProfileScreen(state = state, onSaveClick = component::save)
|
||||
}
|
||||
```
|
||||
|
||||
If effect handling grows, extract `ProfileEffects(component, snackbarHostState)` rather than pushing the component into the UI composable.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Why it hurts | Fix |
|
||||
|---|---|---|
|
||||
| `fun Screen(viewModel: MyViewModel)` contains all layout | Hard to preview/test without Android lifecycle and DI | Add a plain UI overload that takes `state` and callbacks |
|
||||
| Child composables take `component` | Dependencies leak through the tree | Pass only the state/callbacks that child needs |
|
||||
| UI composable launches navigation | UI becomes coupled to app routing | Expose `onBackClick`, `onItemClick`, etc. |
|
||||
| UI composable collects app/business flows | Collection lifecycle is hidden in layout | Collect near the state holder and pass values down |
|
||||
| UI-local state is hoisted into the state holder for no reason | State holder starts owning layout mechanics | Keep scroll/focus/animation/text-field interaction state in the UI composable when it is only UI behavior |
|
||||
| Every tiny composable gets a state-holder overload | Too much ceremony | Split at screen/section boundaries, not every `Row` |
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- Tiny one-off composables that already take plain values and callbacks.
|
||||
- Design-system primitives such as `Button`, `Card`, or `ListItem`; those should expose slots and modifiers, not state holders.
|
||||
- Cases where the state-holder composable would only forward one primitive and add no isolation.
|
||||
|
||||
## Related
|
||||
|
||||
- [`compose-expert`](../compose-expert/SKILL.md) — Amethyst's shared-UI patterns, including state hoisting for UI element state and plain state holder classes.
|
||||
- [`compose-side-effects`](../compose-side-effects/SKILL.md) — effect keys and cleanup in Compose.
|
||||
- [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) — deferred reads for frame-rate / UI-local values passed across boundaries.
|
||||
- [`kotlin-multiplatform`](../kotlin-multiplatform/SKILL.md) — platform services, native views, and expect/interface boundaries when shared UI meets platform-specific leaves.
|
||||
@@ -0,0 +1,441 @@
|
||||
---
|
||||
name: kotlin-coroutines-structured-concurrency
|
||||
description: Use when writing or reviewing Kotlin code that stores CoroutineScope, launches from init/non-suspending APIs, calls runBlocking, or catches broad exceptions around suspend calls. Technique-layer skill — complements the codebase-specific kotlin-coroutines.
|
||||
---
|
||||
|
||||
# Kotlin coroutines: structured concurrency
|
||||
|
||||
## Core principle
|
||||
|
||||
A well-structured coroutine is a self-contained unit of asynchronous work — single entry, single exit, scoped to a lifecycle known at the call site.
|
||||
|
||||
**Scopes should usually be tied to the caller's lifecycle, not stored as a property on the callee.** A stored `CoroutineScope` is a strong review signal: the class must prove it owns cancellation, error reporting, restart behavior, and lifecycle. Most repositories, managers, use cases, and data sources cannot prove that, so they should expose `suspend` APIs instead.
|
||||
|
||||
The fix is almost always the same: **make the API `suspend` and let the caller own the scope.**
|
||||
|
||||
## When to use this skill
|
||||
|
||||
You're writing or reviewing Kotlin code and you see any of these:
|
||||
|
||||
- A class with `private val scope: CoroutineScope` (constructor param stored as a property)
|
||||
- An `init { scope.launch { ... } }` block
|
||||
- A non-suspending public function whose body is `scope.launch { ... }`
|
||||
- `runBlocking { ... }` in suspend-capable application code, or in tests where `runTest` should apply
|
||||
- `runCatching { suspendCall() }` or a `catch` on `Exception` / `Throwable` around a `suspend` call without rethrowing `CancellationException`
|
||||
- A `catch (e: CancellationException)` (or equivalent) around suspension that does not rethrow
|
||||
|
||||
## The silent-cancellation bug
|
||||
|
||||
The reason an unowned `CoroutineScope` property is so dangerous: "once a scope is cancelled, every future `launch` on it silently completes as cancelled — no exception, no log, nothing." The work just doesn't happen. This is one of the hardest coroutine bugs to diagnose, and it appears when a class holds a long-lived reference to a lifecycle it does not own.
|
||||
|
||||
If APIs are `suspend`, this can't happen: the caller's scope is either alive (work runs) or the call site cancels (the caller knows).
|
||||
|
||||
## Anti-patterns and fixes
|
||||
|
||||
### 1. CoroutineScope stored as a property
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD
|
||||
@Inject
|
||||
class UserRepository(
|
||||
private val scope: CoroutineScope,
|
||||
private val api: UserApi,
|
||||
) {
|
||||
fun refresh() {
|
||||
scope.launch { _state.value = api.fetchUser() }
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ GOOD
|
||||
@Inject
|
||||
class UserRepository(
|
||||
private val api: UserApi,
|
||||
) {
|
||||
suspend fun refresh(): User = api.fetchUser()
|
||||
}
|
||||
```
|
||||
|
||||
The repository no longer needs to know about coroutines at all. The caller (a ViewModel, a use case) decides on what scope, with what error handling, with what cancellation semantics.
|
||||
|
||||
### 2. init-block launches
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD: construction-time side effect, unbounded work
|
||||
class UserSession(private val scope: CoroutineScope, private val api: Api) {
|
||||
init { scope.launch { _user.value = api.load() } }
|
||||
}
|
||||
```
|
||||
|
||||
The constructor returns immediately. The caller can't `await` the load, can't see errors, can't cancel. The class is "alive" but its state is undefined.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD: explicit bootstrap, caller owns the suspension
|
||||
class UserSession(private val api: Api) {
|
||||
private var _user: User? = null
|
||||
val user: User get() = checkNotNull(_user) { "Call init() first" }
|
||||
|
||||
suspend fun init() { _user = api.load() }
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Fire-and-forget from non-UI classes
|
||||
|
||||
A non-suspending public function on a **non-UI class** (repository, manager, use case, data source) that launches into a class-owned scope. The caller gets no result, no error, no cancellation, and no guarantee the work ever ran.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — repository with stored scope and fire-and-forget public API
|
||||
class AnalyticsClient(private val scope: CoroutineScope, private val api: Api) {
|
||||
fun track(event: Event) {
|
||||
scope.launch { api.send(event) } // caller has no idea what happens
|
||||
}
|
||||
fun signOut() {
|
||||
scope.launch { api.signOut() } // silent failure if scope cancelled
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD
|
||||
class AnalyticsClient(private val api: Api) {
|
||||
suspend fun track(event: Event) = api.send(event)
|
||||
suspend fun signOut() = api.signOut()
|
||||
}
|
||||
```
|
||||
|
||||
#### Carve-out: the UI ↔ state-holder boundary
|
||||
|
||||
UI frameworks are non-suspending. A Composable's `onClick`, a Fragment's `onKeyEvent`, an Activity's `onNewIntent` — none can `suspend`. The state holder (ViewModel, Decompose Component, feature model, etc. — anything whose role is to absorb UI events and hold UI state) **is** the boundary that translates one-shot UI events into asynchronous work bound to the UI lifecycle. That's its job.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — state holder absorbs a non-suspending UI event onto its scope
|
||||
class FavouritesViewModel(private val repo: FavouritesRepository) : ViewModel() {
|
||||
fun onToggleFavourite(item: Item) {
|
||||
viewModelScope.launch { repo.toggleFavourite(item) }
|
||||
}
|
||||
}
|
||||
|
||||
// in Compose:
|
||||
ListItem(onClick = { viewModel.onToggleFavourite(item) })
|
||||
```
|
||||
|
||||
This is **not** the fire-and-forget anti-pattern. All three conditions must hold:
|
||||
|
||||
1. **State holder for a UI surface** — a ViewModel, Decompose Component, feature model, or equivalent UI state holder. Not a repository, manager, use case, or data source.
|
||||
2. **Lifecycle-bound scope** — `viewModelScope`, a Component's `coroutineScope` that's cancelled on destroy, a Composable's `rememberCoroutineScope()`. Not `AppScope`, not an injected long-lived scope, not an ad-hoc `CoroutineScope(...)`.
|
||||
3. **Caller really is a UI event** — Composable callback, key handler, lifecycle hook. Not another business-logic class calling through the state holder.
|
||||
|
||||
The repository / use case / data source layers underneath still expose `suspend` APIs. The state holder is the *only* layer where the non-suspending → suspending translation belongs.
|
||||
|
||||
"It feels like a state holder" isn't enough. The question is "does the UI directly bind to this?" If no, the carve-out doesn't apply.
|
||||
|
||||
### 4. Stored scopes that aren't injected
|
||||
|
||||
The same anti-pattern, without an injected scope:
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — same problem, scope is constructed in-class instead of injected
|
||||
class FooManager {
|
||||
private val scope = MainScope()
|
||||
private val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
|
||||
}
|
||||
```
|
||||
|
||||
Lifecycle is now owned by nothing and lives forever. Replace with `suspend` APIs.
|
||||
|
||||
The same is true if the instantiation is nested inside a function body — `fun foo() { CoroutineScope(...).launch { … } }` is just a stored scope with extra steps. Each call leaks a new uncancellable scope; bundling it into a `by lazy` property doesn't fix the underlying issue (the scope shouldn't exist at all).
|
||||
|
||||
### 5. DI-bound singletons / initializers that launch
|
||||
|
||||
A specific pattern that is hard to spot: a DI-bound class (`@SingleIn(AppScope)`, `@Singleton`, an `Initializer.initialize()`) launches a coroutine from its constructor / `init` block / `initialize()`. The launched work then has:
|
||||
|
||||
- **A non-deterministic start time** — whenever the graph realizes the binding. Cold-start ordering is invisible.
|
||||
- **No observable lifecycle.** Nothing else in the codebase can see whether it's running or has crashed.
|
||||
- **No `stop()` / restart path.** If upstream enters a bad state, the loop is uncancellable.
|
||||
- **No calling code to grep for.** Readers can't find "who starts this and when".
|
||||
|
||||
§1 says scopes should be tied to the caller's lifecycle. The DI-bound variant violates this indirectly: the *scope* may be injected, but the *launch* is hidden inside construction — same effect, harder to see.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — singleton boots work as a side effect of being constructed
|
||||
@SingleIn(AppScope::class)
|
||||
@Inject
|
||||
class TokenRefresher(
|
||||
@ForScope(AppScope::class) private val scope: CoroutineScope,
|
||||
private val auth: AuthService,
|
||||
) {
|
||||
init {
|
||||
scope.launch {
|
||||
while (isActive) {
|
||||
delay(5.minutes)
|
||||
auth.refreshIfNeeded()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ ALSO BAD — Initializer.initialize() that *launches*, not just registers
|
||||
class TokenInvalidatorInitializer @Inject constructor(
|
||||
@ForScope(AppScope::class) private val scope: CoroutineScope,
|
||||
private val store: AuthStore,
|
||||
private val invalidator: TokenInvalidator,
|
||||
) : Initializer {
|
||||
override fun initialize() {
|
||||
scope.launch { store.tokenChanges.collect { invalidator.invalidate() } }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Both look like "application-scoped singletons", but the **When NOT to apply** carve-out is *not* permission to launch from `init` / `initialize()`. It's permission for a singleton to own a scope when its API is suspending.
|
||||
|
||||
#### First ask: does this background-loop class need to exist at all?
|
||||
|
||||
Most background-loop classes exist only because no one inverted the observation. Three answers, in order of preference:
|
||||
|
||||
**Pattern 1 — invert into the consumer.** The class observes state forever to react when it changes. But *someone* mutates the state — sign-out flow, profile switch, flag-update handler. That mutation site is already in a coroutine context and is the natural place to do the work directly.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — no background loop, no scope, no class. The mutation site does the work.
|
||||
class Authenticator(
|
||||
private val authStore: AuthStore,
|
||||
private val tokenInvalidator: TokenInvalidator,
|
||||
) {
|
||||
suspend fun signOut() {
|
||||
authStore.clearTokens()
|
||||
tokenInvalidator.invalidate() // direct call at the mutation site
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The background-loop class is **deleted**. The work happens where the state changes.
|
||||
|
||||
When this applies: the consumer of the state has a clear lifecycle (a use case, an Authenticator, a service handler) and can perform the reaction inline.
|
||||
|
||||
**Pattern 2 — scheduled work.** Genuinely periodic or deferred. Use WorkManager / BGTaskScheduler. The enqueue is one-shot; make it suspending and call it once from an orchestrator that already runs at startup.
|
||||
|
||||
**Pattern 3 — explicit named launch site.** Sometimes the consumer is a synchronous API with no observable lifecycle (e.g., OpenTelemetry's `Sampler.shouldSample(...)`, an AIDL stub fanout, a broadcast receiver bridge). The observation has to live somewhere coroutine-aware, but it must live at an *explicit named call site* — not in the class's own `init`.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — work is named; an explicit call site owns the launch
|
||||
@SingleIn(AppScope::class)
|
||||
class OtelConfigurableSampler(...) : Sampler {
|
||||
@Volatile private var delegate: Sampler = ...
|
||||
|
||||
suspend fun observeRate(featureFlags: FeatureFlags) {
|
||||
featureFlags.observe(OTEL_SAMPLING_RATE).collect { rate ->
|
||||
delegate = Sampler.traceIdRatioBased(rate.coerceIn(0.0, 1.0))
|
||||
}
|
||||
}
|
||||
|
||||
override fun shouldSample(...) = delegate.shouldSample(...)
|
||||
}
|
||||
|
||||
// wired explicitly at the OTel SDK init module:
|
||||
applicationScope.launch { otelSampler.observeRate(featureFlags) }
|
||||
```
|
||||
|
||||
When this applies: the consumer is a synchronous API that calls *into* you with no observable lifecycle. The launch can't be invertible, but it must still be visible at a named call site.
|
||||
|
||||
#### Test for which pattern fits
|
||||
|
||||
"Is the consumer's lifecycle observable to me?"
|
||||
|
||||
- **Yes, and they're already in a coroutine context** → Pattern 1. Push the subscription into them; delete the background-loop class.
|
||||
- **The work is periodic / deferred** → Pattern 2. Suspend enqueue called once.
|
||||
- **No, they're a synchronous API with no observable lifecycle** → Pattern 3. Explicit launch site, not `init`.
|
||||
|
||||
If a fourth answer seems to fit — e.g., "I want a `Bootable` interface that launches everything for me" — that's the same anti-pattern with an extra layer of abstraction. The whole point is that launches be *visible*; auto-discovery by interface defeats it.
|
||||
|
||||
#### Initializers are still fine — *if they only register*
|
||||
|
||||
The `Initializer` pattern is correct when `initialize()` *registers* a listener or hook. The bug is when `initialize()` *launches* a coroutine.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD Initializer — registers a contributor, doesn't launch
|
||||
class FavouritesContributorInitializer @Inject constructor(
|
||||
private val registry: ContributorRegistry,
|
||||
private val favouritesContributor: FavouritesContributor,
|
||||
) : Initializer {
|
||||
override fun initialize() {
|
||||
registry.register(favouritesContributor)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`Initializer.initialize()` must not `launch` a coroutine.** If yours does, it's a Pattern 1/2/3 candidate.
|
||||
|
||||
#### Diagnostic for review
|
||||
|
||||
- Where is the start moment defined? If "wherever DI realizes me", bad.
|
||||
- Who can observe whether the work is running? If "no one", bad.
|
||||
- Who can stop or restart it? If "no one", bad.
|
||||
- Can a reader grep for the launch site? If no, bad.
|
||||
|
||||
If the answers are "the consumer / the orchestrator / the named call site" — you're good.
|
||||
|
||||
### 6. Swallowing `CancellationException`
|
||||
|
||||
A `catch` clause around a `suspend` call that matches `CancellationException` — directly, or through `Exception` / `Throwable` — and doesn't rethrow usually turns cancellation into silent success. The parent coroutine thinks the child finished; the child keeps running (or its side effects do); the cancellation contract is broken.
|
||||
|
||||
Same failure shape as §1's stored-scope bug, viewed from the other end: §1 hides the work *from* the caller's lifecycle; this hides cancellation *from* the work.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — catches CancellationException, never rethrows
|
||||
suspend fun fetch() {
|
||||
try {
|
||||
api.load()
|
||||
} catch (e: Exception) { // matches CancellationException too
|
||||
logger.warn("load failed", e)
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ ALSO BAD — runCatching has the same problem
|
||||
suspend fun fetch() {
|
||||
runCatching { api.load() }
|
||||
.onFailure { logger.warn("load failed", it) }
|
||||
}
|
||||
```
|
||||
|
||||
The acceptable shapes:
|
||||
|
||||
```kotlin
|
||||
// ✅ Separate catch first
|
||||
try { api.load() }
|
||||
catch (e: CancellationException) { throw e }
|
||||
catch (e: Exception) { logger.warn("load failed", e) }
|
||||
|
||||
// ✅ Conditional rethrow inside the broad catch
|
||||
try { api.load() }
|
||||
catch (e: Exception) {
|
||||
if (e is CancellationException) throw e
|
||||
logger.warn("load failed", e)
|
||||
}
|
||||
|
||||
// ✅ ensureActive() — good when the catch handles ordinary failures and you only need
|
||||
// to rethrow if the current coroutine is cancelled
|
||||
try { api.load() }
|
||||
catch (e: Exception) {
|
||||
currentCoroutineContext().ensureActive()
|
||||
logger.warn("load failed", e)
|
||||
}
|
||||
|
||||
// ✅ runCatching with explicit guard
|
||||
runCatching { api.load() }
|
||||
.onFailure {
|
||||
if (it is CancellationException) throw it
|
||||
logger.warn("load failed", it)
|
||||
}
|
||||
|
||||
// ✅ runCatching terminated with getOrThrow (cancellation flows back out)
|
||||
runCatching { api.load() }.getOrThrow()
|
||||
```
|
||||
|
||||
The trigger is "a suspend call inside the `try`", not "the enclosing function is declared `suspend`". This applies inside any suspending body — `suspend fun`, a `launch { … }` lambda, a Flow `collect { … }`, etc.
|
||||
|
||||
The common carve-out is an intentionally local timeout: catching `TimeoutCancellationException` from your own `withTimeout` and converting it to a domain result can be correct. Keep that catch narrow and close to the timeout. Do not use it as permission to swallow arbitrary cancellation.
|
||||
|
||||
Catching a non-cancellation subtype (`IOException`, your own exception types) is fine — they don't extend `CancellationException`.
|
||||
|
||||
### 7. `runBlocking`
|
||||
|
||||
`runBlocking` parks the current thread until the lambda finishes. Inside suspend-capable or lifecycle-scoped application paths it is wrong: a thread that meant to be async is now blocked, structured concurrency is broken, and any cancellation upstream has no effect. It is the "callee makes a structural decision for the caller" anti-pattern at its most direct.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — bridging to suspend by blocking the calling thread
|
||||
fun saveUser(user: User) {
|
||||
runBlocking { repository.save(user) }
|
||||
}
|
||||
```
|
||||
|
||||
Three fixes, by context:
|
||||
|
||||
**Suspend-capable application code** — make the function `suspend`:
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD
|
||||
suspend fun saveUser(user: User) = repository.save(user)
|
||||
```
|
||||
|
||||
If the immediate caller can't suspend either (a non-suspending UI callback, a `BroadcastReceiver` hook), use the existing lifecycle-bound scope at the boundary — see §3's UI ↔ state-holder carve-out. The fix is at the boundary, not inside `saveUser`.
|
||||
|
||||
Legitimate blocking boundaries exist: `main` in a CLI tool, Java interop APIs that must return synchronously, framework callbacks with no suspending alternative, and migration shims. Keep `runBlocking` at that outer boundary, keep the body small, and call suspending code immediately.
|
||||
|
||||
**Tests** — use `runTest`:
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — real time, slow tests, no virtual delay
|
||||
@Test fun loadsUser() = runBlocking {
|
||||
assertThat(repository.load().name).isEqualTo("Alice")
|
||||
}
|
||||
|
||||
// ✅ GOOD
|
||||
@Test fun loadsUser() = runTest {
|
||||
assertThat(repository.load().name).isEqualTo("Alice")
|
||||
}
|
||||
```
|
||||
|
||||
`runTest` gives you virtual time (`delay()` returns immediately), `TestDispatcher` integration, and proper coroutine cleanup. Real-time `runBlocking` in tests makes them slow and flaky.
|
||||
|
||||
**`ContentProvider` carve-out** — Android's `ContentProvider` methods (`query`, `insert`, `update`, `delete`, `onCreate`, `call`) are synchronous from outside the process. There is no way to suspend them. Inside *member functions* of a `ContentProvider` subclass (direct or indirect — not companion objects), `runBlocking` is the unavoidable bridge. Keep the body as short as possible and call into suspending code immediately:
|
||||
|
||||
```kotlin
|
||||
// ✅ Acceptable in ContentProvider members only
|
||||
class MyProvider : ContentProvider() {
|
||||
override fun query(...): Cursor? = runBlocking { dao.query(...) }
|
||||
}
|
||||
```
|
||||
|
||||
This carve-out is for `android.content.ContentProvider` subclasses *only*. "It's like a `ContentProvider`" doesn't apply, and a `runBlocking` in a `ContentProvider`'s companion object is still a regular violation — the helper isn't part of the framework's synchronous surface.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Symptom | Anti-pattern | Fix |
|
||||
|---|---|---|
|
||||
| Class has `private val scope: CoroutineScope` | Stored scope on the callee | Remove. Make public APIs `suspend`. |
|
||||
| `init { scope.launch { ... } }` | Construction-time launch | Move to `suspend fun init()` / `login()` |
|
||||
| `fun foo() { scope.launch { ... } }` on a repository/manager/use case | Fire-and-forget from non-UI class | `suspend fun foo()`, let UI state holder pick the scope |
|
||||
| `fun onClick() { viewModelScope.launch { ... } }` on a state holder, called from UI | UI ↔ state-holder boundary — fine | Keep as-is (see §3 carve-out) |
|
||||
| `private val scope = MainScope()` | Internally-constructed stored scope | Same — remove, make APIs `suspend` |
|
||||
| `@SingleIn(AppScope) class X(scope) { init { scope.launch { … } } }` | DI-bound opaque launch (§5) | Expose `suspend fun run()`, launch from startup orchestrator |
|
||||
| `class Y : Initializer { override fun initialize() { scope.launch { … } } }` | Initializer that launches, not registers (§5) | Same — `suspend fun run()`, orchestrator owns lifecycle |
|
||||
| `try { suspendCall() } catch (e: Exception\|Throwable\|CancellationException) { … }` with no rethrow | Swallowed cancellation (§6) | Prefer `catch (e: CancellationException) { throw e }`; use `ensureActive()` only when that matches the intent |
|
||||
| `runCatching { suspendCall() }.onFailure { … }` with no cancellation guard | Same shape as above (§6) | Add `if (it is CancellationException) throw it`, or terminate with `.getOrThrow()` |
|
||||
| `runBlocking { … }` inside suspend-capable app code | Thread-blocking bridge (§7) | Make caller `suspend`; or use a lifecycle scope at the boundary |
|
||||
| `runBlocking { … }` in a test | Same — real-time bridging (§7) | Use `runTest { … }` |
|
||||
| `runBlocking { … }` inside a `ContentProvider.query`/`insert`/… member | Carve-out (§7) | Acceptable; keep the body minimal |
|
||||
|
||||
## Refactoring guidance
|
||||
|
||||
Removing an existing offender:
|
||||
|
||||
1. **Start at the leaf.** Pick the class farthest from any UI — usually a repository or data source. Its public surface should be the easiest to convert.
|
||||
2. **Convert public functions to `suspend`** one at a time. The compiler will surface every caller.
|
||||
3. **At each caller, choose the scope deliberately:** `viewModelScope`, `lifecycleScope`, `coroutineScope { }`, or an explicit job. This is the choice that was missing before.
|
||||
4. **Delete the `CoroutineScope` constructor parameter** once nothing uses it. Remove the injection binding.
|
||||
|
||||
Don't try to fix every class in one MR. Removing an anti-pattern is incremental work.
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- **UI state holders absorbing UI events.** A ViewModel/Component/feature model with `fun onClick(...) { viewModelScope.launch { ... } }` is correct — that's the boundary the framework needs. See §3 carve-out.
|
||||
- **Lifecycle owners with explicit cancellation and error policy.** Actors/services, app infrastructure, or application-scoped singletons may own a scope when they expose clear `close`/`cancel`/restart behavior or otherwise map directly to an application lifecycle. Inject `Application.applicationScope` explicitly rather than creating one ad-hoc. **This is not permission to launch from `init` / `initialize()`** — see §5.
|
||||
- **Already-suspending APIs** don't need any of this work.
|
||||
- **Tests** sometimes use `TestScope` as a deliberate ambient scope — that's a different pattern with explicit virtual-time control.
|
||||
|
||||
## Red flags during review
|
||||
|
||||
These thoughts mean the anti-pattern is back:
|
||||
|
||||
| Thought | Reality |
|
||||
|---|---|
|
||||
| "I'll just add a `CoroutineExceptionHandler` to the scope" | The problem isn't error handling. The problem is the scope shouldn't exist. |
|
||||
| "I need to launch from `init` so the data's ready when consumers arrive" | Consumers reading state that isn't ready is the bug. Use phasing. |
|
||||
| "The caller doesn't want to deal with `suspend`" | Then the caller chooses fire-and-forget at their scope. Don't decide for them. |
|
||||
| "It's just a small fire-and-forget call" | Silent cancellation makes every fire-and-forget a potential silent failure. |
|
||||
| "We caught and logged the exception, so we're fine" | Did the catch rethrow `CancellationException`? If no, the coroutine is silently un-cancelled. (§6) |
|
||||
| "It's just one `runBlocking`, in a non-critical path" | Every `runBlocking` asserts the caller has no async option. If they do, it's the wrong primitive. (§7) |
|
||||
| "Tests are simpler with `runBlocking`" | They run in real time, can't fast-forward `delay`, and lose `TestDispatcher` semantics. Use `runTest`. (§7) |
|
||||
|
||||
## Related
|
||||
|
||||
- [`kotlin-flow-state-event-modeling`](../kotlin-flow-state-event-modeling/SKILL.md) — `StateFlow`, `SharedFlow`, `Channel`, `stateIn`, one-shot events, and related modeling.
|
||||
- [`kotlin-coroutines`](../kotlin-coroutines/SKILL.md) — Amethyst's relay-pool / callbackFlow / testing async patterns.
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
name: kotlin-flow-state-event-modeling
|
||||
description: Use when writing or reviewing Kotlin StateFlow/SharedFlow/Channel choices, sentinel default values, stateIn placement, WhileSubscribed staleness, or MutableStateFlow update patterns. Technique-layer skill — complements the codebase-specific kotlin-expert.
|
||||
---
|
||||
|
||||
# Kotlin Flow: state and event modeling
|
||||
|
||||
## Core principle
|
||||
|
||||
**Pick the primitive that matches replay, fan-out, and synchronous-read requirements.** `StateFlow`, `SharedFlow`, `Channel`-backed flows, and cold `Flow` differ in buffering, who sees each emission, and whether `.value` exists. Wrong choices drop events, leak sharing coroutines, or force fake domain sentinels into state.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
You're writing or reviewing Kotlin code involving:
|
||||
|
||||
- `MutableStateFlow<T>(SomeSentinel)` — `NoUser`, `Empty`, `Loading`, etc. — because the real value is async
|
||||
- `.stateIn(...)` called inside a function rather than assigned to a property
|
||||
- `SharingStarted.WhileSubscribed(...)` on a flow whose `.value` is read synchronously and must stay fresh
|
||||
- `MutableSharedFlow` for navigation events, snackbars, or other one-shot emissions where loss would be a bug
|
||||
- `.map { }` on a `StateFlow` when consumers still need synchronous `.value`
|
||||
- `MutableStateFlow.value = _state.value.copy(...)` or update code that builds expensive objects inside `update { ... }`
|
||||
|
||||
## SharedFlow for single-consumer fire-once events
|
||||
|
||||
`SharedFlow` defaults have no replay buffer. If nothing is collecting at the exact instant of emission, the event is gone. For a **single UI consumer** handling exactly-once events such as navigation or snackbars, a buffered `Channel` exposed as a `Flow` often matches the semantics better:
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD
|
||||
private val _navEvents = MutableSharedFlow<NavigationEvent>()
|
||||
val navEvents: SharedFlow<NavigationEvent> = _navEvents.asSharedFlow()
|
||||
|
||||
// ✅ GOOD
|
||||
private val _navEvents = Channel<NavigationEvent>(Channel.BUFFERED)
|
||||
val navEvents: Flow<NavigationEvent> = _navEvents.receiveAsFlow()
|
||||
```
|
||||
|
||||
`Channel.receiveAsFlow()` is **fan-out, not broadcast**: with multiple collectors, each event is delivered to **one** collector. `Channel.BUFFERED` is bounded, so sends can suspend and `trySend` can fail. If multiple observers must all see the same event, use explicit state, durable storage, or a deliberately configured `SharedFlow` instead.
|
||||
|
||||
## StateFlow polluted with invalid sentinel defaults
|
||||
|
||||
`StateFlow` forces an initial value. When the real value is async, developers sometimes invent fake domain values — `NoUser`, `EmptyUser`, placeholder IDs — and every consumer is forced to treat that sentinel as real data.
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — sentinel leaks into the type
|
||||
class UserSession(private val db: Db) {
|
||||
private val _user = MutableStateFlow<User>(NoUser)
|
||||
val user: StateFlow<User> = _user.asStateFlow()
|
||||
init { scope.launch { _user.value = db.load() } }
|
||||
}
|
||||
```
|
||||
|
||||
One fix is **phasing**: don't expose the `StateFlow` until the real value exists.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — bootstrap suspends; observers only see real users
|
||||
class UserSession(private val db: Db) {
|
||||
private var _user: MutableStateFlow<User>? = null
|
||||
val user: StateFlow<User>
|
||||
get() = checkNotNull(_user) { "Call login() first" }
|
||||
|
||||
suspend fun login() {
|
||||
_user = MutableStateFlow(db.load())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If absence, loading, or error is a real state, model it explicitly (`User?`, `sealed interface UserUiState`, `Result`, etc.). The bug is a fake domain value masquerading as real data, not every initial value.
|
||||
|
||||
## Mutate MutableStateFlow with `update { ... }`
|
||||
|
||||
Prefer `MutableStateFlow.update { current -> ... }` over reading `.value` and writing it back. `update` applies the transform atomically against the latest state, which avoids lost updates when multiple coroutines mutate the same state.
|
||||
|
||||
```kotlin
|
||||
// BAD — read/modify/write can lose concurrent updates.
|
||||
_state.value = _state.value.copy(
|
||||
selectedId = id,
|
||||
details = details,
|
||||
)
|
||||
|
||||
// GOOD — transform starts from the latest state.
|
||||
_state.update { current ->
|
||||
current.copy(
|
||||
selectedId = id,
|
||||
details = details,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Keep object creation outside the `update` block unless it needs the current state. The update lambda can be retried, so expensive work or side effects inside it may run more than once:
|
||||
|
||||
```kotlin
|
||||
// GOOD — details does not depend on current state, so build it once.
|
||||
val details = Details.from(response)
|
||||
_state.update { current ->
|
||||
current.copy(details = details)
|
||||
}
|
||||
|
||||
// GOOD — derived value depends on current state, so compute it inside.
|
||||
_state.update { current ->
|
||||
val nextItems = current.items.replaceById(updatedItem)
|
||||
current.copy(items = nextItems)
|
||||
}
|
||||
```
|
||||
|
||||
The block should be a pure, fast state transformation: no network calls, database writes, logging side effects, random IDs, or time reads unless those values were captured before the block.
|
||||
|
||||
## `stateIn()` inside a function
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — new sharing coroutine every call
|
||||
fun getPreferences(): StateFlow<Prefs> =
|
||||
repo.prefsFlow.stateIn(scope, SharingStarted.Eagerly, Prefs.Default)
|
||||
```
|
||||
|
||||
Every call to `getPreferences()` launches a fresh coroutine on `scope` that never completes. Performance dies fast under repeated reads.
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD — one shared instance, computed once
|
||||
val preferences: StateFlow<Prefs> =
|
||||
repo.prefsFlow.stateIn(viewModelScope, SharingStarted.Eagerly, Prefs.Default)
|
||||
```
|
||||
|
||||
## `WhileSubscribed` with synchronous `.value`
|
||||
|
||||
`SharingStarted.WhileSubscribed(timeout)` disconnects the upstream when there are no active collectors. While disconnected, `.value` returns the last cached value, which may be stale or still the initial value.
|
||||
|
||||
**Rule:** if `.value` must be fresh or initialized without an active collector, use `SharingStarted.Eagerly` or explicit initialization. `WhileSubscribed` is fine when stale/cached values are acceptable and consumers primarily collect asynchronously.
|
||||
|
||||
## `.map` on `StateFlow` loses `.value`
|
||||
|
||||
```kotlin
|
||||
// ❌ BAD — `name.value` won't compile; it's now a plain Flow
|
||||
val name: Flow<String> = userState.map { it.name }
|
||||
```
|
||||
|
||||
If you need synchronous `.value`, terminate the chain with `.stateIn(...)`:
|
||||
|
||||
```kotlin
|
||||
// ✅ GOOD
|
||||
val name: StateFlow<String> = userState
|
||||
.map { it.name }
|
||||
.stateIn(viewModelScope, SharingStarted.Eagerly, userState.value.name)
|
||||
```
|
||||
|
||||
Community "derived state flow" utilities run the transform on every `.value` read — only acceptable for fast, idempotent transforms. Default to `.stateIn(...)`.
|
||||
|
||||
## Decision: which Flow type?
|
||||
|
||||
| Need | Primitive |
|
||||
|------|-----------|
|
||||
| State that always has a value, read by both async collectors **and** synchronous code | `StateFlow`, often with `SharingStarted.Eagerly` when `.value` matters |
|
||||
| Hot stream, multiple subscribers, **no** requirement for synchronous `.value` | `SharedFlow` |
|
||||
| Discrete events for **one** consumer, exactly-once handoff | Consider `Channel(BUFFERED).receiveAsFlow()` |
|
||||
| Cold stream, one consumer per collection | Plain `Flow` |
|
||||
|
||||
If you're tempted to reach for `SharedFlow`, ask: would dropping an emission be a bug, and how many consumers must see it? If one consumer must handle it exactly once, a `Channel` may fit. If every observer must see it, model durable state or configure a broadcast stream deliberately.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Symptom | Problem | Fix |
|
||||
|---------|---------|-----|
|
||||
| `MutableStateFlow<X>(FakeDomainValue)` | Invalid placeholder default | Model absence explicitly or use phase initialization |
|
||||
| `MutableSharedFlow<Event>` for single-consumer nav/snackbar | Lossy default event stream | Consider `Channel(BUFFERED).receiveAsFlow()` |
|
||||
| `fun foo() = flow.stateIn(...)` | Per-call sharing coroutine | Make it a `val` / shared instance |
|
||||
| `WhileSubscribed` + `.value` must be fresh/initialized | Stale or initial data | `SharingStarted.Eagerly` or explicit initialization |
|
||||
| `stateFlow.map { ... }` consumed as state | Lost `.value` | Terminate with `.stateIn(...)` |
|
||||
| `_state.value = _state.value.copy(...)` | Non-atomic read/modify/write | `_state.update { it.copy(...) }` |
|
||||
| Expensive object creation inside `update { ... }` that doesn't use current state | Work can repeat if update retries | Build before `update`; keep only current-state transforms inside |
|
||||
|
||||
## Red flags during review
|
||||
|
||||
| Thought | Reality |
|
||||
|---------|---------|
|
||||
| "We need `SharedFlow` because there are multiple subscribers" | Multiple subscribers change the semantics. `Channel.receiveAsFlow()` is not broadcast; choose the event model deliberately. |
|
||||
| "We'll use `WhileSubscribed` to save resources" | Only if stale/initial `.value` reads are acceptable. Verify before applying. |
|
||||
| "I'll use a sentinel until real data loads" | Consumers treat it as real domain; prefer explicit UI/state modeling or phasing. |
|
||||
| "I'll construct the new object inside `update` because it's convenient" | The lambda may retry. Construct outside unless it depends on the current state. |
|
||||
|
||||
## Related
|
||||
|
||||
- [`kotlin-coroutines-structured-concurrency`](../kotlin-coroutines-structured-concurrency/SKILL.md) — scope ownership, init launches, fire-and-forget boundaries, cancellation, `runBlocking`
|
||||
- [`compose-side-effects`](../compose-side-effects/SKILL.md) — collecting event flows and wiring side effects in Compose
|
||||
- [`compose-state-holder-ui-split`](../compose-state-holder-ui-split/SKILL.md) — where state holders expose flows to UI
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: kotlin-types-value-class
|
||||
description: Use when writing or reviewing Kotlin type declarations to choose @JvmInline value class over data class where appropriate, including Compose stability implications. Technique-layer skill — complements the codebase-specific kotlin-expert.
|
||||
---
|
||||
|
||||
# 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) |
|
||||
|
||||
```kotlin
|
||||
// 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:
|
||||
|
||||
- Value classes passed as composable parameters avoid "unstable parameter" warnings
|
||||
- No need for `@Immutable` annotations at Compose boundaries when wrapping primitives or strings
|
||||
- Replacing single-field data classes with value classes at UI boundaries improves skippability
|
||||
|
||||
```kotlin
|
||||
// Before: data class wrapping a single field
|
||||
data class UiState(val userId: String) // works, but allocates a wrapper object
|
||||
|
||||
// After: value class is stable and zero-allocation at runtime
|
||||
@JvmInline value class UserId(val value: String)
|
||||
data class UiState(val userId: UserId)
|
||||
```
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Autoboxing**: Value classes are unboxed at compile time but boxed (allocated) when used as nullable (`UserId?`), generic type arguments (`List<UserId>`), or vararg parameters. In hot paths these allocations matter; in most code they don't.
|
||||
- **No backing fields**: You cannot use `init` blocks, `lateinit`, or delegated properties like `by lazy`. The class body is extremely constrained — only the single constructor parameter exists.
|
||||
- **No data-class conveniences**: No `copy()`, no `component1()` for destructuring, and no way to customize `toString()`. If you need any of these, use a data class.
|
||||
- **No custom equals/hashCode/toString**: These always delegate to the underlying type. Need custom equality → use a data class.
|
||||
- **when exhaustiveness**: Sealed hierarchies of value classes work differently than data class hierarchies. Test `when` branches carefully.
|
||||
- **Serialization semantics**: With kotlinx.serialization, a `@Serializable data class A(val value: String)` serializes as `{"value":"..."}`, but a `@Serializable value class A(val value: String)` serializes as the underlying value (`"..."`). Replacing a single-field data class with a value class is a breaking change for your API/JSON contract.
|
||||
- **Serialization**: Some serialization frameworks need explicit support for value classes (e.g., kotlinx.serialization's `@Serializable` works, but Jackson may need configuration).
|
||||
- **Interoperability**: From Java, value classes appear as their underlying type. Java callers bypass the type-safety wrapper.
|
||||
- **Reflection and runtime erasure**: When passed as `Any` or used in generic contexts, value classes box into a synthetic wrapper class. Java reflection sees mangled method signatures, and frameworks that rely on raw runtime types (some ORMs, DI containers, or serializers) may see the underlying type rather than the value class.
|
||||
|
||||
## Packing multiple values
|
||||
|
||||
A value class can only declare one field, but Compose provides `packFloats`, `packInts`, and matching `unpack*` functions in `androidx.compose.ui.util` to store multiple primitives in a single `Long`. This lets you represent composite values (e.g., a 2D point, size, or padding) as a zero-allocation value class instead of a multi-field data class.
|
||||
|
||||
```kotlin
|
||||
@JvmInline value class Offset(val packedValue: Long)
|
||||
|
||||
fun Offset(x: Float, y: Float): Offset = Offset(packFloats(x, y))
|
||||
val Offset.x: Float get() = unpackFloat1(packedValue)
|
||||
val Offset.y: Float get() = unpackFloat2(packedValue)
|
||||
```
|
||||
|
||||
- **Only use this in performance-critical paths** — manual bit-packing is error-prone. A data class is simpler and safer for most UI types.
|
||||
- **Available in `androidx.compose.ui.util`** — `packFloats`, `packInts`, `unpackFloat1`, `unpackFloat2`, `unpackInt1`, `unpackInt2`.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| Data class wrapping a single domain field | Replace with `@JvmInline value class` |
|
||||
| Value class with no domain meaning (just a wrapper) | Use a type alias or the primitive directly |
|
||||
| Value class needing custom equality | Use a data class instead |
|
||||
| Value class as generic type argument in hot path | Accept autoboxing cost or use the primitive |
|
||||
| `@Immutable` annotation on a type that could be a value class | Replace with value class — it's Stable by default |
|
||||
| Forgetting `@JvmInline` annotation | Always pair `value class` with `@JvmInline` for single-field classes |
|
||||
|
||||
## Red flags during review
|
||||
|
||||
- A data class with exactly one property
|
||||
- A `String`, `Long`, or `Int` used where different values should not be interchangeable (e.g., `fun transfer(from: String, to: String, amount: Long)`)
|
||||
- An `@Immutable` annotation on a single-field wrapper
|
||||
- A type alias used for domain distinction where value-class semantics are needed (type aliases are type-erased, no runtime protection)
|
||||
|
||||
## When NOT to apply
|
||||
|
||||
- The type needs multiple fields → data class
|
||||
- The type needs custom `equals`/`hashCode`/`toString` → data class
|
||||
- The type is used heavily as a nullable or generic in performance-critical code → measure autoboxing cost first
|
||||
- The project does not need the type-safety distinction → a type alias or primitive is sufficient
|
||||
|
||||
## Related
|
||||
|
||||
- [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) — diagnose unstable Compose parameters; value classes are one fix
|
||||
Reference in New Issue
Block a user