@mnaoumov/obsidian-lib 0.0.0 → 1.0.1

package/dist/lib/cjs/file-system.d.cts

@@ -0,0 +1,554 @@
+/// <reference path="./library.d.cts" />
+/**
+ * @file
+ *
+ * This module provides utility functions for working with {@link TAbstractFile}, {@link TFile}, and {@link TFolder} instances in Obsidian.
+ */
+import type { App } from 'obsidian' with { 'resolution-mode': 'import' };
+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"
+}
+/**
+ * How {@link getBasename} and {@link getExtension} should answer for a path that resolves to nothing in the vault.
+ *
+ * Nothing in the vault says whether an unresolved `alpha.bravo` names a dotted folder or a `.bravo` file, so the caller decides.
+ */
+export declare enum MissingPathTreatment {
+    /**
+     * Read the path as a file path: `alpha.bravo` is basename `alpha` plus extension `bravo`.
+     */
+    File = "file",
+    /**
+     * Read the path as a folder path: `alpha.bravo` is basename `alpha.bravo` with no extension.
+     */
+    Folder = "folder",
+    /**
+     * Throw instead of guessing. This is the default.
+     */
+    Throw = "throw"
+}
+/**
+ * Parameters for {@link doesExist}.
+ */
+export interface DoesExistParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path to check.
+     */
+    readonly path: string;
+    /**
+     * The type of the file system object to check. Default is `undefined`.
+     */
+    readonly type?: FileSystemType;
+}
+/**
+ * Parameters for {@link getAbstractFileOrNull}.
+ */
+export interface GetAbstractFileOrNullParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path or abstract file to retrieve.
+     */
+    readonly pathOrFile: null | PathOrAbstractFile;
+}
+/**
+ * Parameters for {@link getAbstractFile}.
+ */
+export interface GetAbstractFileParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path or abstract file to retrieve the abstract file for.
+     */
+    readonly pathOrFile: PathOrAbstractFile;
+}
+/**
+ * Parameters for {@link getBasename}.
+ */
+export interface GetBasenameParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * The path or abstract file to get the base name of.
+     */
+    readonly pathOrFile: PathOrAbstractFile;
+    /**
+     * How to answer when the path resolves to nothing in the vault.
+     *
+     * @default `MissingPathTreatment.Throw`
+     */
+    readonly whenMissingTreatAs?: MissingPathTreatment;
+}
+/**
+ * Parameters for {@link getExtension}.
+ */
+export interface GetExtensionParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * The path or abstract file to get the extension of.
+     */
+    readonly pathOrFile: PathOrAbstractFile;
+    /**
+     * How to answer when the path resolves to nothing in the vault.
+     *
+     * @default `MissingPathTreatment.Throw`
+     */
+    readonly whenMissingTreatAs?: MissingPathTreatment;
+}
+/**
+ * Parameters for {@link getFileOrNull}.
+ */
+export interface GetFileOrNullParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path or file.
+     */
+    readonly pathOrFile: null | PathOrFile;
+}
+/**
+ * Parameters for {@link getFile}.
+ */
+export interface GetFileParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path or file to retrieve the file for.
+     */
+    readonly pathOrFile: PathOrFile;
+    /**
+     * 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.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeNonExisting?: boolean;
+}
+/**
+ * Parameters for {@link getFolderOrNull}.
+ */
+export interface GetFolderOrNullParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path or folder to retrieve the folder from.
+     */
+    readonly pathOrFolder: null | PathOrFolder;
+}
+/**
+ * Parameters for {@link getFolder}.
+ */
+export interface GetFolderParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to perform a case-insensitive search. When `undefined` or not specified, the behavior is determined by the actual file system.
+     *
+     * @default `undefined`
+     */
+    readonly isCaseInsensitive?: boolean;
+    /**
+     * The path or folder identifier.
+     */
+    readonly pathOrFolder: PathOrFolder;
+    /**
+     * 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.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeNonExisting?: boolean;
+}
+/**
+ * Parameters for {@link getMarkdownFiles}.
+ */
+export interface GetMarkdownFilesParams {
+    /**
+     * The Obsidian App instance.
+     */
+    readonly app: App;
+    /**
+     * Specifies whether to recursively search for markdown files within subfolders. Default is `false`.
+     *
+     * @default `false`
+     */
+    readonly isRecursive?: boolean;
+    /**
+     * The path or folder to retrieve the markdown files from.
+     */
+    readonly pathOrFolder: PathOrFolder;
+}
+/**
+ * Parameters for {@link isTreatedAsAttachment}.
+ */
+export interface IsTreatedAsAttachmentParams {
+    /**
+     * The Obsidian app instance, which lets a `property:` entry of {@link attachmentExtensions} read the file's frontmatter from the metadata cache.
+     * Without it, `property:` entries match nothing and only the extension entries are evaluated.
+     */
+    readonly app?: App;
+    /**
+     * The entries that mark a file as an attachment, e.g. `['.excalidraw.md', 'property:excalidraw-plugin']`.
+     *
+     * An extension entry is normalized before matching: surrounding whitespace is trimmed, a single leading dot is enforced, and the comparison is
+     * case-insensitive. Empty entries are ignored.
+     *
+     * A `property:name` entry matches a markdown file whose frontmatter has `name`, and `property:name=value` one whose `name` renders as `value` — the
+     * same syntax note priorities use. It is evaluated only when {@link app} is given.
+     */
+    readonly attachmentExtensions: readonly string[];
+    /**
+     * The path or file to classify.
+     */
+    readonly pathOrFile: null | PathOrAbstractFile;
+}
+/**
+ * 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 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(pathOrFile: null | PathOrAbstractFile, extension: string): boolean;
+/**
+ * Checks if the given path exists.
+ *
+ * @param params - The parameters for the check.
+ * @returns `true` if the path exists, `false` otherwise.
+ */
+export declare function doesExist(params: DoesExistParams): boolean;
+/**
+ * Retrieves the TAbstractFile object for the given path or abstract file.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns The abstract file.
+ * @throws Error if the abstract file is not found.
+ */
+export declare function getAbstractFile(params: GetAbstractFileParams): TAbstractFile;
+/**
+ * Retrieves an abstract file or `null` based on the provided path or abstract file.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns The abstract file if found, otherwise `null`.
+ */
+export declare function getAbstractFileOrNull(params: GetAbstractFileOrNullParams): null | TAbstractFile;
+/**
+ * Returns the base name of the given `pathOrFile`: a file's name without its extension, a folder's full name.
+ *
+ * Unlike `basename` from `path.ts`, which is a pure string function, this resolves the argument against the vault first. That is what lets a folder whose name
+ * contains a dot answer with its whole name instead of a bogus extension split, and it is why a caller handling both kinds no longer has to branch on
+ * {@link isFile} itself — a folder has no `basename` of its own.
+ *
+ * A path that resolves to nothing has no answer to look up, so {@link GetBasenameParams.whenMissingTreatAs} decides what happens. It defaults to
+ * {@link MissingPathTreatment.Throw} rather than to a guess: `alpha.bravo` may name a dotted folder or a `.bravo` file, and nothing in the vault says
+ * which, so a silently wrong answer is worse than an error. Pass {@link MissingPathTreatment.File} for the `checkExtension` reading of a bare string, or
+ * {@link MissingPathTreatment.Folder} for the other one.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns The base name of the `pathOrFile`.
+ * @throws Error if the path resolves to nothing and `whenMissingTreatAs` is {@link MissingPathTreatment.Throw} (the default).
+ */
+export declare function getBasename(params: GetBasenameParams): string;
+/**
+ * Returns the extension of the given `pathOrFile`: a file's extension without the leading dot, and an empty string for a folder.
+ *
+ * Unlike `extname` from `path.ts`, which is a pure string function, this resolves the argument against the vault first, so a folder whose name contains a dot
+ * answers with an empty string rather than a bogus extension. A folder has no `extension` of its own, which is why a caller handling both kinds would
+ * otherwise branch on {@link isFile} itself.
+ *
+ * A path that resolves to nothing has no answer to look up, so {@link GetExtensionParams.whenMissingTreatAs} decides what happens. It defaults to
+ * {@link MissingPathTreatment.Throw} rather than to a guess: `alpha.bravo` may name a dotted folder or a `.bravo` file, and nothing in the vault says
+ * which, so a silently wrong answer is worse than an error. Pass {@link MissingPathTreatment.File} for the `checkExtension` reading of a bare string, or
+ * {@link MissingPathTreatment.Folder} for the other one.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns The extension of the `pathOrFile`, or an empty string if it has none.
+ * @throws Error if the path resolves to nothing and `whenMissingTreatAs` is {@link MissingPathTreatment.Throw} (the default).
+ */
+export declare function getExtension(params: GetExtensionParams): string;
+/**
+ * Retrieves a file based on the provided path or file.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns The file corresponding to the provided path or file.
+ * @throws Error if the file is not found.
+ */
+export declare function getFile(params: GetFileParams): 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 params - The parameters for the retrieval.
+ * @returns The file if found, otherwise `null`.
+ */
+export declare function getFileOrNull(params: GetFileOrNullParams): 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 params - The parameters for the retrieval.
+ * @returns The retrieved folder.
+ * @throws If the folder is not found.
+ */
+export declare function getFolder(params: GetFolderParams): TFolder;
+/**
+ * Retrieves a folder or `null` based on the provided path or folder.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns The folder if found, otherwise `null`.
+ */
+export declare function getFolderOrNull(params: GetFolderOrNullParams): null | TFolder;
+/**
+ * Retrieves an array of files representing the markdown files within a specified folder or path.
+ *
+ * @param params - The parameters for the retrieval.
+ * @returns An array of files representing the markdown files.
+ */
+export declare function getMarkdownFiles(params: GetMarkdownFilesParams): 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 pathOrFile - The path or file to check.
+ * @returns A boolean indicating whether the file is a base file.
+ */
+export declare function isBaseFile(pathOrFile: null | PathOrAbstractFile): boolean;
+/**
+ * Checks if the given file is a canvas file.
+ *
+ * @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(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 pathOrFile - The path or file to check.
+ * @returns A boolean indicating whether the file is a Markdown file.
+ */
+export declare function isMarkdownFile(pathOrFile: null | PathOrAbstractFile): boolean;
+/**
+ * Checks if the given file is a note.
+ *
+ * @param pathOrFile - The path or file to check.
+ * @returns A boolean indicating whether the file is a note.
+ */
+export declare function isNote(pathOrFile: null | PathOrAbstractFile): boolean;
+/**
+ * Checks if the given file should be treated as an attachment because of its extension.
+ *
+ * Some plugins store their data in files that are markdown on disk but are not prose — Excalidraw, for example, saves each drawing as `sketch.excalidraw.md`.
+ * Obsidian reports such a file's extension as `md`, so a caller that wants to tell a drawing apart from a note has to match the full multi-part extension
+ * (`.excalidraw.md`) against the file name. Which extensions count is the caller's configuration, not this library's — only the matching rule is shared.
+ *
+ * A drawing can also be recognized by its frontmatter, the way Excalidraw itself recognizes one (`excalidraw-plugin: parsed`), through a
+ * `property:name[=value]` entry. That answer comes from the metadata cache, which can be cold at startup or right after the file is created, so an
+ * uncached file answers "no match" and is treated as a note. That is the conservative side for every current caller: a note is not moved as an
+ * attachment, and it spares its folder from a delete sweep.
+ *
+ * @param params - The path or file to classify and the configured attachment extensions.
+ * @returns A boolean indicating whether the file should be treated as an attachment.
+ */
+export declare function isTreatedAsAttachment(params: IsTreatedAsAttachmentParams): 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 file - The file to trim the markdown extension from.
+ * @returns The file path with the markdown extension trimmed.
+ */
+export declare function trimMarkdownExtension(file: TAbstractFile): string;