@mnaoumov/obsidian-lib 8.0.0 → 9.0.0

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

@@ -72,17 +72,17 @@ export declare enum LinkStyle {
  * @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`.
+     * {@link EditBacklinksSnapshotParams.shouldVisitUnmatchedReferences} is `true`.
      */
     readonly payload: TPayload | undefined;
+    /**
+     * The reference being converted.
+     */
+    readonly reference: Reference;
     /**
      * The path of the note holding the link.
      */
@@ -135,17 +135,6 @@ 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.
      *
@@ -163,6 +152,17 @@ export interface BuildBacklinksSnapshotParams<TPayload> {
      * @returns The payload.
      */
     readonly payloadProvider: (link: Reference) => TPayload;
+    /**
+     * 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 referenceIdentityKeyProvider?: (link: Reference) => string;
     /**
      * An existing snapshot to merge into, so several sets of backlinks can be accumulated into one.
      *
@@ -194,10 +194,6 @@ export interface ConvertLinkParams {
      * @default `true`
      */
     readonly isEmptyEmbedAliasAllowed?: boolean;
-    /**
-     * A reference for the link.
-     */
-    readonly link: Reference;
     /**
      * A style of the link path.
      */
@@ -214,6 +210,10 @@ export interface ConvertLinkParams {
      * An old path of the link.
      */
     readonly oldSourcePathOrFile?: PathOrFile;
+    /**
+     * The reference whose link is converted.
+     */
+    readonly reference: Reference;
     /**
      * Whether to escape the alias.
      *
@@ -293,10 +293,6 @@ 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.
@@ -306,6 +302,10 @@ export interface EditBacklinksParams extends EditBacklinksOptions {
      * The path or file to edit the backlinks for.
      */
     readonly pathOrFile: PathOrFile;
+    /**
+     * The function that converts each link.
+     */
+    readonly referenceConverter: (link: Reference) => Promisable<MaybeReturn<string>>;
 }
 /**
  * Options for {@link editBacklinksSnapshot}.
@@ -321,10 +321,15 @@ export interface EditBacklinksSnapshotParams<TPayload> extends EditBacklinksSnap
      * The Obsidian application instance.
      */
     readonly app: App;
+    /**
+     * 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 function that converts each link.
      */
-    readonly linkConverter: (params: BacklinkConversionParams<TPayload>) => Promisable<MaybeReturn<string>>;
+    readonly referenceConverter: (params: BacklinkConversionParams<TPayload>) => Promisable<MaybeReturn<string>>;
     /**
      * Computes the identity key of a link.
      *
@@ -335,12 +340,7 @@ export interface EditBacklinksSnapshotParams<TPayload> extends EditBacklinksSnap
      *
      * @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;
+    readonly referenceIdentityKeyProvider?: (link: Reference) => string;
     /**
      * Whether the converter is also shown links that are **not** in the snapshot, with an `undefined`
      * {@link BacklinkConversionParams.payload}.
@@ -352,16 +352,16 @@ export interface EditBacklinksSnapshotParams<TPayload> extends EditBacklinksSnap
      *
      * @default `false`
      */
-    readonly shouldVisitUnmatchedLinks?: boolean;
+    readonly shouldVisitUnmatchedReferences?: boolean;
     /**
      * The captured backlinks to edit.
      */
     readonly snapshot: BacklinksSnapshot<TPayload>;
 }
 /**
- * Parameters for {@link editLinksInContent}.
+ * Parameters for {@link editReferencesInContent}.
  */
-export interface EditLinksInContentParams {
+export interface EditReferencesInContentParams {
     /**
      * The abort signal to control the execution of the function.
      */
@@ -375,11 +375,7 @@ export interface EditLinksInContentParams {
      */
     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
+     * A range within {@link EditReferencesInContentParams.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
@@ -392,6 +388,10 @@ export interface EditLinksInContentParams {
      * @default `undefined`
      */
     readonly offsetRange?: OffsetRange;
+    /**
+     * The function that converts each link.
+     */
+    readonly referenceConverter: (link: Reference) => Promisable<MaybeReturn<string>>;
     /**
      * Whether to also edit external links parsed from the note body. When `true`, the converter also
      * receives references for external links.
@@ -414,23 +414,27 @@ export interface EditLinksInContentParams {
      * @default `false`
      */
     readonly shouldEditMultiValueFrontmatterExternalLinks?: boolean;
+    /**
+     * Whether to leave every link inside a heading unchanged: the converter is not called for it, so it stays
+     * byte-for-byte as written. A link in a heading is part of the heading's text, so rewriting it changes
+     * that text and breaks every `#heading` subpath pointing at the heading. See {@link isReferenceInHeading}.
+     *
+     * @default `false`
+     */
+    readonly shouldSkipReferencesInHeadings?: boolean;
 }
 /**
- * Options for {@link editLinks}.
+ * Options for {@link editReferences}.
  */
-export type EditLinksOptions = ProcessOptions;
+export type EditReferencesOptions = ProcessOptions;
 /**
- * Parameters for {@link editLinks}.
+ * Parameters for {@link editReferences}.
  */
