obsidian-typings 1.0.0 → 1.0.1

package/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish
+on:
+    push:
+        tags:
+            - '*'
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v3
+              with:
+                  node-version: '20.x'
+                  registry-url: 'https://registry.npmjs.org'
+            - run: npm ci
+            - run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## v1.0.0 (initial npm release)
+- Made package installable via npm
+- Clarified README, added contribution guidelines

package/CONTRIBUTING.MD

@@ -0,0 +1,238 @@
+# Introduction
+
+## General Notes
+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.
+
+### TSDoc
+Please use [TSDoc](https://tsdoc.org/) to document the typings. This will allow the documentation to be automatically generated
+within your IDE, and can help with the discoverability of the typings.
+
+
+Example: 
+```ts
+interface someObject {
+    /**
+     * Does something specific
+     * @param val1 Enables some functionality
+     * @tutorial Useful for implementing some features for your plugin
+     * @remark Prefer using `someOtherMethod` instead
+     */
+    someMethod(val1: boolean): number;
+
+    /**
+     * Does something that you're not certain about, and should probably not be used
+     * @internal
+     */
+    someInternalMethod(): void;
+}
+```
+
+> [!NOTE]
+> `@internal` --- Method is *very likely* not fully/correctly typed, and/or is not intended to be used by plugins.
+> 
+> `@remark` --- Alternatives that should be used instead, or warnings about the function.
+> 
+> `@tutorial` --- Short description on how the function could be used in your plugin.
+> 
+> `@deprecated` --- Method is deprecated in a particular version (can't be found in `app.js` anymore).
+
+
+# Tutorial
+
+## Adding new typings
+
+### Finding/Discovering new typings 
+
+The first step to add new typings, is finding the object/interface/module you want to add typings for within the Obsidian app.
+One of the easiest way to do this, is to open the developer console (Ctrl+Shift+I), and start searching for the interface you wish to
+type from the `app.` object.
+
+If you want to, for example, add typings for the `InternalPlugins` object, you can type `app.internalPlugins` into the console,
+which will produce the following output:
+
+![images/prototype-reference.png](images/prototype-reference.png)
+
+Note how the internalPlugins object contains multiple prototypes: the `InternalPlugins` interface itself, but also
+the `Events` class and then the `Object` literal (does not need to be typed). This can be determined this by looking at the other definitions in the (un)official API,
+and checking whether the two objects define the same properties.
+
+Thus, to define `InternalPlugin`, you can start by adding each of the methods and properties to a `InternalPlugins` interface:
+
+```ts
+interface InternalPlugins extends Events {
+    // Variables
+    app: App;
+    config: Record<any, any>;
+    migration: any;
+    plugins: Record<any, any>;
+    
+    // Methods
+    requestSaveConfig(): any;
+    enable(): any;
+    getEnabledPluginById(var1: any): any;
+    getEnabledPlugins(): any;
+    // ...
+}
+```
+To keep it simple, we first add `any` as type to every variable and method -- unless it is obvious what the type should be
+(i.e. `app` will always be an instance of `App`).
+
+Next up, is the most tedious part of adding typings: finding the correct types for each of the methods and variables.
+
+### Typing variables
+
+The easiest way to start, is by tackling the variables first. For example, in the console output, you can see that `config`
+is mapping a string to `true`. In this case, it would be safe to assume that the type of `config` is `Record<string, boolean>`.
+
+```ts
+interface InternalPlugins extends Events {
+    // ...
+    config: Record<string, boolean>;
+    // ...
+}
+```
+
+However, you can take this one step further still by considering the fact that each string is essentialy a different plugin ID.
+In this case, we might just define a new type that contains all the plugin IDs, and use this as the key for the `config` object:
+
+```ts
+type InternalPluginName = 'audio-recorder' | 'backlink' | 'bookmarks' | 'canvas' /*| ... */;
+interface InternalPlugins extends Events {
+    // ...
+    config: Record<InternalPluginName, boolean>;
+    // ...
+}
+```
+
+Similarly, you can define the `plugins` variable as `Record<InternalPluginName, any>`.
+
+Further, it is safe to assume that each element in `Plugins` would be some instance of a `InternalPlugin` class, so we
+will also need to add a new interface for this:
+
+```ts
+interface InternalPlugin {
+    app: App;
+    commands: any;
+    // etc. (repeat the same procedure)
+}
+
+interface InternalPlugins extends Events {
+    // ...
+    plugins: Record<InternalPluginName, InternalPlugin>;
+    // ...
+}
+```
+
+Make sure to also add brief descriptions (using [TSDoc](https://tsdoc.org/)) to each of the variables. Mark variables that you are not entirely sure about with `@internal`.
+Feel free to copy descriptions from previous typings, or from the official API.
+
+
+### Typing methods
+
+Typing methods is a bit more difficult, as aside you will need to know what the method does, and what the expected input and output is.
+
+You could start by typing the methods that do not take any arguments, and have a simple return type. For example, the `requestSaveConfig` method.
+From the name, we can already make the assumption that this method will probably _not_ return anything, as it is just telling
+the app that a config should be saved, the method will thus _likely_ be of type `void`.
+
+However, to make sure whether this assumption is correct, you _**should**_ check the source code (see next section).
+If possible, you can also run the method in the console, and see what happens (in this case, nothing happens, so it is likely just `void`).
+
+As before, if you are not certain about the return type or the workings of the function in general,
+add a `@internal` tag to the method description, and/or mark the return type as `any`.
+
+
+```ts
+interface InternalPlugins extends Events {
+    // ...
+    /**
+     * @internal Request save of plugin configs
+     */
+    requestSaveConfig(): any;
+    // ...
+}
+```
+
+Next up, are methods that take arguments. For example, the `getEnabledPluginById` method takes a single argument.
+It is very likely that this argument will just be of type `InternalPluginName`, but again, you could easily verify this by
+running the method in the console (i.e. `app.internalPlugins.getEnabledPluginById('audio-recorder')` and `app.internalPlugins.getEnabledPluginById('wrong-id')`).
+
+```ts
+interface InternalPlugins extends Events {
+    // ...
+    /**
+     * Get an internal plugin by ID
+     * @param id - ID of the plugin to get
+     * @returns Plugin instance
+     */
+    getEnabledPluginById(id: InternalPluginName): InternalPlugin;
+    // ...
+}
+```
+
+
+## Traversing and analysing the source code
+
+Finally, this is both the most tedious but also the most important technique: finding the definition of the method in the minified source code.
+
+Start off by going back to the console, and going into the `Sources` tab. Here you will find the `app.js` file where
+all the internal methods are defined.
+
+1. Go to the `Sources` tab
+2. Select the `app.js` file
+3. `Pretty format` the code (optional)
+4. Copy the code to your IDE of choice (optional, but recommended)
+
+
+![images/accessing-main.png](images/accessing-main.png)
+
+With access to the minified code, you can now start searching through it and find the definition of the method you are trying to type.
+
+For any method "XYZ", start by just searching for "XYZ". Generally, the method is defined as either:
+- `t.XYZ = ...` (for prototype methods)
+- `t.prototype.XYZ = ...` (for prototype methods)
+- `function XYZ(` (for internal/minified methods)
+
+At this stage, you might get lucky and get a single definition, or you might get multiple definitions. In the latter case,
+you will need try to look at the context of the code to determine which interface/class the method belongs to. 
+The main tip for finding the correct definition, is to look at the other methods being defined on the prototype, 
+and check if these match with the other methods of your object.
+
+With the correct line found for the definition, you can now start analysing the code to determine the input/output types
+and its behaviour. 
+
+For example, the `requestSaveConfig` method (seen earlier) is defined as follows:
+
+```js
+n.requestSaveConfig = at(n.saveConfig.bind(n), 1e3, !0),
+```
+
+Here, we find the following three things:
+- `at` is a minified function that takes three arguments, and its return value is the return value of the method
+- `1e3` is shorthand notation for `1000`
+- `!0` is shorthand notation for `true`
+
+(There are many shorthands and structural changes that you will need to get used to in the minified code)
+
+Since we don't know what `at` does, we need to start searching through the code again. Make sure to enable caps + whole word search, as `at` is a very common word.
+Start by searching for `function at`, or `.prototype.at`. With any luck, this will lead you to the following definition:
+
+```js
+function at(e, t, n) {
+    void 0 === t && (t = 0),
+    void 0 === n && (n = !1);
+    var i, r = null, o = null, a = null, s = 0, l = function() {
+        var t = o
+            , n = a;
+        /*   ...    */
+    }
+}
+```
+
+At this point, you may want to pass the code through your favourite flavour of LLM or de-minifier, to make the code more understandable.
+In this case, it seems that a function is constructed and some timeouts are started/reset, and other shenanigans.
+Since I personally didn't want to spend too much time on this, I forewent the effort of trying to understand what the code does,
+and just marked the method as `@internal`. Generally, if you can't understand the code within 10 minutes, it's probably not something
+you should be touching anyway.  (Though feel free to open an issue if you understand what semi-arcane magic is happening here!)
+

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Fevol
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023 Fevol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,36 +1,63 @@
-This repository contains TypeScript typings for undocumented [Obsidian](https://obsidian.md/) API functions.
-
-There are three options for installing this package:
-1. **Explicit type importing:** Each typing has to be imported explicitly, e.g. `import {App, MarkdownView} from "@fevol/obsidian-typings"`. <br> _Install via:_ `npm install --save-dev  npm install @fevol/obsidian-typings`
-
-
-
-
-
-You can add the code as a submodule to your project - or as an NPM package via `npm install --save-dev  npm install @fevol/obsidian-typings`.
-
-If you prefer to have automatic types discovery without needing to explicitly `import` current package, use `npm install --save-dev @types/obsidian-typings@npm:@fevol/obsidian-typings`
-
-These typings contain _almost_ all of the undocumented API methods and variables, excluding those that 
-seem to be intended solely for internal use and will not be relevant for plugin development.
-
-Please be aware that there is a good reason why 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
-
-So, please use the functions and variables provided 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 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.
-
-Furthermore, there is a very high chance that I made a mistake in the typings, despite my best efforts.
-All the types had to be deduced from either context, manually running the function, or the minified app code. 
-You will have to verify if the code behaves as expected, both with regard to the expected types, as well as what 
-the function description says.
-
-With all the scary disclaimers out of the way, hopefully these typings will help in removing 90% of the `@ts-ignore`s
-you have in your codebase, or let you discover solutions that didn't seem possible before.
-
-PR's and issue reports are welcome for missing, deprecated or incorrectly defined typings.
+
+# Obsidian Extended Typings
+
+This repository contains TypeScript typings for undocumented [Obsidian](https://obsidian.md/) API functions and variables and additional descriptions, 
+essentially extending the official [Obsidian API](https://github.com/obsidianmd/obsidian-api/blob/master/obsidian.d.ts).
+
+Be aware that the typings currently only cover a subset of all methods: most of the `App` interface and its sub-interfaces
+are covered, but typings for views like `Graph`, `Canvas`, ... are still missing -- contributions for these would be very welcome!
+
+## Installation
+
+There are three options for installing this package:
+1. **Explicit type importing** <br> Each typing has to be imported explicitly from `obsidian-typings` instead of `obsidian`, e.g. `import {App, MarkdownView} from "obsidian-typings"`. <br> _Install via:_ `npm install --save-dev  obsidian-typings`
+
+2. **Automatic type extending** (recommended) <br> The typings are automatically added to the existing `obsidian` module, so you can use them without any changes to your code. <br> _Install via:_ `npm install --save-dev @types/obsidian-typings@npm:obsidian-typings`
+
+3. **Add extended typings as submodule** <br> Your IDE will likely pick up the typings automatically when the project is added as a submodule for your plugin, this also makes it simpler to test and submit features to the repository. <br> _Install via:_ `git submodule add https://github.com/Fevol/obsidian-typings.git typings` (or any other folder)
+
+
+## Disclaimer
+
+> [!WARNING]
+> Make sure to read below section in detail before using these typings.
+
+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 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.
+
+Methods marked `@internal` are especially risky to use: these are either not fully typed yet, or are solely intended
+to be used internally by the Obsidian app.
+
+Furthermore, there is a very high chance that there are mistakes in the typings, despite best efforts.
+All types had to be deduced from either context, manually running the function, or from the minified app code. 
+You _**should**_ verify that the code behaves as expected, both with regard to the expected (input/output)types, as well as what 
+the function description promises.
+
+With these scary disclaimers out of the way, hopefully these typings will help you in removing 90% of the `@ts-ignore`s
+you have in your codebase, or discover solutions that didn't seem possible before.
+
+
+> [!NOTE] 
+> **TL;DR:** Use at your own risk, verify that the code behaves as expected, and be prepared to update your code if the API changes.
+> 
+> `@internal` methods are especially risky to use.
+> 
+> `@remark` tags give some warnings about the inputs/outputs of the function, or provide better alternatives.
+> 
+> `@tutorial` gives additional information on how to use the function in your plugin.
+
+
+## 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.
+
+A brief tutorial is available on how you can get started with adding new typings, or fixing existing ones, see: [CONTRIBUTING.md](CONTRIBUTING.md).