obsidian-integration-testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Michael Naumov
+
+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

@@ -0,0 +1,298 @@
+# obsidian-integration-testing
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/mnaoumov)
+[![GitHub release](https://img.shields.io/github/v/release/mnaoumov/obsidian-integration-testing)](https://github.com/mnaoumov/obsidian-integration-testing/releases)
+[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/mnaoumov/obsidian-integration-testing)
+
+A set of helpers that simplify integration testing of [Obsidian](https://obsidian.md/) plugins against a running Obsidian instance via the [Obsidian CLI](https://obsidian.md/help/cli/).
+
+## Prerequisites
+
+- [Obsidian](https://obsidian.md/) must be running with the CLI enabled.
+
+## Installation
+
+```bash
+npm install --save-dev obsidian-integration-testing
+```
+
+## Usage
+
+### Plugin Vitest setup
+
+> **This entry point is designed for Obsidian plugin repos only.** It expects your built plugin in `dist/dev` or `dist/build` (whichever has a newer `main.js`), with a `manifest.json` at the root of the chosen folder. The setup creates a temporary vault, copies the build into it, and enables the plugin via the Obsidian CLI.
+
+Add it as a Vitest global setup:
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globalSetup: ['obsidian-integration-testing/obsidian-plugin-vitest-setup']
+  }
+});
+```
+
+### Write integration tests
+
+Use `evalInObsidian()` to run code inside the Obsidian process. The `vaultPath` is optional — it defaults to `process.cwd()`:
+
+```ts
+import { evalInObsidian } from 'obsidian-integration-testing';
+
+// Simple expression
+const sum = await evalInObsidian({
+  args: { a: 2, b: 3 },
+  fn: ({ a, b }) => a + b
+});
+// sum === 5
+```
+
+### Access the Obsidian API
+
+Every callback receives `app` (the Obsidian `App` instance) and `obsidianModule` (the full `obsidian` module):
+
+```ts
+// Read the vault config directory
+const configDir = await evalInObsidian({
+  fn: ({ app }) => app.vault.configDir
+});
+
+// Use the obsidian module
+const yaml = await evalInObsidian({
+  fn: ({ obsidianModule }) => obsidianModule.stringifyYaml({ key: 'value' })
+});
+
+// Access internal APIs
+const title = await evalInObsidian({
+  fn: ({ app }) => app.title
+});
+```
+
+### Pass complex arguments
+
+Arguments are JSON-serialized. You can even pass functions — they are serialized via `toString()`:
+
+```ts
+const result = await evalInObsidian({
+  args: {
+    transform(x: number): number {
+      return x * 2;
+    },
+    value: 5
+  },
+  fn: ({ transform, value }) => transform(value)
+});
+// result === 10
+```
+
+### Persist non-serializable values across calls
+
+Obsidian objects like `TFile` or `Editor` live in the Obsidian process and can't be returned to the test. Use `ContextId` to create a typed store that persists across calls:
+
+```ts
+import type { TFile } from 'obsidian';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ContextId, evalInObsidian } from 'obsidian-integration-testing';
+
+interface Context {
+  file: TFile;
+}
+
+const contextId = new ContextId<Context>();
+
+beforeEach(async () => {
+  await evalInObsidian({
+    contextId,
+    fn: async ({ app, context }) => {
+      context.file = await app.vault.create('test.md', '# Hello');
+    }
+  });
+});
+
+afterEach(async () => {
+  await evalInObsidian({
+    contextId,
+    fn: async ({ app, context: { file } }) => {
+      await app.vault.delete(file);
+    }
+  });
+  await contextId.dispose();
+});
+
+it('should read the file path', async () => {
+  const path = await evalInObsidian({
+    contextId,
+    fn: ({ context: { file } }) => file.path
+  });
+  expect(path).toBe('test.md');
+});
+```
+
+### Create a temporary vault
+
+Use `TempVault` to create a disposable vault pre-populated with files:
+
+```ts
+import type { TFile } from 'obsidian';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { ContextId, evalInObsidian, TempVault } from 'obsidian-integration-testing';
+
+interface Context {
+  file: TFile;
+}
+
+const vault = new TempVault({
+  files: {
+    'note.md': '# Hello',
+    'folder/nested.md': 'nested content',
+  }
+});
+
+const contextId = new ContextId<Context>();
+
+beforeAll(async () => {
+  await vault.register();
+
+  // Resolve the pre-populated file into a TFile and store it in the context
+  await evalInObsidian({
+    contextId,
+    fn: async ({ app, context }) => {
+      const file = app.vault.getFileByPath('note.md');
+      if (!file) {
+        throw new Error('File not found');
+      }
+      context.file = file;
+    },
+    vaultPath: vault.path
+  });
+});
+
+afterAll(async () => {
+  await contextId.dispose(vault.path);
+  await vault.dispose();
+});
+
+it('should read a pre-populated file', async () => {
+  const content = await evalInObsidian({
+    fn: ({ app }) => app.vault.adapter.read('note.md'),
+    vaultPath: vault.path
+  });
+  expect(content).toBe('# Hello');
+});
+
+it('should access the TFile from context', async () => {
+  const path = await evalInObsidian({
+    contextId,
+    fn: ({ context: { file } }) => file.path,
+    vaultPath: vault.path
+  });
+  expect(path).toBe('note.md');
+});
+```
+
+Parent directories are created automatically. To create an empty folder, use a path ending with `/` and an empty string as content.
+
+### Test your plugin
+
+Use `getTempVaultPath()` to get the temporary vault created by the global setup:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { evalInObsidian } from 'obsidian-integration-testing';
+import { getTempVaultPath } from 'obsidian-integration-testing/obsidian-plugin-vitest-setup';
+
+describe('my-plugin', () => {
+  const vaultPath = getTempVaultPath();
+
+  it('should be enabled', async () => {
+    const isEnabled = await evalInObsidian({
+      args: { pluginId: 'my-plugin' },
+      fn: ({ app, pluginId }) => app.plugins.enabledPlugins.has(pluginId),
+      vaultPath
+    });
+    expect(isEnabled).toBe(true);
+  });
+
+  it('should create a file', async () => {
+    await evalInObsidian({
+      fn: async ({ app }) => {
+        await app.vault.create('test.md', '# Hello');
+      },
+      vaultPath
+    });
+
+    const content = await evalInObsidian({
+      fn: ({ app }) => app.vault.adapter.read('test.md'),
+      vaultPath
+    });
+    expect(content).toBe('# Hello');
+  });
+});
+```
+
+> [!WARNING]
+>
+> **`evalInObsidian` limitations:**
+>
+> - The function is serialized via `toString()` and executed in a separate process. It must be **self-contained** — closures over local variables will not work.
+> - Pass any needed values via `args`. Arguments must be **JSON-serializable** (strings, numbers, booleans, arrays, plain objects). Functions in `args` are supported — they are serialized via `toString()` with the same self-contained constraint.
+> - The **return value** must also be JSON-serializable. You cannot return functions, class instances, `Map`, `Set`, DOM elements, or other non-serializable values.
+> - Imports (`import`/`require`) are not available inside the function. Use `obsidianModule` to access the `obsidian` API, and `app` to access the Obsidian `App` instance.
+
+### Accessing internal APIs
+
+Since `evalInObsidian` runs inside a real Obsidian process, you have access to internal (undocumented) APIs like `app.plugins`, `app.commands`, `app.title`, etc. However, these are not declared in `obsidian.d.ts`, so TypeScript won't compile references to them. Here are the options to make it work, from best to worst:
+
+**1. Use `obsidian-typings`** (recommended) — install [`obsidian-typings`](https://www.npmjs.com/package/obsidian-typings) which declares the full internal API. Everything compiles with no extra work:
+
+```ts
+// With obsidian-typings installed — no casts needed
+const title = await evalInObsidian({
+  fn: ({ app }) => app.title
+});
+```
+
+**2. Manual module augmentation** — declare only what you need:
+
+```ts
+declare module 'obsidian' {
+  interface App {
+    title: string;
+  }
+}
+
+const title = await evalInObsidian({
+  fn: ({ app }) => app.title
+});
+```
+
+**3. `as any` / `@ts-expect-error` / `@ts-ignore`** (not recommended) — suppresses all type checking and hides real errors:
+
+```ts
+const title = await evalInObsidian({
+  // @ts-expect-error -- accessing internal API
+  fn: ({ app }) => app.title
+});
+
+// or
+const title2 = await evalInObsidian({
+  fn: ({ app }) => (app as any).title
+});
+```
+
+## Support
+
+<!-- markdownlint-disable MD033 -->
+
+<a href="https://www.buymeacoffee.com/mnaoumov" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60" width="217"></a>
+
+<!-- markdownlint-enable MD033 -->
+
+## My other Obsidian resources
+
+[See my other Obsidian resources](https://github.com/mnaoumov/obsidian-resources).
+
+## License
+
+© [Michael Naumov](https://github.com/mnaoumov/)

package/dist/lib/cjs/context-id.cjs

@@ -0,0 +1,83 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var context_id_exports = {};
+__export(context_id_exports, {
+  ContextId: () => ContextId
+});
+module.exports = __toCommonJS(context_id_exports);
+var import_obsidian_cli = require("./obsidian-cli.cjs");
+class ContextId {
+  id;
+  /**
+   * Creates a new context id.
+   */
+  constructor() {
+    const SLICE_START = 2;
+    this.id = `__ctx_${String(Math.random()).slice(SLICE_START)}`;
+  }
+  /**
+   * Removes this context from the Obsidian process.
+   *
+   * @param vaultPath - The path to the Obsidian vault. Defaults to `process.cwd()`.
+   */
+  async dispose(vaultPath) {
+    await (0, import_obsidian_cli.evalInObsidian)({
+      args: { id: this.id },
+      /* v8 ignore start -- Serialized via toString() and executed inside the Obsidian process. Covered by integration tests. */
+      fn({ id }) {
+        const holder = window;
+        if (holder.__obsidianContexts__) {
+          delete holder.__obsidianContexts__[id];
+        }
+      },
+      /* v8 ignore stop */
+      shouldSkipPreflightChecks: true,
+      ...vaultPath === void 0 ? {} : { vaultPath }
+    });
+  }
+  /**
+   * Disposes this context id.
+   *
+   * @returns A promise that resolves when the context id is disposed.
+   */
+  async [Symbol.asyncDispose]() {
+    await this.dispose();
+  }
+  /**
+   * Returns the JSON representation of the context id.
+   *
+   * @returns The JSON representation of the context id.
+   */
+  toJSON() {
+    return this.id;
+  }
+  /**
+   * Returns the string representation of the context id.
+   *
+   * @returns The string representation of the context id.
+   */
+  toString() {
+    return this.id;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ContextId
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2NvbnRleHQtaWQudHMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbIi8qKlxuICogQHBhY2thZ2VEb2N1bWVudGF0aW9uXG4gKlxuICogVHlwZWQgY29udGV4dCBpZGVudGlmaWVycyBmb3IgcGVyc2lzdGluZyBub24tc2VyaWFsaXphYmxlIHZhbHVlc1xuICogYWNyb3NzIHtAbGluayBldmFsSW5PYnNpZGlhbn0gY2FsbHMuXG4gKi9cblxuaW1wb3J0IHsgZXZhbEluT2JzaWRpYW4gfSBmcm9tICcuL29ic2lkaWFuLWNsaS5janMnO1xuXG4vKipcbiAqIFdyYXBzIGEge0BsaW5rIENvbnRleHRPZn0gZXh0cmFjdGlvbiBpbnRvIGFuIG9iamVjdCB3aXRoIGEgYGNvbnRleHRgIHByb3BlcnR5LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIENvbnRleHRBcmdzPFRDb250ZXh0SWQgZXh0ZW5kcyBDb250ZXh0SWQ8dW5rbm93bj4gfCB1bmRlZmluZWQgPSB1bmRlZmluZWQ+IHtcbiAgY29udGV4dDogQ29udGV4dE9mPFRDb250ZXh0SWQ+O1xufVxuXG4vKipcbiAqIEV4dHJhY3RzIHRoZSBjb250ZXh0IHR5cGUgZnJvbSBhIHtAbGluayBDb250ZXh0SWR9LlxuICovXG5leHBvcnQgdHlwZSBDb250ZXh0T2Y8VD4gPSBUIGV4dGVuZHMgQ29udGV4dElkPGluZmVyIENvbnRleHQ+ID8gQ29udGV4dCA6IG5ldmVyO1xuXG4vKipcbiAqIEEgdHlwZWQgY29udGV4dCBpZGVudGlmaWVyIGZvciBwZXJzaXN0aW5nIG5vbi1zZXJpYWxpemFibGUgdmFsdWVzXG4gKiBhY3Jvc3Mge0BsaW5rIGV2YWxJbk9ic2lkaWFufSBjYWxscy5cbiAqXG4gKiBUaGUgY29udGV4dCBpcyBhIHBlcnNpc3RlbnQgb2JqZWN0IHN0b3JlZCBvbiBgd2luZG93YCBpbiB0aGUgT2JzaWRpYW4gcHJvY2Vzcy5cbiAqIEFsbCBjYWxscyBzaGFyaW5nIHRoZSBzYW1lIGBDb250ZXh0SWRgIHNoYXJlIHRoZSBzYW1lIGNvbnRleHQgb2JqZWN0LFxuICogYWxsb3dpbmcgbm9uLXNlcmlhbGl6YWJsZSB2YWx1ZXMgKGUuZy4gYFRGaWxlYCwgYEVkaXRvcmApIHRvIHN1cnZpdmUgYWNyb3NzIGNhbGxzLlxuICpcbiAqIEltcGxlbWVudHMgYEFzeW5jRGlzcG9zYWJsZWAgZm9yIHVzZSB3aXRoIGBhd2FpdCB1c2luZ2AuXG4gKi9cbmV4cG9ydCBjbGFzcyBDb250ZXh0SWQ8X0NvbnRleHQ+IGltcGxlbWVudHMgQXN5bmNEaXNwb3NhYmxlIHtcbiAgcHJpdmF0ZSByZWFkb25seSBpZDogc3RyaW5nO1xuXG4gIC8qKlxuICAgKiBDcmVhdGVzIGEgbmV3IGNvbnRleHQgaWQuXG4gICAqL1xuICBwdWJsaWMgY29uc3RydWN0b3IoKSB7XG4gICAgY29uc3QgU0xJQ0VfU1RBUlQgPSAyO1xuICAgIHRoaXMuaWQgPSBgX19jdHhfJHtTdHJpbmcoTWF0aC5yYW5kb20oKSkuc2xpY2UoU0xJQ0VfU1RBUlQpfWA7XG4gIH1cblxuICAvKipcbiAgICogUmVtb3ZlcyB0aGlzIGNvbnRleHQgZnJvbSB0aGUgT2JzaWRpYW4gcHJvY2Vzcy5cbiAgICpcbiAgICogQHBhcmFtIHZhdWx0UGF0aCAtIFRoZSBwYXRoIHRvIHRoZSBPYnNpZGlhbiB2YXVsdC4gRGVmYXVsdHMgdG8gYHByb2Nlc3MuY3dkKClgLlxuICAgKi9cbiAgcHVibGljIGFzeW5jIGRpc3Bvc2UodmF1bHRQYXRoPzogc3RyaW5nKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgYXdhaXQgZXZhbEluT2JzaWRpYW4oe1xuICAgICAgYXJnczogeyBpZDogdGhpcy5pZCB9LFxuICAgICAgLyogdjggaWdub3JlIHN0YXJ0IC0tIFNlcmlhbGl6ZWQgdmlhIHRvU3RyaW5nKCkgYW5kIGV4ZWN1dGVkIGluc2lkZSB0aGUgT2JzaWRpYW4gcHJvY2Vzcy4gQ292ZXJlZCBieSBpbnRlZ3JhdGlvbiB0ZXN0cy4gKi9cbiAgICAgIGZuKHsgaWQgfSk6IHZvaWQge1xuICAgICAgICBpbnRlcmZhY2UgQ29udGV4dEhvbGRlciB7XG4gICAgICAgICAgX19vYnNpZGlhbkNvbnRleHRzX186IFJlY29yZDxzdHJpbmcsIHVua25vd24+O1xuICAgICAgICB9XG4gICAgICAgIGNvbnN0IGhvbGRlciA9IHdpbmRvdyBhcyBQYXJ0aWFsPENvbnRleHRIb2xkZXI+O1xuICAgICAgICBpZiAoaG9sZGVyLl9fb2JzaWRpYW5Db250ZXh0c19fKSB7XG4gICAgICAgICAgLy8gZXNsaW50LWRpc2FibGUtbmV4dC1saW5lIEB0eXBlc2NyaXB0LWVzbGludC9uby1keW5hbWljLWRlbGV0ZSAtLSBObyBvdGhlciB3YXkuXG4gICAgICAgICAgZGVsZXRlIGhvbGRlci5fX29ic2lkaWFuQ29udGV4dHNfX1tpZF07XG4gICAgICAgIH1cbiAgICAgIH0sXG4gICAgICAvKiB2OCBpZ25vcmUgc3RvcCAqL1xuICAgICAgc2hvdWxkU2tpcFByZWZsaWdodENoZWNrczogdHJ1ZSxcbiAgICAgIC4uLih2YXVsdFBhdGggPT09IHVuZGVmaW5lZCA/IHt9IDogeyB2YXVsdFBhdGggfSlcbiAgICB9KTtcbiAgfVxuXG4gIC8qKlxuICAgKiBEaXNwb3NlcyB0aGlzIGNvbnRleHQgaWQuXG4gICAqXG4gICAqIEByZXR1cm5zIEEgcHJvbWlzZSB0aGF0IHJlc29sdmVzIHdoZW4gdGhlIGNvbnRleHQgaWQgaXMgZGlzcG9zZWQuXG4gICAqL1xuICBwdWJsaWMgYXN5bmMgW1N5bWJvbC5hc3luY0Rpc3Bvc2VdKCk6IFByb21pc2U8dm9pZD4ge1xuICAgIGF3YWl0IHRoaXMuZGlzcG9zZSgpO1xuICB9XG5cbiAgLyoqXG4gICAqIFJldHVybnMgdGhlIEpTT04gcmVwcmVzZW50YXRpb24gb2YgdGhlIGNvbnRleHQgaWQuXG4gICAqXG4gICAqIEByZXR1cm5zIFRoZSBKU09OIHJlcHJlc2VudGF0aW9uIG9mIHRoZSBjb250ZXh0IGlkLlxuICAgKi9cbiAgcHVibGljIHRvSlNPTigpOiBzdHJpbmcge1xuICAgIHJldHVybiB0aGlzLmlkO1xuICB9XG5cbiAgLyoqXG4gICAqIFJldHVybnMgdGhlIHN0cmluZyByZXByZXNlbnRhdGlvbiBvZiB0aGUgY29udGV4dCBpZC5cbiAgICpcbiAgICogQHJldHVybnMgVGhlIHN0cmluZyByZXByZXNlbnRhdGlvbiBvZiB0aGUgY29udGV4dCBpZC5cbiAgICovXG4gIHB1YmxpYyB0b1N0cmluZygpOiBzdHJpbmcge1xuICAgIHJldHVybiB0aGlzLmlkO1xuICB9XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBT0EsMEJBQStCO0FBd0J4QixNQUFNLFVBQStDO0FBQUEsRUFDekM7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQUtWLGNBQWM7QUFDbkIsVUFBTSxjQUFjO0FBQ3BCLFNBQUssS0FBSyxTQUFTLE9BQU8sS0FBSyxPQUFPLENBQUMsRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUFBLEVBQzdEO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBT0EsTUFBYSxRQUFRLFdBQW1DO0FBQ3RELGNBQU0sb0NBQWU7QUFBQSxNQUNuQixNQUFNLEVBQUUsSUFBSSxLQUFLLEdBQUc7QUFBQTtBQUFBLE1BRXBCLEdBQUcsRUFBRSxHQUFHLEdBQVM7QUFJZixjQUFNLFNBQVM7QUFDZixZQUFJLE9BQU8sc0JBQXNCO0FBRS9CLGlCQUFPLE9BQU8scUJBQXFCLEVBQUU7QUFBQSxRQUN2QztBQUFBLE1BQ0Y7QUFBQTtBQUFBLE1BRUEsMkJBQTJCO0FBQUEsTUFDM0IsR0FBSSxjQUFjLFNBQVksQ0FBQyxJQUFJLEVBQUUsVUFBVTtBQUFBLElBQ2pELENBQUM7QUFBQSxFQUNIO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBT0EsT0FBYyxPQUFPLFlBQVksSUFBbUI7QUFDbEQsVUFBTSxLQUFLLFFBQVE7QUFBQSxFQUNyQjtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQU9PLFNBQWlCO0FBQ3RCLFdBQU8sS0FBSztBQUFBLEVBQ2Q7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUEsRUFPTyxXQUFtQjtBQUN4QixXQUFPLEtBQUs7QUFBQSxFQUNkO0FBQ0Y7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/cjs/context-id.d.cts

@@ -0,0 +1,57 @@
+/**
+ * @packageDocumentation
+ *
+ * Typed context identifiers for persisting non-serializable values
+ * across {@link evalInObsidian} calls.
+ */
+/**
+ * Wraps a {@link ContextOf} extraction into an object with a `context` property.
+ */
+export interface ContextArgs<TContextId extends ContextId<unknown> | undefined = undefined> {
+    context: ContextOf<TContextId>;
+}
+/**
+ * Extracts the context type from a {@link ContextId}.
+ */
+export type ContextOf<T> = T extends ContextId<infer Context> ? Context : never;
+/**
+ * A typed context identifier for persisting non-serializable values
+ * across {@link evalInObsidian} calls.
+ *
+ * The context is a persistent object stored on `window` in the Obsidian process.
+ * All calls sharing the same `ContextId` share the same context object,
+ * allowing non-serializable values (e.g. `TFile`, `Editor`) to survive across calls.
+ *
+ * Implements `AsyncDisposable` for use with `await using`.
+ */
+export declare class ContextId<_Context> implements AsyncDisposable {
+    private readonly id;
+    /**
+     * Creates a new context id.
+     */
+    constructor();
+    /**
+     * Removes this context from the Obsidian process.
+     *
+     * @param vaultPath - The path to the Obsidian vault. Defaults to `process.cwd()`.
+     */
+    dispose(vaultPath?: string): Promise<void>;
+    /**
+     * Disposes this context id.
+     *
+     * @returns A promise that resolves when the context id is disposed.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Returns the JSON representation of the context id.
+     *
+     * @returns The JSON representation of the context id.
+     */
+    toJSON(): string;
+    /**
+     * Returns the string representation of the context id.
+     *
+     * @returns The string representation of the context id.
+     */
+    toString(): string;
+}