@mnaoumov/obsidian-lib 10.10.0 → 10.12.0

package/dist/lib/esm/plugin/plugin-instance.d.mts

@@ -0,0 +1,251 @@
+/// <reference path="../library-references.d.mts" />
+/// <reference lib="dom" />
+/**
+ * @file
+ *
+ * Another plugin's INSTANCE: whether it is there, waiting for it, and asking the user to bring it in.
+ *
+ * This is the path for a plugin that publishes nothing through the library's registry, which is most of
+ * them. A provider that does publish is better reached through `watchPluginApi` (`./plugin-api.ts`): its
+ * reference is live, version-negotiated and revoked when the provider goes away, none of which a bare
+ * instance offers. And a plugin that must STOP running when another one goes away declares it through
+ * `PluginBase.getPluginDependencies()`, whose gate owns that teardown — {@link requirePlugin} is a one-shot
+ * wait, not a second dependency system.
+ *
+ * What "loaded" can and cannot mean, read from Obsidian `1.15.1`:
+ *
+ * - `Plugins.loadPlugin` stores the instance in `app.plugins.plugins` BEFORE it awaits `plugin.load()`, and
+ *   `Plugin.load` sets `_loaded` before it awaits `onload()`. So `app.plugins.getPlugin(id)` can return a
+ *   plugin whose `onload` is still running, and `_loaded` cannot tell the two apart.
+ *   `Plugins.enablePlugin` brackets the load with `loadingPluginId`, which is the one signal that does, so
+ *   an instance whose id is `loadingPluginId` reads as {@link PluginAvailability.Loading}.
+ * - `onload` having settled is the most anything can promise. A plugin that starts further work from
+ *   `onload` without awaiting it, or waits for layout-ready, is "loaded" before that work is done, and
+ *   Obsidian has no hook saying every plugin has finished initializing. A plugin built on this library
+ *   says more through the `obsidian-lib:plugin-loaded` broadcast, which follows its published APIs.
+ * - `app.plugins` is an `Events` source that triggers `changed`, debounced by one macrotask, after every
+ *   enable, disable, install, uninstall and manifest reload. That is what a wait subscribes to, so nothing
+ *   here polls. It fires after `enablePlugin` returned, when `loadingPluginId` is `null` again.
+ *
+ * A type argument alone is a caller's ASSERTION about the instance, not a check: nothing at runtime knows
+ * what `TPlugin` is. Pass `isPlugin` to have the shape verified; an instance failing it reads as
+ * {@link PluginAvailability.ShapeMismatch}, the usual sign of a release that renamed what the caller uses.
+ */
+import type { App, Plugin } from 'obsidian';
+import { Component } from 'obsidian';
+import type { PluginNoticeComponent } from '../components/plugin-notice-component.mjs';
+/**
+ * Whether another plugin's instance can be used right now, and if not, why.
+ */
+export declare enum PluginAvailability {
+    /**
+     * Loaded, `onload` settled, and every declared requirement met.
+     */
+    Available = "available",
+    /**
+     * Running at a release whose `manifest.version` cannot be parsed, while the caller declared a
+     * {@link GetPluginAvailabilityParams.minPluginVersion}. Counts as unavailable, because failing closed is the
+     * safe direction.
+     */
+    InvalidVersion = "invalidVersion",
+    /**
+     * The instance exists but its `onload` has not settled yet.
+     */
+    Loading = "loading",
+    /**
+     * Installed but neither enabled nor running.
+     */
+    NotEnabled = "notEnabled",
+    /**
+     * Not installed in this vault.
+     */
+    NotInstalled = "notInstalled",
+    /**
+     * Installed and enabled in the configuration, but no instance is running. At startup that is a plugin
+     * Obsidian has not reached yet; later it is one that failed to load, or one switched off by a disable that
+     * does not touch the configuration.
+     */
+    NotLoaded = "notLoaded",
+    /**
+     * Running at a release older than the caller's {@link GetPluginAvailabilityParams.minPluginVersion}.
+     */
+    Outdated = "outdated",
+    /**
+     * Running, but the caller's {@link GetPluginAvailabilityParams.isPlugin} rejected the instance.
+     */
+    ShapeMismatch = "shapeMismatch"
+}
+/**
+ * Parameters for {@link getLoadedPlugin}.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects.
+ */
+export type GetLoadedPluginParams<TPlugin extends Plugin = Plugin> = GetPluginAvailabilityParams<TPlugin>;
+/**
+ * Parameters for {@link getPluginAvailability}.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects.
+ */
+export interface GetPluginAvailabilityParams<TPlugin extends Plugin = Plugin> {
+    /**
+     * The Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * Verifies that the running instance is the shape the caller uses. Without it, `TPlugin` is an
+     * assertion nothing checks.
+     *
+     * @param plugin - The running instance.
+     * @returns Whether the instance is a `TPlugin`.
+     */
+    readonly isPlugin?: (plugin: Plugin) => plugin is TPlugin;
+    /**
+     * The oldest release of the plugin the caller works with, compared with its `manifest.version`. This is
+     * a plugin RELEASE, never an API contract version: a provider publishing a versioned contract is reached
+     * through `watchPluginApi`'s `apiVersionRange` instead.
+     */
+    readonly minPluginVersion?: string;
+    /**
+     * The `manifest.id` of the plugin.
+     */
+    readonly pluginId: string;
+}
+/**
+ * Parameters for the {@link PluginInstanceUnavailableError} constructor.
+ */
+export interface PluginInstanceUnavailableErrorConstructorParams {
+    /**
+     * Why the plugin was unavailable when the wait gave up.
+     */
+    readonly availability: PluginAvailability;
+    /**
+     * The `manifest.id` of the plugin.
+     */
+    readonly pluginId: string;
+}
+/**
+ * Parameters for {@link requirePlugin}.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects.
+ */
+export interface RequirePluginParams<TPlugin extends Plugin = Plugin> extends GetPluginAvailabilityParams<TPlugin> {
+    /**
+     * Ends the wait early; the promise rejects with the signal's reason.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * The component owning the wait and its notice. Its unload ends both, rejecting the promise.
+     */
+    readonly component: Component;
+    /**
+     * The display name of the required plugin, shown to the user.
+     */
+    readonly pluginName: string;
+    /**
+     * The asking plugin's notice component, which shows what is missing and the button that fixes it.
+     */
+    readonly pluginNoticeComponent: PluginNoticeComponent;
+    /**
+     * The display name of the asking plugin, named in the notice.
+     */
+    readonly requestingPluginName: string;
+    /**
+     * How long to wait before giving up. By default the wait lasts until the user repairs the plugin, the
+     * {@link RequirePluginParams.abortSignal} aborts or the {@link RequirePluginParams.component} unloads.
+     */
+    readonly timeoutInMilliseconds?: number;
+}
+/**
+ * Parameters for {@link waitForPlugin}.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects.
+ */
+export interface WaitForPluginParams<TPlugin extends Plugin = Plugin> extends GetPluginAvailabilityParams<TPlugin> {
+    /**
+     * Ends the wait early; the promise rejects with the signal's reason.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * A component whose unload ends the wait, rejecting the promise. Pass the waiting plugin, or the
+     * component that will use the instance, so a wait never outlives its consumer.
+     */
+    readonly component?: Component;
+    /**
+     * How long to wait before rejecting with a {@link PluginInstanceUnavailableError}.
+     *
+     * @default 10000
+     */
+    readonly timeoutInMilliseconds?: number;
+}
+/**
+ * Thrown when a plugin did not become available before a wait gave up.
+ */
+export declare class PluginInstanceUnavailableError extends Error {
+    /**
+     * Why the plugin was unavailable when the wait gave up.
+     */
+    readonly availability: PluginAvailability;
+    /**
+     * The `manifest.id` of the plugin.
+     */
+    readonly pluginId: string;
+    /**
+     * Creates an instance of {@link PluginInstanceUnavailableError}.
+     *
+     * @param params - The constructor parameters.
+     */
+    constructor(params: PluginInstanceUnavailableErrorConstructorParams);
+}
+/**
+ * Returns another plugin's instance when it is {@link PluginAvailability.Available}, and `null` otherwise.
+ *
+ * Unlike `app.plugins.getPlugin`, it never returns an instance whose `onload` is still running.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects; checked only through `isPlugin`.
+ * @param params - The {@link GetPluginAvailabilityParams}.
+ * @returns The instance, or `null`.
+ */
+export declare function getLoadedPlugin<TPlugin extends Plugin = Plugin>(params: GetLoadedPluginParams<NoInfer<TPlugin>>): null | TPlugin;
+/**
+ * Reads whether another plugin's instance can be used right now, and if not, why.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects.
+ * @param params - The {@link GetPluginAvailabilityParams}.
+ * @returns The {@link PluginAvailability}.
+ */
+export declare function getPluginAvailability<TPlugin extends Plugin = Plugin>(params: GetPluginAvailabilityParams<NoInfer<TPlugin>>): PluginAvailability;
+/**
+ * Waits for another plugin to become {@link PluginAvailability.Available}, asking the user to repair it
+ * while it is not.
+ *
+ * Resolves at once when it already is. Otherwise, once the workspace layout is ready — before that, a
+ * plugin Obsidian has not loaded yet is indistinguishable from a missing one — a notice says what is wrong
+ * and offers the matching repair: install, enable, or update, plus a way to the community plugins list.
+ * The notice follows the state as it changes and goes away when the wait settles. A repair that fails is
+ * reported and leaves the wait running, so the user can try again or fix it by hand.
+ *
+ * The promise settles ONCE. It does not watch the plugin afterwards: a consumer that must stop when the
+ * plugin goes away declares a dependency through `PluginBase.getPluginDependencies()` instead.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects; checked only through `isPlugin`.
+ * @param params - The {@link RequirePluginParams}.
+ * @returns A {@link Promise} resolving with the instance.
+ * @throws The abort reason, or an error naming the unloaded component, when the wait is ended early.
+ * @throws {@link PluginInstanceUnavailableError} When {@link RequirePluginParams.timeoutInMilliseconds} elapses.
+ */
+export declare function requirePlugin<TPlugin extends Plugin = Plugin>(params: RequirePluginParams<NoInfer<TPlugin>>): Promise<TPlugin>;
+/**
+ * Waits for another plugin to become {@link PluginAvailability.Available}.
+ *
+ * Resolves at once when it already is, which covers a consumer reloaded after its dependency. Otherwise it
+ * re-reads the state on every `app.plugins` `changed` and every `obsidian-lib:plugin-loaded` broadcast, so a
+ * plugin enabled, updated or reloaded later is picked up with no polling. It subscribes before its first
+ * read, so a change landing in between cannot be missed. Every listener and timer is removed when it settles.
+ *
+ * @typeParam TPlugin - The plugin type the caller expects; checked only through `isPlugin`.
+ * @param params - The {@link WaitForPluginParams}.
+ * @returns A {@link Promise} resolving with the instance.
+ * @throws The abort reason, or an error naming the unloaded component, when the wait is ended early.
+ * @throws {@link PluginInstanceUnavailableError} When the timeout elapses, carrying the availability at that moment.
+ */
+export declare function waitForPlugin<TPlugin extends Plugin = Plugin>(params: WaitForPluginParams<NoInfer<TPlugin>>): Promise<TPlugin>;