obsidian-dev-utils 50.0.0 → 51.0.1

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

@@ -1,716 +0,0 @@
-/**
- * @packageDocumentation
- *
- * 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.
- */
-import type { App, CachedMetadata, Plugin, Reference, TFile } from 'obsidian';
-import type { Promisable } from 'type-fest';
-import type { MaybeReturn } from '../Type.mjs';
-import type { PathOrFile } from './FileSystem.mjs';
-import type { ProcessOptions } from './Vault.mjs';
-/**
- * A style of the link path.
- */
-export declare enum LinkPathStyle {
-    /**
-     * Use the absolute path in the vault.
-     *
-     * @example `[[path/from/the/vault/root/target]]`
-     */
-    AbsolutePathInVault = "AbsolutePathInVault",
-    /**
-     * Use the default link path style defined in Obsidian settings.
-     */
-    ObsidianSettingsDefault = "ObsidianSettingsDefault",
-    /**
-     * Use the relative path to the source.
-     *
-     * @example `[[../../relative/path/to/target]]`
-     */
-    RelativePathToTheSource = "RelativePathToTheSource",
-    /**
-     * Use the shortest path when possible.
-     *
-     * @example `[[shortest-path-to-target]]`
-     */
-    ShortestPathWhenPossible = "ShortestPathWhenPossible"
-}
-/**
- * A style of the link.
- */
-export declare enum LinkStyle {
-    /**
-     * Force the link to be in markdown format.
-     *
-     * @example `[alias](path/to/target.md)`
-     */
-    Markdown = "Markdown",
-    /**
-     * Use the default link style defined in Obsidian settings.
-     */
-    ObsidianSettingsDefault = "ObsidianSettingsDefault",
-    /**
-     * Preserve the existing link style.
-     */
-    PreserveExisting = "PreserveExisting",
-    /**
-     * Force the link to be in wikilink format.
-     *
-     * @example `[[path/to/target]]`
-     * @example `[[path/to/target|alias]]`
-     */
-    Wikilink = "Wikilink"
-}
-/**
- * Options for {@link convertLink}.
- */
-export interface ConvertLinkParams {
-    /**
-     * An Obsidian app instance.
-     */
-    readonly app: App;
-    /**
-     * A reference for the link.
-     */
-    readonly link: Reference;
-    /**
-     * A style of the link.
-     */
-    readonly linkStyle?: LinkStyle;
-    /**
-     * A source file containing the link.
-     */
-    readonly newSourcePathOrFile: PathOrFile;
-    /**
-     * An old path of the link.
-     */
-    readonly oldSourcePathOrFile?: PathOrFile;
-    /**
-     * Whether to update file name alias. Defaults to `true`.
-     */
-    readonly shouldUpdateFileNameAlias?: boolean;
-}
-/**
- * Options for {@link generateMarkdownLink}.
- */
-export interface GenerateMarkdownLinkParams {
-    /**
-     * An alias for the link.
-     *
-     * @example `[[alias|link]]`
-     * @example `[alias](link.md)`
-     */
-    readonly alias?: string;
-    /**
-     * An Obsidian app instance.
-     */
-    readonly app: App;
-    /**
-     * Indicates if the link should be embedded. If not provided, it will be inferred based on the file type.
-     *
-     * If `true`: `![[target]]`.
-     *
-     * If `false`: `[[target]]`.
-     */
-    readonly isEmbed?: boolean;
-    /**
-     * Whether to allow an empty alias for embeds. Defaults to `true`.
-     *
-     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
-     *
-     * If `true`: `![](foo.png)`.
-     *
-     * If `false`: `![foo](foo.png)`.
-     */
-    readonly isEmptyEmbedAliasAllowed?: boolean;
-    /**
-     * Whether to allow non-existing files. Defaults to `false`.
-     *
-     * If `false` and {@link targetPathOrFile} is a non-existing file, an error will be thrown.
-     */
-    readonly isNonExistingFileAllowed?: boolean;
-    /**
-     * Whether to allow a single subpath. Defaults to `true`.
-     *
-     * Applicable only if {@link targetPathOrFile} and {@link sourcePathOrFile} are the same file.
-     *
-     * If `true`: `[[#subpath]]`.
-     *
-     * If `false`: `[[source#subpath]]`
-     */
-    readonly isSingleSubpathAllowed?: boolean;
-    /**
-     * A style of the link path.
-     */
-    readonly linkPathStyle?: LinkPathStyle;
-    /**
-     * A style of the link.
-     */
-    readonly linkStyle?: LinkStyle;
-    /**
-     * An original link text.
-     *
-     * If provided, it will be used to infer the values of
-     *
-     * - {@link isEmbed}
-     * - {@link linkStyle}
-     * - {@link shouldUseAngleBrackets}
-     * - {@link shouldUseLeadingDotForRelativePaths}
-     * - {@link shouldUseLeadingSlashForAbsolutePaths}
-     *
-     * These inferred values will be overridden by corresponding settings if specified.
-     */
-    readonly originalLink?: string;
-    /**
-     * Whether to escape the alias. Defaults to `false`.
-     *
-     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
-     *
-     * If `true`: `[\*\*alias\*\*](link.md)`.
-     *
-     * If `false`: `[**alias**](link.md)`.
-     */
-    readonly shouldEscapeAlias?: boolean;
-    /**
-     * Whether to include the attachment extension in the embed alias. Defaults to `false`.
-     *
-     * Applicable only if {@link isEmptyEmbedAliasAllowed} is `false`.
-     *
-     * If `true`: `[foo.png](foo.png)`.
-     *
-     * If `false`: `[foo](foo.png)`.
-     */
-    readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
-    /**
-     * Indicates if the link should use angle brackets. Defaults to `false`.
-     *
-     * Applicable only if {@link linkStyle} is {@link LinkStyle.Markdown}.
-     *
-     * If `true`: `[alias](<path with spaces.md>)`.
-     *
-     * If `false`: `[alias](path%20with%20spaces.md)`.
-     */
-    readonly shouldUseAngleBrackets?: boolean;
-    /**
-     * Indicates if the link should use a leading dot. Defaults to `false`.
-     *
-     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.RelativePathToSource}.
-     *
-     * If `true`: `[[./relative/path/to/target]]`
-     *
-     * If `false`: `[[relative/path/to/target]]`
-     */
-    readonly shouldUseLeadingDotForRelativePaths?: boolean;
-    /**
-     * Indicates if the link should use a leading slash. Defaults to `false`.
-     *
-     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.AbsolutePathInVault}.
-     *
-     * If `true`: `[[/absolute/path/to/target]]`
-     *
-     * If `false`: `[[absolute/path/to/target]]`
-     */
-    readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
-    /**
-     * A source path of the link.
-     */
-    readonly sourcePathOrFile: PathOrFile;
-    /**
-     * A subpath of the link.
-     *
-     * Should be empty or start with `#`.
-     *
-     * @example `[[link-with-empty-subpath]]`
-     * @example `[[link-with-subpath#subpath]]`
-     * @example `[[link-with-subpath#subpath#nested-subpath]]`
-     */
-    readonly subpath?: string;
-    /**
-     * A target path or file.
-     */
-    readonly targetPathOrFile: PathOrFile;
-}
-/**
- * Options for {@link generateRawMarkdownLink}.
- */
-export interface GenerateRawMarkdownLinkParams {
-    /**
-     * An alias of the link. Defaults to `undefined`.
-     */
-    readonly alias?: string | undefined;
-    /**
-     * Whether the link should be an embed link. Defaults to `false`.
-     */
-    readonly isEmbed?: boolean;
-    /**
-     * Whether the link should be a wikilink.
-     */
-    readonly isWikilink: boolean;
-    /**
-     * Whether to escape the alias. Applicable only if {@link isWikilink} is `false`. Defaults to `false`.
-     */
-    readonly shouldEscapeAlias?: boolean;
-    /**
-     * Whether to use angle brackets. Applicable only if {@link isWikilink} is `false`. Defaults to `false`.
-     */
-    readonly shouldUseAngleBrackets?: boolean;
-    /**
-     * A title of the link.
-     */
-    readonly title?: string;
-    /**
-     * An URL of the link.
-     */
-    readonly url: string;
-}
-/**
- * A result of parsing a link.
- */
-export interface ParseLinkResult {
-    /**
-     * An alias of the link.
-     *
-     * @example
-     * ```
-     * [\*alias\*](link.md) -> \*alias\*
-     * ```
-     */
-    alias?: string;
-    /**
-     * An encoded URL of the link.
-     *
-     * @example
-     * ```
-     * [alias](<link with space.md>) -> link%20with%20space.md
-     * ```
-     */
-    encodedUrl?: string;
-    /**
-     * An end offset of the link in the original text.
-     */
-    endOffset: number;
-    /**
-     * Indicates if the link has angle brackets.
-     *
-     * @example
-     * ```
-     * [alias](<link.md>) -> true
-     * [alias](link.md) -> false
-     * ```
-     */
-    hasAngleBrackets?: boolean;
-    /**
-     * Indicates if the link is an embed link.
-     *
-     * @example
-     * ```
-     * ![[alias]] -> true
-     * [[alias]] -> false
-     * ```
-     */
-    isEmbed: boolean;
-    /**
-     * Indicates if the link is external.
-     *
-     * @example
-     * ```
-     * [alias](https://example.com) -> true
-     * [alias](file.md) -> false
-     * ```
-     */
-    isExternal: boolean;
-    /**
-     * Indicates if the link is a wikilink.
-     *
-     * @example
-     * ```
-     * [[alias]] -> true
-     * [alias](link.md) -> false
-     * ```
-     */
-    isWikilink: boolean;
-    /**
-     * A raw link text.
-     *
-     * @example
-     * ```
-     * [alias](link.md) -> [alias](link.md)
-     * ```
-     */
-    raw: string;
-    /**
-     * A start offset of the link in the original text.
-     */
-    startOffset: number;
-    /**
-     * A title of the link.
-     *
-     * @example
-     * ```
-     * [alias](link.md "title") -> title
-     * ```
-     */
-    title?: string;
-    /**
-     * An unescaped alias of the link.
-     *
-     * @example
-     * ```
-     * [\*alias\*](link.md) -> *alias*
-     * ```
-     */
-    unescapedAlias?: string;
-    /**
-     * An URL of the link.
-     *
-     * @example
-     * ```
-     * [alias](link%20with%20space.md) -> link with space.md
-     * ```
-     */
-    url: string;
-}
-/**
- * Options for {@link shouldResetAlias}.
- */
-export interface ShouldResetAliasParams {
-    /**
-     * An Obsidian app instance.
-     */
-    readonly app: App;
-    /**
-     * A display text of the link.
-     */
-    readonly displayText: string | undefined;
-    /**
-     * Indicates if the link is a wikilink.
-     */
-    readonly isWikilink?: boolean;
-    /**
-     * A source path of the link.
-     */
-    readonly newSourcePathOrFile: PathOrFile;
-    /**
-     * An old source file containing the link.
-     */
-    readonly oldSourcePathOrFile?: PathOrFile;
-    /**
-     * An old target path of the link.
-     */
-    readonly oldTargetPath: PathOrFile;
-    /**
-     * A target path or file.
-     */
-    readonly targetPathOrFile: PathOrFile;
-}
-/**
- * Splits a link into its link path and subpath.
- */
-export interface SplitSubpathResult {
-    /**
-     * A link path.
-     */
-    linkPath: string;
-    /**
-     * A subpath.
-     */
-    subpath: string;
-}
-/**
- * Options for {@link updateLink}.
- */
-export interface UpdateLinkParams {
-    /**
-     * An Obsidian app instance.
-     */
-    readonly app: App;
-    /**
-     * A reference for the link.
-     */
-    readonly link: Reference;
-    /**
-     * Whether to force markdown links.
-     */
-    readonly linkStyle?: LinkStyle;
-    /**
-     * A source file containing the link.
-     */
-    readonly newSourcePathOrFile: PathOrFile;
-    /**
-     * A file associated with the link.
-     */
-    readonly newTargetPathOrFile: PathOrFile;
-    /**
-     * An old source file containing the link.
-     */
-    readonly oldSourcePathOrFile?: PathOrFile;
-    /**
-     * An old path of the file.
-     */
-    readonly oldTargetPathOrFile?: PathOrFile;
-    /**
-     * Whether to update file name alias. Defaults to `true`.
-     */
-    readonly shouldUpdateFileNameAlias?: boolean;
-}
-/**
- * Options for {@link updateLinksInFile}.
- */
-export interface UpdateLinksInFileParams extends ProcessOptions {
-    /**
-     * An Obsidian app instance.
-     */
-    readonly app: App;
-    /**
-     * A style of the link.
-     */
-    readonly linkStyle?: LinkStyle;
-    /**
-     * A file to update the links in.
-     */
-    readonly newSourcePathOrFile: PathOrFile;
-    /**
-     * An old path of the file.
-     */
-    readonly oldSourcePathOrFile?: PathOrFile;
-    /**
-     * Whether to update only embedded links.
-     */
-    readonly shouldUpdateEmbedOnlyLinks?: boolean;
-    /**
-     * Whether to update file name alias. Defaults to `true`.
-     */
-    readonly shouldUpdateFileNameAlias?: boolean;
-}
-/**
- * Options for {@link updateLinksInContent}.
- */
-interface UpdateLinksInContentParams {
-    /**
-     * An Obsidian app instance.
-     */
-    readonly app: App;
-    /**
-     * A content to update the links in.
-     */
-    readonly content: string;
-    /**
-     * A style of the link.
-     */
-    readonly linkStyle?: LinkStyle;
-    /**
-     * A new source path or file.
-     */
-    readonly newSourcePathOrFile: PathOrFile;
-    /**
-     * An old source path or file.
-     */
-    readonly oldSourcePathOrFile?: PathOrFile;
-    /**
-     * Whether to update only embedded links.
-     */
-    readonly shouldUpdateEmbedOnlyLinks?: boolean;
-    /**
-     * Whether to update file name alias.
-     */
-    readonly shouldUpdateFileNameAlias?: boolean;
-}
-/**
- * Converts a link to a new path.
- *
- * @param params - The parameters for converting the link.
- * @returns The converted link.
- */
-export declare function convertLink(params: ConvertLinkParams): 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 {@link Promise} that resolves when the backlinks have been edited.
- */
-export declare function editBacklinks(app: App, pathOrFile: PathOrFile, linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>, 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 {@link Promise} that resolves when the backlinks have been edited.
- */
-export declare function editLinks(app: App, pathOrFile: PathOrFile, linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>, processOptions?: ProcessOptions): Promise<void>;
-/**
- * Edits the links in a content string.
- *
- * @param app - The Obsidian application instance.
- * @param content - The content to edit the links in.
- * @param linkConverter - The function that converts each link.
- * @param abortSignal - The abort signal to control the execution of the function.
- * @returns The promise that resolves to the updated content.
- */
-export declare function editLinksInContent(app: App, content: string, linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>, abortSignal?: AbortSignal): Promise<string>;
-/**
- * Encodes a URL.
- *
- * @param url - The URL to encode.
- * @returns The encoded URL.
- */
-export declare function encodeUrl(url: string): string;
-/**
- * Escapes the alias of a markdown link.
- *
- * @param alias - An alias of a markdown link.
- * @returns An escaped alias.
- *
- * @example
- * ```ts
- * escapeAlias('**alias**') // '\\*\\*alias\\*\\*'
- * ```
- */
-export declare function escapeAlias(alias: string): string;
-/**
- * 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.
- * @param shouldAllowNonExistingFile - Whether to allow non-existing files. Defaults to `false`.
- * @returns The file associated with the link, or null if not found.
- */
-export declare function extractLinkFile(app: App, link: Reference, sourcePathOrFile: PathOrFile, shouldAllowNonExistingFile?: boolean): null | TFile;
-/**
- * Fixes the frontmatter markdown links in the provided metadata cache.
- *
- * @param cache - The metadata cache to fix the frontmatter markdown links in.
- * @returns Whether the frontmatter markdown links were fixed.
- */
-export declare function fixFrontmatterMarkdownLinks(cache: CachedMetadata): boolean;
-/**
- * Generates a markdown link based on the provided parameters.
- *
- * @param params - The parameters for generating the markdown link.
- * @returns The generated markdown link.
- */
-export declare function generateMarkdownLink(params: GenerateMarkdownLinkParams): string;
-/**
- * Generates a raw markdown link based on the provided options.
- *
- * @param params - The parameters for generating a raw markdown link.
- * @returns A raw markdown link.
- */
-export declare function generateRawMarkdownLink(params: GenerateRawMarkdownLinkParams): 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;
-/**
- * Parses all links in a string.
- *
- * @param str - The string to parse the links in.
- * @returns The parsed links.
- */
-export declare function parseLinks(str: string): ParseLinkResult[];
-/**
- * Registers a function that returns default options for generating a markdown link.
- *
- * @param plugin - The plugin instance.
- * @param fn - The function that returns the default options.
- */
-export declare function registerGenerateMarkdownLinkDefaultOptionsFn(plugin: Plugin, fn: () => Partial<GenerateMarkdownLinkParams>): void;
-/**
- * Determines if the alias of a link should be reset.
- *
- * @param params - The parameters for determining if the alias should be reset.
- * @returns Whether the alias should be reset.
- */
-export declare function shouldResetAlias(params: ShouldResetAliasParams): 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 has a leading slash, possibly embed:
- * `[[/link]]`, `[title](/link)`, `[title](</link>)`,
- * `![[/link]]`, `![title](/link)`, `![title](</link>)`.
- *
- * @param link - Link to test
- * @returns Whether the link has a leading slash
- */
-export declare function testLeadingSlash(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;
-/**
- * Unescapes the alias of a markdown link.
- *
- * @param escapedAlias - An escaped alias.
- * @returns An unescaped alias.
- *
- * @example
- * ```ts
- * unescapeAlias('\\*\\*alias\\*\\*') // '**alias**'
- * ```
- */
-export declare function unescapeAlias(escapedAlias: string): string;
-/**
- * Updates a link based on the provided parameters.
- *
- * @param params - The parameters for updating the link.
- * @returns The updated link.
- */
-export declare function updateLink(params: UpdateLinkParams): string;
-/**
- * Updates the links in a content string based on the provided parameters.
- *
- * @param params - The parameters for updating the links.
- * @returns A {@link Promise} that resolves to the content with updated links.
- */
-export declare function updateLinksInContent(params: UpdateLinksInContentParams): Promise<string>;
-/**
- * Updates the links in a file based on the provided parameters.
- *
- * @param params - The parameters for updating the links.
- * @returns A {@link Promise} that resolves when the links are updated.
- */
-export declare function updateLinksInFile(params: UpdateLinksInFileParams): Promise<void>;
-export {};