obsidian-dev-utils 18.4.0 → 19.0.0

package/dist/lib/obsidian/Frontmatter.d.mts

@@ -0,0 +1,69 @@
+/**
+ * @packageDocumentation Frontmatter
+ * This module provides utility functions for processing and managing YAML front matter in Obsidian notes.
+ */
+/**
+ * Represents the combined front matter of a document.
+ * It is a union of custom front matter, Obsidian front matter, and additional properties.
+ * @typeParam CustomFrontmatter - The type of custom front matter.
+ */
+export type CombinedFrontmatter<CustomFrontmatter> = CustomFrontmatter & ObsidianFrontmatter & Record<string, unknown>;
+/**
+ * Represents the front matter of an Obsidian file.
+ * @see {@link https://help.obsidian.md/Editing+and+formatting/Properties#Default+properties}
+ */
+export interface ObsidianFrontmatter {
+    /**
+     * An array of aliases for the note.
+     */
+    aliases?: string[];
+    /**
+     * An array of CSS classes to apply to the note.
+     */
+    cssclasses?: string[];
+    /**
+     * An array of tags for the note.
+     */
+    tags?: string[];
+}
+/**
+ * Represents the front matter for publishing in Obsidian.
+ * @see {@link https://help.obsidian.md/Editing+and+formatting/Properties#Properties+for+Obsidian+Publish}
+ */
+export interface ObsidianPublishFrontmatter {
+    /**
+     * The cover image for the note.
+     */
+    cover?: string;
+    /**
+     * The description for the note.
+     */
+    description?: string;
+    /**
+     * The image for the note.
+     */
+    image?: string;
+    /**
+     * The permanent link for the note.
+     */
+    permalink?: string;
+    /**
+     * Whether the note is published.
+     */
+    publish?: boolean;
+}
+/**
+ * Parses the front matter of a given content string.
+ *
+ * @param content - The content string to parse.
+ * @returns The parsed front matter.
+ */
+export declare function parseFrontmatter<CustomFrontmatter = unknown>(content: string): CombinedFrontmatter<CustomFrontmatter>;
+/**
+ * Sets the front matter of a given content string.
+ *
+ * @param content - The content string to set the front matter in.
+ * @param newFrontmatter - The new front matter to set.
+ * @returns The new content string with the front matter set.
+ */
+export declare function setFrontmatter(content: string, newFrontmatter: object): string;

package/dist/lib/obsidian/{Link.d.ts → Link.d.cts}

@@ -5,9 +5,9 @@
  * The functions integrate with Obsidian's API to ensure that links are managed correctly within the vault.
  */
 import type { App, Reference, TFile } from 'obsidian';
-import type { MaybePromise } from '../Async.ts';
-import type { PathOrFile } from './FileSystem.ts';
-import type { ProcessOptions } from './Vault.ts';
+import type { MaybePromise } from '../Async.cjs';
+import type { PathOrFile } from './FileSystem.cjs';
+import type { ProcessOptions } from './Vault.cjs';
 /**
  * Options for converting a link.
  */

package/dist/lib/obsidian/Link.d.mts

