obsidian-dev-utils/dist/lib/esm/obsidian/Vault.d.mts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * This module provides utility functions for working with the Obsidian Vault.
 */
import type { App, ListedFiles } from 'obsidian';
import { TAbstractFile, TFile, TFolder } from 'obsidian';
import type { RetryOptions } from '../Async.mjs';
import type { ValueProvider } from '../ValueProvider.mjs';
import type { PathOrAbstractFile, PathOrFile, PathOrFolder } from './FileSystem.mjs';
import { FileSystemType } from './FileSystem.mjs';
/**
 * Options for {@link process}.
 */
export interface ProcessOptions extends RetryOptions {
    /**
     * Whether to fail if the file is missing or deleted. Default is `true`.
     */
    shouldFailOnMissingFile?: boolean;
    /**
     * Whether to lock the editor while processing the file. Applicable only for markdown files. Default is `true`.
     */
    shouldLockEditorWhileProcessing?: boolean;
    /**
     * Whether to show a timeout notice. Default is `true`.
     */
    shouldShowTimeoutNotice?: boolean;
}
/**
 * Copies a file safely in the vault.
 *
 * @param app - The application instance.
 * @param oldPathOrFile - The old path or file to copy.
 * @param newPath - The new path to copy the file to.
 * @returns A {@link Promise} that resolves to the new path of the copied file.
 */
export declare function copySafe(app: App, oldPathOrFile: PathOrFile, newPath: string): Promise<string>;
/**
 * Creates a folder safely in the specified path.
 *
 * @param app - The application instance.
 * @param path - The path of the folder to create.
 * @returns A {@link Promise} that resolves to a boolean indicating whether the folder was created.
 * @throws If an error occurs while creating the folder and it still doesn't exist.
 */
export declare function createFolderSafe(app: App, path: string): Promise<boolean>;
/**
 * Creates a temporary file in the vault with parent folders if needed.
 *
 * @param app - The application instance.
 * @param path - The path of the file to create.
 * @returns A {@link Promise} that resolves to a function that can be called to delete the temporary file and all its created parents.
 */
export declare function createTempFile(app: App, path: string): Promise<() => Promise<void>>;
/**
 * Creates a temporary folder in the vault with parent folders if needed.
 *
 * @param app - The application instance.
 * @param path - The path of the folder to create.
 * @returns A {@link Promise} that resolves to a function that can be called to delete the temporary folder and all its created parents.
 */
export declare function createTempFolder(app: App, path: string): Promise<() => Promise<void>>;
/**
 * Gets a safe path for a file or folder.
 *
 * @param app - The application instance.
 * @param path - The path of the file or folder to get a safe path for.
 * @param type - The type of the file system object.
 * @returns The safe path for the file or folder.
 */
export declare function getAbstractFilePathSafe(app: App, path: string, type: FileSystemType): string;
/**
 * Gets an available path for a file in the vault.
 *
 * @param app - The application instance.
 * @param path - The path of the file to get an available path for.
 * @returns The available path for the file.
 */
export declare function getAvailablePath(app: App, path: string): string;
/**
 * Gets a safe file path for a file or folder.
 *
 * @param app - The application instance.
 * @param path - The path of the file or folder to get a safe path for.
 * @returns The safe path for the file or folder.
 */
export declare function getFilePathSafe(app: App, path: string): string;
/**
 * Gets a safe folder path for a file or folder.
 *
 * @param app - The application instance.
 * @param path - The path of the file or folder to get a safe path for.
 * @returns The safe path for the file or folder.
 */
export declare function getFolderPathSafe(app: App, path: string): string;
/**
 * Retrieves an array of Markdown files from the app's vault and sorts them alphabetically by their file path.
 *
 * @param app - The Obsidian app instance.
 * @returns An array of Markdown files sorted by file path.
 */
export declare function getMarkdownFilesSorted(app: App): TFile[];
/**
 * Retrieves an array of all note files from the app's vault and sorts them alphabetically by their file path.
 *
 * @param app - The Obsidian app instance.
 * @returns An array of all note files in the vault sorted by file path.
 */
export declare function getNoteFilesSorted(app: App): TFile[];
/**
 * Gets or creates an abstract file safely in the specified path.
 *
 * If the file already exists, it will be returned.
 * If the file does not exist, it will be created and returned.
 *
 * @param app - The application instance.
 * @param path - The path of the abstract file to get or create.
 * @param type - The type of the abstract file to get or create.
 * @returns A {@link Promise} that resolves to the abstract file.
 */
export declare function getOrCreateAbstractFileSafe(app: App, path: string, type: FileSystemType): Promise<TAbstractFile>;
/**
 * Gets or creates a file safely in the specified path.
 *
 * If the file already exists, it will be returned.
 * If the file does not exist, it will be created and returned.
 *
 * @param app - The application instance.
 * @param path - The path of the file to get or create.
 * @returns A {@link Promise} that resolves to the file.
 */
