kotlin-expert

Kotlin Expert

Advanced Kotlin patterns for AmethystMultiplatform. Covers Flow state management, sealed hierarchies, immutability, DSL builders, and inline functions with real codebase examples.

Mental Model

Kotlin in Amethyst:

State Management (Hot Flows)
    ├── StateFlow<T>           # Single value, always has value, replays to new subscribers
    ├── SharedFlow<T>          # Event stream, configurable replay, multiple subscribers
    └── MutableStateFlow<T>    # Private mutable, public via .asStateFlow()

Type Safety (Sealed Hierarchies)
    ├── sealed class           # State variants with data (AccountState.LoggedIn/LoggedOut)
    └── sealed interface       # Generic result types (SignerResult<T>)

Compose Performance (@Immutable)
    ├── @Immutable             # 173+ event classes - prevents recomposition
    └── data class             # Structural equality, copy(), immutable by convention

DSL Patterns
    ├── Builder classes        # Fluent APIs (TagArrayBuilder)
    ├── Lambda receivers       # inline fun tagArray { ... }
    └── Method chaining        # return this

Performance
    ├── inline fun             # Eliminate lambda overhead
    ├── reified type params    # Runtime type info (OptimizedJsonMapper)
    └── value class            # Zero-cost wrappers (NOT USED yet in Amethyst)

Delegation:

• kotlin-coroutines agent: Deep async (structured concurrency, channels, operators)
• kotlin-multiplatform skill: expect/actual, source sets
• This skill: Amethyst Kotlin idioms, state patterns, type safety

---

1. Flow State Management

StateFlow: State that Changes

Mental model: StateFlow is a "hot" observable state holder. Always has a value, new collectors immediately get current state.

Amethyst pattern:

// AccountManager.kt:48-50
class AccountManager {
    private val _accountState = MutableStateFlow<AccountState>(AccountState.LoggedOut)
    val accountState: StateFlow<AccountState> = _accountState.asStateFlow()

    fun login(key: String) {
        _accountState.value = AccountState.LoggedIn(...)
    }
}

Key principles:

1. Private mutable, public immutable: _accountState (MutableStateFlow) private, accountState (StateFlow) public
2. Always has value: Initial value required (LoggedOut)
3. Single value: Replays ONE most recent value to new subscribers
4. Hot: Stays in memory, all collectors share same instance

See: AccountManager.kt:48-50, RelayConnectionManager.kt:49-52

SharedFlow: Event Streams

Mental model: SharedFlow is a "hot" broadcast stream for events. Configurable replay buffer, doesn't require initial value.

Amethyst pattern:

// RelayConnectionManager.kt:52-53
val connectedRelays: StateFlow<Set<NormalizedRelayUrl>> = client.connectedRelaysFlow()
val availableRelays: StateFlow<Set<NormalizedRelayUrl>> = client.availableRelaysFlow()

When to use StateFlow vs SharedFlow:

Scenario	Use StateFlow	Use SharedFlow
UI state	✅ Current screen data, login status	❌
One-time events	❌	✅ Navigation, snackbars, toasts
Always has value	✅	❌ Optional
Replay count	1 (latest only)	Configurable (0, 1, n)
Backpressure	Conflates (drops old)	Configurable buffer

Best practice:

// State: Use StateFlow
private val _uiState = MutableStateFlow(UiState.Loading)
val uiState: StateFlow<UiState> = _uiState.asStateFlow()

// Events: Use SharedFlow
private val _navigationEvents = MutableSharedFlow<NavEvent>(replay = 0)
val navigationEvents: SharedFlow<NavEvent> = _navigationEvents.asSharedFlow()

Flow Anti-Patterns

❌ Exposing mutable state:

val accountState: MutableStateFlow<AccountState>  // BAD: Can be mutated externally

✅ Expose immutable:

val accountState: StateFlow<AccountState> = _accountState.asStateFlow()  // GOOD

---

❌ SharedFlow for state:

val loginState = MutableSharedFlow<LoginState>()  // BAD: State might get lost

✅ StateFlow for state:

val loginState = MutableStateFlow(LoginState.LoggedOut)  // GOOD: Always has value

See: references/flow-patterns.md for comprehensive examples.

---

2. Sealed Hierarchies

Sealed Classes: State Variants

Mental model: Sealed classes represent a closed set of variants that share common data/behavior.

Amethyst pattern:

// AccountManager.kt:36-46
sealed class AccountState {
    data object LoggedOut : AccountState()

    data class LoggedIn(
        val signer: NostrSigner,
        val pubKeyHex: String,
        val npub: String,
        val nsec: String?,
        val isReadOnly: Boolean
    ) : AccountState()
}

// Usage
when (state) {
    is AccountState.LoggedOut -> showLogin()
    is AccountState.LoggedIn -> showFeed(state.pubKeyHex)
}  // Exhaustive - compiler enforces all cases

