PluginApiRef<TApi>

A live reference to another plugin’s API.

The ref is the WHOLE consumer surface, deliberately. A plain Promise cannot model this because it settles once, whereas availability is a repeating signal (available → gone → available again across a disable/enable cycle) — which is why PluginApiRef.whenAvailable is a method ON the ref rather than the thing handed back. The change event exists for consumers that must react rather than read, and is secondary: it imposes no ceremony on the common case, which is reading PluginApiRef.value.

Import:

import type { PluginApiRef } from '@mnaoumov/obsidian-lib/plugin/plugin-api';

Signature:

export interface PluginApiRef<TApi extends object> extends AsyncEventSource<PluginApiRefEventMap>

Extends: AsyncEventSource<PluginApiRefEventMap>

Properties

Property	Type	Description
unavailabilityReason	null | PluginApiUnavailabilityReason	Why the API is not available right now, or null while it is. Classified at the moment of reading, by the same probe PluginApiRef.whenAvailable uses for its error, so a caller that must decide synchronously — which message to show, which button to offer — can tell "not installed" from "too old" without waiting for a timeout. Like PluginApiRef.value, it describes now: during a consumer's onload a provider that has not loaded yet reads as PluginApiUnavailabilityReason.NotPublished.
value	null | TApi	The API, or null when it is not currently available. Always current, synchronous, and free — the ref maintains it, so there is no registry lookup per read. null here means "not available right now", NOT "not installed": during a consumer's onload the provider may simply not have loaded yet, and the value becomes non-null on its own.
whenAvailable	(options?: WhenAvailablePluginApiOptions) => Promise<TApi>	Waits for the API to become available.

---

Links to this page:

• PluginApiRefEventMap
• watchPluginApi