obsidian-typings 4.22.0 → 4.23.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +208 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,15 +4,218 @@
|
|
|
4
4
|
|
|
5
5
|
</center>
|
|
6
6
|
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
<div align="center">
|
|
10
|
+
<a href="https://www.npmjs.com/package/obsidian-typings" style="text-decoration: none">
|
|
11
|
+
<img alt="NPM downloads" src="https://img.shields.io/npm/v/obsidian-typings?color=red&label=Version%3A&logo=npm&logoColor=white&labelColor=red">
|
|
12
|
+
</a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/obsidian-typings" style="text-decoration: none">
|
|
14
|
+
<img alt="NPM downloads" src="https://img.shields.io/npm/dw/obsidian-typings?style=flat&label=Downloads">
|
|
15
|
+
</a>
|
|
16
|
+
<a href="https://github.com/Fevol/obsidian-typings/stargazers" style="text-decoration: none">
|
|
17
|
+
<img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/fevol/obsidian-typings?color=yellow&label=Stargazers%3A&logo=OpenTelemetry&logoColor=yellow">
|
|
18
|
+
</a><br>
|
|
19
|
+
<a href="https://www.typescriptlang.org/" style="text-decoration: none">
|
|
20
|
+
<img alt="Typescript" src="https://img.shields.io/badge/-Typescript-3178C6?logo=Typescript&logoColor=white&style=flat&">
|
|
21
|
+
</a>
|
|
22
|
+
</div>
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
7
26
|
<div align="center">
|
|
8
|
-
|
|
9
|
-
|
|
27
|
+
<h4>
|
|
28
|
+
<a href="https://fevol.github.io/obsidian-typings">DOCS</a>
|
|
29
|
+
<span> · </span>
|
|
30
|
+
<a href="https://fevol.github.io/obsidian-typings/resources/obsidian-typings-changelog">CHANGELOG</a>
|
|
31
|
+
<span> · </span>
|
|
32
|
+
<a href="https://www.npmjs.com/package/obsidian-typings">NPM</a>
|
|
33
|
+
<span> · </span>
|
|
34
|
+
<a href="https://fevol.github.io/obsidian-typings/contributing">CONTRIBUTING</a>
|
|
35
|
+
|
|
36
|
+
</h4>
|
|
10
37
|
</div>
|
|
11
38
|
|
|
12
|
-
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
**Obsidian Typings** provides **TypeScript definitions** for Obsidian’s **undocumented and internal APIs**.
|
|
42
|
+
|
|
43
|
+
It extends the official [Obsidian API](https://github.com/obsidianmd/obsidian-api/) with:
|
|
44
|
+
- Additional type definitions for internal methods, properties, and plugins.
|
|
45
|
+
- Explanations and usage examples to make undocumented parts easier to understand.
|
|
46
|
+
- Helper utilities and interfaces for working with Obsidian’s internals in a safer, type-safe way.
|
|
47
|
+
|
|
48
|
+
This package is designed for plugin developers who want to access Obsidian's internal APIs in a type-safe manner,
|
|
49
|
+
while also keeping their code maintainable and less reliant on `@ts-ignore`/`@ts-expect-error`.
|
|
50
|
+
|
|
51
|
+
> [!IMPORTANT]
|
|
52
|
+
>
|
|
53
|
+
> - This package is **not affiliated with, or endorsed by, the Obsidian team**.
|
|
54
|
+
> - It does **not** cover every aspect of the Obsidian API.
|
|
55
|
+
> - Typings are based on reverse engineering and may be **inaccurate or unstable**. They can change without notice in future releases.
|
|
56
|
+
> - Always **test thoroughly** and **add fallbacks** when using internal APIs.
|
|
57
|
+
|
|
58
|
+
## Versioning and Release Channels
|
|
59
|
+
|
|
60
|
+
[Obsidian](https://obsidian.md) has two main release channels:
|
|
61
|
+
|
|
62
|
+
- `public` - stable versions available to all users.
|
|
63
|
+
- [`catalyst`](https://help.obsidian.md/catalyst) (`beta`, `early access`) - versions only available to users with a catalyst license, has early access to new features.
|
|
64
|
+
|
|
65
|
+
If you use internal APIs, you may need to support users on both channels.
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
To make it easier to adapt to these differences, this package provides typings for both channels.
|
|
69
|
+
|
|
70
|
+
Typings for each `Obsidian` version can be found in their own git branches: namely `release/obsidian-public/*` and `release/obsidian-catalyst/*`:
|
|
71
|
+
|
|
72
|
+
- Latest `public` release: [`release/obsidian-public/1.9.10`](https://github.com/Fevol/obsidian-typings/tree/release/obsidian-public/1.9.10)
|
|
73
|
+
- Latest `catalyst` release: [`release/obsidian-catalyst/1.9.10`](https://github.com/Fevol/obsidian-typings/tree/release/obsidian-catalyst/1.9.10)
|
|
74
|
+
|
|
75
|
+
Older versions of the package are available, but support for them is limited.
|
|
76
|
+
In most cases, we recommend to always use the latest release.
|
|
77
|
+
|
|
78
|
+
## Set-up
|
|
79
|
+
|
|
80
|
+
### 1. Install via `npm`
|
|
81
|
+
|
|
82
|
+
- Latest `public` release (recommended):
|
|
83
|
+
- `npm install --save-dev obsidian-typings`
|
|
84
|
+
- Explicitly install latest `public` release:
|
|
85
|
+
- `npm pkg set "dependencies.obsidian-typings=obsidian-public-latest" && npm install`
|
|
86
|
+
- Install the latest `catalyst` (`beta`) release:
|
|
87
|
+
- `npm pkg set "dependencies.obsidian-typings=obsidian-catalyst-latest" && npm install`
|
|
88
|
+
- Install a specific release (should match `minAppVersion` in your plugin's `manifest.json`):
|
|
89
|
+
- `npm pkg set "dependencies.obsidian-typings=obsidian-public-1.8.10" && npm install`
|
|
90
|
+
- `npm pkg set "dependencies.obsidian-typings=obsidian-catalyst-1.9.9" && npm install`
|
|
91
|
+
|
|
92
|
+
### 2. Enable in `tsconfig.json` (recommended) <span id="add-types-setting-to-tsconfig-json"></span>
|
|
93
|
+
|
|
94
|
+
Add `obsidian-typings` to the `types` array of your `tsconfig.json` to make all extended typings available globally without explicit importing them:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"compilerOptions": {
|
|
99
|
+
"...": "...",
|
|
100
|
+
"types": [
|
|
101
|
+
"obsidian-typings"
|
|
102
|
+
]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
13
106
|
|
|
14
107
|
> [!WARNING]
|
|
15
108
|
>
|
|
16
|
-
> If
|
|
109
|
+
> 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.
|
|
110
|
+
> ```json
|
|
111
|
+
> {
|
|
112
|
+
> "compilerOptions": {
|
|
113
|
+
> "...": "...",
|
|
114
|
+
> "types": [
|
|
115
|
+
> "obsidian-typings",
|
|
116
|
+
> "some-package-name"
|
|
117
|
+
> ]
|
|
118
|
+
> }
|
|
119
|
+
> }
|
|
120
|
+
|
|
121
|
+
### 3. Importing explicitly (alternative)
|
|
122
|
+
|
|
123
|
+
Instead of adding `obsidian-typings` to your `types`, you can also import the package directly:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
import 'obsidian-typings';
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Usage
|
|
130
|
+
|
|
131
|
+
### `obsidian` module internals
|
|
132
|
+
|
|
133
|
+
To access types from the `obsidian` module, the import syntax does not change:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
import type { App } from 'obsidian';
|
|
137
|
+
|
|
138
|
+
console.log(this.app.internalPlugins);
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### `obsidian-typings` additional interfaces
|
|
142
|
+
|
|
143
|
+
Additional interfaces added by this package (which do not exist in the official API), can be imported as:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import type { InternalPlugins } from 'obsidian-typings';
|
|
147
|
+
|
|
148
|
+
const internalPlugins: InternalPlugins = this.app.internalPlugins;
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### `obsidian-typings/implementations`
|
|
152
|
+
|
|
153
|
+
Additional helper functions/types/... added by this package can be used by importing from `obsidian-typings/implementations`:
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
import { InternalPluginName } from 'obsidian-typings/implementations';
|
|
157
|
+
|
|
158
|
+
// If you forget the `/implementations` part:
|
|
159
|
+
// import { InternalPluginName } from 'obsidian-typings';
|
|
160
|
+
// You will not be able to use the runtime values and the code below will not compile.
|
|
161
|
+
|
|
162
|
+
this.app.internalPlugins.getEnabledPluginById(InternalPluginName.FileExplorer);
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
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)).
|
|
166
|
+
|
|
167
|
+
### Extend with your own typings
|
|
168
|
+
|
|
169
|
+
If you need to extend the typings provided by this package, add the following to any `.d.ts` file in your project:
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
export {}; // This line is required. If there are no top-level `import/export` statements, your typings will work not as expected.
|
|
173
|
+
declare module 'obsidian-typings' {
|
|
174
|
+
interface PluginsPluginsRecord {
|
|
175
|
+
['my-plugin-id']: MyPlugin;
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Disclaimer
|
|
181
|
+
|
|
182
|
+
> [!WARNING]
|
|
183
|
+
>
|
|
184
|
+
> Make sure to read below section in detail before using these typings.
|
|
185
|
+
>
|
|
186
|
+
> Use at your own risk, verify that the code behaves as expected, and be prepared to update your code if the API changes.
|
|
187
|
+
|
|
188
|
+
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:
|
|
189
|
+
|
|
190
|
+
- The methods are not fully defined, and will be changed or removed in the near-future
|
|
191
|
+
- There is a high risk of the code behaving unexpectedly if used improperly
|
|
192
|
+
- The function was never meant to be used
|
|
193
|
+
|
|
194
|
+
Please use the functions and variables provided by this package with caution.
|
|
195
|
+
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.
|
|
196
|
+
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.
|
|
197
|
+
Some functions will also contain `@remark` TSDoc tags that provide alternatives or better solutions.
|
|
198
|
+
|
|
199
|
+
Furthermore, there is a very high chance that there are mistakes in the typings, despite best efforts.
|
|
200
|
+
All types had to be deduced from context, manually running the function, or from the minified app code.
|
|
201
|
+
Always verify that your code behaves as expected, both in terms of types and runtime behavior.
|
|
202
|
+
|
|
203
|
+
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.
|
|
204
|
+
|
|
205
|
+
## Tags
|
|
206
|
+
|
|
207
|
+
- `@remark` warnings, caveats, or suggested alternatives.
|
|
208
|
+
- `@tutorial` extra guidance and examples.
|
|
209
|
+
- `@official` comes from the [official API](https://github.com/obsidianmd/obsidian-api/blob/master/obsidian.d.ts).
|
|
210
|
+
- `@unofficial` based on reverse engineering.
|
|
211
|
+
|
|
212
|
+
## Migration
|
|
213
|
+
|
|
214
|
+
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.
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
## Contributing
|
|
218
|
+
|
|
219
|
+
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.
|
|
17
220
|
|
|
18
|
-
|
|
221
|
+
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).
|