@mnaoumov/obsidian-lib 0.0.0 → 1.0.0

package/dist/lib/esm/vault.d.mts

@@ -0,0 +1,506 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * This module provides utility functions for working with the Obsidian Vault.
+ */
+import type { RetryOptions } from '@mnaoumov/typescript-lib/async';
+import type { ValueProvider } from '@mnaoumov/typescript-lib/value-provider';
+import type { App, ListedFiles } from 'obsidian';
+import { TAbstractFile, TFile, TFolder } from 'obsidian';
+import type { PluginNoticeComponent } from './components/plugin-notice-component.mjs';
+import type { PathOrAbstractFile, PathOrFile, PathOrFolder } from './file-system.mjs';
+import type { ResourceLockComponent } from './resource-lock.mjs';
+import { FileSystemType } from './file-system.mjs';
+/**
+ * The result of {@link createFolderSafe}.
+ */
+export declare enum CreateFolderSafeResult {
+    /**
+     * The folder was created.
+     */
+    Created = "created",
+    /**
+     * The folder was not created because it already exists.
+     */
+    NotCreated = "not-created"
+}
+/**
+ * A behavior for handling empty folders during cleanup.
+ */
+export declare enum EmptyFolderBehavior {
+    /**
+     * Delete the empty folder.
+     */
+    Delete = "Delete",
+    /**
+     * Delete the empty folder and all its empty parents.
+     */
+    DeleteWithEmptyParents = "DeleteWithEmptyParents",
+    /**
+     * Keep the empty folder.
+     */
+    Keep = "Keep"
+}
+/**
+ * The result of {@link invokeFileActionSafe}.
+ */
+export declare enum InvokeFileActionSafeResult {
+    Invoked = "invoked",
+    NotInvoked = "not-invoked"
+}
+/**
+ * Parameters for {@link cleanupEmptyFolders}.
+ */
+export interface CleanupEmptyFoldersParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The behavior determining how empty folders are cleaned up.
+     */
+    readonly emptyFolderBehavior: EmptyFolderBehavior;
+    /**
+     * The paths of the folders to clean up when empty.
+     */
+    readonly folderPaths: string[];
+}
+/**
+ * Arguments for {@link process}.
+ */
+export interface ContentArguments {
+    /**
+     * The current content of the file.
+     */
+    readonly content: string;
+}
+/**
+ * Parameters for {@link copySafe}.
+ */
+export interface CopySafeParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The new path to copy the file or folder to.
+     */
+    readonly newPath: string;
+    /**
+     * The old path, file or folder to copy. A folder is copied with its whole subtree.
+     */
+    readonly oldPathOrFile: PathOrAbstractFile;
+}
+/**
+ * Parameters for {@link getAbstractFilePathSafe}.
+ */
+export interface GetAbstractFilePathSafeParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The path of the file or folder to get a safe path for.
+     */
+    readonly path: string;
+    /**
+     * The type of the file system object.
+     */
+    readonly type: FileSystemType;
+}
+/**
+ * Parameters for {@link getOrCreateAbstractFileSafe}.
+ */
+export interface GetOrCreateAbstractFileSafeParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The path of the abstract file to get or create.
+     */
+    readonly path: string;
+    /**
+     * The type of the abstract file to get or create.
+     */
+    readonly type: FileSystemType;
+}
+/**
+ * Parameters for {@link getSafeRenamePath}.
+ */
+export interface GetSafeRenamePathParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The new path to rename the abstract file to.
+     */
+    readonly newPath: string;
+    /**
+     * The old path or abstract file to rename.
+     */
+    readonly oldPathOrAbstractFile: PathOrAbstractFile;
+}
+/**
+ * Parameters for {@link invokeWithFileSystemLock}.
+ */
+export interface InvokeWithFileSystemLockParams {
+    /**
+     * The function to execute.
+     *
+     * @param content - The content of the file.
+     */
+    readonly $function: (content: string) => void;
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The path or file to execute the function with the file system lock of.
+     */
+    readonly pathOrFile: PathOrFile;
+}
+/**
+ * Parameters for {@link isChildOrSelf}.
+ */
+export interface IsChildOrSelfParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The path or file to check whether it is a child or self.
+     */
+    readonly childPathOrFile: PathOrAbstractFile;
+    /**
+     * The path or file to check whether it is a parent or self.
+     */
+    readonly parentPathOrFile: PathOrAbstractFile;
+}
+/**
+ * Parameters for {@link isChild}.
+ */
+export interface IsChildParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The path or file to check whether it is a child.
+     */
+    readonly childPathOrFile: PathOrAbstractFile;
+    /**
+     * The path or file to check whether it is a parent.
+     */
+    readonly parentPathOrFile: PathOrAbstractFile;
+}
+/**
+ * Options for {@link process}.
+ */
+export interface ProcessOptions extends RetryOptions {
+    /**
+     * Plugin notice component used to show the timeout notice. When `null`, no timeout notice is shown
+     * regardless of {@link ProcessOptions.shouldShowTimeoutNotice}; the timeout is only logged.
+     */
+    readonly pluginNoticeComponent: null | PluginNoticeComponent;
+    /**
+     * An resource-lock component used to lock the file's editor read-only for the duration of
+     * processing. The lock is reference-counted, so it composes with any outer operation-level lock
+     * on the same note.
+     */
+    readonly resourceLockComponent: null | ResourceLockComponent;
+    /**
+     * Whether to fail if the file is missing or deleted.
+     *
+     * @default `true`
+     */
+    readonly shouldFailOnMissingFile?: boolean;
+    /**
+     * Whether to show a timeout notice.
+     *
+     * @default `true`
+     */
+    readonly shouldShowTimeoutNotice?: boolean;
+}
+/**
+ * Parameters for {@link process}.
+ */
+export interface ProcessParams extends ProcessOptions {
+    /**
+     * The application instance, typically used for accessing the vault.
+     */
+    readonly app: App;
+    /**
+     * 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.
+     *
+     * A function has three outcomes:
+     *
+     * - `null` — the new content cannot be produced YET; the process is retried.
+     * - the old content, returned unchanged — there is nothing to write; the process completes without
+     *   touching the file. Use this for a refusal that is permanent, as returning `null` for one retries
+     *   forever and holds the operation open.
+     * - any other string — the content to write.
+     */
+    readonly newContentProvider: ValueProvider<null | string, ContentArguments>;
+    /**
+     * The path or file to be processed. It can be a string representing the path or a file object.
+     */
+    readonly pathOrFile: PathOrFile;
+}
+/**
+ * Parameters for {@link renameSafe}.
+ */
+export interface RenameSafeParams {
+    /**
+     * The application instance.
+     */
+    readonly app: App;
+    /**
+     * The new path to rename the file to.
+     */
+    readonly newPath: string;
+    /**
+     * The old path or abstract file to rename.
+     */
+    readonly oldPathOrAbstractFile: PathOrAbstractFile;
+}
+/**
+ * Cleans up empty folders according to the given {@link EmptyFolderBehavior}.
+ *
+ * @param params - The parameters for cleaning up empty folders.
+ * @returns A {@link Promise} that resolves when the cleanup is complete.
+ */
+export declare function cleanupEmptyFolders(params: CleanupEmptyFoldersParams): Promise<void>;
+/**
+ * Copies a file or folder safely in the vault. A folder is copied with its whole subtree, empty
+ * subfolders included.
+ *
+ * @param params - The parameters for copying the file or folder.
+ * @returns A {@link Promise} that resolves to the new path of the copy.
+ * @throws Error if the destination resolves inside the source folder.
+ */
+export declare function copySafe(params: CopySafeParams): 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 {@link CreateFolderSafeResult.Created} if the folder was
+ * created, or {@link CreateFolderSafeResult.NotCreated} if it already existed.
+ * @throws If an error occurs while creating the folder and it still doesn't exist.
+ */
+export declare function createFolderSafe(app: App, path: string): Promise<CreateFolderSafeResult>;
+/**
+ * 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 createTemporaryFile(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 createTemporaryFolder(app: App, path: string): Promise<() => Promise<void>>;
+/**
+ * Deletes an empty folder.
+ *
+ * A folder the vault index still holds but the disk has already lost is not empty: it is nothing to delete, so it
+ * is left alone rather than handed to the trash as a missing path.
+ *
+ * @param app - The application instance.
+ * @param pathOrFolder - The folder to delete.
+ * @returns A {@link Promise} that resolves when the folder is deleted.
+ */
+export declare function deleteEmptyFolder(app: App, pathOrFolder: null | PathOrFolder): Promise<void>;
+/**
+ * Removes empty folder hierarchy starting from the given folder.
+ *
+ * The walk stops at the first folder that is not empty or no longer exists on disk.
+ *
+ * @param app - The application instance.
+ * @param pathOrFolder - The folder to start removing empty hierarchy from.
+ * @returns A {@link Promise} that resolves when the empty hierarchy is deleted.
+ */
+export declare function deleteEmptyFolderHierarchy(app: App, pathOrFolder: null | PathOrFolder): Promise<void>;
+/**
+ * Gets a safe path for a file or folder.
+ *
+ * @param params - The parameters for getting a safe path.
+ * @returns The safe path for the file or folder.
+ */
+export declare function getAbstractFilePathSafe(params: GetAbstractFilePathSafeParams): 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 params - The parameters for getting or creating the abstract file.
+ * @returns A {@link Promise} that resolves to the abstract file.
+ */
+export declare function getOrCreateAbstractFileSafe(params: GetOrCreateAbstractFileSafeParams): 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 params - The parameters for getting a safe rename path.
+ * @returns The safe rename path for the abstract file.
+ */
+export declare function getSafeRenamePath(params: GetSafeRenamePathParams): string;
+/**
+ * Invokes a function with the file system lock.
+ *
+ * @param params - The parameters for invoking the function with the file system lock.
+ * @returns A {@link Promise} that resolves when the function is invoked.
+ */
+export declare function invokeWithFileSystemLock(params: InvokeWithFileSystemLockParams): Promise<void>;
+/**
+ * Checks if a path or file is a child of another path or file.
+ *
+ * @param params - The parameters for checking whether the child path or file is a child of the parent path or file.
+ * @returns A boolean indicating whether the child path or file is a child of the parent path or file.
+ */
+export declare function isChild(params: IsChildParams): boolean;
+/**
+ * Checks if a path or file is a child or self of another path or file.
+ *
+ * @param params - The parameters for checking whether the child path or file is a child or self of the parent path or file.
+ * @returns A boolean indicating whether the child path or file is a child or self of the parent path or file.
+ */
+export declare function isChildOrSelf(params: IsChildOrSelfParams): 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 params - The parameters for processing the file.
+ *
+ * @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(params: ProcessParams): Promise<void>;
+/**
+ * Reads the content of a file safely from the vault.
+ *
+ * It covers the case when the file was removed during the reading.
+ *
+ * This is NOT a pure read: it calls {@link saveNote} first, which saves any open editor view of the
+ * note that has unsaved changes, so the content it returns is what the user sees. Do not call it from
+ * an automatic trigger that only decides whether to act. See `getCacheSafe` in
+ * `obsidian-dev-utils/obsidian/metadata-cache` for why.
+ *
+ * @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 params - The parameters for renaming the file.
+ * @returns A {@link Promise} that resolves to the new path of the file.
+ */
+export declare function renameSafe(params: RenameSafeParams): Promise<string>;
+/**
+ * Saves the specified note in the Obsidian app.
+ *
+ * Calls `view.save()` on every open markdown view of the note that has unsaved changes. This is a
+ * write, and several helpers whose names read as reads call it: {@link readSafe}, and `getCacheSafe`,
+ * `getFrontmatterSafe` and `getBacklinksForFileSafe` in `obsidian-dev-utils/obsidian/metadata-cache`.
+ *
+ * @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>;
+/**
+ * Trashes an abstract file safely from the vault.
+ *
+ * @param app - The Obsidian application instance.
+ * @param pathOrFile - The path or abstract file to trash.
+ * @returns A {@link Promise} that resolves when the file is trashed.
+ */
+export declare function trashSafe(app: App, pathOrFile: PathOrAbstractFile): Promise<void>;