obsidian-typings 5.11.0 → 5.12.0

package/README.md

@@ -1,18 +1,220 @@
-<center>
-
 # Obsidian Typings
 
-</center>
+[![NPM downloads](https://img.shields.io/npm/v/obsidian-typings?color=red&label=Version%3A&logo=npm&logoColor=white&labelColor=red)](https://www.npmjs.com/package/obsidian-typings)
+[![NPM downloads](https://img.shields.io/npm/dw/obsidian-typings?style=flat&label=Downloads)](https://www.npmjs.com/package/obsidian-typings)
+[![GitHub Repo stars](https://img.shields.io/github/stars/fevol/obsidian-typings?color=yellow&label=Stargazers%3A&logo=OpenTelemetry&logoColor=yellow)](https://github.com/Fevol/obsidian-typings/stargazers)
+
+**Obsidian Typings** provides **TypeScript definitions** for Obsidian’s **undocumented and internal APIs**.
+
+It extends the official [Obsidian API](https://github.com/obsidianmd/obsidian-api/) with:
+
+- Additional type definitions for internal methods, properties, and plugins.
+- Explanations and usage examples to make undocumented parts easier to understand.
+- Helper utilities and interfaces for working with Obsidian’s internals in a safer, type-safe way.
+
+This package is designed for plugin developers who want to access Obsidian's internal APIs in a type-safe manner,
+while also keeping their code maintainable and less reliant on `@ts-ignore`/`@ts-expect-error`.
+
+> [!IMPORTANT]
+>
+> - This package is **not affiliated with, or endorsed by, the Obsidian team**.
+> - It does **not** cover every aspect of the Obsidian API.
+> - Typings are based on reverse engineering and may be **inaccurate or unstable**. They can change without notice in future releases.
+> - Always **test thoroughly** and **add fallbacks** when using internal APIs.
+
+## Versioning and Release Channels
+
+[Obsidian](https://obsidian.md) has two main release channels:
+
+- `public` - stable versions available to all users.
+- [`catalyst`](https://help.obsidian.md/catalyst) (`beta`, `early access`) - versions only available to users with a catalyst license, has early access to new features.
 
-<div align="center">
-    <a href="https://obsidian.md/changelog/2026-02-27-desktop-v1.12.4/"><img src="https://img.shields.io/badge/Obsidian_version-1.12.4_public-blue?logo=obsidian" alt="Obsidian version: 1.12.4 public"></a>
-    <a href="https://github.com/Fevol/obsidian-typings/tree/release/obsidian-public/1.12.4"><img src="https://img.shields.io/badge/Git_branch-release/obsidian--public/1.12.4-red?logo=git" alt="Git branch: release/obsidian-public/1.12.4"></a>
-</div>
+If you use internal APIs, you may need to support users on both channels.
+The availability or behavior of some APIs can differ between versions, which may lead to bugs or errors if these changes are not accounted for in your plugin.
 
-This branch contains the typings for Obsidian version [`1.12.4 public`](https://obsidian.md/changelog/2026-02-27-desktop-v1.12.4/).
+To make it easier to adapt to these differences, this package provides typings for both channels.
+
+Typings for each `Obsidian` version can be found in their own git branches: namely `release/obsidian-public/*` and `release/obsidian-catalyst/*`:
+
+- Latest `public` release: [`release/obsidian-public/1.12.4`](https://github.com/Fevol/obsidian-typings/tree/release/obsidian-public/1.12.4)
+- Latest `catalyst` release: [`release/obsidian-catalyst/1.12.5`](https://github.com/Fevol/obsidian-typings/tree/release/obsidian-catalyst/1.12.5)
+
+Older versions of the package are available, but support for them is limited.
+In most cases, we recommend to always use the latest release.
+
+## Set-up
+
+### 1. Install via `npm`
+
+- Latest `public` release (recommended):
+  - `npm install --save-dev obsidian-typings`
+- Explicitly install latest `public` release:
+  - `npm pkg set "dependencies.obsidian-typings=obsidian-public-latest" && npm install`
+- Install the latest `catalyst` (`beta`) release:
+  - `npm pkg set "dependencies.obsidian-typings=obsidian-catalyst-latest" && npm install`
+- Install a specific release (should match `minAppVersion` in your plugin's `manifest.json`):
+  - `npm pkg set "dependencies.obsidian-typings=obsidian-public-1.8.10" && npm install`
+  - `npm pkg set "dependencies.obsidian-typings=obsidian-catalyst-1.9.9" && npm install`
+
+> [!IMPORTANT]
+>
+> If you installed library using `npm pkg set` approach, you will have to update it using `npm update obsidian-typings` command.
+>
+> If you run `npm install obsidian-typings` instead, the most likely, the library will not get updated.
+
+&nbsp;
+
+> [!WARNING]
+>
+> The package installs several libraries that trigger `npm audit` warnings.
+>
+> Those packages cannot be updated because they should match the exact versions Obsidian uses internally.
+
+<!-- markdownlint-disable MD033 -->
+
+### 2. Enable in `tsconfig.json` (recommended) <span id="add-types-setting-to-tsconfig-json"></span>
+
+<!-- markdownlint-enable MD033 -->
+
+Add `obsidian-typings` to the `types` array of your `tsconfig.json` to make all extended typings available globally without explicit importing them:
+
+```json
+{
+    "compilerOptions": {
+        "...": "...",
+        "types": [
+            "obsidian-typings"
+        ]
+    }
+}
+```
 
 > [!WARNING]
 >
-> If you are making a PR to this branch, please make sure to verify that all your changes are applicable to this version.
+> If other `@types/*` packages stop being recognized after adding `obsidian-typings` to the `types`, you may need to re-add them to the `types` list.
+>
+> ```json
+> {
+>     "compilerOptions": {
+>         "...": "...",
+>         "types": [
+>             "obsidian-typings",
+>             "some-package-name"
+>         ]
+>     }
+> }
+
+### 3. Importing explicitly (alternative)
+
+Instead of adding `obsidian-typings` to your `types`, you can also import the package directly:
+
+```ts
+import type {} from 'obsidian-typings';
+```
+
+## Usage
+
+### `obsidian` module internals
+
+To access types from the `obsidian` module, the import syntax does not change:
+
+```ts
+import type { App } from 'obsidian';
+
+function printInternalPlugins(app: App): void {
+  console.log(app.internalPlugins);
+}
+```
+
+### `obsidian-typings` additional interfaces
+
+Additional interfaces added by this package (which do not exist in the official API), can be imported as:
+
+```ts
+import type { InternalPlugins } from 'obsidian-typings';
+
+function getInternalPlugins(app: App): InternalPlugins {
+  return app.internalPlugins;
+}
+```
+
+### `obsidian-typings/implementations`
+
+Additional helper functions/types/... added by this package can be used by importing from `obsidian-typings/implementations`:
+
+```ts
+import { InternalPluginName } from 'obsidian-typings/implementations';
+
+// If you forget the `/implementations` part:
+// import { InternalPluginName } from 'obsidian-typings';
+// You will not be able to use the runtime values and the code below will not compile.
+
+this.app.internalPlugins.getEnabledPluginById(InternalPluginName.FileExplorer);
+```
+
+The list of all available implementations can be found in the `src/obsidian/implementations` folder in the corresponding release branch ([example for `1.9.10 public`](https://github.com/Fevol/obsidian-typings/tree/release/obsidian-public/1.9.10/src/obsidian/implementations)).
+
+### Extend with your own typings
+
+If you need to extend the typings provided by this package, add the following to any `.d.ts` file in your project:
+
+```ts
+export {}; // This line is required. If there are no top-level `import/export` statements, your typings will work not as expected.
+declare module 'obsidian-typings' {
+    interface PluginsPluginsRecord {
+        ['my-plugin-id']: MyPlugin;
+    }
+}
+```
+
+## Disclaimer
+
+> [!WARNING]
+>
+> Make sure to read below section in detail before using these typings.
+>
+> Use at your own risk, verify that the code behaves as expected, and be prepared to update your code if the API changes.
+
+Please be aware that there is a good reason why (some of) the functions and types defined here are not included with the official API definitions:
+
+- The methods are not fully defined, and will be changed or removed in the near-future
+- There is a high risk of the code behaving unexpectedly if used improperly
+- The function was never meant to be used
+
+Please use the functions and variables provided by this package with caution.
+Be prepared to update your code if the API changes, and only use the functions if you are confident that you understand what they will do.
+Reference the [official API](https://github.com/obsidianmd/obsidian-api/blob/master/obsidian.d.ts) first to see if your problem may be solved with a documented function, or search in the `#plugin-dev` channel of the Obsidian Discord server.
+Some functions will also contain `@remark` TSDoc tags that provide alternatives or better solutions.
+
+Furthermore, there is a very high chance that there are mistakes in the typings, despite best efforts.
+All types had to be deduced from context, manually running the function, or from the minified app code.
+Always verify that your code behaves as expected, both in terms of types and runtime behavior.
+
+> [!WARNING]
+>
+> While the typings themselves were hand-written by the package maintainers and contributors, the majority of the `@tsdoc` documentation has been minimally completed using generative AI and may be inaccurate.
+
+&nbsp;
+
+> [!TIP]
+>
+> If you find any issues with the typings or documentation, please feel free to [open an issue](https://github.com/Fevol/obsidian-typings/issues) or submit a pull request.
+
+With these scary disclaimers out of the way, hopefully these typings will help you in removing 90% of the `@ts-ignore`/`@ts-expect-error` you have in your codebase, or discover solutions that didn't seem possible before.
+
+## Tags
+
+- `@remark` warnings, caveats, or suggested alternatives.
+- `@tutorial` extra guidance and examples.
+- `@official` comes from the [official API](https://github.com/obsidianmd/obsidian-api/blob/master/obsidian.d.ts).
+- `@unofficial` based on reverse engineering.
+
+## Migration
+
+If you were using a `1.x.x` version of this package, see the [Migration guide](https://github.com/Fevol/obsidian-typings/blob/main/MIGRATION.md) for upgrading to `2.0.0` or newer.
+
+## Contributing
+
+Feel free to start typing any part of the Obsidian API that is not yet typed, or fixing/adding additional descriptions to existing typings. If you are unsure about anything, don't hesitate to open an issue.
 
-[See full docs](https://github.com/Fevol/obsidian-typings/blob/main/README.md)
+A brief tutorial is available on how you can get started with adding new typings, or fixing existing ones, see: [CONTRIBUTING.md](https://github.com/Fevol/obsidian-typings/blob/main/CONTRIBUTING.md).

package/dist/cjs/types.d.cts

@@ -1701,7 +1701,7 @@ declare global {
 	 * CodeMirror adapter providing CM5-compatible API over CM6.
 	 * @unofficial
 	 */
-	const CodeMirrorAdapter: CodeMirrorAdapterEx;
+	var CodeMirrorAdapter: CodeMirrorAdapterEx;
 }
 declare global {
 	/**
@@ -1709,7 +1709,7 @@ declare global {
 	 *
 	 * @unofficial
 	 */
-	const FS: ExtractConstructor<CapacitorAdapterFs>;
+	var FS: ExtractConstructor<CapacitorAdapterFs>;
 }
 declare global {
 	/**
@@ -1805,42 +1805,42 @@ declare global {
 	 * @unofficial
 	 * @deprecated - Added only for typing purposes. Use {@link DOMPurify} instead.
 	 */
-	const DOMPurify__: typeof import("dompurify");
+	var DOMPurify__: typeof import("dompurify");
 }
 declare global {
 	/**
 	 * Default internationalization strings bundled with Obsidian.
 	 * @unofficial
 	 */
-	const OBSIDIAN_DEFAULT_I18N: Localization;
+	var OBSIDIAN_DEFAULT_I18N: Localization;
 }
 declare global {
 	/**
 	 * Electron BrowserWindow instance for the current window.
 	 * @unofficial
 	 */
-	const electronWindow: ElectronWindow;
+	var electronWindow: ElectronWindow;
 }
 declare global {
 	/**
 	 * Electron BrowserWindow instance for the current window.
 	 * @unofficial
 	 */
-	const frameDom: FrameDom;
+	var frameDom: FrameDom;
 }
 declare global {
 	/**
 	 * Electron WebView tag for embedding external web content.
 	 * @unofficial
 	 */
-	const WebView: WebviewTag;
+	var WebView: WebviewTag;
 }
 declare global {
 	/**
 	 * Electron module for desktop platform APIs.
 	 * @unofficial
 	 */
-	const electron: typeof import("electron");
+	var electron: typeof import("electron");
 }
 declare global {
 	/**
@@ -1897,7 +1897,7 @@ declare global {
 	 * @unofficial
 	 * @deprecated - Added only for typing purposes. Use {@link CodeMirror} instead.
 	 */
-	const CodeMirror__: typeof import("codemirror");
+	var CodeMirror__: typeof import("codemirror");
 }
 declare global {
 	/**
@@ -1906,7 +1906,7 @@ declare global {
 	 * @unofficial
 	 * @deprecated - Prefer not to use this value directly.
 	 */
-	const app: App;
+	var app: App;
 }
 declare global {
 	/**
@@ -1943,21 +1943,21 @@ declare global {
 	 *
 	 * @unofficial
 	 */
-	const OBS_ACT__: ObsidianProtocolHandler;
+	var OBS_ACT__: ObsidianProtocolHandler;
 }
 declare global {
 	/**
 	 * MathJax instance for rendering mathematical notation.
 	 * @unofficial
 	 */
-	const MathJax: MathJaxEx;
+	var MathJax: MathJaxEx;
 }
 declare global {
 	/**
 	 * Mermaid library instance for rendering diagrams and charts.
 	 * @unofficial
 	 */
-	const mermaid: Mermaid;
+	var mermaid: Mermaid;
 }
 declare global {
 	/**
@@ -2009,35 +2009,35 @@ declare global {
 	 * Minified reference to `Object.defineProperties`.
 	 * @unofficial
 	 */
-	const Sf: typeof Object.defineProperties;
+	var Sf: typeof Object.defineProperties;
 }
 declare global {
 	/**
 	 * Minified reference to `Object.defineProperty`.
 	 * @unofficial
 	 */
-	const i18next: typeof import("i18next");
+	var i18next: typeof import("i18next");
 }
 declare global {
 	/**
 	 * Minified reference to `Object.defineProperty`.
 	 * @unofficial
 	 */
-	const wf: typeof Object.defineProperty;
+	var wf: typeof Object.defineProperty;
 }
 declare global {
 	/**
 	 * Minified reference to `Object.getOwnPropertyDescriptors`.
 	 * @unofficial
 	 */
-	const Cf: typeof Object.getOwnPropertyDescriptors;
+	var Cf: typeof Object.getOwnPropertyDescriptors;
 }
 declare global {
 	/**
 	 * Minified reference to `Object.getOwnPropertySymbols`.
 	 * @unofficial
 	 */
-	const mr: typeof Object.getOwnPropertySymbols;
+	var mr: typeof Object.getOwnPropertySymbols;
 }
 declare global {
 	/**
@@ -2045,42 +2045,42 @@ declare global {
 	 *
 	 * @unofficial
 	 */
-	const bl: typeof Object.hasOwnProperty;
+	var bl: typeof Object.hasOwnProperty;
 }
 declare global {
 	/**
 	 * Minified reference to `Object.propertyIsEnumerable`.
 	 * @unofficial
 	 */
-	const El: typeof Object.propertyIsEnumerable;
+	var El: typeof Object.propertyIsEnumerable;
 }
 declare global {
 	/**
 	 * Native Blink engine FormData constructor.
 	 * @unofficial
 	 */
-	const blinkFormData: typeof FormData;
+	var blinkFormData: typeof FormData;
 }
 declare global {
 	/**
 	 * Native Blink engine Headers constructor.
 	 * @unofficial
 	 */
-	const blinkHeaders: typeof Headers;
+	var blinkHeaders: typeof Headers;
 }
 declare global {
 	/**
 	 * Native Blink engine Request constructor.
 	 * @unofficial
 	 */
-	const blinkRequest: typeof Request;
+	var blinkRequest: typeof Request;
 }
 declare global {
 	/**
 	 * Native Blink engine Response constructor.
 	 * @unofficial
 	 */
-	const blinkResponse: typeof Response;
+	var blinkResponse: typeof Response;
 }
 declare global {
 	/**
@@ -2088,16 +2088,16 @@ declare global {
 	 * @unofficial
 	 * @hidden
 	 */
-	const blinkfetch: typeof fetch;
+	var blinkfetch: typeof fetch;
 }
 declare global {
 	/**
 	 * Notification component. Use to present timely, high-value information.
 	 *
 	 * @unofficial
-	 * @deprecated - Added only for typing purposes. Use {@link Notice} instead.
+	 * @deprecated - Added only for typing purposes. Use `window.Notice` or `import type { Notice } from 'obsidian'` instead.
 	 */
-	const Notice__: typeof Notice;
+	var Notice__: typeof Notice;
 }
 declare global {
 	/**
@@ -2338,7 +2338,7 @@ declare global {
 	 * PDF.js library for parsing and rendering PDF documents.
 	 * @unofficial
 	 */
-	const pdfjsLib: typeof import("pdfjs-dist");
+	var pdfjsLib: typeof import("pdfjs-dist");
 }
 declare global {
 	/**
@@ -2347,14 +2347,14 @@ declare global {
 	 * @unofficial
 	 * @deprecated - Added only for typing purposes. Use {@link moment} instead.
 	 */
-	const moment__: typeof momentInstance;
+	var moment__: typeof momentInstance;
 }
 declare global {
 	/**
 	 * PixiJS library for 2D rendering (used for canvas views).
 	 * @unofficial
 	 */
-	const PIXI: typeof import("pixi.js");
+	var PIXI: typeof import("pixi.js");
 }
 declare global {
 	/**
@@ -2362,7 +2362,7 @@ declare global {
 	 * @unofficial
 	 * @deprecated - Added only for typing purposes. Use {@link Prism} instead.
 	 */
-	const Prism__: typeof import("prismjs");
+	var Prism__: typeof import("prismjs");
 }
 declare global {
 	/**
@@ -2370,14 +2370,14 @@ declare global {
 	 * @unofficial
 	 */
 	// eslint-disable-next-line import-x/no-deprecated -- No other way.
-	const CapacitorPlatforms: typeof CapacitorPlatformsInstance;
+	var CapacitorPlatforms: typeof CapacitorPlatformsInstance;
 }
 declare global {
 	/**
 	 * Registry of available Capacitor platform implementations.
 	 * @unofficial
 	 */
-	const Capacitor: typeof CapacitorInstance;
+	var Capacitor: typeof CapacitorInstance;
 }
 declare global {
 	/**
@@ -2385,7 +2385,7 @@ declare global {
 	 * @unofficial
 	 * @deprecated - Added only for typing purposes. Use {@link scrypt} instead.
 	 */
-	const scrypt__: typeof scryptInstance;
+	var scrypt__: typeof scryptInstance;
 }
 declare global {
 	/**
@@ -2438,7 +2438,7 @@ declare global {
 	 *
 	 * @unofficial
 	 */
-	const requestUrl: typeof requestUrlInstance;
+	var requestUrl: typeof requestUrlInstance;
 }
 declare global {
 	/**
@@ -2447,7 +2447,7 @@ declare global {
 	 * Returns the text value of the response.
 	 * @unofficial
 	 */
-	const request: typeof requestInstance;
+	var request: typeof requestInstance;
 }
 declare global {
 	/**
@@ -2468,14 +2468,14 @@ declare global {
 	 * Temporary reference to the WebSQL database `changeVersion` method.
 	 * @unofficial
 	 */
-	const temp1: Database["changeVersion"];
+	var temp1: Database["changeVersion"];
 }
 declare global {
 	/**
 	 * Testing utilities for PDF.js.
 	 * @unofficial
 	 */
-	const pdfjsTestingUtils: PdfJsTestingUtils;
+	var pdfjsTestingUtils: PdfJsTestingUtils;
 }
 declare global {
 	/**
@@ -2485,7 +2485,7 @@ declare global {
 	 * @official
 	 * @deprecated - Added only for typing purposes. Use {@link activeDocument} instead.
 	 */
-	let activeDocument__: Document;
+	var activeDocument__: Document;
 }
 declare global {
 	/**
@@ -2495,21 +2495,21 @@ declare global {
 	 * @official
 	 * @deprecated - Added only for typing purposes. Use {@link activeWindow} instead.
 	 */
-	let activeWindow__: Window;
+	var activeWindow__: Window;
 }
 declare global {
 	/**
 	 * The style of the window title bar (e.g., "hidden", "default").
 	 * @unofficial
 	 */
-	const titlebarStyle: string;
+	var titlebarStyle: string;
 }
 declare global {
 	/**
 	 * TurndownService for converting HTML to Markdown.
 	 * @unofficial
 	 */
-	const TurndownService: typeof import("turndown");
+	var TurndownService: typeof import("turndown");
 }
 declare global {
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-typings",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "Extended type definitions for the Obsidian API (https://obsidian.md)",
   "main": "",
   "module": "",