/** * @file * * Mock of Obsidian's `Vault`, which tracks the vault's file tree over a data adapter, usually the in-memory one. */ import type { DataAdapter as DataAdapterOriginal, DataWriteOptions as DataWriteOptionsOriginal, Vault as VaultOriginal } from 'obsidian'; import type { TAbstractFile } from './TAbstractFile.mjs'; import { Events } from './Events.mjs'; import { TFile } from './TFile.mjs'; import { TFolder } from './TFolder.mjs'; /** * Mock of Obsidian's `Vault`. * * File operations go through {@link Vault.adapter}; the vault keeps a path-keyed tree of `TFile` / `TFolder` * objects in {@link Vault.fileMap} in step with them and fires `create`, `modify`, `delete` and `rename` events. * Dot-prefixed paths such as the config folder are never tracked. The `__` helpers add synchronous access and * re-syncing, and work only over an {@link InMemoryAdapter}. */ export declare class Vault extends Events { /** * The data adapter every file operation reads from and writes to. */ adapter: DataAdapterOriginal; /** * Backs `getConfig` / `setConfig`. Only `attachmentFolderPath`, `focusNewTab` and `trashOption` carry modeled * defaults — every other key reads as `undefined` until a test sets it. */ config: Record; /** * The vault-relative path of the config folder, typically `.obsidian`. */ configDir: string; /** * Every tracked file and folder, keyed by exact path; the root is keyed as `/`. */ fileMap: Record; private fileMapLowerCase; /** * Creates a vault over an adapter, tracking only the root folder. * * @param adapter - The data adapter the vault reads from and writes to. */ protected constructor(adapter: DataAdapterOriginal); /** * Mock-only factory: creates a vault, spyable via `vi.spyOn(Vault, 'create2__')`. It is numbered because * `Events.create__` takes no adapter, so a `create__` here would conflict on the static side. * * @param adapter - The data adapter the vault reads from and writes to. * @returns The new vault. */ static create2__(adapter: DataAdapterOriginal): Vault; /** * Mock-only: views a value typed as Obsidian's `Vault` as this mock. * * @param value - The value typed as the original `Vault`. * @returns The same object, typed as the mock. */ static fromOriginalType2__(value: VaultOriginal): Vault; /** * Walks a folder and everything under it, exactly as Obsidian's own walk does: the folder ITSELF is visited first, * and the walk is a stack, so each folder's children are visited last-first. A folder's `children` are read only * after the callback has run on it, and the callback's return value is ignored - there is no early stop. * * @param folder - The folder to walk, visited first. * @param callback - Called with the folder and with each descendant file and folder. */ static recurseChildren(folder: TFolder, callback: (f: TAbstractFile) => unknown): void; /** * Visits a folder's descendants in pre-order, each child before its own children and siblings first-to-last, never * the folder itself. The order the mock's own folder copy, rename and removal have always used; the public walk is * {@link Vault.recurseChildren}, which is Obsidian's. * * @param folder - The folder whose descendants to visit. * @param callback - Called with each descendant file and folder. */ private static forEachDescendant; /** * Adds text to the end of a plaintext file, then refreshes its `stat` and fires `modify`. * * @param file - The file to append to. * @param data - The text to add. * @param options - Write options such as timestamps to set. */ append(file: TFile, data: string, options?: DataWriteOptionsOriginal): Promise; /** * Adds data to the end of a binary file, then refreshes its `stat` and fires `modify`. * * @param file - The file to append to. * @param data - The data to add. * @param options - Write options such as timestamps to set. */ appendBinary(file: TFile, data: ArrayBuffer, options?: DataWriteOptionsOriginal): Promise; /** * Mock-only: views this mock as Obsidian's `Vault` type. * * @returns The same object, typed as the original `Vault`. */ asOriginalType2__(): VaultOriginal; /** * Reads a plaintext file for display. Obsidian may serve it from a cache; the mock reads the adapter, exactly as * {@link Vault.read} does. * * @param file - The file to read. * @returns The file's text. */ cachedRead(file: TFile): Promise; /** * Mock-only construction hook, called at the end of the constructor; a no-op meant for * `vi.spyOn(Vault.prototype, 'constructor2__')`. * * @param _adapter - The adapter the vault was created with. */ constructor2__(_adapter: DataAdapterOriginal): void; /** * Copies a file, or a folder together with everything under it, tracks the copies, and fires `create` for each new * entry: the copy itself first, then its descendants depth-first. A folder copied onto an existing folder merges * into it, as in Obsidian. * * @typeParam T - The type of the file or folder being copied. * @param file - The file or folder to copy. * @param newPath - The vault-relative path for the copy. * @returns The copy, of the same type as `file`. * @throws Error from the adapter when a file would be copied onto an existing path. */ copy(file: T, newPath: string): Promise; /** * Creates a plaintext file, tracks it, and fires `create`. * * @param path - The vault-relative path for the new file, with extension. * @param data - The file's text. * @param options - Write options such as timestamps to set. * @returns The new file. * @throws Error `File already exists.` when the adapter reports anything at `path`, which on a case-insensitive * adapter includes a path differing only in case. */ create(path: string, data: string, options?: DataWriteOptionsOriginal): Promise; /** * Creates a binary file, tracks it, and fires `create`. * * @param path - The vault-relative path for the new file, with extension. * @param data - The file's content. * @param options - Write options such as timestamps to set. * @returns The new file. * @throws Error `File already exists.` when the adapter reports anything at `path`, which on a case-insensitive * adapter includes a path differing only in case. */ createBinary(path: string, data: ArrayBuffer, options?: DataWriteOptionsOriginal): Promise; /** * Creates a folder along with any missing ancestors, tracking each new one and firing `create` for it. * * @param path - The vault-relative path for the new folder. * @returns The new folder. * @throws Error `Folder already exists.` when the adapter reports anything at `path`, a file included. */ createFolder(path: string): Promise; /** * Mock-only: a synchronous {@link Vault.createFolder} for setting up a test vault. Unlike `createFolder`, it returns * the existing folder when `path` is already one. * * @param path - The vault-relative path for the new folder. * @returns The folder at `path`. * @throws TypeError when the adapter is not an {@link InMemoryAdapter}. */ createFolderSync__(path: string): TFolder; /** * Mock-only: a synchronous {@link Vault.create} for setting up a test vault; it also fires `create`. Unlike * `create`, it overwrites a file that already exists at `path`. * * @param path - The vault-relative path for the new file, with extension. * @param content - The file's text. * @returns The new file. * @throws TypeError when the adapter is not an {@link InMemoryAdapter}. */ createSync__(path: string, content: string): TFile; /** * Deletes a file or a folder and stops tracking it. For a folder, every descendant is untracked and marked `deleted` * too, each firing its own `delete` depth-first before the folder's. As in Obsidian, `force` goes straight to the * adapter as `rmdir`'s `recursive`, and deleting the root does nothing. * * @param file - The file or folder to delete. * @param force - Whether to remove a folder recursively. Without it the desktop `FileSystemAdapter` refuses any * folder, an empty one included, while the mobile `CapacitorAdapter` removes it anyway. * @throws Error from the adapter, in which case nothing is untracked. */ delete(file: TAbstractFile, force?: boolean): Promise; /** * Mock-only: stops tracking the entry at `path`, marks it `deleted` and detaches it from its parent, setting its * `parent` to `null` as Obsidian does before it fires `delete`, without touching the adapter or firing an event. * Does nothing when no entry is tracked there. A folder's descendants are left tracked; untrack each of them the * same way. * * @param path - The exact path of the entry. */ deleteVaultAbstractFile__(path: string): void; /** * Whether anything exists at `path`. * * @param path - The path to test. * @param isCaseSensitive - Force a case-sensitive check. Obsidian's own default is a * case-insensitive lookup, because most vaults sit on a case-insensitive file system. * @returns Whether a file or folder exists at that path. */ exists(path: string, isCaseSensitive?: boolean): Promise; /** * Gets the tracked file or folder at a path. * * @param path - The vault-relative path, with extension; matched case-sensitively. * @returns The file or folder, or `null` when none is tracked there. */ getAbstractFileByPath(path: string): null | TAbstractFile; /** * Gets the tracked file or folder at a path, ignoring case. * * @param path - The vault-relative path, with extension. * @returns The file or folder, or `null` when none is tracked there. */ getAbstractFileByPathInsensitive(path: string): null | TAbstractFile; /** * Gets every tracked folder. * * @param includeRoot - Whether to include the root folder; it is left out by default. * @returns The folders. */ getAllFolders(includeRoot?: boolean): TFolder[]; /** * Gets every tracked file and folder, the root included. * * @returns The files and folders. */ getAllLoadedFiles(): TAbstractFile[]; /** * Obsidian's de-duplicator: the plain name first, then ` 1`, ` 2`, … until one is free. * * @param basePath - The desired path without extension. * @param extension - The file extension without the leading dot. * @returns A path that no existing file occupies. */ getAvailablePath(basePath: string, extension: string): string; /** * Resolves where an attachment of `file` goes, per the `attachmentFolderPath` setting, creating the * target folder when it is missing. Confirmed against a real Obsidian 1.13.4: for a note * `Docs/api/get.md` the setting `/` yields `img.png`, `./` yields `Docs/api/img.png`, `./assets` * yields `Docs/api/assets/img.png` (creating `Docs/api/assets`), and `Files` yields `Files/img.png` * (creating `Files`). A `null` file resolves as a root-level note does. * * @param fileName - The attachment base name without extension. * @param extension - The attachment extension without the leading dot. * @param file - The note the attachment belongs to, or `null`. * @returns A {@link Promise} that resolves to the available attachment path. */ getAvailablePathForAttachments(fileName: string, extension: string, file: null | TFile): Promise; /** * Reads a vault setting. * * @param key - The setting key. * @returns The setting value, or `undefined` when the key was never set. */ getConfig(key: string): unknown; /** * Gets the tracked file at a path. * * @param path - The vault-relative path, with extension; matched case-sensitively. * @returns The file, or `null` when nothing, or a folder, is tracked there. */ getFileByPath(path: string): null | TFile; /** * Gets every tracked file. * * @returns The files, in tracking order. */ getFiles(): TFile[]; /** * Gets the tracked folder at a path. * * @param path - The vault-relative path; matched case-sensitively, with `/` for the root. * @returns The folder, or `null` when nothing, or a file, is tracked there. */ getFolderByPath(path: string): null | TFolder; /** * Gets every tracked Markdown file, meaning every file whose extension is exactly `md`. * * @returns The Markdown files. */ getMarkdownFiles(): TFile[]; /** * Gets the vault's name. * * @returns The name; always an empty string in the mock. */ getName(): string; /** * Gets a URI the browser engine can load a file from, for example to embed an image. * * @param _file - The file to get the URI for. * @returns The URI; always an empty string in the mock. */ getResourcePath(_file: TFile): string; /** * Gets the vault's root folder, creating and tracking a fresh one if the root entry is missing. * * @returns The root folder. */ getRoot(): TFolder; /** * Replaces a plaintext file's contents, then refreshes its `stat` and fires `modify`. * * @param file - The file to modify. * @param data - The new text. * @param options - Write options such as timestamps to set. */ modify(file: TFile, data: string, options?: DataWriteOptionsOriginal): Promise; /** * Replaces a binary file's contents, then refreshes its `stat` and fires `modify`. * * @param file - The file to modify. * @param data - The new content. * @param options - Write options such as timestamps to set. */ modifyBinary(file: TFile, data: ArrayBuffer, options?: DataWriteOptionsOriginal): Promise; /** * Reads a plaintext file, transforms its text with a synchronous function, writes the result back, then refreshes * its `stat` and fires `modify`. Obsidian does this atomically; the mock simply runs the steps in order. * * @param file - The file to process. * @param $function - Returns the new text for the current text. * @param options - Write options such as timestamps to set. * @returns The text that was written. */ process(file: TFile, $function: (data: string) => string, options?: DataWriteOptionsOriginal): Promise; /** * Reads a plaintext file from the adapter. * * @param file - The file to read. * @returns The file's text. */ read(file: TFile): Promise; /** * Reads a binary file from the adapter. * * @param file - The file to read. * @returns The file's content. */ readBinary(file: TFile): Promise; /** * Mock-only: a synchronous {@link Vault.read}. * * @param file - The file to read. * @returns The file's text. * @throws TypeError when the adapter is not an {@link InMemoryAdapter}. */ readSync__(file: TFile): string; /** * Mock-only: re-syncs the tracked tree with the adapter's contents after a test wrote to the adapter directly. * Missing folders and files are tracked (firing `create` for each new file), `stat` is refreshed for files already * tracked, and entries the adapter no longer has are dropped (firing `delete`). Dot-prefixed paths are skipped. * * @throws TypeError when the adapter is not an {@link InMemoryAdapter}. */ reconcile__(): void; /** * Copies the adapter's recorded `ctime` / `mtime` / `size` onto `file.stat`, mutating the existing * object in place so a reference a test captured stays valid. Real Obsidian has stat'ed the file by * the time it fires `create` / `modify`, so every write path calls this BEFORE triggering its event. * * Only the in-memory adapter records stat, so this is a silent no-op for any other adapter — * deliberately not the `TypeError` that `createSync__` / `readSync__` / `reconcile__` throw: unlike * those explicit helpers it runs as a side effect of an ordinary `create()` / `modify()`, so it must * not break a caller that supplied a partial adapter. * * @param file - The file whose `stat` to refresh. */ refreshStat__(file: TFile): void; /** * Renames or moves a file or folder. The mock updates the object in place (path, name, and for a file its * basename and extension), re-parents it, cascades the new path prefix to a folder's descendants, and fires * `rename` with the old path. Unlike `FileManager.renameFile`, it does not update links. Renaming onto the current * path does nothing and fires no event. * * @param file - The file or folder to rename. * @param newPath - The new vault-relative path. * @throws Error from the adapter when something already exists at `newPath`. */ rename(file: TAbstractFile, newPath: string): Promise; /** * Writes a vault setting. * * @param key - The setting key. * @param value - The setting value. */ setConfig(key: string, value: unknown): void; /** * Mock-only: tracks an entry at `path`, clears its `deleted` flag, and attaches it to the parent folder when that * folder is tracked, without touching the adapter or firing an event. * * @param path - The exact path to track the entry under. * @param file - The file or folder to track. */ setVaultAbstractFile__(path: string, file: TAbstractFile): void; /** * Moves a file or folder to the system or the local trash, routing through the adapter exactly as Obsidian does: * `system` tries `trashSystem` first and only falls back to `trashLocal` when it answers `false`, while * `system: false` goes straight to `trashLocal`. Either way the entry stops being tracked and, for a folder, so * does every descendant, each firing its own `delete` as {@link Vault.delete} does. As in Obsidian, trashing the * root does nothing. * * With an `InMemoryAdapter`, `trashLocal` moves the entry into the vault's `.trash` folder, so a trashed file is * still readable from the adapter, while `trashSystem` removes it outright. * * @param file - The file or folder to trash. * @param system - Whether to try the system trash first. * @throws Error from the adapter, in which case nothing is untracked. */ trash(file: TAbstractFile, system: boolean): Promise; private ensureNothingExists; private registerFolderTree; private removeTree; private trackCopiedFile; }