obsidian-dev-utils/dist/lib/cjs/obsidian/MetadataCache.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 the metadata cache in Obsidian.
 */
import type { App, CachedMetadata, Reference, TAbstractFile } from 'obsidian';
import type { CustomArrayDict } from 'obsidian-typings';
import type { RetryOptions } from '../Async.cjs';
import type { PathOrFile } from './FileSystem.cjs';
import type { CombinedFrontmatter } from './Frontmatter.cjs';
/**
 * Wrapper for the getBacklinksForFile method that provides a safe overload.
 */
export interface GetBacklinksForFileSafeWrapper {
    /**
     * Retrieves the backlinks for a file safely.
     *
     * @param pathOrFile - The path or file object.
     * @returns A {@link Promise} that resolves to an array dictionary of backlinks.
     */
    safe(pathOrFile: PathOrFile): Promise<CustomArrayDict<Reference>>;
}
/**
 * Ensures that the metadata cache is ready for all files.
 *
 * @param app - The Obsidian app instance.
 * @returns A {@link Promise} that resolves when the metadata cache is ready.
 */
export declare function ensureMetadataCacheReady(app: App): Promise<void>;
/**
 * Retrieves all links from the provided cache.
 *
 * @param cache - The cached metadata.
 * @returns An array of reference caches representing the links.
 */
export declare function getAllLinks(cache: CachedMetadata): Reference[];
/**
 * Retrieves the backlinks for a file or path.
 * NOTE: The file may be non-existent.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFile - The path or file object.
 * @returns The backlinks for the file.
 */
export declare function getBacklinksForFileOrPath(app: App, pathOrFile: PathOrFile): CustomArrayDict<Reference>;
/**
 * Retrieves the backlinks for a file safely.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFile - The path or file object.
 * @param retryOptions - Optional retry options.
 * @returns A {@link Promise} that resolves to an array dictionary of backlinks.
 */
export declare function getBacklinksForFileSafe(app: App, pathOrFile: PathOrFile, retryOptions?: RetryOptions): Promise<CustomArrayDict<Reference>>;
/**
 * Retrieves the cached metadata for a given file or path.
 *
 * @param app - The Obsidian app instance.
 * @param fileOrPath - The file or path to retrieve the metadata for.
 * @returns The cached metadata for the file, or null if it doesn't exist.
 */
export declare function getCacheSafe(app: App, fileOrPath: PathOrFile): Promise<CachedMetadata | null>;
/**
 * Retrieves the front matter from the metadata cache safely.
 *
 * @typeParam CustomFrontmatter - The type of custom front matter.
 * @param app - The Obsidian app instance.
 * @param pathOrFile - The path or file to retrieve the front matter from.
 * @returns The combined front matter.
 */
export declare function getFrontmatterSafe<CustomFrontmatter = unknown>(app: App, pathOrFile: PathOrFile): Promise<CombinedFrontmatter<CustomFrontmatter>>;
/**
 * Parses the metadata for a given string.
 *
 * @param app - The Obsidian app instance.
 * @param str - The string to parse the metadata for.
 * @returns The parsed metadata.
 */
export declare function parseMetadata(app: App, str: string): Promise<CachedMetadata>;
/**
 * Registers the file cache for a non-existing file.
 *
 * @param app - The Obsidian app instance.
 * @param pathOrFile - The path or file to register the file cache for.
 * @param cache - The file cache to register.
 */
export declare function registerFileCacheForNonExistingFile(app: App, pathOrFile: PathOrFile, cache: CachedMetadata): void;
/**
 * Registers files in the Obsidian app.
 *
 * @param app - The Obsidian app instance.
 * @param files - The files to register.
 */
export declare function registerFiles(app: App, files: TAbstractFile[]): void;
/**
 * Temporarily registers files and runs a function.
 *
 * @typeParam T - The type of the result of the function.
 * @param app - The Obsidian app instance.
 * @param files - The files to temporarily register.
 * @param fn - The function to run.
 * @returns The result of the function.
 */
export declare function tempRegisterFilesAndRun<T>(app: App, files: TAbstractFile[], fn: () => T): T;
/**
 * Temporarily registers files and runs an async function.
 *
 * @typeParam T - The type of the result of the function.
 * @param app - The Obsidian app instance.
 * @param files - The files to temporarily register.
 * @param fn - The function to run.
 * @returns The result of the function.
 */
export declare function tempRegisterFilesAndRunAsync<T>(app: App, files: TAbstractFile[], fn: () => Promise<T>): Promise<T>;
/**
 * Unregisters the file cache for a non-existing file.
 *
 * @param app - The Obsidian app instance.
 * @param pathOrFile - The path or file to unregister the file cache for.
 */
export declare function unregisterFileCacheForNonExistingFile(app: App, pathOrFile: PathOrFile): void;
/**
 * Unregisters files from the Obsidian app.
 *
 * @param app - The Obsidian app instance.
 * @param files - The files to unregister.
 */
export declare function unregisterFiles(app: App, files: TAbstractFile[]): void;