-export interface EditLinksParams extends EditLinksOptions {
+export interface EditReferencesParams extends EditReferencesOptions {
     /**
      * 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.
@@ -455,6 +459,10 @@ export interface EditLinksParams extends EditLinksOptions {
      * The path or file to edit the links for.
      */
     readonly pathOrFile: PathOrFile;
+    /**
+     * The function that converts each link.
+     */
+    readonly referenceConverter: (link: Reference) => Promisable<MaybeReturn<string>>;
     /**
      * Whether to also edit external links parsed from the note body. When `true`, the converter also
      * receives references for external links.
@@ -477,19 +485,27 @@ export interface EditLinksParams extends EditLinksOptions {
      * @default `false`
      */
     readonly shouldEditMultiValueFrontmatterExternalLinks?: boolean;
+    /**
+     * Whether to leave every link inside a heading unchanged: the converter is not called for it, so it stays
+     * byte-for-byte as written. A link in a heading is part of the heading's text, so rewriting it changes
+     * that text and breaks every `#heading` subpath pointing at the heading. See {@link isReferenceInHeading}.
+     *
+     * @default `false`
+     */
+    readonly shouldSkipReferencesInHeadings?: boolean;
 }
 /**
- * Parameters for {@link extractLinkFile}.
+ * Parameters for {@link extractReferenceFile}.
  */
-export interface ExtractLinkFileParams {
+export interface ExtractReferenceFileParams {
     /**
      * The Obsidian application instance.
      */
     readonly app: App;
     /**
-     * The reference cache for the link.
+     * The reference to resolve.
      */
-    readonly link: Reference;
+    readonly reference: Reference;
     /**
      * Whether to allow non-existing files.
      *
@@ -779,6 +795,13 @@ export interface UpdateFileUrlLinksInContentParams {
      * @default `undefined`
      */
     readonly offsetRange?: OffsetRange;
+    /**
+     * Whether to leave every link inside a heading unchanged. See
+     * {@link EditReferencesInContentParams.shouldSkipReferencesInHeadings}.
+     *
+     * @default `false`
+     */
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to emit the normalized links with angle brackets and raw spaces instead of `%20`-encoding.
      *
@@ -818,6 +841,12 @@ export interface UpdateFileUrlLinksInFileParams extends ProcessOptions {
      * The path or file to normalize the `file://` links in.
      */
     readonly pathOrFile: PathOrFile;
+    /**
+     * Whether to leave every link inside a heading unchanged. See {@link EditReferencesParams.shouldSkipReferencesInHeadings}.
+     *
+     * @default `false`
+     */
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to emit the normalized links with angle brackets and raw spaces instead of `%20`-encoding.
      *
@@ -845,10 +874,6 @@ export interface UpdateLinkParams {
      * @default `true`
      */
     readonly isEmptyEmbedAliasAllowed?: boolean;
-    /**
-     * A reference for the link.
-     */
-    readonly link: Reference;
     /**
      * A style of the link path.
      */
@@ -873,6 +898,10 @@ export interface UpdateLinkParams {
      * An old path of the file.
      */
     readonly oldTargetPathOrFile?: PathOrFile;
+    /**
+     * The reference whose link is updated.
+     */
+    readonly reference: Reference;
     /**
      * Whether to escape the alias.
      *
@@ -941,9 +970,9 @@ export interface UpdateLinkParams {
     readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
 }
 /**
- * Params for {@link updateLinksInFile}.
+ * Params for {@link updateReferencesInFile}.
  */
-export interface UpdateLinksInFileParams extends ProcessOptions {
+export interface UpdateReferencesInFileParams extends ProcessOptions {
     /**
      * An Obsidian app instance.
      */
@@ -1031,6 +1060,15 @@ export interface UpdateLinksInFileParams extends ProcessOptions {
      * @default `false`
      */
     readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Whether to leave every link inside a heading unchanged: it is neither converted nor restyled, so it
+     * stays byte-for-byte as written. A link in a heading is part of the heading's text, so rewriting it
+     * changes that text and breaks every `#heading` subpath pointing at the heading. See
+     * {@link isReferenceInHeading}.
+     *
+     * @default `false`
+     */
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to update only embedded links.
      */
@@ -1079,9 +1117,9 @@ export interface UpdateLinksInFileParams extends ProcessOptions {
     readonly shouldUseLeadingSlashForAbsolutePaths?: boolean;
 }
 /**
- * Params for {@link updateLinksInContent}.
+ * Params for {@link updateReferencesInContent}.
  */
-interface UpdateLinksInContentParams {
+interface UpdateReferencesInContentParams {
     /**
      * An Obsidian app instance.
      */
@@ -1126,7 +1164,7 @@ interface UpdateLinksInContentParams {
      */
     readonly newSourcePathOrFile: PathOrFile;
     /**
-     * A range within {@link UpdateLinksInContentParams.content}, in character offsets, restricting the pass
+     * A range within {@link UpdateReferencesInContentParams.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
@@ -1167,6 +1205,15 @@ interface UpdateLinksInContentParams {
      * @default `false`
      */
     readonly shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
+    /**
+     * Whether to leave every link inside a heading unchanged: it is neither converted nor restyled, so it
+     * stays byte-for-byte as written. A link in a heading is part of the heading's text, so rewriting it
+     * changes that text and breaks every `#heading` subpath pointing at the heading. See
+     * {@link isReferenceInHeading}.
+     *
+     * @default `false`
+     */
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to update only embedded links.
      */
@@ -1257,21 +1304,21 @@ export declare function editBacklinksSnapshot<TPayload>(params: EditBacklinksSna
  * @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>;
+export declare function editReferences(params: EditReferencesParams): 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>;
+export declare function editReferencesInContent(params: EditReferencesInContentParams): 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;
+export declare function extractReferenceFile(params: ExtractReferenceFileParams): null | TFile;
 /**
  * Generates a markdown link based on the provided parameters.
  *
@@ -1381,12 +1428,12 @@ export declare function updateLink(params: UpdateLinkParams): string;
  * @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>;
+export declare function updateReferencesInContent(params: UpdateReferencesInContentParams): 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 declare function updateReferencesInFile(params: UpdateReferencesInFileParams): Promise<void>;
 export {};