@mnaoumov/obsidian-lib 0.0.0 → 1.0.1

package/dist/lib/esm/vault-delete.d.mts

@@ -0,0 +1,82 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * This module provides deletion utilities that require metadata cache access.
+ */
+import type { App, TAbstractFile, TFile } from 'obsidian';
+import type { PluginNoticeComponent } from './components/plugin-notice-component.mjs';
+import type { PathOrAbstractFile } from './file-system.mjs';
+/**
+ * The result of {@link deleteIfNotUsed}.
+ */
+export declare enum DeleteIfNotUsedResult {
+    /**
+     * The file/folder was deleted.
+     */
+    Deleted = "deleted",
+    /**
+     * The file/folder was not deleted.
+     */
+    NotDeleted = "not-deleted",
+    /**
+     * The file was still used, and {@link DeleteIfNotUsedParams.rescueStillUsedFile} moved it out of the way
+     * instead of it being deleted or left where it was.
+     */
+    Rescued = "rescued"
+}
+/**
+ * Parameters passed to {@link DeleteIfNotUsedParams.rescueStillUsedFile}.
+ */
+export interface RescueStillUsedFileParams {
+    /**
+     * The file that is about to be kept because other notes still reference it.
+     */
+    readonly file: TFile;
+    /**
+     * The paths of the notes that still reference the file once everything being deleted alongside it is
+     * gone. Never empty.
+     */
+    readonly survivingNotePaths: readonly string[];
+}
+interface DeleteIfNotUsedParams {
+    readonly app: App;
+    readonly deleteAbstractFile?: (file: TAbstractFile) => Promise<void>;
+    readonly deletedNotePath?: string;
+    readonly deletedNotePaths?: readonly string[];
+    readonly pathOrFile: PathOrAbstractFile;
+    readonly pluginNoticeComponent?: PluginNoticeComponent;
+    readonly rescueStillUsedFile?: (params: RescueStillUsedFileParams) => Promise<boolean>;
+    readonly shouldDeleteEmptyFolders?: boolean;
+    readonly shouldProtectIfStillUsed?: (file: TFile) => boolean;
+}
+/**
+ * Deletes an abstract file safely from the vault, but only if it is not referenced by other notes.
+ *
+ * Backlinks originating from {@link DeleteIfNotUsedParams.deletedNotePath} and
+ * {@link DeleteIfNotUsedParams.deletedNotePaths} are discounted before deciding whether a file is still
+ * used — a note that is itself going away cannot keep an attachment alive. Deleting a single note needs
+ * only the former; deleting a folder needs the latter, because every note inside it disappears at once.
+ *
+ * {@link DeleteIfNotUsedParams.shouldProtectIfStillUsed} narrows which files that protection covers; a file
+ * it rejects is deleted no matter how many notes link to it. Deleting a whole folder of notes uses this to
+ * exempt the notes themselves — leaving a dangling link behind is what Obsidian normally does, so keeping
+ * every linked-to note would make folder deletion impossible. By default every still-used file is kept.
+ *
+ * A kept file is stranded: it survives in a folder whose owning note is gone, while the note still
+ * referencing it lives elsewhere. {@link DeleteIfNotUsedParams.rescueStillUsedFile} is the seam that lets
+ * the caller relocate it instead, since where it belongs is the caller's attachment-path policy, not this
+ * function's. Without that callback the file is simply kept, exactly as before.
+ *
+ * The actual removal goes through {@link DeleteIfNotUsedParams.deleteAbstractFile} when supplied,
+ * otherwise through {@link trashSafe}. A caller that intercepted a specific deletion primitive passes its
+ * unpatched original here, so the user's chosen semantics (permanent delete vs trash) survive the detour.
+ *
+ * @param params - The parameters for the function.
+ * @returns A {@link Promise} that resolves to {@link DeleteIfNotUsedResult.Deleted} if the abstract file
+ * was deleted, {@link DeleteIfNotUsedResult.Rescued} if it was moved away by
+ * {@link DeleteIfNotUsedParams.rescueStillUsedFile}, or {@link DeleteIfNotUsedResult.NotDeleted} if it was
+ * kept where it was.
+ */
+export declare function deleteIfNotUsed(params: DeleteIfNotUsedParams): Promise<DeleteIfNotUsedResult>;
+export {};

package/dist/lib/esm/vault-delete.mjs

