intellij-shared-autocleankey

name	intellij-shared-autocleankey
description	AutoCleanKey usage guide for UserData lifecycle management in IntelliJ plugins. Use when working with UserDataHolder cleanup tied to Disposable or CoroutineScope.

intellij-shared 公用模块

modules/intellij-shared 提供跨插件共享的工具类。当前包含 AutoCleanKey。

模块依赖

在插件的 build.gradle.kts 中添加：

dependencies {
    implementation(project(":modules:intellij-shared"))
}

AutoCleanKey

AutoCleanKey 封装 Key<T>，在关联的 Disposable 或 CoroutineScope 结束时自动清理所有使用该 key 的 UserDataHolder。避免手动管理 removeUserData。

构造方式

val key = Key.create<String>("my.key")

// 1. 直接绑定 Disposable
val cleaner = AutoCleanKey(disposable, key)

// 2. 延迟解析 Disposable（仅在首次 track 时调用 provider）
val cleaner = AutoCleanKey({ getDisposable() }, key)

// 3. 绑定 CoroutineScope（内部创建 Disposable，scope 结束时自动 dispose）
val cleaner = AutoCleanKey(scope, key)

toAutoCleanKey 扩展

从已有 Key 创建 AutoCleanKey：

val cleaner = myKey.toAutoCleanKey { disposable }
val cleaner = myKey.toAutoCleanKey(scope)

Kotlin 委托属性

val holder = object : UserDataHolderBase() {
    var value: String? by cleaner  // getValue/setValue 自动 track holder
}

支持的 Key 类型：

• Key<T> — 可空值
• KeyWithDefaultValue<T> — 带默认值，未设置时返回 defaultValue
• NotNullLazyKey<T, H> — 惰性计算，首次访问调用 factory

清理行为

当 Disposable 被 dispose 或 CoroutineScope 完成时，所有通过委托属性访问过该 key 的 UserDataHolder 上的该 key 都会被自动 removeUserData。一个 AutoCleanKey 可被多个 holder 复用。