Key principles:

1. Closed hierarchy: All subclasses known at compile-time
2. Exhaustive when: Compiler ensures all cases handled
3. Shared data: Sealed class can hold common properties
4. Single inheritance: Subclass can't extend another class

When to use:

• Modeling UI states (Loading, Success, Error)
• Login states (LoggedOut, LoggedIn)
• Result types with different data per variant

Sealed Interfaces: Generic Result Types

Mental model: Sealed interfaces for contracts with multiple implementations that need generics or multiple inheritance.

Amethyst pattern:

// SignerResult.kt:25-46
sealed interface SignerResult<T : IResult> {
    sealed interface RequestAddressed<T : IResult> : SignerResult<T> {
        class Successful<T : IResult>(val result: T) : RequestAddressed<T>
        class Rejected<T : IResult> : RequestAddressed<T>
        class TimedOut<T : IResult> : RequestAddressed<T>
        class ReceivedButCouldNotPerform<T : IResult>(
            val message: String?
        ) : RequestAddressed<T>
    }
}

// Usage with generics
fun handleResult(result: SignerResult<SignResult>) {
    when (result) {
        is SignerResult.RequestAddressed.Successful -> processEvent(result.result.event)
        is SignerResult.RequestAddressed.Rejected -> showRejected()
        is SignerResult.RequestAddressed.TimedOut -> showTimeout()
    }
}

Key principles:

1. Multiple inheritance: Subtype can implement other interfaces
2. Variance: Supports out/in modifiers for generics
3. No constructor: Can't hold state directly (subtypes can)
4. Nested hierarchies: Can create sub-sealed hierarchies

Sealed Class vs Sealed Interface

Feature	Sealed Class	Sealed Interface
Constructor	✅ Can hold common state	❌ No constructor
Inheritance	❌ Single parent only	✅ Multiple interfaces
Generics	❌ No variance	✅ Covariance/contravariance
Use case	State variants	Result types, contracts

Decision tree:

Need to hold common data in base?
    YES → sealed class
    NO → sealed interface

Need generics with variance (out/in)?
    YES → sealed interface
    NO → Either works

Subtypes need multiple inheritance?
    YES → sealed interface
    NO → Either works

Amethyst examples:

• sealed class AccountState - state variants with different data
• sealed interface SignerResult<T> - generic result types with variance

See: references/sealed-class-catalog.md for all sealed types in quartz.

---

3. Immutability & Compose Performance

@Immutable Annotation

Mental model: @Immutable tells Compose "this value never changes after construction." Compose can skip recomposition if @Immutable object reference doesn't change.

Amethyst pattern:

// TextNoteEvent.kt:51-63
@Immutable
class TextNoteEvent(
    id: HexKey,
    pubKey: HexKey,
    createdAt: Long,
    tags: Array<Array<String>>,
    content: String,
    sig: HexKey
) : BaseThreadedEvent(id, pubKey, createdAt, KIND, tags, content, sig) {
    // All properties immutable (val), no mutable state
}

Key principles:

1. All properties immutable: Only val, never var
2. No mutable collections: Use ImmutableList, Array, not MutableList
3. Deep immutability: Nested objects also immutable
4. Compose optimization: Skips recomposition if reference equals

Why it matters:

// Without @Immutable
@Composable
fun NoteCard(note: TextNoteEvent) {  // Recomposes every time parent recomposes
    Text(note.content)
}

// With @Immutable
@Composable
fun NoteCard(note: TextNoteEvent) {  // Only recomposes if note reference changes
    Text(note.content)
}

173+ @Immutable classes in quartz - all events immutable for Compose performance.

Data Classes & Immutability

Pattern:

@Immutable
data class RelayStatus(
    val url: NormalizedRelayUrl,
    val connected: Boolean,
    val error: String? = null
) {
    // Implicit: equals(), hashCode(), copy(), toString()
}

// Usage
val oldStatus = RelayStatus(url, connected = false)
val newStatus = oldStatus.copy(connected = true)  // Immutable update

Key principles:

1. Structural equality: equals() compares properties, not reference
2. copy(): Create modified copies without mutating
3. All properties in constructor: For proper equals()/hashCode()
4. Prefer val: Make properties immutable

kotlinx.collections.immutable

Pattern:

import kotlinx.collections.immutable.ImmutableList
import kotlinx.collections.immutable.persistentListOf
import kotlinx.collections.immutable.toImmutableList

// Instead of List (which could be mutable internally)
val relays: ImmutableList<String> = persistentListOf("wss://relay1.com", "wss://relay2.com")

// Add returns new instance
val updated = relays.add("wss://relay3.com")  // relays unchanged, updated has 3 items

---

Content truncated.