plugin/third-party-plugin
Typed access to the API of a THIRD-PARTY plugin: one that publishes nothing through this library’s registry.
A plugin built on this library publishes a versioned contract (getPluginApis()), and a consumer reaches it through watchPluginApi (./plugin-api.ts). Most plugins a consumer wants to talk to — Dataview, Templater, Notebook Navigator — are not built on it, so their API hangs off the plugin instance under a name of their own choosing, and every consumer used to reach it by hand through app.plugins with a cast.
A ThirdPartyPluginAdapter says ONCE, for one plugin, how to get from its instance to its typed API, and VERIFIES the shape on the way, so a release that renamed what the adapter reads is “not there” rather than a Cannot read properties of undefined from inside a callback. Everything else here is generic:
- getThirdPartyPluginApi answers “now”, for a one-shot use. - watchThirdPartyPluginApi answers “now” for as long as a component lives: its ref re-reads on every
app.pluginschangedand everyobsidian-lib:plugin-loaded/-unloadedbroadcast, so an OPTIONAL dependency is a ref whosevalueisnullwhile the plugin is absent, and becomes the API the moment it is enabled. - waitForThirdPartyPluginApi and requireThirdPartyPluginApi are the one-shot waits, built onwaitForPlugin/requirePlugin(./plugin-instance.ts), so they share that module’s availability classification, its notice and its repair buttons. - A REQUIRED dependency is declared throughPluginBase.getPluginDependencies()as a ThirdPartyPluginDependency (built by createThirdPartyPluginDependency), and the plugin gate keepsonloadImplfrom running while it is missing, too old or the wrong shape — the same treatment an own-plugin dependency gets.
Availability is PluginAvailability, read from Obsidian 1.15.1 as plugin-instance.ts documents: an instance whose onload is still running reads as loading, never as available. An adapter’s getApi returning null reads as PluginAvailability.ShapeMismatch.
Interfaces
Section titled “Interfaces”| Interface | Description |
|---|---|
| CreateThirdPartyPluginDependencyParams | Parameters for createThirdPartyPluginDependency. |
| GetThirdPartyPluginApiParams | Parameters for getThirdPartyPluginApi and getThirdPartyPluginAvailability. |
| RequireThirdPartyPluginApiParams | Parameters for requireThirdPartyPluginApi. |
| ThirdPartyPluginAdapter | How to get from one third-party plugin’s instance to its typed API. An adapter is plain data plus one function, so it can be a module-level constant shared by every consumer, and adding a plugin means adding one adapter. |
| ThirdPartyPluginApiRef | A live reference to a third-party plugin’s API. |
| ThirdPartyPluginApiRefEventMap | The events a ThirdPartyPluginApiRef fires. |
| ThirdPartyPluginDependency | A third-party plugin another plugin cannot work without, declared through PluginBase.getPluginDependencies(). Built by createThirdPartyPluginDependency, which copies the adapter’s id and name. |
| WaitForThirdPartyPluginApiParams | Parameters for waitForThirdPartyPluginApi. |
| WatchThirdPartyPluginApiParams | Parameters for watchThirdPartyPluginApi. |
Functions
Section titled “Functions”| Function | Description |
|---|---|
| createThirdPartyPluginDependency | Builds the declaration of a required third-party plugin, for PluginBase.getPluginDependencies(). |
| getThirdPartyPluginApi | Returns a third-party plugin’s typed API when the plugin is PluginAvailability.Available, and null otherwise. |
| getThirdPartyPluginAvailability | Reads whether a third-party plugin’s API can be used right now, and if not, why. |
| isThirdPartyPluginDependency | Checks whether a dependency declared through PluginBase.getPluginDependencies() is a third-party one. |
| requireThirdPartyPluginApi | Waits for a third-party plugin’s API, asking the user to install, enable or update the plugin while it is not available. Settles once; see requirePlugin. |
| waitForThirdPartyPluginApi | Waits for a third-party plugin’s API to become available. Settles once; see waitForPlugin. |
| watchThirdPartyPluginApi | Watches a third-party plugin’s API and returns a live ThirdPartyPluginApiRef. The ref re-reads on every app.plugins changed and every library lifecycle broadcast, so it follows the plugin through enable, disable, update and reload with no polling. This is the shape of an OPTIONAL dependency: read ref.value where the integration is used, and treat null as “not there”. |
| Type | Description |
|---|---|
| GetThirdPartyPluginAvailabilityParams | Parameters for getThirdPartyPluginAvailability. |