plugin/plugin-async-cleanup
Async cleanup that outlives a plugin instance, so the next instance of the same plugin can await it.
Obsidian’s onunload is synchronous and nothing awaits what it starts. Read from Obsidian 1.15.1: Plugins.unloadPlugin calls the old instance’s unload() and returns, and enablePlugin then constructs the new instance and awaits its load(). So on a disable / enable, a reload or an update while enabled, work like closing an IndexedDB connection is still in flight when the new instance starts, and the new instance can open a database the old one still holds.
The registry here closes that gap without owning the reload lifecycle: a cleanup starts when the component it is registered on unloads, its promise is kept realm-wide under the plugin id, and the next instance awaits it, bounded by a timeout, before it starts. PluginBase does both halves itself.
The registry lives in the realm-global shared-state bag under the versioned key pluginAsyncCleanupsV1, because the old instance and the new one may bundle different copies of this library. It is a wire format between those copies: a plain Map from plugin id to a Promise<void> that never rejects. A change of meaning moves to a new key.
Interfaces
Section titled “Interfaces”| Interface | Description |
|---|---|
| DidPluginAsyncCleanupsSettleParams | Parameters for didPluginAsyncCleanupsSettle. |
| RegisterPluginAsyncCleanupParams | Parameters for registerPluginAsyncCleanup. |
| TrackPluginAsyncCleanupParams | Parameters for trackPluginAsyncCleanup. |
Functions
Section titled “Functions”| Function | Description |
|---|---|
| didPluginAsyncCleanupsSettle | Awaits every cleanup still in flight for the plugin, bounded by a timeout. Resolves at once when nothing is pending. Never rejects. |
| hasPendingPluginAsyncCleanups | Checks whether a plugin has cleanups still in flight. |
| registerPluginAsyncCleanup | Registers an async cleanup that starts when the component unloads and that the next instance of the plugin awaits. The cleanup runs exactly once, on the component’s unload. Register it on the component whose lifetime matches the resource: a PluginBase subclass calls registerAsyncCleanup instead, which scopes it to the feature surface. |
| trackPluginAsyncCleanup | Runs an async cleanup now and tracks it under the plugin id until it settles. A cleanup that throws or rejects is printed and counts as settled, so a failing cleanup never stops the next instance from loading. |
| Type | Description |
|---|---|
| PluginAsyncCleanup | An async cleanup. |
Variables
Section titled “Variables”| Variable | Description |
|---|---|
| DEFAULT_PLUGIN_ASYNC_CLEANUP_NOTICE_DELAY_IN_MILLISECONDS | How long a new plugin instance waits for the previous instance’s cleanups, by default, before it shows a notice that its load is paused. Shorter waits show nothing, so the usual few milliseconds never flash a notice. |
| DEFAULT_PLUGIN_ASYNC_CLEANUP_TIMEOUT_IN_MILLISECONDS | How long a new plugin instance waits for the previous instance’s cleanups by default. |
| PLUGIN_ASYNC_CLEANUPS_STATE_KEY | The shared-state key of the pending cleanups. Versioned, because it is a wire format between copies of this library. |