@@ -0,0 +1,366 @@
+/**
+ * @packageDocumentation Link
+ * This module provides utilities for handling and updating links within Obsidian vaults. It includes
+ * functions to split paths, update links in files, and generate markdown links with various options.
+ * The functions integrate with Obsidian's API to ensure that links are managed correctly within the vault.
+ */
+import type { App, Reference, TFile } from 'obsidian';
+import type { MaybePromise } from '../Async.mjs';
+import type { PathOrFile } from './FileSystem.mjs';
+import type { ProcessOptions } from './Vault.mjs';
+/**
+ * Options for converting a link.
+ */
+export interface ConvertLinkOptions {
+    /**
+     * The Obsidian app instance.
+     */
+    app: App;
+    /**
+     * The reference for the link.
+     */
+    link: Reference;
+    /**
+     * The source file containing the link.
+     */
+    newSourcePathOrFile: PathOrFile;
+    /**
+     * The old path of the link.
+     */
+    oldSourcePathOrFile?: PathOrFile;
+    /**
+     * Whether to force markdown links.
+     */
+    shouldForceMarkdownLinks?: boolean;
+    /**
+     * Whether to update filename alias. Defaults to `true`.
+     */
+    shouldUpdateFilenameAlias?: boolean;
+}
+/**
+ * Wrapper for default options for generating markdown links.
+ */
+export interface GenerateMarkdownLinkDefaultOptionsWrapper {
+    /**
+     * The default options for generating markdown links.
+     */
+    defaultOptionsFn: () => Partial<GenerateMarkdownLinkOptions>;
+}
+/**
+ * Options for generating a markdown link.
+ */
+export interface GenerateMarkdownLinkOptions {
+    /**
+     * The alias for the link.
+     */
+    alias?: string;
+    /**
+     * The Obsidian app instance.
+     */
+    app: App;
+    /**
+     * Indicates if the link should be embedded. If not provided, it will be inferred based on the file type.
+     */
+    isEmbed?: boolean;
+    /**
+     * Whether to allow an empty alias for embeds. Defaults to `true`.
+     */
+    isEmptyEmbedAliasAllowed?: boolean;
+    /**
+     * Whether to allow non-existing files. If `false` and `pathOrFile` is a non-existing file, an error will be thrown. Defaults to `false`.
+     */
+    isNonExistingFileAllowed?: boolean;
+    /**
+     * Indicates if the link should be a wikilink. If not provided, it will be inferred based on the Obsidian settings.
+     */
+    isWikilink?: boolean;
+    /**
+     * The original link text. If provided, it will be used to infer the values of `isEmbed`, `isWikilink`, `useLeadingDot`, and `useAngleBrackets`.
+     * These inferred values will be overridden by corresponding settings if specified.
+     */
+    originalLink?: string;
+    /**
+     * Indicates if the link should be relative. If not provided or `false`, it will be inferred based on the Obsidian settings.
+     */
+    shouldForceRelativePath?: boolean;
+    /**
+     * Whether to include the attachment extension in the embed alias. Has no effect if `allowEmptyEmbedAlias` is `true`. Defaults to `false`.
+     */
+    shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Indicates if the link should use angle brackets. Defaults to `false`. Has no effect if `isWikilink` is `true`
+     */
+    shouldUseAngleBrackets?: boolean;
+    /**
+     * Indicates if the link should use a leading dot. Defaults to `false`. Has no effect if `isWikilink` is `true` or `isRelative` is `false`.
+     */
+    shouldUseLeadingDot?: boolean;
+    /**
+     * The source path of the link.
+     */
+    sourcePathOrFile: PathOrFile;
+    /**
+     * The subpath of the link.
+     */
+    subpath?: string;
+    /**
+     * The target path or file.
+     */
+    targetPathOrFile: PathOrFile;
+}
+/**
+ * The result of parsing a link.
+ */
+export interface ParseLinkResult {
+    /**
+     * The alias of the link.
+     */
+    alias?: string;
+    /**
+     * Indicates if the link has angle brackets.
+     */
+    hasAngleBrackets?: boolean;
+    /**
+     * Indicates if the link is an embed link.
+     */
+    isEmbed: boolean;
+    /**
+     * Indicates if the link is external.
+     */
+    isExternal?: boolean;
+    /**
+     * Indicates if the link is a wikilink.
+     */
+    isWikilink: boolean;
+    /**
+     * The title of the link.
+     */
+    title?: string;
+    /**
+     * The URL of the link.
+     */
+    url: string;
+}
+/**
+ * Options for determining if the alias of a link should be reset.
+ */
+export interface ShouldResetAliasOptions {
+    /**
+     * The Obsidian app instance.
+     */
+    app: App;
+    /**
+     * The display text of the link.
+     */
+    displayText: string | undefined;
+    /**
+     * Indicates if the link is a wikilink.
+     */
+    isWikilink?: boolean;
+    /**
+     * The source path of the link.
+     */
+    newSourcePathOrFile: PathOrFile;
+    /**
+     * The old source file containing the link.
+     */
+    oldSourcePathOrFile?: PathOrFile;
+    /**
+     * The old target path of the link.
+     */
+    oldTargetPath: PathOrFile;
+    /**
+     * The target path or file.
+     */
+    targetPathOrFile: PathOrFile;
+}
+/**
+ * Splits a link into its link path and subpath.
+ */
+export interface SplitSubpathResult {
+    /**
+     * The link path.
+     */
+    linkPath: string;
+    /**
+     * The subpath.
+     */
+    subpath: string;
+}
+/**
+ * Options for updating a link.
+ */
+export interface UpdateLinkOptions {
+    /**
+     * The Obsidian app instance.
+     */
+    app: App;
+    /**
+     * The reference for the link.
+     */
+    link: Reference;
+    /**
+     * The source file containing the link.
+     */
+    newSourcePathOrFile: PathOrFile;
+    /**
+     * The file associated with the link.
+     */
+    newTargetPathOrFile: PathOrFile;
+    /**
+     * The old source file containing the link.
+     */
+    oldSourcePathOrFile?: PathOrFile;
+    /**
+     * The old path of the file.
+     */
+    oldTargetPathOrFile?: PathOrFile;
+    /**
+     * Whether to force markdown links.
+     */
+    shouldForceMarkdownLinks?: boolean;
+    /**
+     * Whether to update filename alias. Defaults to `true`.
+     */
+    shouldUpdateFilenameAlias?: boolean;
+}
+/**
+ * Options for updating links in a file.
+ */
+export interface UpdateLinksInFileOptions extends ProcessOptions {
+    /**
+     * The obsidian app instance.
+     */
+    app: App;
+    /**
+     * The file to update the links in.
+     */
+    newSourcePathOrFile: PathOrFile;
+    /**
+     * The old path of the file.
+     */
+    oldSourcePathOrFile?: PathOrFile;
+    /**
+     * Whether to force the links to be in Markdown format.
+     */
+    shouldForceMarkdownLinks?: boolean;
+    /**
+     * Whether to update only embedded links.
+     */
+    shouldUpdateEmbedOnlyLinks?: boolean;
+    /**
+     * Whether to update filename alias. Defaults to `true`.
+     */
+    shouldUpdateFilenameAlias?: boolean;
+}
+/**
+ * Converts a link to a new path.
+ *
+ * @param options - The options for converting the link.
+ * @returns The converted link.
+ */
+export declare function convertLink(options: ConvertLinkOptions): string;
+/**
+ * Edits the backlinks for a file or path.
+ *
+ * @param app - The Obsidian application instance.
+ * @param pathOrFile - The path or file to edit the backlinks for.
+ * @param linkConverter - The function that converts each link.
+ * @param processOptions - Optional options for retrying the operation.
+ * @returns A promise that resolves when the backlinks have been edited.
+ */
+export declare function editBacklinks(app: App, pathOrFile: PathOrFile, linkConverter: (link: Reference) => MaybePromise<string | void>, processOptions?: ProcessOptions): Promise<void>;
+/**
+ * Edits the backlinks for a file or path.
+ *
+ * @param app - The Obsidian application instance.
+ * @param pathOrFile - The path or file to edit the backlinks for.
+ * @param linkConverter - The function that converts each link.
+ * @param processOptions - Optional options for retrying the operation.
+ * @returns A promise that resolves when the backlinks have been edited.
+ */
+export declare function editLinks(app: App, pathOrFile: PathOrFile, linkConverter: (link: Reference) => MaybePromise<string | void>, processOptions?: ProcessOptions): Promise<void>;
+/**
+ * Extracts the file associated with a link.
+ *
+ * @param app - The Obsidian application instance.
+ * @param link - The reference cache for the link.
+ * @param sourcePathOrFile - The source path or file.
+ * @returns The file associated with the link, or null if not found.
+ */
+export declare function extractLinkFile(app: App, link: Reference, sourcePathOrFile: PathOrFile): null | TFile;
+/**
+ * Generates a markdown link based on the provided parameters.
+ *
+ * @param options - The options for generating the markdown link.
+ * @returns The generated markdown link.
+ */
+export declare function generateMarkdownLink(options: GenerateMarkdownLinkOptions): string;
+/**
+ * Parses a link into its components.
+ *
+ * @param str - The link to parse.
+ * @returns The parsed link.
+ */
+export declare function parseLink(str: string): null | ParseLinkResult;
+/**
+ * Determines if the alias of a link should be reset.
+ *
+ * @param options - The options for determining if the alias should be reset.
+ * @returns Whether the alias should be reset.
+ */
+export declare function shouldResetAlias(options: ShouldResetAliasOptions): boolean;
+/**
+ * Splits a link into its link path and subpath.
+ *
+ * @param link - The link to split.
+ * @returns An object containing the link path and subpath.
+ */
+export declare function splitSubpath(link: string): SplitSubpathResult;
+/**
+ * Tests whether a link uses angle brackets, possibly embed:
+ * `[title](<link>)`, `![title](<link>)`.
+ *
+ * @param link - Link to test
+ * @returns Whether the link uses angle brackets
+ */
+export declare function testAngleBrackets(link: string): boolean;
+/**
+ * Tests whether a link is an embed link:
+ * `![[link]]`, `![title](link)`.
+ *
+ * @param link - Link to test
+ * @returns Whether the link is an embed link
+ */
+export declare function testEmbed(link: string): boolean;
+/**
+ * Tests whether a link has a leading dot, possibly embed:
+ * `[[./link]]`, `[title](./link)`, `[title](<./link>)`,
+ * `![[./link]]`, `![title](./link)`, `![title](<./link>)`.
+ *
+ * @param link - Link to test
+ * @returns Whether the link has a leading dot
+ */
+export declare function testLeadingDot(link: string): boolean;
+/**
+ * Tests whether a link is a wikilink, possibly embed:
+ * `[[link]]`, `![[link]]`.
+ *
+ * @param link - Link to test
+ * @returns Whether the link is a wikilink
+ */
+export declare function testWikilink(link: string): boolean;
+/**
+ * Updates a link based on the provided parameters.
+ *
+ * @param options - The options for updating the link.
+ * @returns The updated link.
+ */
+export declare function updateLink(options: UpdateLinkOptions): string;
+/**
+ * Updates the links in a file based on the provided parameters.
+ *
+ * @param options - The options for updating the links.
+ * @returns A promise that resolves when the links are updated.
+ */
+export declare function updateLinksInFile(options: UpdateLinksInFileOptions): Promise<void>;

