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 'obsidian-dev-utils/obsidian/plugin/plugin-api';

Signature:

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

Extends: AsyncEventSource<PluginApiRefEventMap>

Properties

Property	Type	Description
[ASYNC_EVENT_MAP]?	PluginApiRefEventMap	Phantom marker that makes EventMap inferable from an AsyncEventSource (e.g. via Source extends AsyncEventSource<infer EventMap>). Never present at runtime. (Inherited from AsyncEventSource)
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.

Methods

Method	Returns	Description
off(name, callback)	void	Remove an event listener. (Inherited from AsyncEventSource)
offref(eventRef)	void	Remove an event listener by reference. (Inherited from AsyncEventSource)
on(name, callback, thisArgument?)	AsyncEventRef	Add an event listener. (Inherited from AsyncEventSource)
once(name, callback, thisArgument?)	AsyncEventRef	Add an event listener that will be triggered only once. (Inherited from AsyncEventSource)
whenAvailable(options?)	Promise<TApi>	Waits for the API to become available.

---

Links to this page:

• PluginApiRefEventMap
• watchPluginApi