obsidian-dev-utils/dist/lib/esm/obsidian/FileChange.d.mts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * Contains utility types and functions for handling file changes in Obsidian.
 */
import type { App, FrontmatterLinkCache, Reference, ReferenceCache } from 'obsidian';
import type { ValueProvider } from '../ValueProvider.mjs';
import type { PathOrFile } from './FileSystem.mjs';
import type { FrontmatterLinkCacheWithOffsets } from './FrontmatterLinkCacheWithOffsets.mjs';
import type { CanvasFileNodeReference, CanvasReference, CanvasTextNodeReference } from './Reference.mjs';
import type { ProcessOptions } from './Vault.mjs';
/**
 * A file change in the vault.
 */
export interface FileChange {
    /**
     * A new content to replace the old content.
     */
    newContent: string;
    /**
     * An old content that will be replaced.
     */
    oldContent: string;
    /**
     * A reference that caused the change.
     */
    reference: Reference;
}
type CanvasChange = {
    reference: CanvasReference;
} & FileChange;
type CanvasFileNodeChange = {
    reference: CanvasFileNodeReference;
} & FileChange;
type CanvasTextNodeChange = {
    reference: CanvasTextNodeReference;
} & FileChange;
type ContentChange = {
    reference: ReferenceCache;
} & FileChange;
type FrontmatterChange = {
    reference: FrontmatterLinkCache;
} & FileChange;
type FrontmatterChangeWithOffsets = {
    reference: FrontmatterLinkCacheWithOffsets;
} & FileChange;
/**
 * Applies a series of content changes to the specified content.
 *
 * @param abortSignal - The abort signal to control the execution of the function.
 * @param content - The content to which the changes should be applied.
 * @param path - The path to which the changes should be applied.
 * @param changesProvider - A provider that returns an array of content changes to apply.
 * @param shouldRetryOnInvalidChanges - Whether to retry the operation if the changes are invalid.
 * @returns A {@link Promise} that resolves to the updated content or to `null` if update didn't succeed.
 */
export declare function applyContentChanges(abortSignal: AbortSignal, content: string, path: string, changesProvider: ValueProvider<FileChange[] | null, [content: string]>, shouldRetryOnInvalidChanges?: boolean): Promise<null | string>;
/**
 * Applies a series of file changes to the specified file or path within the application.
 *
 * @param app - The application instance where the file changes will be applied.
 * @param pathOrFile - The path or file to which the changes should be applied.
 * @param changesProvider - A provider that returns an array of file changes to apply.
 * @param processOptions - Optional options for processing/retrying the operation.
 * @param shouldRetryOnInvalidChanges - Whether to retry the operation if the changes are invalid.
 *
 * @returns A {@link Promise} that resolves when the file changes have been successfully applied.
 */
export declare function applyFileChanges(app: App, pathOrFile: PathOrFile, changesProvider: ValueProvider<FileChange[] | null, [content: string]>, processOptions?: ProcessOptions, shouldRetryOnInvalidChanges?: boolean): Promise<void>;
/**
 * Checks if a file change is a canvas change.
 *
 * @param change - The file change to check.
 * @returns Whether the file change is a canvas change.
 */
export declare function isCanvasChange(change: FileChange): change is CanvasChange;
/**
 * Checks if a file change is a canvas file node change.
 *
 * @param change - The file change to check.
 * @returns Whether the file change is a canvas file node change.
 */
export declare function isCanvasFileNodeChange(change: FileChange): change is CanvasFileNodeChange;
/**
 * Checks if a file change is a canvas text node change.
 *
 * @param change - The file change to check.
 * @returns Whether the file change is a canvas text node change.
 */
export declare function isCanvasTextNodeChange(change: FileChange): change is CanvasTextNodeChange;
/**
 * Checks if a file change is a content change.
 *
 * @param fileChange - The file change to check.
 * @returns A boolean indicating whether the file change is a content change.
 */
export declare function isContentChange(fileChange: FileChange): fileChange is ContentChange;
/**
 * Checks if a file change is a frontmatter change.
 *
 * @param fileChange - The file change to check.
 * @returns A boolean indicating whether the file change is a frontmatter change.
 */
export declare function isFrontmatterChange(fileChange: FileChange): fileChange is FrontmatterChange;
/**
 * Checks if a file change is a frontmatter change with offsets.
 *
 * @param fileChange - The file change to check.
 * @returns A boolean indicating whether the file change is a frontmatter change with offsets.
 */
export declare function isFrontmatterChangeWithOffsets(fileChange: FileChange): fileChange is FrontmatterChangeWithOffsets;
/**
 * Converts a frontmatter change to a frontmatter change with offsets.
 *
 * @param fileChange - The file change to convert.
 * @returns The converted file change.
 */
export declare function toFrontmatterChangeWithOffsets(fileChange: FrontmatterChange): FrontmatterChangeWithOffsets;
export {};