package/dist/lib/obsidian/{Logger.d.ts → Logger.d.cts}

@@ -2,7 +2,7 @@
  * @packageDocumentation Logger
  * Contains utility functions for logging in Obsidian.
  */
-import type { MaybePromise } from '../Async.ts';
+import type { MaybePromise } from '../Async.cjs';
 /**
  * Invokes a function and logs the start, end, and duration of the invocation.
  *

package/dist/lib/obsidian/Logger.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @packageDocumentation Logger
+ * Contains utility functions for logging in Obsidian.
+ */
+import type { MaybePromise } from '../Async.mjs';
+/**
+ * Invokes a function and logs the start, end, and duration of the invocation.
+ *
+ * @param title - The title of the log.
+ * @param fn - The function to invoke.
+ * @param stackTrace - Optional stack trace.
+ */
+export declare function invokeAsyncAndLog(title: string, fn: () => MaybePromise<void>, stackTrace?: string): Promise<void>;

package/dist/lib/obsidian/{Loop.d.ts → Loop.d.cts}

@@ -2,7 +2,7 @@
  * @packageDocumentation Loop
  * Contains utility functions for looping in Obsidian.
  */
-import type { MaybePromise } from '../Async.ts';
+import type { MaybePromise } from '../Async.cjs';
 /**
  * Options for the loop function.
  */