@@ -0,0 +1,132 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function () {
+function ensureDisposeSymbols(symbolConstructor = Symbol) {
+  symbolConstructor.asyncDispose ??= symbolConstructor.for("Symbol.asyncDispose");
+  symbolConstructor.dispose ??= symbolConstructor.for("Symbol.dispose");
+}
+
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return "/";
+    },
+    env: {},
+    platform: "android"
+  };
+  const existingProcess = globalThis.process;
+  if (!existingProcess) {
+    globalThis.process = browserProcess;
+    return;
+  }
+  if (existingProcess.versions?.node) {
+    return;
+  }
+  const existingProcessRecord = existingProcess;
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+  existingProcessRecord["browser"] = true;
+}
+
+(function initEsm() {
+  ensureDisposeSymbols();
+  ensureBrowserProcess();
+})();
+})();
+
+import { printError } from "@mnaoumov/typescript-lib/error";
+import { normalizeOptionalProperties } from "@mnaoumov/typescript-lib/object-utils";
+import {
+  getAbstractFileOrNull,
+  isFile,
+  isFolder
+} from "./file-system.mjs";
+import { t } from "./i18n/i18n.mjs";
+import { getBacklinksForFileSafe } from "./metadata-cache.mjs";
+import {
+  isEmptyFolder,
+  listSafe,
+  trashSafe
+} from "./vault.mjs";
+var DeleteIfNotUsedResult = /* @__PURE__ */ ((DeleteIfNotUsedResult2) => {
+  DeleteIfNotUsedResult2["Deleted"] = "deleted";
+  DeleteIfNotUsedResult2["NotDeleted"] = "not-deleted";
+  DeleteIfNotUsedResult2["Rescued"] = "rescued";
+  return DeleteIfNotUsedResult2;
+})(DeleteIfNotUsedResult || {});
+async function deleteIfNotUsed(params) {
+  const file = getAbstractFileOrNull({ app: params.app, pathOrFile: params.pathOrFile });
+  if (!file) {
+    return "not-deleted" /* NotDeleted */;
+  }
+  let canDelete = isFile(file) || (params.shouldDeleteEmptyFolders ?? true);
+  if (isFile(file)) {
+    const survivingNotePaths = await getSurvivingNotePaths(params, file);
+    if (survivingNotePaths.length > 0) {
+      if (await params.rescueStillUsedFile?.({ file, survivingNotePaths })) {
+        return "rescued" /* Rescued */;
+      }
+      params.pluginNoticeComponent?.showNotice(t(($) => $.obsidianDevUtils.notices.attachmentIsStillUsed, { attachmentPath: file.path }));
+      canDelete = false;
+    }
+  } else if (isFolder(file)) {
+    const listedFiles = await listSafe(params.app, file);
+    for (const child of [...listedFiles.files, ...listedFiles.folders]) {
+      const isChildGone = isGoneFromParent(
+        await deleteIfNotUsed(normalizeOptionalProperties({
+          app: params.app,
+          deleteAbstractFile: params.deleteAbstractFile,
+          deletedNotePath: params.deletedNotePath,
+          deletedNotePaths: params.deletedNotePaths,
+          pathOrFile: child,
+          pluginNoticeComponent: params.pluginNoticeComponent,
+          rescueStillUsedFile: params.rescueStillUsedFile,
+          shouldDeleteEmptyFolders: params.shouldDeleteEmptyFolders,
+          shouldProtectIfStillUsed: params.shouldProtectIfStillUsed
+        }))
+      );
+      canDelete &&= isChildGone;
+    }
+    canDelete &&= await isEmptyFolder(params.app, file);
+  }
+  if (canDelete) {
+    try {
+      if (params.deleteAbstractFile) {
+        await params.deleteAbstractFile(file);
+      } else {
+        await trashSafe(params.app, file);
+      }
+    } catch (error) {
+      printError(new Error(`Failed to delete ${file.path}`, { cause: error }));
+      canDelete = false;
+    }
+  }
+  return canDelete ? "deleted" /* Deleted */ : "not-deleted" /* NotDeleted */;
+}
+async function getSurvivingNotePaths(params, file) {
+  if (!(params.shouldProtectIfStillUsed?.(file) ?? true)) {
+    return [];
+  }
+  const backlinks = await getBacklinksForFileSafe({ app: params.app, pathOrFile: file });
+  const deletedNotePaths = new Set(params.deletedNotePaths);
+  if (params.deletedNotePath) {
+    deletedNotePaths.add(params.deletedNotePath);
+  }
+  for (const deletedNotePath of deletedNotePaths) {
+    backlinks.clear(deletedNotePath);
+  }
+  return backlinks.keys();
+}
+function isGoneFromParent(result) {
+  return result === "deleted" /* Deleted */ || result === "rescued" /* Rescued */;
+}
+export {
+  DeleteIfNotUsedResult,
+  deleteIfNotUsed
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL3ZhdWx0LWRlbGV0ZS50cyJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiLyoqXG4gKiBAZmlsZVxuICpcbiAqIFRoaXMgbW9kdWxlIHByb3ZpZGVzIGRlbGV0aW9uIHV0aWxpdGllcyB0aGF0IHJlcXVpcmUgbWV0YWRhdGEgY2FjaGUgYWNjZXNzLlxuICovXG5cbmltcG9ydCB0eXBlIHtcbiAgQXBwLFxuICBUQWJzdHJhY3RGaWxlLFxuICBURmlsZVxufSBmcm9tICdvYnNpZGlhbic7XG5cbmltcG9ydCB7IHByaW50RXJyb3IgfSBmcm9tICdAbW5hb3Vtb3YvdHlwZXNjcmlwdC1saWIvZXJyb3InO1xuaW1wb3J0IHsgbm9ybWFsaXplT3B0aW9uYWxQcm9wZXJ0aWVzIH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL29iamVjdC11dGlscyc7XG5cbmltcG9ydCB0eXBlIHsgUGx1Z2luTm90aWNlQ29tcG9uZW50IH0gZnJvbSAnLi9jb21wb25lbnRzL3BsdWdpbi1ub3RpY2UtY29tcG9uZW50LnRzJztcbmltcG9ydCB0eXBlIHsgUGF0aE9yQWJzdHJhY3RGaWxlIH0gZnJvbSAnLi9maWxlLXN5c3RlbS50cyc7XG5cbmltcG9ydCB7XG4gIGdldEFic3RyYWN0RmlsZU9yTnVsbCxcbiAgaXNGaWxlLFxuICBpc0ZvbGRlclxufSBmcm9tICcuL2ZpbGUtc3lzdGVtLnRzJztcbmltcG9ydCB7IHQgfSBmcm9tICcuL2kxOG4vaTE4bi50cyc7XG5pbXBvcnQgeyBnZXRCYWNrbGlua3NGb3JGaWxlU2FmZSB9IGZyb20gJy4vbWV0YWRhdGEtY2FjaGUudHMnO1xuaW1wb3J0IHtcbiAgaXNFbXB0eUZvbGRlcixcbiAgbGlzdFNhZmUsXG4gIHRyYXNoU2FmZVxufSBmcm9tICcuL3ZhdWx0LnRzJztcblxuLyoqXG4gKiBUaGUgcmVzdWx0IG9mIHtAbGluayBkZWxldGVJZk5vdFVzZWR9LlxuICovXG5leHBvcnQgZW51bSBEZWxldGVJZk5vdFVzZWRSZXN1bHQge1xuICAvKipcbiAgICogVGhlIGZpbGUvZm9sZGVyIHdhcyBkZWxldGVkLlxuICAgKi9cbiAgRGVsZXRlZCA9ICdkZWxldGVkJyxcblxuICAvKipcbiAgICogVGhlIGZpbGUvZm9sZGVyIHdhcyBub3QgZGVsZXRlZC5cbiAgICovXG4gIE5vdERlbGV0ZWQgPSAnbm90LWRlbGV0ZWQnLFxuXG4gIC8qKlxuICAgKiBUaGUgZmlsZSB3YXMgc3RpbGwgdXNlZCwgYW5kIHtAbGluayBEZWxldGVJZk5vdFVzZWRQYXJhbXMucmVzY3VlU3RpbGxVc2VkRmlsZX0gbW92ZWQgaXQgb3V0IG9mIHRoZSB3YXlcbiAgICogaW5zdGVhZCBvZiBpdCBiZWluZyBkZWxldGVkIG9yIGxlZnQgd2hlcmUgaXQgd2FzLlxuICAgKi9cbiAgUmVzY3VlZCA9ICdyZXNjdWVkJ1xufVxuXG4vKipcbiAqIFBhcmFtZXRlcnMgcGFzc2VkIHRvIHtAbGluayBEZWxldGVJZk5vdFVzZWRQYXJhbXMucmVzY3VlU3RpbGxVc2VkRmlsZX0uXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmVzY3VlU3RpbGxVc2VkRmlsZVBhcmFtcyB7XG4gIC8qKlxuICAgKiBUaGUgZmlsZSB0aGF0IGlzIGFib3V0IHRvIGJlIGtlcHQgYmVjYXVzZSBvdGhlciBub3RlcyBzdGlsbCByZWZlcmVuY2UgaXQuXG4gICAqL1xuICByZWFkb25seSBmaWxlOiBURmlsZTtcblxuICAvKipcbiAgICogVGhlIHBhdGhzIG9mIHRoZSBub3RlcyB0aGF0IHN0aWxsIHJlZmVyZW5jZSB0aGUgZmlsZSBvbmNlIGV2ZXJ5dGhpbmcgYmVpbmcgZGVsZXRlZCBhbG9uZ3NpZGUgaXQgaXNcbiAgICogZ29uZS4gTmV2ZXIgZW1wdHkuXG4gICAqL1xuICByZWFkb25seSBzdXJ2aXZpbmdOb3RlUGF0aHM6IHJlYWRvbmx5IHN0cmluZ1tdO1xufVxuXG5pbnRlcmZhY2UgRGVsZXRlSWZOb3RVc2VkUGFyYW1zIHtcbiAgcmVhZG9ubHkgYXBwOiBBcHA7XG4gIHJlYWRvbmx5IGRlbGV0ZUFic3RyYWN0RmlsZT86IChmaWxlOiBUQWJzdHJhY3RGaWxlKSA9PiBQcm9taXNlPHZvaWQ+O1xuICByZWFkb25seSBkZWxldGVkTm90ZVBhdGg/OiBzdHJpbmc7XG4gIHJlYWRvbmx5IGRlbGV0ZWROb3RlUGF0aHM/OiByZWFkb25seSBzdHJpbmdbXTtcbiAgcmVhZG9ubHkgcGF0aE9yRmlsZTogUGF0aE9yQWJzdHJhY3RGaWxlO1xuICByZWFkb25seSBwbHVnaW5Ob3RpY2VDb21wb25lbnQ/OiBQbHVnaW5Ob3RpY2VDb21wb25lbnQ7XG4gIHJlYWRvbmx5IHJlc2N1ZVN0aWxsVXNlZEZpbGU/OiAocGFyYW1zOiBSZXNjdWVTdGlsbFVzZWRGaWxlUGFyYW1zKSA9PiBQcm9taXNlPGJvb2xlYW4+O1xuICByZWFkb25seSBzaG91bGREZWxldGVFbXB0eUZvbGRlcnM/OiBib29sZWFuO1xuICByZWFkb25seSBzaG91bGRQcm90ZWN0SWZTdGlsbFVzZWQ/OiAoZmlsZTogVEZpbGUpID0+IGJvb2xlYW47XG59XG5cbi8qKlxuICogRGVsZXRlcyBhbiBhYnN0cmFjdCBmaWxlIHNhZmVseSBmcm9tIHRoZSB2YXVsdCwgYnV0IG9ubHkgaWYgaXQgaXMgbm90IHJlZmVyZW5jZWQgYnkgb3RoZXIgbm90ZXMuXG4gKlxuICogQmFja2xpbmtzIG9yaWdpbmF0aW5nIGZyb20ge0BsaW5rIERlbGV0ZUlmTm90VXNlZFBhcmFtcy5kZWxldGVkTm90ZVBhdGh9IGFuZFxuICoge0BsaW5rIERlbGV0ZUlmTm90VXNlZFBhcmFtcy5kZWxldGVkTm90ZVBhdGhzfSBhcmUgZGlzY291bnRlZCBiZWZvcmUgZGVjaWRpbmcgd2hldGhlciBhIGZpbGUgaXMgc3RpbGxcbiAqIHVzZWQgXHUyMDE0IGEgbm90ZSB0aGF0IGlzIGl0c2VsZiBnb2luZyBhd2F5IGNhbm5vdCBrZWVwIGFuIGF0dGFjaG1lbnQgYWxpdmUuIERlbGV0aW5nIGEgc2luZ2xlIG5vdGUgbmVlZHNcbiAqIG9ubHkgdGhlIGZvcm1lcjsgZGVsZXRpbmcgYSBmb2xkZXIgbmVlZHMgdGhlIGxhdHRlciwgYmVjYXVzZSBldmVyeSBub3RlIGluc2lkZSBpdCBkaXNhcHBlYXJzIGF0IG9uY2UuXG4gKlxuICoge0BsaW5rIERlbGV0ZUlmTm90VXNlZFBhcmFtcy5zaG91bGRQcm90ZWN0SWZTdGlsbFVzZWR9IG5hcnJvd3Mgd2hpY2ggZmlsZXMgdGhhdCBwcm90ZWN0aW9uIGNvdmVyczsgYSBmaWxlXG4gKiBpdCByZWplY3RzIGlzIGRlbGV0ZWQgbm8gbWF0dGVyIGhvdyBtYW55IG5vdGVzIGxpbmsgdG8gaXQuIERlbGV0aW5nIGEgd2hvbGUgZm9sZGVyIG9mIG5vdGVzIHVzZXMgdGhpcyB0b1xuICogZXhlbXB0IHRoZSBub3RlcyB0aGVtc2VsdmVzIFx1MjAxNCBsZWF2aW5nIGEgZGFuZ2xpbmcgbGluayBiZWhpbmQgaXMgd2hhdCBPYnNpZGlhbiBub3JtYWxseSBkb2VzLCBzbyBrZWVwaW5nXG4gKiBldmVyeSBsaW5rZWQtdG8gbm90ZSB3b3VsZCBtYWtlIGZvbGRlciBkZWxldGlvbiBpbXBvc3NpYmxlLiBCeSBkZWZhdWx0IGV2ZXJ5IHN0aWxsLXVzZWQgZmlsZSBpcyBrZXB0LlxuICpcbiAqIEEga2VwdCBmaWxlIGlzIHN0cmFuZGVkOiBpdCBzdXJ2aXZlcyBpbiBhIGZvbGRlciB3aG9zZSBvd25pbmcgbm90ZSBpcyBnb25lLCB3aGlsZSB0aGUgbm90ZSBzdGlsbFxuICogcmVmZXJlbmNpbmcgaXQgbGl2ZXMgZWxzZXdoZXJlLiB7QGxpbmsgRGVsZXRlSWZOb3RVc2VkUGFyYW1zLnJlc2N1ZVN0aWxsVXNlZEZpbGV9IGlzIHRoZSBzZWFtIHRoYXQgbGV0c1xuICogdGhlIGNhbGxlciByZWxvY2F0ZSBpdCBpbnN0ZWFkLCBzaW5jZSB3aGVyZSBpdCBiZWxvbmdzIGlzIHRoZSBjYWxsZXIncyBhdHRhY2htZW50LXBhdGggcG9saWN5LCBub3QgdGhpc1xuICogZnVuY3Rpb24ncy4gV2l0aG91dCB0aGF0IGNhbGxiYWNrIHRoZSBmaWxlIGlzIHNpbXBseSBrZXB0LCBleGFjdGx5IGFzIGJlZm9yZS5cbiAqXG4gKiBUaGUgYWN0dWFsIHJlbW92YWwgZ29lcyB0aHJvdWdoIHtAbGluayBEZWxldGVJZk5vdFVzZWRQYXJhbXMuZGVsZXRlQWJzdHJhY3RGaWxlfSB3aGVuIHN1cHBsaWVkLFxuICogb3RoZXJ3aXNlIHRocm91Z2gge0BsaW5rIHRyYXNoU2FmZX0uIEEgY2FsbGVyIHRoYXQgaW50ZXJjZXB0ZWQgYSBzcGVjaWZpYyBkZWxldGlvbiBwcmltaXRpdmUgcGFzc2VzIGl0c1xuICogdW5wYXRjaGVkIG9yaWdpbmFsIGhlcmUsIHNvIHRoZSB1c2VyJ3MgY2hvc2VuIHNlbWFudGljcyAocGVybWFuZW50IGRlbGV0ZSB2cyB0cmFzaCkgc3Vydml2ZSB0aGUgZGV0b3VyLlxuICpcbiAqIEBwYXJhbSBwYXJhbXMgLSBUaGUgcGFyYW1ldGVycyBmb3IgdGhlIGZ1bmN0aW9uLlxuICogQHJldHVybnMgQSB7QGxpbmsgUHJvbWlzZX0gdGhhdCByZXNvbHZlcyB0byB7QGxpbmsgRGVsZXRlSWZOb3RVc2VkUmVzdWx0LkRlbGV0ZWR9IGlmIHRoZSBhYnN0cmFjdCBmaWxlXG4gKiB3YXMgZGVsZXRlZCwge0BsaW5rIERlbGV0ZUlmTm90VXNlZFJlc3VsdC5SZXNjdWVkfSBpZiBpdCB3YXMgbW92ZWQgYXdheSBieVxuICoge0BsaW5rIERlbGV0ZUlmTm90VXNlZFBhcmFtcy5yZXNjdWVTdGlsbFVzZWRGaWxlfSwgb3Ige0BsaW5rIERlbGV0ZUlmTm90VXNlZFJlc3VsdC5Ob3REZWxldGVkfSBpZiBpdCB3YXNcbiAqIGtlcHQgd2hlcmUgaXQgd2FzLlxuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gZGVsZXRlSWZOb3RVc2VkKHBhcmFtczogRGVsZXRlSWZOb3RVc2VkUGFyYW1zKTogUHJvbWlzZTxEZWxldGVJZk5vdFVzZWRSZXN1bHQ+IHtcbiAgY29uc3QgZmlsZSA9IGdldEFic3RyYWN0RmlsZU9yTnVsbCh7IGFwcDogcGFyYW1zLmFwcCwgcGF0aE9yRmlsZTogcGFyYW1zLnBhdGhPckZpbGUgfSk7XG5cbiAgaWYgKCFmaWxlKSB7XG4gICAgcmV0dXJuIERlbGV0ZUlmTm90VXNlZFJlc3VsdC5Ob3REZWxldGVkO1xuICB9XG5cbiAgbGV0IGNhbkRlbGV0ZSA9IGlzRmlsZShmaWxlKSB8fCAocGFyYW1zLnNob3VsZERlbGV0ZUVtcHR5Rm9sZGVycyA/PyB0cnVlKTtcblxuICAvKiB2OCBpZ25vcmUgc3RhcnQgLS0gVEFic3RyYWN0RmlsZSBpcyBhbHdheXMgVEZpbGUgb3IgVEZvbGRlciBpbiBPYnNpZGlhbjsgdGhlIGZhbHNlIGJyYW5jaCBvZiBpc0ZpbGUgbGVhZHMgdG8gaXNGb2xkZXIuICovXG4gIGlmIChpc0ZpbGUoZmlsZSkpIHtcbiAgICAvKiB2OCBpZ25vcmUgc3RvcCAqL1xuICAgIGNvbnN0IHN1cnZpdmluZ05vdGVQYXRocyA9IGF3YWl0IGdldFN1cnZpdmluZ05vdGVQYXRocyhwYXJhbXMsIGZpbGUpO1xuICAgIGlmIChzdXJ2aXZpbmdOb3RlUGF0aHMubGVuZ3RoID4gMCkge1xuICAgICAgaWYgKGF3YWl0IHBhcmFtcy5yZXNjdWVTdGlsbFVzZWRGaWxlPy4oeyBmaWxlLCBzdXJ2aXZpbmdOb3RlUGF0aHMgfSkpIHtcbiAgICAgICAgcmV0dXJuIERlbGV0ZUlmTm90VXNlZFJlc3VsdC5SZXNjdWVkO1xuICAgICAgfVxuXG4gICAgICBwYXJhbXMucGx1Z2luTm90aWNlQ29tcG9uZW50Py5zaG93Tm90aWNlKHQoKCQpID0+ICQub2JzaWRpYW5EZXZVdGlscy5ub3RpY2VzLmF0dGFjaG1lbnRJc1N0aWxsVXNlZCwgeyBhdHRhY2htZW50UGF0aDogZmlsZS5wYXRoIH0pKTtcbiAgICAgIGNhbkRlbGV0ZSA9IGZhbHNlO1xuICAgIH1cbiAgICAvKiB2OCBpZ25vcmUgc3RhcnQgLS0gVEFic3RyYWN0RmlsZSBpcyBhbHdheXMgVEZpbGUgb3IgVEZvbGRlciBpbiBPYnNpZGlhbjsgZGVmZW5zaXZlIGZhbGxiYWNrLiAqL1xuICB9IGVsc2UgaWYgKGlzRm9sZGVyKGZpbGUpKSB7XG4gICAgLyogdjggaWdub3JlIHN0b3AgKi9cbiAgICBjb25zdCBsaXN0ZWRGaWxlcyA9IGF3YWl0IGxpc3RTYWZlKHBhcmFtcy5hcHAsIGZpbGUpO1xuICAgIGZvciAoY29uc3QgY2hpbGQgb2YgWy4uLmxpc3RlZEZpbGVzLmZpbGVzLCAuLi5saXN0ZWRGaWxlcy5mb2xkZXJzXSkge1xuICAgICAgLy8gRXZlcnkgY2hpbGQgaXMgdmlzaXRlZCBldmVuIG9uY2UgdGhlIGZvbGRlciBpdHNlbGYgaXMga25vd24gdG8gc3RheTogYGNhbkRlbGV0ZSAmJj0gYXdhaXQgXHUyMDI2YCB3b3VsZCBza2lwIHRoZSBjYWxsLlxuICAgICAgY29uc3QgaXNDaGlsZEdvbmUgPSBpc0dvbmVGcm9tUGFyZW50KFxuICAgICAgICBhd2FpdCBkZWxldGVJZk5vdFVzZWQobm9ybWFsaXplT3B0aW9uYWxQcm9wZXJ0aWVzPERlbGV0ZUlmTm90VXNlZFBhcmFtcz4oe1xuICAgICAgICAgIGFwcDogcGFyYW1zLmFwcCxcbiAgICAgICAgICBkZWxldGVBYnN0cmFjdEZpbGU6IHBhcmFtcy5kZWxldGVBYnN0cmFjdEZpbGUsXG4gICAgICAgICAgZGVsZXRlZE5vdGVQYXRoOiBwYXJhbXMuZGVsZXRlZE5vdGVQYXRoLFxuICAgICAgICAgIGRlbGV0ZWROb3RlUGF0aHM6IHBhcmFtcy5kZWxldGVkTm90ZVBhdGhzLFxuICAgICAgICAgIHBhdGhPckZpbGU6IGNoaWxkLFxuICAgICAgICAgIHBsdWdpbk5vdGljZUNvbXBvbmVudDogcGFyYW1zLnBsdWdpbk5vdGljZUNvbXBvbmVudCxcbiAgICAgICAgICByZXNjdWVTdGlsbFVzZWRGaWxlOiBwYXJhbXMucmVzY3VlU3RpbGxVc2VkRmlsZSxcbiAgICAgICAgICBzaG91bGREZWxldGVFbXB0eUZvbGRlcnM6IHBhcmFtcy5zaG91bGREZWxldGVFbXB0eUZvbGRlcnMsXG4gICAgICAgICAgc2hvdWxkUHJvdGVjdElmU3RpbGxVc2VkOiBwYXJhbXMuc2hvdWxkUHJvdGVjdElmU3RpbGxVc2VkXG4gICAgICAgIH0pKVxuICAgICAgKTtcbiAgICAgIGNhbkRlbGV0ZSAmJj0gaXNDaGlsZEdvbmU7XG4gICAgfVxuXG4gICAgY2FuRGVsZXRlICYmPSBhd2FpdCBpc0VtcHR5Rm9sZGVyKHBhcmFtcy5hcHAsIGZpbGUpO1xuICB9XG5cbiAgaWYgKGNhbkRlbGV0ZSkge1xuICAgIHRyeSB7XG4gICAgICBpZiAocGFyYW1zLmRlbGV0ZUFic3RyYWN0RmlsZSkge1xuICAgICAgICBhd2FpdCBwYXJhbXMuZGVsZXRlQWJzdHJhY3RGaWxlKGZpbGUpO1xuICAgICAgfSBlbHNlIHtcbiAgICAgICAgYXdhaXQgdHJhc2hTYWZlKHBhcmFtcy5hcHAsIGZpbGUpO1xuICAgICAgfVxuICAgIH0gY2F0Y2ggKGVycm9yKSB7XG4gICAgICBwcmludEVycm9yKG5ldyBFcnJvcihgRmFpbGVkIHRvIGRlbGV0ZSAke2ZpbGUucGF0aH1gLCB7IGNhdXNlOiBlcnJvciB9KSk7XG4gICAgICBjYW5EZWxldGUgPSBmYWxzZTtcbiAgICB9XG4gIH1cblxuICByZXR1cm4gY2FuRGVsZXRlID8gRGVsZXRlSWZOb3RVc2VkUmVzdWx0LkRlbGV0ZWQgOiBEZWxldGVJZk5vdFVzZWRSZXN1bHQuTm90RGVsZXRlZDtcbn1cblxuLyoqXG4gKiBMaXN0cyB0aGUgbm90ZXMgdGhhdCB3b3VsZCBzdGlsbCByZWZlcmVuY2UgYSBmaWxlIG9uY2UgZXZlcnl0aGluZyBiZWluZyBkZWxldGVkIGFsb25nc2lkZSBpdCBpcyBnb25lLlxuICpcbiAqIEBwYXJhbSBwYXJhbXMgLSBUaGUgcGFyYW1ldGVycyB7QGxpbmsgZGVsZXRlSWZOb3RVc2VkfSB3YXMgY2FsbGVkIHdpdGguXG4gKiBAcGFyYW0gZmlsZSAtIFRoZSBmaWxlIHdob3NlIHJlbWFpbmluZyByZWZlcmVuY2VzIGFyZSBjb3VudGVkLlxuICogQHJldHVybnMgQSB7QGxpbmsgUHJvbWlzZX0gdGhhdCByZXNvbHZlcyB0byB0aGUgcGF0aHMgb2YgdGhlIG5vdGVzIHRoYXQga2VlcCB0aGUgZmlsZSBhbGl2ZS4gRW1wdHkgbWVhbnNcbiAqIHRoZSBmaWxlIGlzIGZyZWUgdG8gZ28uXG4gKi9cbmFzeW5jIGZ1bmN0aW9uIGdldFN1cnZpdmluZ05vdGVQYXRocyhwYXJhbXM6IERlbGV0ZUlmTm90VXNlZFBhcmFtcywgZmlsZTogVEZpbGUpOiBQcm9taXNlPHJlYWRvbmx5IHN0cmluZ1tdPiB7XG4gIGlmICghKHBhcmFtcy5zaG91bGRQcm90ZWN0SWZTdGlsbFVzZWQ/LihmaWxlKSA/PyB0cnVlKSkge1xuICAgIHJldHVybiBbXTtcbiAgfVxuXG4gIGNvbnN0IGJhY2tsaW5rcyA9IGF3YWl0IGdldEJhY2tsaW5rc0ZvckZpbGVTYWZlKHsgYXBwOiBwYXJhbXMuYXBwLCBwYXRoT3JGaWxlOiBmaWxlIH0pO1xuICBjb25zdCBkZWxldGVkTm90ZVBhdGhzID0gbmV3IFNldChwYXJhbXMuZGVsZXRlZE5vdGVQYXRocyk7XG4gIGlmIChwYXJhbXMuZGVsZXRlZE5vdGVQYXRoKSB7XG4gICAgZGVsZXRlZE5vdGVQYXRocy5hZGQocGFyYW1zLmRlbGV0ZWROb3RlUGF0aCk7XG4gIH1cbiAgZm9yIChjb25zdCBkZWxldGVkTm90ZVBhdGggb2YgZGVsZXRlZE5vdGVQYXRocykge1xuICAgIGJhY2tsaW5rcy5jbGVhcihkZWxldGVkTm90ZVBhdGgpO1xuICB9XG5cbiAgcmV0dXJuIGJhY2tsaW5rcy5rZXlzKCk7XG59XG5cbi8qKlxuICogQ2hlY2tzIHdoZXRoZXIgYSBjaGlsZCBubyBsb25nZXIgc2l0cyBpbiB0aGUgZm9sZGVyIGJlaW5nIHdhbGtlZCBcdTIwMTQgZGVsZXRlZCBvdXRyaWdodCwgb3IgbW92ZWQgZWxzZXdoZXJlXG4gKiBieSBhIHJlc2N1ZS4gRWl0aGVyIHdheSB0aGUgZm9sZGVyIGhvbGRpbmcgaXQgY2FuIHN0aWxsIGJlIHJlbW92ZWQ7IG9ubHkgYSBjaGlsZCBrZXB0IGluIHBsYWNlIGJsb2NrcyBpdC5cbiAqXG4gKiBAcGFyYW0gcmVzdWx0IC0gVGhlIHJlc3VsdCBvZiBkZWxldGluZyB0aGUgY2hpbGQuXG4gKiBAcmV0dXJucyBgdHJ1ZWAgd2hlbiB0aGUgY2hpbGQgaXMgZ29uZSBmcm9tIGl0cyBwYXJlbnQgZm9sZGVyLlxuICovXG5mdW5jdGlvbiBpc0dvbmVGcm9tUGFyZW50KHJlc3VsdDogRGVsZXRlSWZOb3RVc2VkUmVzdWx0KTogYm9vbGVhbiB7XG4gIHJldHVybiByZXN1bHQgPT09IERlbGV0ZUlmTm90VXNlZFJlc3VsdC5EZWxldGVkIHx8IHJlc3VsdCA9PT0gRGVsZXRlSWZOb3RVc2VkUmVzdWx0LlJlc2N1ZWQ7XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztBQVlBLFNBQVMsa0JBQWtCO0FBQzNCLFNBQVMsbUNBQW1DO0FBSzVDO0FBQUEsRUFDRTtBQUFBLEVBQ0E7QUFBQSxFQUNBO0FBQUEsT0FDSztBQUNQLFNBQVMsU0FBUztBQUNsQixTQUFTLCtCQUErQjtBQUN4QztBQUFBLEVBQ0U7QUFBQSxFQUNBO0FBQUEsRUFDQTtBQUFBLE9BQ0s7QUFLQSxJQUFLLHdCQUFMLGtCQUFLQSwyQkFBTDtBQUlMLEVBQUFBLHVCQUFBLGFBQVU7QUFLVixFQUFBQSx1QkFBQSxnQkFBYTtBQU1iLEVBQUFBLHVCQUFBLGFBQVU7QUFmQSxTQUFBQTtBQUFBLEdBQUE7QUEwRVosZUFBc0IsZ0JBQWdCLFFBQStEO0FBQ25HLFFBQU0sT0FBTyxzQkFBc0IsRUFBRSxLQUFLLE9BQU8sS0FBSyxZQUFZLE9BQU8sV0FBVyxDQUFDO0FBRXJGLE1BQUksQ0FBQyxNQUFNO0FBQ1QsV0FBTztBQUFBLEVBQ1Q7QUFFQSxNQUFJLFlBQVksT0FBTyxJQUFJLE1BQU0sT0FBTyw0QkFBNEI7QUFHcEUsTUFBSSxPQUFPLElBQUksR0FBRztBQUVoQixVQUFNLHFCQUFxQixNQUFNLHNCQUFzQixRQUFRLElBQUk7QUFDbkUsUUFBSSxtQkFBbUIsU0FBUyxHQUFHO0FBQ2pDLFVBQUksTUFBTSxPQUFPLHNCQUFzQixFQUFFLE1BQU0sbUJBQW1CLENBQUMsR0FBRztBQUNwRSxlQUFPO0FBQUEsTUFDVDtBQUVBLGFBQU8sdUJBQXVCLFdBQVcsRUFBRSxDQUFDLE1BQU0sRUFBRSxpQkFBaUIsUUFBUSx1QkFBdUIsRUFBRSxnQkFBZ0IsS0FBSyxLQUFLLENBQUMsQ0FBQztBQUNsSSxrQkFBWTtBQUFBLElBQ2Q7QUFBQSxFQUVGLFdBQVcsU0FBUyxJQUFJLEdBQUc7QUFFekIsVUFBTSxjQUFjLE1BQU0sU0FBUyxPQUFPLEtBQUssSUFBSTtBQUNuRCxlQUFXLFNBQVMsQ0FBQyxHQUFHLFlBQVksT0FBTyxHQUFHLFlBQVksT0FBTyxHQUFHO0FBRWxFLFlBQU0sY0FBYztBQUFBLFFBQ2xCLE1BQU0sZ0JBQWdCLDRCQUFtRDtBQUFBLFVBQ3ZFLEtBQUssT0FBTztBQUFBLFVBQ1osb0JBQW9CLE9BQU87QUFBQSxVQUMzQixpQkFBaUIsT0FBTztBQUFBLFVBQ3hCLGtCQUFrQixPQUFPO0FBQUEsVUFDekIsWUFBWTtBQUFBLFVBQ1osdUJBQXVCLE9BQU87QUFBQSxVQUM5QixxQkFBcUIsT0FBTztBQUFBLFVBQzVCLDBCQUEwQixPQUFPO0FBQUEsVUFDakMsMEJBQTBCLE9BQU87QUFBQSxRQUNuQyxDQUFDLENBQUM7QUFBQSxNQUNKO0FBQ0Esb0JBQWM7QUFBQSxJQUNoQjtBQUVBLGtCQUFjLE1BQU0sY0FBYyxPQUFPLEtBQUssSUFBSTtBQUFBLEVBQ3BEO0FBRUEsTUFBSSxXQUFXO0FBQ2IsUUFBSTtBQUNGLFVBQUksT0FBTyxvQkFBb0I7QUFDN0IsY0FBTSxPQUFPLG1CQUFtQixJQUFJO0FBQUEsTUFDdEMsT0FBTztBQUNMLGNBQU0sVUFBVSxPQUFPLEtBQUssSUFBSTtBQUFBLE1BQ2xDO0FBQUEsSUFDRixTQUFTLE9BQU87QUFDZCxpQkFBVyxJQUFJLE1BQU0sb0JBQW9CLEtBQUssSUFBSSxJQUFJLEVBQUUsT0FBTyxNQUFNLENBQUMsQ0FBQztBQUN2RSxrQkFBWTtBQUFBLElBQ2Q7QUFBQSxFQUNGO0FBRUEsU0FBTyxZQUFZLDBCQUFnQztBQUNyRDtBQVVBLGVBQWUsc0JBQXNCLFFBQStCLE1BQXlDO0FBQzNHLE1BQUksRUFBRSxPQUFPLDJCQUEyQixJQUFJLEtBQUssT0FBTztBQUN0RCxXQUFPLENBQUM7QUFBQSxFQUNWO0FBRUEsUUFBTSxZQUFZLE1BQU0sd0JBQXdCLEVBQUUsS0FBSyxPQUFPLEtBQUssWUFBWSxLQUFLLENBQUM7QUFDckYsUUFBTSxtQkFBbUIsSUFBSSxJQUFJLE9BQU8sZ0JBQWdCO0FBQ3hELE1BQUksT0FBTyxpQkFBaUI7QUFDMUIscUJBQWlCLElBQUksT0FBTyxlQUFlO0FBQUEsRUFDN0M7QUFDQSxhQUFXLG1CQUFtQixrQkFBa0I7QUFDOUMsY0FBVSxNQUFNLGVBQWU7QUFBQSxFQUNqQztBQUVBLFNBQU8sVUFBVSxLQUFLO0FBQ3hCO0FBU0EsU0FBUyxpQkFBaUIsUUFBd0M7QUFDaEUsU0FBTyxXQUFXLDJCQUFpQyxXQUFXO0FBQ2hFOyIsCiAgIm5hbWVzIjogWyJEZWxldGVJZk5vdFVzZWRSZXN1bHQiXQp9Cg==

package/dist/lib/esm/vault-transaction.d.mts

@@ -0,0 +1,163 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * A reversible, transactional log of vault mutations. Each mutation records how to undo itself;
+ * {@link VaultTransaction.rollback} reverses the completed steps in reverse order and
+ * {@link VaultTransaction.commit} finalizes them. It is built on the `*Safe` vault wrappers so it
+ * inherits their case-insensitive / retry / missing-file handling.
+ *
+ * A deletion is performed as a **soft-delete**: the resource is moved aside into a dot-prefixed
+ * staging folder (a folder moves its whole subtree in a single rename, so subtree rollback is cheap
+ * and faithful). Because Obsidian's vault file-tree and file watcher ignore any `.`-prefixed path,
+ * staged resources are **untracked** — they do not churn the metadata cache, flash in the file
+ * explorer, or get propagated by sync while the transaction is in flight. The flip side is that
+ * `vault.*` methods cannot see the staging area, so ALL staging I/O goes through
+ * {@link App.vault.adapter} (`mkdir`/`rename`/`exists`/`trashSystem`/`rmdir`).
+ * {@link VaultTransaction.commit} then trashes the staged resources for real; {@link VaultTransaction.rollback}
+ * moves them back.
+ */
+import type { App, TFile } from 'obsidian';
+import type { PathOrAbstractFile } from './file-system.mjs';
+/**
+ * Parameters for the {@link VaultTransaction} constructor.
+ */
+export interface VaultTransactionConstructorParams {
+    /**
+     * The Obsidian application instance.
+     */
+    readonly app: App;
+    /**
+     * Opens an ambient mutation-bypass scope covering the paths this transaction touches, so the
+     * transaction's own writes pass a `shouldBlockMutations` lock that the owning operation holds. It is
+     * called once when the transaction is constructed, and the returned {@link Disposable} is disposed
+     * when the transaction settles (on `commit`, `rollback`, or `await using` disposal) — so the bypass
+     * stays active through rollback, including auto-rollback, which a caller managing the scope itself
+     * could easily get wrong. Typically
+     * `() => resourceLockComponent.bypassBlockedMutations(lockedPathsOrFiles)`. Omit it for the common
+     * standalone case where the transaction operates on unlocked paths.
+     *
+     * @returns A {@link Disposable} that ends the bypass scope.
+     */
+    readonly openMutationBypass?: () => Disposable;
+    /**
+     * The dot-prefixed folder that soft-deleted resources are moved into until the transaction is
+     * committed or rolled back. It must stay `.`-prefixed so Obsidian leaves the staged resources
+     * untracked.
+     *
+     * @default `'.obsidian-dev-utils-temp'`
+     */
+    readonly stagingFolderPath?: string;
+}
+/**
+ * A reversible log of vault mutations. Perform mutations through its methods, then call
+ * {@link VaultTransaction.commit} on success or {@link VaultTransaction.rollback} on failure. It is
+ * `await using`-friendly: if neither is called, disposal rolls back.
+ */
+export declare class VaultTransaction {
+    /**
+     * The Obsidian application instance the transaction mutates.
+     */
+    protected readonly app: App;
+    private hasStagingFolder;
+    private mutationBypass;
+    private readonly stagedTrashPaths;
+    private readonly stagingFolderPath;
+    private state;
+    private readonly undoSteps;
+    /**
+     * Creates a new vault transaction.
+     *
+     * @param params - The parameters.
+     */
+    constructor(params: VaultTransactionConstructorParams);
+    /**
+     * Commits the transaction: finalizes soft-deletes by trashing the staged resources for real and
+     * removes the staging folder. After this the transaction can no longer be mutated or rolled back.
+     *
+     * @returns A {@link Promise} that resolves when the commit completes.
+     */
+    commit(): Promise<void>;
+    /**
+     * Copies a file or folder, recording the removal of the copy as the inverse. A folder is copied with
+     * its whole subtree, so the single recorded removal undoes the whole tree. Unlike
+     * {@link VaultTransaction.create}, the content is copied byte for byte, so a binary resource
+     * round-trips faithfully.
+     *
+     * Parent folders that had to be created for the destination are NOT undone individually, matching
+     * {@link VaultTransaction.create} and {@link VaultTransaction.rename}.
+     *
+     * @param oldPathOrFile - The path, file or folder to copy.
+     * @param newPath - The desired new path (an available path is chosen if it is taken).
+     * @returns A {@link Promise} resolving to the actual path of the copy.
+     */
+    copy(oldPathOrFile: PathOrAbstractFile, newPath: string): Promise<string>;
+    /**
+     * Creates a file with the given content, recording its removal as the inverse.
+     *
+     * @param path - The path of the file to create.
+     * @param data - The content of the file.
+     * @returns A {@link Promise} resolving to the created {@link TFile}.
+     */
+    create(path: string, data: string): Promise<TFile>;
+    /**
+     * Creates a folder (including missing ancestors), recording its removal as the inverse. A no-op if
+     * the folder already exists.
+     *
+     * @param path - The path of the folder to create.
+     * @returns A {@link Promise} that resolves when the folder exists.
+     */
+    createFolder(path: string): Promise<void>;
+    /**
+     * Replaces the content of a file, capturing the old content so it can be restored on rollback.
+     *
+     * @param pathOrFile - The path or file to modify.
+     * @param newContent - The new content.
+     * @returns A {@link Promise} that resolves when the file is modified.
+     */
+    modify(pathOrFile: PathOrAbstractFile, newContent: string): Promise<void>;
+    /**
+     * Transforms the content of a file, capturing the old content so it can be restored on rollback.
+     *
+     * @param pathOrFile - The path or file to process.
+     * @param newContentProvider - Maps the current content to the new content.
+     * @returns A {@link Promise} that resolves when the file is processed.
+     */
+    process(pathOrFile: PathOrAbstractFile, newContentProvider: (content: string) => string): Promise<void>;
+    /**
+     * Renames or moves a resource, recording the reverse rename as the inverse.
+     *
+     * @param oldPathOrFile - The resource to rename.
+     * @param newPath - The desired new path (an available path is chosen if it is taken).
+     * @returns A {@link Promise} resolving to the actual new path.
+     */
+    rename(oldPathOrFile: PathOrAbstractFile, newPath: string): Promise<string>;
+    /**
+     * Rolls back the transaction: undoes the completed steps in reverse order and removes the staging
+     * folder. Idempotent.
+     *
+     * @returns A {@link Promise} that resolves when the rollback completes.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Rolls back the transaction on disposal unless it was already committed or rolled back.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Soft-deletes a resource by moving it into the staging folder, recording the move-back as the
+     * inverse. The real trash happens on {@link VaultTransaction.commit}. A no-op if the resource does
+     * not exist.
+     *
+     * @param pathOrFile - The path or resource to trash.
+     * @returns A {@link Promise} that resolves when the resource has been staged.
+     */
+    trash(pathOrFile: PathOrAbstractFile): Promise<void>;
+    private assertNotCommitted;
+    private assertOpen;
+    private disposeMutationBypass;
+    private ensureStagingFolder;
+    private getAvailableStagedPath;
+    private hardDelete;
+    private pushUndo;
+    private removeStagingFolder;
+}