obsidian-dev-utils/dist/lib/esm/obsidian/FileSystem.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 TAbstractFile, TFile, and TFolder instances in Obsidian.
 */
import type { App } from 'obsidian';
import { TAbstractFile, TFile, TFolder } from 'obsidian';
/**
 * Represents the file extension for base files.
 */
export declare const BASE_FILE_EXTENSION = "base";
/**
 * Represents the file extension for canvas files.
 */
export declare const CANVAS_FILE_EXTENSION = "canvas";
/**
 * The file extension for Markdown files.
 */
export declare const MARKDOWN_FILE_EXTENSION = "md";
/**
 * Represents a path or an instance of TAbstractFile.
 */
export type PathOrAbstractFile = string | TAbstractFile;
/**
 * Represents a path or a file.
 */
export type PathOrFile = string | TFile;
/**
 * Represents a path or an instance of TFolder.
 */
export type PathOrFolder = string | TFolder;
/**
 * Checks if the given path or file has the specified extension.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or abstract file to check.
 * @param extension - The extension to compare against.
 * @returns Returns `true` if the path or file has the specified extension, `false` otherwise.
 */
export declare function checkExtension(app: App, pathOrFile: null | PathOrAbstractFile, extension: string): boolean;
/**
 * Retrieves the TAbstractFile object for the given path or abstract file.
 *
 * @param app - The App instance.
 * @param pathOrFile - The path or abstract file to retrieve the TAbstractFile for.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The TAbstractFile object.
 * @throws Error if the abstract file is not found.
 */
export declare function getAbstractFile(app: App, pathOrFile: PathOrAbstractFile, isCaseInsensitive?: boolean): TAbstractFile;
/**
 * Retrieves an instance of TAbstractFile or null based on the provided path or abstract file.
 *
 * @param app - The application instance.
 * @param pathOrFile - The path or abstract file to retrieve.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The instance of TAbstractFile if found, otherwise null.
 */
export declare function getAbstractFileOrNull(app: App, pathOrFile: null | PathOrAbstractFile, isCaseInsensitive?: boolean): null | TAbstractFile;
/**
 * Retrieves a TFile object based on the provided path or file.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file to retrieve the TFile object for.
 * @param shouldIncludeNonExisting - Whether to include a non-existing file.
 *  If `true`, a new TFile object is created for the provided path.
 *  If `false`, an error is thrown if the file is not found.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The TFile object corresponding to the provided path or file.
 * @throws Error if the file is not found.
 */
export declare function getFile(app: App, pathOrFile: PathOrFile, shouldIncludeNonExisting?: boolean, isCaseInsensitive?: boolean): TFile;
/**
 * Retrieves a TFile object based on the provided path or file.
 * If the provided argument is already a TFile object, it is returned as is.
 * Otherwise, the function uses the app's vault to retrieve the TFile object by its path.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or TFile object.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The TFile object if found, otherwise null.
 */
export declare function getFileOrNull(app: App, pathOrFile: null | PathOrFile, isCaseInsensitive?: boolean): null | TFile;
/**
 * Retrieves a TFolder object based on the provided app and pathOrFolder.
 *
 * @param app - The Obsidian app instance.
 * @param pathOrFolder - The path or folder identifier.
 * @param shouldIncludeNonExisting - Whether to allow the folder to not exist.
 *  If `true`, a new TFolder object is created for the provided path.
 *  If `false`, an error is thrown if the folder is not found.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The retrieved TFolder object.
 * @throws If the folder is not found.
 */
export declare function getFolder(app: App, pathOrFolder: PathOrFolder, shouldIncludeNonExisting?: boolean, isCaseInsensitive?: boolean): TFolder;
/**
 * Retrieves a TFolder object or null based on the provided path or folder.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFolder - The path or folder to retrieve the TFolder from.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The TFolder object if found, otherwise null.
 */
export declare function getFolderOrNull(app: App, pathOrFolder: null | PathOrFolder, isCaseInsensitive?: boolean): null | TFolder;
/**
 * Retrieves an array of TFile objects representing the markdown files within a specified folder or path.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFolder - The path or folder to retrieve the markdown files from.
 * @param isRecursive - Optional. Specifies whether to recursively search for markdown files within subfolders. Default is false.
 * @returns An array of TFile objects representing the markdown files.
 */
export declare function getMarkdownFiles(app: App, pathOrFolder: PathOrFolder, isRecursive?: boolean): TFile[];
/**
 * Retrieves the TFile object for the given path or creates a new one if it does not exist.
 *
 * @param app - The Obsidian App instance.
 * @param path - The path of the file to retrieve or create.
 * @returns The TFile object representing the file
 */
export declare function getOrCreateFile(app: App, path: string): Promise<TFile>;
/**
 * Retrieves the TFolder object for the given path or creates a new one if it does not exist.
 *
 * @param app - The Obsidian App instance.
 * @param path - The path of the folder to retrieve or create.
 * @returns The TFolder object representing the folder.
 */
export declare function getOrCreateFolder(app: App, path: string): Promise<TFolder>;
/**
 * Returns the path of the given `pathOrFile`.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or abstract file.
 * @returns The path of the `pathOrFile`.
 */
export declare function getPath(app: App, pathOrFile: PathOrAbstractFile): string;
/**
 * Checks if the given file is an instance of TAbstractFile.
 *
 * @param file - The file to check.
 * @returns A boolean indicating whether the file is an instance of TAbstractFile.
 */
export declare function isAbstractFile(file: unknown): file is TAbstractFile;
/**
 *   Checks if the given file is a base file.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file to check.
 * @returns A boolean indicating whether the file is a base file.
 */
export declare function isBaseFile(app: App, pathOrFile: null | PathOrAbstractFile): boolean;
/**
 * Checks if the given file is a canvas file.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file to check.
 * @returns A boolean indicating whether the file is a canvas file or not.
 */
export declare function isCanvasFile(app: App, pathOrFile: null | PathOrAbstractFile): boolean;
/**
 * Checks if the given file is an instance of TFile.
 *
 * @param file - The file to check.
 * @returns A boolean indicating whether the file is an instance of TFile.
 */
export declare function isFile(file: unknown): file is TFile;
/**
 * Checks if the given file is a folder.
 *
 * @param file - The file to check.
 * @returns `true` if the file is a folder, `false` otherwise.
 */
export declare function isFolder(file: unknown): file is TFolder;
/**
 * Checks if the given file is a Markdown file.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file to check.
 * @returns A boolean indicating whether the file is a Markdown file.
 */
export declare function isMarkdownFile(app: App, pathOrFile: null | PathOrAbstractFile): boolean;
/**
 * Checks if the given file is a note.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file to check.
 * @returns A boolean indicating whether the file is a note.
 */
export declare function isNote(app: App, pathOrFile: null | PathOrAbstractFile): boolean;
/**
 * Trims the markdown extension from the file path if the file is a markdown file.
 * If the file is not a markdown file, the original file path is returned.
 *
 * @param app - The Obsidian App instance.
 * @param file - The file to trim the markdown extension from.
 * @returns The file path with the markdown extension trimmed.
 */
export declare function trimMarkdownExtension(app: App, file: TAbstractFile): string;