@mnaoumov/obsidian-lib 0.0.0 → 1.0.1

package/dist/lib/cjs/file-manager.d.cts

@@ -0,0 +1,123 @@
+/// <reference path="./library.d.cts" />
+/**
+ * @file
+ *
+ * Contains utility functions for managing files in Obsidian.
+ */
+import type { MaybeReturn } from '@mnaoumov/typescript-lib/type' with { 'resolution-mode': 'import' };
+import type { App } from 'obsidian' with { 'resolution-mode': 'import' };
+import type { Promisable } from 'type-fest' with { 'resolution-mode': 'import' };
+import type { PathOrFile } from './file-system.cjs';
+import type { CombinedFrontmatter } from './frontmatter.cjs';
+import type { ResourceLockComponent } from './resource-lock.cjs';
+import type { ProcessOptions } from './vault.cjs';
+/**
+ * Parameters for {@link addAlias}.
+ */
+export interface AddAliasParams {
+    /**
+     * The alias to add.
+     */
+    readonly alias?: string;
+    /**
+     * The Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * The path or TFile object representing the note.
+     */
+    readonly pathOrFile: PathOrFile;
+    /**
+     * The resource-lock component used to lock the note while it is being modified.
+     */
+    readonly resourceLockComponent: null | ResourceLockComponent;
+}
+/**
+ * Parameters for {@link deleteAlias}.
+ */
+export interface DeleteAliasParams {
+    /**
+     * The alias to delete.
+     */
+    readonly alias?: string;
+    /**
+     * The Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * The path or TFile object representing the note.
+     */
+    readonly pathOrFile: PathOrFile;
+    /**
+     * The resource-lock component used to lock the note while it is being modified.
+     */
+    readonly resourceLockComponent: null | ResourceLockComponent;
+}
+/**
+ * Options for {@link processFrontmatter}.
+ */
+export type ProcessFrontmatterOptions = ProcessOptions;
+/**
+ * Parameters for {@link processFrontmatter}.
+ *
+ * @typeParam CustomFrontmatter - The type of custom front matter.
+ */
+export interface ProcessFrontmatterParams<CustomFrontmatter = unknown> extends ProcessFrontmatterOptions {
+    /**
+     * The Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * A function that modifies the front matter.
+     *
+     * @param frontmatter - The front matter to modify.
+     * @param abortSignal - The abort signal to listen to.
+     * @returns A value that may be `null` to abort the process.
+     */
+    readonly frontmatterFunction: (frontmatter: CombinedFrontmatter<CustomFrontmatter>, abortSignal: AbortSignal) => Promisable<MaybeReturn<null>>;
+    /**
+     * The path or TFile object representing the note.
+     */
+    readonly pathOrFile: PathOrFile;
+}
+/**
+ * Adds an alias to the front matter of a given file if it does not already exist.
+ *
+ * @param params - The parameters for adding the alias.
+ * @returns A {@link Promise} that resolves when the alias has been added.
+ */
+export declare function addAlias(params: AddAliasParams): Promise<void>;
+/**
+ * Deletes an alias from the front matter of a given file if it exists.
+ *
+ * @param params - The parameters for deleting the alias.
+ * @returns A {@link Promise} that resolves when the alias has been deleted.
+ */
+export declare function deleteAlias(params: DeleteAliasParams): Promise<void>;
+/**
+ * Processes the front matter of a given file, allowing modifications via a provided function.
+ *
+ * @typeParam CustomFrontmatter - The type of custom front matter.
+ * @param params - The parameters for processing the front matter.
+ * @returns A {@link Promise} that resolves when the front matter has been processed and saved.
+ */
+export declare function processFrontmatter<CustomFrontmatter = unknown>(params: ProcessFrontmatterParams<CustomFrontmatter>): Promise<void>;
+/**
+ * Waits until Obsidian's own in-flight link update has decided which links to rewrite.
+ *
+ * `FileManager.runAsyncLinkUpdate()` snapshots every reference's resolved paths, sets
+ * `FileManager.inProgressUpdates` to an array, and invokes the passed handler — the handler being what
+ * performs the actual rename. In its `finally` block it sets `inProgressUpdates` back to `null` and
+ * then immediately calls `FileManager.updateAllLinks()`, whose per-reference decision — rewrite only
+ * when the link's resolved paths changed — runs synchronously, with no `await` in between. So
+ * observing a `null` `inProgressUpdates` proves that decision has already been made.
+ *
+ * That matters for any code that temporarily registers a phantom file at a path that no longer exists
+ * (see `registerFiles` in `metadata-cache.ts`) and holds that registration across an `await`: while it
+ * is live, a link to the old path still resolves, so Obsidian concludes nothing changed and silently
+ * rewrites nothing. Awaiting this function before registering keeps the phantom out of that decision.
+ *
+ * @param app - The Obsidian app instance.
+ * @returns A {@link Promise} that resolves once no link update is in flight.
+ */
+export declare function waitForPendingLinkUpdates(app: App): Promise<void>;