obsidian-dev-utils/dist/lib/cjs/obsidian/FileSystem.d.cts

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 {@link TAbstractFile}, {@link TFile}, and {@link TFolder} instances in Obsidian.
 */
import type { App } from 'obsidian';
import { TAbstractFile, TFile, TFolder } from 'obsidian';
/**
 * A file extension for `base` files.
 */
export declare const BASE_FILE_EXTENSION = "base";
/**
 * A file extension for `canvas` files.
 */
export declare const CANVAS_FILE_EXTENSION = "canvas";
/**
 * A file extension for `markdown` files.
 */
export declare const MARKDOWN_FILE_EXTENSION = "md";
/**
 * A type of file system object.
 */
export declare enum FileSystemType {
    /**
     * A file.
     */
    File = "file",
    /**
     * A folder.
     */
    Folder = "folder"
}
/**
 * A path or an abstract file.
 */
export type PathOrAbstractFile = string | TAbstractFile;
/**
 * A path or a file.
 */
export type PathOrFile = string | TFile;
/**
 * A path or a folder.
 */
export type PathOrFolder = string | TFolder;
/**
 * Converts an array of abstract files to an array of files.
 *
 * @param abstractFiles - The abstract files to convert.
 * @returns The array of files.
 * @throws Error if any of the abstract files are not files.
 */
export declare function asArrayOfFiles(abstractFiles: TAbstractFile[]): TFile[];
/**
 * Converts an array of abstract files to an array of folders.
 *
 * @param abstractFiles - The abstract files to convert.
 * @returns The array of folders.
 * @throws Error if any of the abstract files are not folders.
 */
export declare function asArrayOfFolders(abstractFiles: TAbstractFile[]): TFolder[];
/**
 * Converts an abstract file to a file.
 *
 * @param abstractFile - The abstract file to convert.
 * @returns The file.
 * @throws Error if the abstract file is not a file.
 */
export declare function asFile(abstractFile: null | TAbstractFile): TFile;
/**
 * Converts an abstract file to a file or `null`.
 *
 * @param abstractFile - The abstract file to convert.
 * @returns The file or `null`.
 * @throws Error if the abstract file is not a file.
 */
export declare function asFileOrNull(abstractFile: null | TAbstractFile): null | TFile;
/**
 * Converts an abstract file to a folder.
 *
 * @param abstractFile - The abstract file to convert.
 * @returns The folder.
 * @throws Error if the abstract file is not a folder.
 */
export declare function asFolder(abstractFile: null | TAbstractFile): TFolder;
/**
 * Converts an abstract file to a folder or `null`.
 *
 * @param abstractFile - The abstract file to convert.
 * @returns The folder or `null`.
 * @throws Error if the abstract file is not a folder.
 */
export declare function asFolderOrNull(abstractFile: null | TAbstractFile): null | 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 abstract file for.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The abstract file.
 * @throws Error if the abstract file is not found.
 */
export declare function getAbstractFile(app: App, pathOrFile: PathOrAbstractFile, isCaseInsensitive?: boolean): TAbstractFile;
/**
 * Retrieves an abstract file 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 abstract file if found, otherwise `null`.
 */
export declare function getAbstractFileOrNull(app: App, pathOrFile: null | PathOrAbstractFile, isCaseInsensitive?: boolean): null | TAbstractFile;
/**
 * Retrieves a file based on the provided path or file.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file to retrieve the file for.
 * @param shouldIncludeNonExisting - Whether to include a non-existing file.
 *  If `true`, a new file 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 file 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 file or `null` based on the provided path or file.
 * If the provided argument is already a file, it is returned as is.
 * Otherwise, the function uses the app's vault to retrieve the file by its path.
 *
 * @param app - The Obsidian App instance.
 * @param pathOrFile - The path or file.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The file if found, otherwise `null`.
 */
export declare function getFileOrNull(app: App, pathOrFile: null | PathOrFile, isCaseInsensitive?: boolean): null | TFile;
/**
 * Gets the type of a file system object.
 *
 * @param abstractFile - The abstract file to get the type of.
 * @returns The type of the abstract file.
 * @throws Error if the abstract file is not a file or a folder.
 */
export declare function getFileSystemType(abstractFile: TAbstractFile): FileSystemType;
/**
 * Retrieves a folder 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 folder 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 folder.
 * @throws If the folder is not found.
 */
export declare function getFolder(app: App, pathOrFolder: PathOrFolder, shouldIncludeNonExisting?: boolean, isCaseInsensitive?: boolean): TFolder;
/**
 * Retrieves a folder or `null` based on the provided path or folder.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFolder - The path or folder to retrieve the folder from.
 * @param isCaseInsensitive - Specifies whether to perform a case-insensitive search. Default is `false`.
 * @returns The folder if found, otherwise `null`.
 */
export declare function getFolderOrNull(app: App, pathOrFolder: null | PathOrFolder, isCaseInsensitive?: boolean): null | TFolder;
/**
 * Retrieves an array of files 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 files representing the markdown files.
 */
export declare function getMarkdownFiles(app: App, pathOrFolder: PathOrFolder, isRecursive?: boolean): TFile[];
/**
 * Retrieves the file 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 file representing the file
 */
export declare function getOrCreateFile(app: App, path: string): Promise<TFile>;
/**
 * Retrieves the folder 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 folder 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 abstract file.
 *
 * @param file - The file to check.
 * @returns A boolean indicating whether the file is an instance of abstract file.
 */
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 file.
 *
 * @param file - The file to check.
 * @returns A boolean indicating whether the file is an instance of file.
 */
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;