package/dist/lib/obsidian/Loop.d.mts

@@ -0,0 +1,36 @@
+/**
+ * @packageDocumentation Loop
+ * Contains utility functions for looping in Obsidian.
+ */
+import type { MaybePromise } from '../Async.mjs';
+/**
+ * Options for the loop function.
+ */
+export interface LoopOptions<T> {
+    /**
+     * An optional abort signal to cancel the loop.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * The function to build the notice message for each item.
+     */
+    buildNoticeMessage(item: T, iterationStr: string): string;
+    /**
+     * The items to loop over.
+     */
+    items: T[];
+    /**
+     * The function to process each item.
+     */
+    processItem(item: T): MaybePromise<void>;
+    /**
+     * Whether to continue the loop on error.
+     */
+    shouldContinueOnError?: boolean;
+}
+/**
+ * Loops over a list of items and processes each item.
+ *
+ * @param options - The options for the loop.
+ */
+export declare function loop<T>(options: LoopOptions<T>): Promise<void>;

package/dist/lib/obsidian/Markdown.d.mts

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation Markdown
+ * This module provides utility functions for processing Markdown content in Obsidian.
+ */
+import { App, Component } from 'obsidian';
+/**
+ * Render the markdown and embeds.
+ *
+ * @param app - The Obsidian app instance.
+ * @param markdown - The Markdown string to render.
+ * @param el - The HTMLElement to render to.
+ * @param sourcePath - The source path to resolve relative links.
+ * @param component - The Component instance.
+ */
+export declare function fullRender(app: App, markdown: string, el: HTMLElement, sourcePath: string, component: Component): Promise<void>;
+/**
+ * Converts Markdown to HTML.
+ *
+ * @param app - The Obsidian app instance.
+ * @param markdown - The Markdown string to convert.
+ * @param sourcePath - (optional) The source path to resolve relative links.
+ * @returns The HTML string.
+ */
+export declare function markdownToHtml(app: App, markdown: string, sourcePath?: string): Promise<string>;