export declare function getOrCreateFileSafe(app: App, path: string): Promise<TFile>;
/**
 * Gets or creates a folder safely in the specified path.
 *
 * If the folder already exists, it will be returned.
 * If the folder does not exist, it will be created and returned.
 *
 * @param app - The application instance.
 * @param path - The path of the folder to get or create.
 * @returns A {@link Promise} that resolves to the folder.
 */
export declare function getOrCreateFolderSafe(app: App, path: string): Promise<TFolder>;
/**
 * Gets a safe rename path for a file.
 *
 * @param app - The application instance.
 * @param oldPathOrAbstractFile - The old path or abstract file to rename.
 * @param newPath - The new path to rename the abstract file to.
 * @returns The safe rename path for the abstract file.
 */
export declare function getSafeRenamePath(app: App, oldPathOrAbstractFile: PathOrAbstractFile, newPath: string): string;
/**
 * Invokes a function with the file system lock.
 *
 * @param app - The application instance.
 * @param pathOrFile - The path or file to execute the function with the file system lock of.
 * @param fn - The function to execute.
 */
export declare function invokeWithFileSystemLock(app: App, pathOrFile: PathOrFile, fn: (content: string) => void): Promise<void>;
/**
 * Checks if a path or file is a child of another path or file.
 *
 * @param app - The application instance.
 * @param a - The first path or file.
 * @param b - The second path or file.
 * @returns A boolean indicating whether the first path or file is a child of the second path or file.
 */
export declare function isChild(app: App, a: PathOrAbstractFile, b: PathOrAbstractFile): boolean;
/**
 * Checks if a path or file is a child or self of another path or file.
 *
 * @param app - The application instance.
 * @param a - The first path or file.
 * @param b - The second path or file.
 * @returns A boolean indicating whether the first path or file is a child or self of the second path or file.
 */
export declare function isChildOrSelf(app: App, a: PathOrAbstractFile, b: PathOrAbstractFile): boolean;
/**
 * Checks if a folder is empty.
 *
 * @param app - The application instance.
 * @param pathOrFolder - The path or folder to check.
 * @returns A {@link Promise} that resolves to a boolean indicating whether the folder is empty.
 */
export declare function isEmptyFolder(app: App, pathOrFolder: PathOrFolder): Promise<boolean>;
/**
 * Safely lists the files and folders at the specified path in the vault.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFolder - The path or folder to list.
 * @returns A {@link Promise} that resolves to a {@link ListedFiles} object containing the listed files and folders.
 */
export declare function listSafe(app: App, pathOrFolder: PathOrFolder): Promise<ListedFiles>;
/**
 * Processes a file with retry logic, updating its content based on a provided value or function.
 *
 * @param app - The application instance, typically used for accessing the vault.
 * @param pathOrFile - The path or file to be processed. It can be a string representing the path or a file object.
 * @param newContentProvider - A value provider that returns the new content based on the old content of the file.
 * It can be a string or a function that takes the old content as an argument and returns the new content.
 * If function is provided, it should return `null` if the process should be retried.
 * @param options - Optional options for processing/retrying the operation.
 *
 * @returns A {@link Promise} that resolves once the process is complete.
 *
 * @throws Will throw an error if the process fails after the specified number of retries or timeout.
 */
export declare function process(app: App, pathOrFile: PathOrFile, newContentProvider: ValueProvider<null | string, [string]>, options?: ProcessOptions): Promise<void>;
/**
 * Reads the content of a file safely from the vault.
 *
 * It covers the case when the file was removed during the reading.
 *
 * @param app - The application instance.
 * @param pathOrFile - The path or file to read.
 * @returns A {@link Promise} that resolves to the content of the file or `null` if the file is missing or deleted.
 */
export declare function readSafe(app: App, pathOrFile: PathOrFile): Promise<null | string>;
/**
 * Renames a file safely in the vault.
 * If the new path already exists, the file will be renamed to an available path.
 *
 * @param app - The application instance.
 * @param oldPathOrAbstractFile - The old path or file to rename.
 * @param newPath - The new path to rename the file to.
 * @returns A {@link Promise} that resolves to the new path of the file.
 */
export declare function renameSafe(app: App, oldPathOrAbstractFile: PathOrAbstractFile, newPath: string): Promise<string>;
/**
 * Saves the specified note in the Obsidian app.
 *
 * @param app - The Obsidian app instance.
 * @param pathOrFile - The note to be saved.
 * @returns A {@link Promise} that resolves when the note is saved.
 */
export declare function saveNote(app: App, pathOrFile: PathOrFile): Promise<void>;