@mnaoumov/obsidian-lib 8.1.0 → 10.0.0

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

@@ -69,20 +69,20 @@ export declare enum LinkStyle {
 /**
  * Params passed to the link converter of {@link editBacklinksSnapshot}.
  *
- * @typeParam TPayload - The payload recorded for each link when the snapshot was built.
+ * @typeParam TPayload - The payload recorded for each reference 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.
      */
@@ -118,34 +118,23 @@ export interface BacklinksLike {
  * 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.
+ * The payload is whatever the caller needs to remember per reference. 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 references
+ * may point at several files that all moved and each reference has to be resolved to its own new path.
  *
- * @typeParam TPayload - The payload recorded for each link.
+ * @typeParam TPayload - The payload recorded for each reference.
  */
 export type BacklinksSnapshot<TPayload> = ReadonlyMap<string, ReadonlyMap<string, TPayload>>;
 /**
  * Params for {@link buildBacklinksSnapshot}.
  *
- * @typeParam TPayload - The payload recorded for each link.
+ * @typeParam TPayload - The payload recorded for each reference.
  */
 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.
      *
@@ -159,10 +148,21 @@ export interface BuildBacklinksSnapshotParams<TPayload> {
     /**
      * Produces the payload to record for a link. See {@link BacklinksSnapshot} for what a payload is for.
      *
-     * @param link - The link being recorded.
+     * @param reference - The reference being recorded.
      * @returns The payload.
      */
-    readonly payloadProvider: (link: Reference) => TPayload;
+    readonly payloadProvider: (reference: 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?: (reference: 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 reference.
+     */
+    readonly referenceConverter: (reference: Reference) => Promisable<MaybeReturn<string>>;
 }
 /**
  * Options for {@link editBacklinksSnapshot}.
@@ -314,7 +314,7 @@ export type EditBacklinksSnapshotOptions = ProcessOptions;
 /**
  * Parameters for {@link editBacklinksSnapshot}.
  *
- * @typeParam TPayload - The payload recorded for each link when the snapshot was built.
+ * @typeParam TPayload - The payload recorded for each reference when the snapshot was built.
  */
 export interface EditBacklinksSnapshotParams<TPayload> extends EditBacklinksSnapshotOptions {
     /**
@@ -322,9 +322,14 @@ export interface EditBacklinksSnapshotParams<TPayload> extends EditBacklinksSnap
      */
     readonly app: App;
     /**
-     * The function that converts each link.
+     * 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 reference.
      */
-    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?: (reference: 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 reference.
+     */
+    readonly referenceConverter: (reference: 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.
@@ -421,24 +421,20 @@ export interface EditLinksInContentParams {
      *
      * @default `false`
      */
-    readonly shouldSkipLinksInHeadings?: boolean;
+    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.
@@ -463,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 reference.
+     */
+    readonly referenceConverter: (reference: 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.
@@ -492,20 +492,20 @@ export interface EditLinksParams extends EditLinksOptions {
      *
      * @default `false`
      */
-    readonly shouldSkipLinksInHeadings?: boolean;
+    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.
      *
@@ -716,7 +716,7 @@ export interface GenerateRawMarkdownLinkParams {
 /**
  * A {@link BacklinksSnapshot} while it is still being accumulated by {@link buildBacklinksSnapshot}.
  *
- * @typeParam TPayload - The payload recorded for each link.
+ * @typeParam TPayload - The payload recorded for each reference.
  */
 export type MutableBacklinksSnapshot<TPayload> = Map<string, Map<string, TPayload>>;
 /**
@@ -797,11 +797,11 @@ export interface UpdateFileUrlLinksInContentParams {
     readonly offsetRange?: OffsetRange;
     /**
      * Whether to leave every link inside a heading unchanged. See
-     * {@link EditLinksInContentParams.shouldSkipLinksInHeadings}.
+     * {@link EditReferencesInContentParams.shouldSkipReferencesInHeadings}.
      *
      * @default `false`
      */
-    readonly shouldSkipLinksInHeadings?: boolean;
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to emit the normalized links with angle brackets and raw spaces instead of `%20`-encoding.
      *
@@ -842,11 +842,11 @@ export interface UpdateFileUrlLinksInFileParams extends ProcessOptions {
      */
     readonly pathOrFile: PathOrFile;
     /**
-     * Whether to leave every link inside a heading unchanged. See {@link EditLinksParams.shouldSkipLinksInHeadings}.
+     * Whether to leave every link inside a heading unchanged. See {@link EditReferencesParams.shouldSkipReferencesInHeadings}.
      *
      * @default `false`
      */
-    readonly shouldSkipLinksInHeadings?: boolean;
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to emit the normalized links with angle brackets and raw spaces instead of `%20`-encoding.
      *
@@ -874,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.
      */
@@ -902,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.
      *
@@ -970,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.
      */
@@ -1007,7 +1007,7 @@ export interface UpdateLinksInFileParams extends ProcessOptions {
      *
      * @default `undefined`
      */
-    readonly linkStyleProvider?: (link: Reference) => LinkStyle | undefined;
+    readonly linkStyleProvider?: (reference: Reference) => LinkStyle | undefined;
     /**
      * A file to update the links in.
      */
@@ -1068,7 +1068,7 @@ export interface UpdateLinksInFileParams extends ProcessOptions {
      *
      * @default `false`
      */
-    readonly shouldSkipLinksInHeadings?: boolean;
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to update only embedded links.
      */
@@ -1117,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.
      */
@@ -1158,13 +1158,13 @@ interface UpdateLinksInContentParams {
      *
      * @default `undefined`
      */
-    readonly linkStyleProvider?: (link: Reference) => LinkStyle | undefined;
+    readonly linkStyleProvider?: (reference: Reference) => LinkStyle | undefined;
     /**
      * A new source path or file.
      */
     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
@@ -1213,7 +1213,7 @@ interface UpdateLinksInContentParams {
      *
      * @default `false`
      */
-    readonly shouldSkipLinksInHeadings?: boolean;
+    readonly shouldSkipReferencesInHeadings?: boolean;
     /**
      * Whether to update only embedded links.
      */
@@ -1267,7 +1267,7 @@ interface UpdateLinksInContentParams {
  * 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.
+ * @typeParam TPayload - The payload recorded for each reference.
  * @param params - The parameters for building the snapshot.
  * @returns The snapshot — {@link BuildBacklinksSnapshotParams.target} itself when one was passed.
  */
@@ -1293,7 +1293,7 @@ export declare function editBacklinks(params: EditBacklinksParams): Promise<void
  * 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.
+ * @typeParam TPayload - The payload recorded for each reference 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.
  */
@@ -1304,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.
  *
@@ -1428,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 {};