package/dist/lib/obsidian/{MarkdownCodeBlockProcessor.d.ts → MarkdownCodeBlockProcessor.d.cts}

@@ -3,7 +3,7 @@
  * This module provides utility functions for processing code blocks in Obsidian.
  */
 import type { App, MarkdownPostProcessorContext } from 'obsidian';
-import type { ValueProvider } from '../ValueProvider.ts';
+import type { ValueProvider } from '../ValueProvider.cjs';
 /**
  * Retrieves the argument of a code block from the given MarkdownPostProcessorContext and HTMLElement.
  *

package/dist/lib/obsidian/MarkdownCodeBlockProcessor.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation MarkdownCodeBlockProcessor
+ * This module provides utility functions for processing code blocks in Obsidian.
+ */
+import type { App, MarkdownPostProcessorContext } from 'obsidian';
+import type { ValueProvider } from '../ValueProvider.mjs';
+/**
+ * Retrieves the argument of a code block from the given MarkdownPostProcessorContext and HTMLElement.
+ *
+ * @param ctx - The MarkdownPostProcessorContext object.
+ * @param el - The HTMLElement representing the code block.
+ * @returns The argument of the code block as a string, or null if no argument is found.
+ */
+export declare function getCodeBlockArguments(ctx: MarkdownPostProcessorContext, el: HTMLElement): string[];
+/**
+ * Replaces the code block.
+ *
+ * @param app - The Obsidian App object.
+ * @param ctx - The MarkdownPostProcessorContext object.
+ * @param el - The HTMLElement representing the code block.
+ * @param codeBlockProvider - The ValueProvider that provides the new code block.
+ */
+export declare function replaceCodeBlock(app: App, ctx: MarkdownPostProcessorContext, el: HTMLElement, codeBlockProvider: ValueProvider<string, [string]>): Promise<void>;

package/dist/lib/obsidian/MarkdownView.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation MarkdownView
+ * Utilities for working with MarkdownView
+ */
+import { MarkdownView } from 'obsidian';
+/**
+ * Get the full HTML content of the current MarkdownView
+ *
+ * @param view - The MarkdownView to get the HTML from
+ * @returns The full HTML of the MarkdownView
+ */
+export declare function getFullContentHtml(view: MarkdownView): string;

package/dist/lib/obsidian/{MetadataCache.d.ts → MetadataCache.d.cts}

@@ -4,9 +4,9 @@
  */
 import type { App, CachedMetadata, Reference, TAbstractFile } from 'obsidian';
 import type { CustomArrayDict } from 'obsidian-typings';
-import type { RetryOptions } from '../Async.ts';
-import type { PathOrFile } from './FileSystem.ts';
-import type { CombinedFrontmatter } from './Frontmatter.ts';
+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.
  */

package/dist/lib/obsidian/MetadataCache.d.mts

@@ -0,0 +1,87 @@
+/**
+ * @packageDocumentation MetadataCache
+ * 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.mjs';
+import type { PathOrFile } from './FileSystem.mjs';
+import type { CombinedFrontmatter } from './Frontmatter.mjs';
+/**
+ * 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 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 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 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.
+ * @param retryOptions - Optional retry options for the retrieval process.
+ * @returns The cached metadata for the file, or null if it doesn't exist.
+ */
+export declare function getCacheSafe(app: App, fileOrPath: PathOrFile, retryOptions?: RetryOptions): 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>>;
+/***
+ * Registers a file in the Obsidian app.
+ *
+ * @param app - The Obsidian app instance.
+ * @param file - The file to register.
+ * @returns A function that unregisters the file.
+ */
+export declare function registerFile(app: App, file: TAbstractFile): () => void;
+/**
+ * Temporarily registers a file and runs a function.
+ *
+ * @param app - The Obsidian app instance.
+ * @param file - The file to temporarily register.
+ * @param fn - The function to run.
+ * @returns The result of the function.
+ */
+export declare function tempRegisterFileAndRun<T>(app: App, file: TAbstractFile, fn: () => T): T;