@mnaoumov/obsidian-lib 0.0.0 → 1.0.0

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

@@ -0,0 +1,1369 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * 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 { MaybeReturn } from '@mnaoumov/typescript-lib/type';
+import type { App, Reference, TFile } from 'obsidian';
+import type { Promisable } from 'type-fest';
+import type { PathOrFile } from './file-system.mjs';
+import type { LinkUpdateProgressReporter } from './link-update-progress.mjs';
+import type { OffsetRange } from './reference.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"
+}
+/**
+ * Params passed to the link converter of {@link editBacklinksSnapshot}.
+ *
+ * @typeParam TPayload - The payload recorded for each link when the snapshot was built.
+ */
+export interface BacklinkConversionParams<TPayload> {
+    /**
+     * The link being converted.
+     */
+    readonly link: Reference;
+    /**
+     * The payload captured for the link when the snapshot was built.
+     *
+     * `undefined` when the link is not in the snapshot, which can only happen if
+     * {@link EditBacklinksSnapshotParams.shouldVisitUnmatchedLinks} is `true`.
+     */
+    readonly payload: TPayload | undefined;
+    /**
+     * The path of the note holding the link.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * The minimal shape {@link buildBacklinksSnapshot} reads a set of backlinks from.
+ *
+ * Both a `CustomArrayDict<Reference>` — what
+ * {@link ../obsidian/metadata-cache!getBacklinksForFileSafe | getBacklinksForFileSafe} returns — and a plain
+ * `Map<string, Reference[]>` satisfy it, so a caller can pass either without converting first.
+ */
+export interface BacklinksLike {
+    /**
+     * Returns the links the note at `key` holds, or a nullish value when it holds none.
+     *
+     * @param key - The path of the backlink-holding note.
+     * @returns The links, or a nullish value.
+     */
+    get: (key: string) => null | readonly Reference[] | undefined;
+    /**
+     * Returns the paths of the backlink-holding notes.
+     *
+     * @returns The paths.
+     */
+    keys: () => Iterable<string>;
+}
+/**
+ * A captured snapshot of a set of backlinks: the path of each backlink-holding note, mapped to the identity
+ * keys of that note's own links to the target(s), each mapped to the payload recorded for it.
+ *
+ * The snapshot exists so that the fetch and the rewrite can happen at different moments. A rename invalidates
+ * the metadata cache for the old path, so a caller that rewrites links **after** renaming has to capture the
+ * backlinks **before** — which is why {@link editBacklinksSnapshot} takes a snapshot rather than a path.
+ *
+ * The payload is whatever the caller needs to remember per link. It is `undefined` for a single-target
+ * rewrite (the target is implied), and the old target's path for a multi-target one, where one note's links
+ * may point at several files that all moved and each link has to be resolved to its own new path.
+ *
+ * @typeParam TPayload - The payload recorded for each link.
+ */
+export type BacklinksSnapshot<TPayload> = ReadonlyMap<string, ReadonlyMap<string, TPayload>>;
+/**
+ * Params for {@link buildBacklinksSnapshot}.
+ *
+ * @typeParam TPayload - The payload recorded for each link.
+ */
+export interface BuildBacklinksSnapshotParams<TPayload> {
+    /**
+     * The backlinks to record.
+     */
+    readonly backlinks: BacklinksLike;
+    /**
+     * Computes the identity key of a link.
+     *
+     * The snapshot remembers it, so {@link editBacklinksSnapshot} looks the links up with the same function
+     * without being told. When {@link BuildBacklinksSnapshotParams.target} was built with a provider, omitting
+     * this reuses that one, and passing a different one throws: a snapshot keyed by two functions matches
+     * nothing.
+     *
+     * @default the provider `target` was built with, else `JSON.stringify`
+     */
+    readonly linkIdentityKeyProvider?: (link: Reference) => string;
+    /**
+     * Rewrites the path of a backlink-holding note as it will be **after** the operation.
+     *
+     * A note that holds a backlink can itself be renamed or moved by the same operation — including the
+     * renamed note's own self-links. Remapping here keys the snapshot by the path the rewrite will actually
+     * open.
+     *
+     * @default the identity function
+     */
+    readonly pathRemapper?: (backlinkPath: string) => string;
+    /**
+     * Produces the payload to record for a link. See {@link BacklinksSnapshot} for what a payload is for.
+     *
+     * @param link - The link being recorded.
+     * @returns The payload.
+     */
+    readonly payloadProvider: (link: Reference) => TPayload;
+    /**
+     * An existing snapshot to merge into, so several sets of backlinks can be accumulated into one.
+     *
+     * Merging is what makes a single rewrite pass per note possible when a note links to several moved
+     * targets: without it, calling the rewrite once per target would open — and write — the same note
+     * repeatedly.
+     *
+     * When omitted, a new snapshot is created.
+     */
+    readonly target?: MutableBacklinksSnapshot<TPayload>;
+}
+/**
+ * Params for {@link convertLink}.
+ */
+export interface ConvertLinkParams {
+    /**
+     * An Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * Whether to allow an empty alias for embeds.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `![](foo.png)`.
+     *
+     * If `false`: `![foo](foo.png)`.
+     *
+     * @default `true`
+     */
+    readonly isEmptyEmbedAliasAllowed?: boolean;
+    /**
+     * A reference for the link.
+     */
+    readonly link: Reference;
+    /**
+     * A style of the link path.
+     */
+    readonly linkPathStyle?: LinkPathStyle;
+    /**
+     * 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 escape the alias.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[\*\*alias\*\*](link.md)`.
+     *
+     * If `false`: `[**alias**](link.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldEscapeAlias?: boolean;
+    /**
+     * Whether to include the attachment extension in the embed alias.
+     *
+     * Applicable only if {@link isEmptyEmbedAliasAllowed} is `false`.
+     *
+     * If `true`: `[foo.png](foo.png)`.
+     *
+     * If `false`: `[foo](foo.png)`.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Whether to update file name alias.
+     *
+     * @default `true`
+     */
+    readonly shouldUpdateFileNameAlias?: boolean;
+    /**
+     * Indicates if the link should use angle brackets.
+     *
+     * Applicable only if {@link linkStyle} is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[alias](<path with spaces.md>)`.
+     *
+     * If `false`: `[alias](path%20with%20spaces.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+    /**
+     * Indicates if the link should use a leading dot.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.RelativePathToTheSource}.
+     *
+     * If `true`: `[[./relative/path/to/target]]`
+     *
+     * If `false`: `[[relative/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingDotForRelativePaths?: boolean;
+    /**
+     * Indicates if the link should use a leading slash.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.AbsolutePathInVault}.
+     *
+     * If `true`: `[[/absolute/path/to/target]]`
+     *
+     * If `false`: `[[absolute/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
+}
+/**
+ * Options for {@link editBacklinks}.
+ */
+export type EditBacklinksOptions = ProcessOptions;
+/**
+ * Parameters for {@link editBacklinks}.
+ */
+export interface EditBacklinksParams extends EditBacklinksOptions {
+    /**
+     * The Obsidian application instance.
+     */
+    readonly app: App;
+    /**
+     * The function that converts each link.
+     */
+    readonly linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>;
+    /**
+     * An optional reporter invoked once per backlink file after its links are updated, with the running
+     * count of processed files and the total. When omitted, no progress is reported.
+     */
+    readonly linkUpdateProgressReporter?: LinkUpdateProgressReporter;
+    /**
+     * The path or file to edit the backlinks for.
+     */
+    readonly pathOrFile: PathOrFile;
+}
+/**
+ * Options for {@link editBacklinksSnapshot}.
+ */
+export type EditBacklinksSnapshotOptions = ProcessOptions;
+/**
+ * Parameters for {@link editBacklinksSnapshot}.
+ *
+ * @typeParam TPayload - The payload recorded for each link when the snapshot was built.
+ */
+export interface EditBacklinksSnapshotParams<TPayload> extends EditBacklinksSnapshotOptions {
+    /**
+     * The Obsidian application instance.
+     */
+    readonly app: App;
+    /**
+     * The function that converts each link.
+     */
+    readonly linkConverter: (params: BacklinkConversionParams<TPayload>) => Promisable<MaybeReturn<string>>;
+    /**
+     * Computes the identity key of a link.
+     *
+     * Leave it out for a snapshot made by {@link buildBacklinksSnapshot}: the snapshot carries the provider it was
+     * built with, and that one is used. Passing a different one throws, because the snapshot is keyed by the
+     * other and not a single link would match — the edit would complete and rewrite nothing. It is needed only
+     * for a snapshot assembled by hand.
+     *
+     * @default the provider the snapshot was built with, else `JSON.stringify`
+     */
+    readonly linkIdentityKeyProvider?: (link: Reference) => string;
+    /**
+     * An optional reporter invoked once per backlink file after its links are updated, with the running
+     * count of processed files and the total. When omitted, no progress is reported.
+     */
+    readonly linkUpdateProgressReporter?: LinkUpdateProgressReporter;
+    /**
+     * Whether the converter is also shown links that are **not** in the snapshot, with an `undefined`
+     * {@link BacklinkConversionParams.payload}.
+     *
+     * The default filters them out, which is what a plain rename wants: a link absent from the snapshot was
+     * either never the caller's to rewrite, or has already been rewritten by someone else. Set this to `true`
+     * only when the caller has its own reason to look at them — a widened match of its own, or logging a skip
+     * that would otherwise be silent.
+     *
+     * @default `false`
+     */
+    readonly shouldVisitUnmatchedLinks?: boolean;
+    /**
+     * The captured backlinks to edit.
+     */
+    readonly snapshot: BacklinksSnapshot<TPayload>;
+}
+/**
+ * Parameters for {@link editLinksInContent}.
+ */
+export interface EditLinksInContentParams {
+    /**
+     * The abort signal to control the execution of the function.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * The Obsidian application instance.
+     */
+    readonly app: App;
+    /**
+     * The content to edit the links in.
+     */
+    readonly content: string;
+    /**
+     * The function that converts each link.
+     */
+    readonly linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>;
+    /**
+     * A range within {@link EditLinksInContentParams.content}, in character offsets, restricting the pass to
+     * the links inside it. When omitted, every link is visited.
+     *
+     * A link is edited only when it is **fully contained** in the range; one that merely overlaps it is left
+     * alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose
+     * offsets coincide exactly with a link's does include that link.
+     *
+     * A reference that carries no position within the content — a frontmatter link, a multi-link frontmatter
+     * value entry, or any canvas reference — is never in range and is skipped whenever a range is supplied.
+     *
+     * @default `undefined`
+     */
+    readonly offsetRange?: OffsetRange;
+    /**
+     * Whether to also edit external links parsed from the note body. When `true`, the converter also
+     * receives references for external links.
+     *
+     * @default `false`
+     */
+    readonly shouldEditExternalLinks?: boolean;
+    /**
+     * Whether to also edit external links parsed from frontmatter values. When `true`, the converter also
+     * receives references for frontmatter external links.
+     *
+     * @default `false`
+     */
+    readonly shouldEditFrontmatterExternalLinks?: boolean;
+    /**
+     * Whether to also edit external links parsed from multi-link (multi-value) frontmatter values. When
+     * `true`, the converter also receives references for each external link within a multi-link frontmatter
+     * value (each located by its offsets, so only that link is spliced back in place).
+     *
+     * @default `false`
+     */
+    readonly shouldEditMultiValueFrontmatterExternalLinks?: boolean;
+}
+/**
+ * Options for {@link editLinks}.
+ */
+export type EditLinksOptions = ProcessOptions;
+/**
+ * Parameters for {@link editLinks}.
+ */
+export interface EditLinksParams extends EditLinksOptions {
+    /**
+     * The Obsidian application instance.
+     */
+    readonly app: App;
+    /**
+     * The function that converts each link.
+     */
+    readonly linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>;
+    /**
+     * A range within the file's content, in character offsets, restricting the pass to the links inside it.
+     * When omitted, every link is visited.
+     *
+     * A link is edited only when it is **fully contained** in the range; one that merely overlaps it is left
+     * alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose
+     * offsets coincide exactly with a link's does include that link.
+     *
+     * A reference that carries no position within the file's content — a frontmatter link, a multi-link
+     * frontmatter value entry, or any canvas reference — is never in range and is skipped whenever a range is
+     * supplied.
+     *
+     * The offsets are into the content this function reads from the vault. Before reading, it saves any
+     * unsaved editor buffer for the file, so a range taken from an open editor via `Editor.posToOffset` is
+     * valid. The caller owns only the case where the buffer changes between computing the range and this
+     * call.
+     *
+     * @default `undefined`
+     */
+    readonly offsetRange?: OffsetRange;
+    /**
+     * The path or file to edit the links for.
+     */
+    readonly pathOrFile: PathOrFile;
+    /**
+     * Whether to also edit external links parsed from the note body. When `true`, the converter also
+     * receives references for external links.
+     *
+     * @default `false`
+     */
+    readonly shouldEditExternalLinks?: boolean;
+    /**
+     * Whether to also edit external links parsed from frontmatter values. When `true`, the converter also
+     * receives references for frontmatter external links.
+     *
+     * @default `false`
+     */
+    readonly shouldEditFrontmatterExternalLinks?: boolean;
+    /**
+     * Whether to also edit external links parsed from multi-link (multi-value) frontmatter values. When
+     * `true`, the converter also receives references for each external link within a multi-link frontmatter
+     * value (each located by its offsets, so only that link is spliced back in place).
+     *
+     * @default `false`
+     */
+    readonly shouldEditMultiValueFrontmatterExternalLinks?: boolean;
+}
+/**
+ * Parameters for {@link extractLinkFile}.
+ */
+export interface ExtractLinkFileParams {
+    /**
+     * The Obsidian application instance.
+     */
+    readonly app: App;
+    /**
+     * The reference cache for the link.
+     */
+    readonly link: Reference;
+    /**
+     * Whether to allow non-existing files.
+     *
+     * @default `false`
+     */
+    readonly shouldAllowNonExistingFile?: boolean;
+    /**
+     * The source path or file.
+     */
+    readonly sourcePathOrFile: PathOrFile;
+}
+/**
+ * Params 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.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `![](foo.png)`.
+     *
+     * If `false`: `![foo](foo.png)`.
+     *
+     * @default `true`
+     */
+    readonly isEmptyEmbedAliasAllowed?: boolean;
+    /**
+     * Whether to allow non-existing files.
+     *
+     * If `false` and {@link targetPathOrFile} is a non-existing file, an error will be thrown.
+     *
+     * @default `false`
+     */
+    readonly isNonExistingFileAllowed?: boolean;
+    /**
+     * Whether to allow a single subpath.
+     *
+     * Applicable only if {@link targetPathOrFile} and {@link sourcePathOrFile} are the same file.
+     *
+     * If `true`: `[[#subpath]]`.
+     *
+     * If `false`: `[[source#subpath]]`
+     *
+     * @default `true`
+     */
+    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 hasEmbedSyntax}
+     * - {@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.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[\*\*alias\*\*](link.md)`.
+     *
+     * If `false`: `[**alias**](link.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldEscapeAlias?: boolean;
+    /**
+     * Whether to include the attachment extension in the embed alias.
+     *
+     * Applicable only if {@link isEmptyEmbedAliasAllowed} is `false`.
+     *
+     * If `true`: `[foo.png](foo.png)`.
+     *
+     * If `false`: `[foo](foo.png)`.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Indicates if the link should use angle brackets.
+     *
+     * Applicable only if {@link linkStyle} is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[alias](<path with spaces.md>)`.
+     *
+     * If `false`: `[alias](path%20with%20spaces.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+    /**
+     * Indicates if the link should use a leading dot.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.RelativePathToTheSource}.
+     *
+     * If `true`: `[[./relative/path/to/target]]`
+     *
+     * If `false`: `[[relative/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingDotForRelativePaths?: boolean;
+    /**
+     * Indicates if the link should use a leading slash.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.AbsolutePathInVault}.
+     *
+     * If `true`: `[[/absolute/path/to/target]]`
+     *
+     * If `false`: `[[absolute/path/to/target]]`
+     *
+     * @default `false`
+     */
+    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]]`
+     * @default `''`
+     */
+    readonly subpath?: string;
+    /**
+     * A target path or file.
+     */
+    readonly targetPathOrFile: PathOrFile;
+}
+/**
+ * Params 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.
+     *
+     * @default `false`
+     */
+    readonly isEmbed?: boolean;
+    /**
+     * Whether the link should be a wikilink.
+     */
+    readonly isWikilink: boolean;
+    /**
+     * Whether to escape the alias. Applicable only if {@link hasWikilinkSyntax} is `false`.
+     *
+     * @default `false`
+     */
+    readonly shouldEscapeAlias?: boolean;
+    /**
+     * Whether to use angle brackets. Applicable only if {@link hasWikilinkSyntax} is `false`.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+    /**
+     * A title of the link.
+     */
+    readonly title?: string;
+    /**
+     * An URL of the link.
+     */
+    readonly url: string;
+}
+/**
+ * A {@link BacklinksSnapshot} while it is still being accumulated by {@link buildBacklinksSnapshot}.
+ *
+ * @typeParam TPayload - The payload recorded for each link.
+ */
+export type MutableBacklinksSnapshot<TPayload> = Map<string, Map<string, TPayload>>;
+/**
+ * Params 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.
+     */
+    readonly linkPath: string;
+    /**
+     * A subpath.
+     */
+    readonly subpath: string;
+}
+/**
+ * Params for {@link updateFileUrlLinksInContent}.
+ */
+export interface UpdateFileUrlLinksInContentParams {
+    /**
+     * The abort signal to control the execution of the function.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * An Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * The content to normalize the `file://` links in.
+     */
+    readonly content: string;
+    /**
+     * A range within {@link UpdateFileUrlLinksInContentParams.content}, in character offsets, restricting
+     * the pass to the links inside it. When omitted, every link is visited.
+     *
+     * A link is normalized only when it is **fully contained** in the range; one that merely overlaps it is
+     * left alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose
+     * offsets coincide exactly with a link's does include that link.
+     *
+     * A reference that carries no position within the content — a frontmatter link, a multi-link frontmatter
+     * value entry, or any canvas reference — is never in range and is skipped whenever a range is supplied.
+     *
+     * @default `undefined`
+     */
+    readonly offsetRange?: OffsetRange;
+    /**
+     * Whether to emit the normalized links with angle brackets and raw spaces instead of `%20`-encoding.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+}
+/**
+ * Params for {@link updateFileUrlLinksInFile}.
+ */
+export interface UpdateFileUrlLinksInFileParams extends ProcessOptions {
+    /**
+     * An Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * A range within the file's content, in character offsets, restricting the pass to the links inside it.
+     * When omitted, every link is visited.
+     *
+     * A link is normalized only when it is **fully contained** in the range; one that merely overlaps it is
+     * left alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose
+     * offsets coincide exactly with a link's does include that link.
+     *
+     * A reference that carries no position within the file's content — a frontmatter link, a multi-link
+     * frontmatter value entry, or any canvas reference — is never in range and is skipped whenever a range is
+     * supplied.
+     *
+     * The offsets are into the content this function reads from the vault. Before reading, it saves any
+     * unsaved editor buffer for the file, so a range taken from an open editor via `Editor.posToOffset` is
+     * valid. The caller owns only the case where the buffer changes between computing the range and this
+     * call.
+     *
+     * @default `undefined`
+     */
+    readonly offsetRange?: OffsetRange;
+    /**
+     * The path or file to normalize the `file://` links in.
+     */
+    readonly pathOrFile: PathOrFile;
+    /**
+     * Whether to emit the normalized links with angle brackets and raw spaces instead of `%20`-encoding.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+}
+/**
+ * Params for {@link updateLink}.
+ */
+export interface UpdateLinkParams {
+    /**
+     * An Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * Whether to allow an empty alias for embeds.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `![](foo.png)`.
+     *
+     * If `false`: `![foo](foo.png)`.
+     *
+     * @default `true`
+     */
+    readonly isEmptyEmbedAliasAllowed?: boolean;
+    /**
+     * A reference for the link.
+     */
+    readonly link: Reference;
+    /**
+     * A style of the link path.
+     */
+    readonly linkPathStyle?: LinkPathStyle;
+    /**
+     * 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 escape the alias.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[\*\*alias\*\*](link.md)`.
+     *
+     * If `false`: `[**alias**](link.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldEscapeAlias?: boolean;
+    /**
+     * Whether to include the attachment extension in the embed alias.
+     *
+     * Applicable only if {@link isEmptyEmbedAliasAllowed} is `false`.
+     *
+     * If `true`: `[foo.png](foo.png)`.
+     *
+     * If `false`: `[foo](foo.png)`.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Whether to update file name alias.
+     *
+     * @default `true`
+     */
+    readonly shouldUpdateFileNameAlias?: boolean;
+    /**
+     * Indicates if the link should use angle brackets.
+     *
+     * Applicable only if {@link linkStyle} is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[alias](<path with spaces.md>)`.
+     *
+     * If `false`: `[alias](path%20with%20spaces.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+    /**
+     * Indicates if the link should use a leading dot.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.RelativePathToTheSource}.
+     *
+     * If `true`: `[[./relative/path/to/target]]`
+     *
+     * If `false`: `[[relative/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingDotForRelativePaths?: boolean;
+    /**
+     * Indicates if the link should use a leading slash.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.AbsolutePathInVault}.
+     *
+     * If `true`: `[[/absolute/path/to/target]]`
+     *
+     * If `false`: `[[absolute/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
+}
+/**
+ * Params for {@link updateLinksInFile}.
+ */
+export interface UpdateLinksInFileParams extends ProcessOptions {
+    /**
+     * An Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * Whether to allow an empty alias for embeds.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `![](foo.png)`.
+     *
+     * If `false`: `![foo](foo.png)`.
+     *
+     * @default `true`
+     */
+    readonly isEmptyEmbedAliasAllowed?: boolean;
+    /**
+     * A style of the link path.
+     */
+    readonly linkPathStyle?: LinkPathStyle;
+    /**
+     * A style of the link.
+     */
+    readonly linkStyle?: LinkStyle;
+    /**
+     * A file to update the links in.
+     */
+    readonly newSourcePathOrFile: PathOrFile;
+    /**
+     * A range within the file's content, in character offsets, restricting the pass to the links inside it.
+     * When omitted, every link is visited.
+     *
+     * A link is updated only when it is **fully contained** in the range; one that merely overlaps it is left
+     * alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose
+     * offsets coincide exactly with a link's does include that link.
+     *
+     * A reference that carries no position within the file's content — a frontmatter link, a multi-link
+     * frontmatter value entry, or any canvas reference — is never in range and is skipped whenever a range is
+     * supplied.
+     *
+     * The offsets are into the content this function reads from the vault. Before reading, it saves any
+     * unsaved editor buffer for the file, so a range taken from an open editor via `Editor.posToOffset` is
+     * valid. The caller owns only the case where the buffer changes between computing the range and this
+     * call.
+     *
+     * @default `undefined`
+     */
+    readonly offsetRange?: OffsetRange;
+    /**
+     * An old path of the file.
+     */
+    readonly oldSourcePathOrFile?: PathOrFile;
+    /**
+     * Whether to escape the alias.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[\*\*alias\*\*](link.md)`.
+     *
+     * If `false`: `[**alias**](link.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldEscapeAlias?: boolean;
+    /**
+     * Whether to include the attachment extension in the embed alias.
+     *
+     * Applicable only if {@link isEmptyEmbedAliasAllowed} is `false`.
+     *
+     * If `true`: `[foo.png](foo.png)`.
+     *
+     * If `false`: `[foo](foo.png)`.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Whether to update only embedded links.
+     */
+    readonly shouldUpdateEmbedOnlyLinks?: boolean;
+    /**
+     * Whether to update file name alias.
+     *
+     * @default `true`
+     */
+    readonly shouldUpdateFileNameAlias?: boolean;
+    /**
+     * Indicates if the link should use angle brackets.
+     *
+     * Applicable only if {@link linkStyle} is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[alias](<path with spaces.md>)`.
+     *
+     * If `false`: `[alias](path%20with%20spaces.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+    /**
+     * Indicates if the link should use a leading dot.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.RelativePathToTheSource}.
+     *
+     * If `true`: `[[./relative/path/to/target]]`
+     *
+     * If `false`: `[[relative/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingDotForRelativePaths?: boolean;
+    /**
+     * Indicates if the link should use a leading slash.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.AbsolutePathInVault}.
+     *
+     * If `true`: `[[/absolute/path/to/target]]`
+     *
+     * If `false`: `[[absolute/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
+}
+/**
+ * Params for {@link updateLinksInContent}.
+ */
+interface UpdateLinksInContentParams {
+    /**
+     * An Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * A content to update the links in.
+     */
+    readonly content: string;
+    /**
+     * Whether to allow an empty alias for embeds.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `![](foo.png)`.
+     *
+     * If `false`: `![foo](foo.png)`.
+     *
+     * @default `true`
+     */
+    readonly isEmptyEmbedAliasAllowed?: boolean;
+    /**
+     * A style of the link path.
+     */
+    readonly linkPathStyle?: LinkPathStyle;
+    /**
+     * A style of the link.
+     */
+    readonly linkStyle?: LinkStyle;
+    /**
+     * A new source path or file.
+     */
+    readonly newSourcePathOrFile: PathOrFile;
+    /**
+     * A range within {@link UpdateLinksInContentParams.content}, in character offsets, restricting the pass
+     * to the links inside it. When omitted, every link is visited.
+     *
+     * A link is updated only when it is **fully contained** in the range; one that merely overlaps it is left
+     * alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose
+     * offsets coincide exactly with a link's does include that link.
+     *
+     * A reference that carries no position within the content — a frontmatter link, a multi-link frontmatter
+     * value entry, or any canvas reference — is never in range and is skipped whenever a range is supplied.
+     *
+     * @default `undefined`
+     */
+    readonly offsetRange?: OffsetRange;
+    /**
+     * An old source path or file.
+     */
+    readonly oldSourcePathOrFile?: PathOrFile;
+    /**
+     * Whether to escape the alias.
+     *
+     * Applicable only if the result link style is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[\*\*alias\*\*](link.md)`.
+     *
+     * If `false`: `[**alias**](link.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldEscapeAlias?: boolean;
+    /**
+     * Whether to include the attachment extension in the embed alias.
+     *
+     * Applicable only if {@link isEmptyEmbedAliasAllowed} is `false`.
+     *
+     * If `true`: `[foo.png](foo.png)`.
+     *
+     * If `false`: `[foo](foo.png)`.
+     *
+     * @default `false`
+     */
+    readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Whether to update only embedded links.
+     */
+    readonly shouldUpdateEmbedOnlyLinks?: boolean;
+    /**
+     * Whether to update file name alias.
+     *
+     * @default `true`
+     */
+    readonly shouldUpdateFileNameAlias?: boolean;
+    /**
+     * Indicates if the link should use angle brackets.
+     *
+     * Applicable only if {@link linkStyle} is {@link LinkStyle.Markdown}.
+     *
+     * If `true`: `[alias](<path with spaces.md>)`.
+     *
+     * If `false`: `[alias](path%20with%20spaces.md)`.
+     *
+     * @default `false`
+     */
+    readonly shouldUseAngleBrackets?: boolean;
+    /**
+     * Indicates if the link should use a leading dot.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.RelativePathToTheSource}.
+     *
+     * If `true`: `[[./relative/path/to/target]]`
+     *
+     * If `false`: `[[relative/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingDotForRelativePaths?: boolean;
+    /**
+     * Indicates if the link should use a leading slash.
+     *
+     * Applicable only if {@link linkPathStyle} is {@link LinkPathStyle.AbsolutePathInVault}.
+     *
+     * If `true`: `[[/absolute/path/to/target]]`
+     *
+     * If `false`: `[[absolute/path/to/target]]`
+     *
+     * @default `false`
+     */
+    readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
+}
+/**
+ * Records a set of backlinks into a snapshot that {@link editBacklinksSnapshot} can rewrite later.
+ *
+ * Call it once per target and pass {@link BuildBacklinksSnapshotParams.target} to accumulate several targets
+ * into one snapshot, so that a note linking to several of them is still rewritten exactly once.
+ *
+ * @typeParam TPayload - The payload recorded for each link.
+ * @param params - The parameters for building the snapshot.
+ * @returns The snapshot — {@link BuildBacklinksSnapshotParams.target} itself when one was passed.
+ */
+export declare function buildBacklinksSnapshot<TPayload>(params: BuildBacklinksSnapshotParams<TPayload>): MutableBacklinksSnapshot<TPayload>;
+/**
+ * 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 params - The parameters for editing the backlinks.
+ * @returns A {@link Promise} that resolves when the backlinks have been edited.
+ */
+export declare function editBacklinks(params: EditBacklinksParams): Promise<void>;
+/**
+ * Edits a captured snapshot of backlinks, rewriting each backlink-holding note exactly once.
+ *
+ * The counterpart of {@link editBacklinks} for callers that cannot fetch the backlinks at rewrite time —
+ * because the rename that invalidated them has already happened — or that rewrite links to several targets
+ * at once. See {@link BacklinksSnapshot} for both cases.
+ *
+ * @typeParam TPayload - The payload recorded for each link when the snapshot was built.
+ * @param params - The parameters for editing the backlinks.
+ * @returns A {@link Promise} that resolves when the backlinks have been edited.
+ */
+export declare function editBacklinksSnapshot<TPayload>(params: EditBacklinksSnapshotParams<TPayload>): Promise<void>;
+/**
+ * Edits the links for a file or path.
+ *
+ * @param params - The parameters for editing the links.
+ * @returns A {@link Promise} that resolves when the links have been edited.
+ */
+export declare function editLinks(params: EditLinksParams): Promise<void>;
+/**
+ * Edits the links in a content string.
+ *
+ * @param params - The parameters for editing the links in the content.
+ * @returns The promise that resolves to the updated content.
+ */
+export declare function editLinksInContent(params: EditLinksInContentParams): Promise<string>;
+/**
+ * Extracts the file associated with a link.
+ *
+ * @param params - The parameters for extracting the link file.
+ * @returns The file associated with the link, or `null` if not found.
+ */
+export declare function extractLinkFile(params: ExtractLinkFileParams): null | TFile;
+/**
+ * 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 params.
+ *
+ * @param params - The parameters for generating a raw markdown link.
+ * @returns A raw markdown link.
+ */
+export declare function generateRawMarkdownLink(params: GenerateRawMarkdownLinkParams): string;
+/**
+ * Returns the shared, mutable list of functions that provide default params for {@link generateMarkdownLink}.
+ *
+ * Each function is invoked on every {@link generateMarkdownLink} call and its result is merged into the params (later
+ * registrations take precedence over the built-in defaults, but never over explicitly passed params). Register entries
+ * by adding a `GenerateMarkdownLinkDefaultParamsComponent` to a component tree rather than mutating this list directly.
+ *
+ * @returns The mutable list of default-params functions.
+ */
+export declare function getGenerateMarkdownLinkDefaultParamsFns(): (() => Partial<GenerateMarkdownLinkParams>)[];
+/**
+ * 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 hasAngleBrackets(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 hasEmbedSyntax(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 hasLeadingDot(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 hasLeadingSlash(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 hasWikilinkSyntax(link: string): boolean;
+/**
+ * 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;
+/**
+ * Normalizes the `file://` links in a content string to a pretty form, converting backslashes to forward
+ * slashes. Other links are left unchanged.
+ *
+ * @param params - The parameters for normalizing the links.
+ * @returns A {@link Promise} that resolves to the content with normalized `file://` links.
+ */
+export declare function updateFileUrlLinksInContent(params: UpdateFileUrlLinksInContentParams): Promise<string>;
+/**
+ * Normalizes the `file://` links in a file to a pretty form, converting backslashes to forward slashes.
+ * Other links are left unchanged.
+ *
+ * @param params - The parameters for normalizing the links.
+ * @returns A {@link Promise} that resolves when the links are normalized.
+ */
+export declare function updateFileUrlLinksInFile(params: UpdateFileUrlLinksInFileParams): Promise<void>;
+/**
+ * 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 {};