obsidian-dev-utils 83.3.0 → 84.1.0

package/dist/lib/cjs/obsidian/editor-lock.d.cts

@@ -1,142 +0,0 @@
-/// <reference path="../library.d.cts" />
-/**
- * @file
- *
- * Note-scoped, reference-counted editor locking.
- *
- * Where {@link toggleEditorReadOnly} from `./editor.ts` toggles the read-only state of a single
- * {@link Editor} instance, the helpers here lock a note by its **path**: while a path is
- * locked, every current and future {@link MarkdownView} of that note (in any window, including
- * popouts) is made read-only and shows a lock indicator in its tab header, its view action bar, and
- * the status bar (while the note is active). Locks are reference-counted per locking plugin, so
- * nested or concurrent operations on the same note are safe — the note is unlocked only when the
- * last lock is released — and the indicators' tooltip lists which plugins currently hold a lock.
- *
- * The acquirers return a {@link Disposable}, so the preferred call style is a `using` declaration
- * that releases automatically at scope exit (including on throw):
- *
- * ```ts
- * using _lock = lockEditorForPath(app, path, this.manifest.id);
- * // ... long-running work (process, processFrontMatter, merge/split) ...
- * // auto-unlocked at scope exit
- * ```
- *
- * The explicit {@link unlockEditorForPath} pair remains available for non-`using` call sites.
- */
-import type { App } from 'obsidian' with { 'resolution-mode': 'import' };
-import type { PathOrFile } from './file-system.cjs';
-import { ComponentEx } from './components/component-ex.cjs';
-/**
- * Options for {@link EditorLockComponent.lockForPath}.
- */
-export interface EditorLockComponentLockForPathOptions {
-    /**
-     * An optional {@link AbortController} associated with the lock. When the lock indicator is
-     * right-clicked and the user confirms an unlock (or {@link requestEditorUnlockForPath} is called for
-     * the path), this controller is aborted so the operation holding the lock can cancel itself and
-     * release the lock in its own cleanup.
-     */
-    readonly abortController?: AbortController;
-}
-/**
- * A per-plugin handle for note-scoped editor locking. Add it as a child of your plugin
- * (`this.addChild(new EditorLockComponent(this.app))`) so that any locks it still holds are released
- * automatically when the plugin unloads — a note can never be left stuck read-only because the
- * plugin that locked it was disabled or reloaded mid-operation.
- *
- * Locks are reference-counted and attributed to this plugin, so the lock indicators' tooltip names
- * it among the plugins currently holding a lock.
- */
-export declare class EditorLockComponent extends ComponentEx {
-    private readonly app;
-    private readonly pluginId;
-    /**
-     * Creates an editor-lock handle owned by a plugin.
-     *
-     * @param app - The Obsidian app instance.
-     * @param pluginId - The id of the owning plugin (e.g. its `manifest.id`). Locks are attributed to
-     * it for reference-counting and the indicators' "locked by" tooltip.
-     */
-    constructor(app: App, pluginId: string);
-    /**
-     * Checks whether the note at the given path is currently locked by any plugin.
-     *
-     * @param pathOrFile - The path or file of the note to check.
-     * @returns `true` if the note has at least one active lock, `false` otherwise.
-     */
-    isLockedForPath(pathOrFile: PathOrFile): boolean;
-    /**
-     * Locks the note at the given path on behalf of this plugin, making it read-only in every current
-     * and future {@link MarkdownView} until the lock is released. Reference-counted: balance each call
-     * with a dispose of the returned {@link Disposable} (ideally via `using`) or {@link unlockForPath}.
-     *
-     * @param pathOrFile - The path or file of the note to lock.
-     * @param options - Optional locking options. Pass an
-     * {@link EditorLockComponentLockForPathOptions.abortController} to make the lock cancelable via the
-     * indicator's right-click "unlock" menu or {@link requestEditorUnlockForPath}.
-     * @returns A {@link Disposable} that releases this lock when disposed. Disposing more than once is a no-op.
-     */
-    lockForPath(pathOrFile: PathOrFile, options?: EditorLockComponentLockForPathOptions): Disposable;
-    /**
-     * Releases every lock still held by this plugin when the component (and thus the plugin) unloads,
-     * so no note is left stuck read-only by an operation that never completed.
-     */
-    onunload(): void;
-    /**
-     * Releases one lock previously acquired for the note at the given path via {@link lockForPath}.
-     *
-     * @param pathOrFile - The path or file of the note to unlock.
-     */
-    unlockForPath(pathOrFile: PathOrFile): void;
-}
-/**
- * Checks whether the note at the given path is currently locked.
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to check.
- * @returns `true` if the note has at least one active lock, `false` otherwise.
- */
-export declare function isEditorLockedForPath(app: App, pathOrFile: PathOrFile): boolean;
-/**
- * Locks the note at the given path, making it read-only in every current and future
- * {@link MarkdownView} until the lock is released, and showing a lock indicator in the tab header,
- * view action bar, and (while active) the status bar. The indicators' tooltip lists the plugins
- * that currently hold a lock on the note.
- *
- * The lock is reference-counted per calling plugin: each call must be balanced by exactly one
- * release (either disposing the returned {@link Disposable} — ideally via a `using` declaration — or
- * a matching {@link unlockEditorForPath} call).
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to lock.
- * @param pluginId - The id of the locking plugin (e.g. its `manifest.id`). The lock is attributed to
- * it for reference-counting and the indicators' "locked by" tooltip.
- * @returns A {@link Disposable} that releases this lock when disposed. Disposing more than once is a no-op.
- */
-export declare function lockEditorForPath(app: App, pathOrFile: PathOrFile, pluginId: string): Disposable;
-/**
- * Requests an unlock of the note at the given path by aborting every {@link AbortController} that was
- * associated with a lock on it (via {@link EditorLockComponent.lockForPath}'s
- * {@link EditorLockComponentLockForPathOptions.abortController}). The operations holding the lock
- * observe the abort and release their own locks. A no-op when no abortable lock is registered for the
- * path.
- *
- * This lets a consuming plugin wire its own "unlock active note" command without reaching into the
- * lock manager directly.
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to request an unlock for.
- */
-export declare function requestEditorUnlockForPath(app: App, pathOrFile: PathOrFile): void;
-/**
- * Releases one lock previously acquired for the note at the given path via {@link lockEditorForPath}.
- *
- * When the last lock is released the note becomes fully editable again and its lock indicators are
- * removed. Calling this when the note is not locked is a no-op.
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to unlock.
- * @param pluginId - The id of the plugin that holds the lock (e.g. its `manifest.id`); one of its
- * locks on the note is released.
- */
-export declare function unlockEditorForPath(app: App, pathOrFile: PathOrFile, pluginId: string): void;

package/dist/lib/esm/obsidian/editor-lock.d.mts

@@ -1,142 +0,0 @@
-/// <reference path="../library.d.mts" />
-/**
- * @file
- *
- * Note-scoped, reference-counted editor locking.
- *
- * Where {@link toggleEditorReadOnly} from `./editor.ts` toggles the read-only state of a single
- * {@link Editor} instance, the helpers here lock a note by its **path**: while a path is
- * locked, every current and future {@link MarkdownView} of that note (in any window, including
- * popouts) is made read-only and shows a lock indicator in its tab header, its view action bar, and
- * the status bar (while the note is active). Locks are reference-counted per locking plugin, so
- * nested or concurrent operations on the same note are safe — the note is unlocked only when the
- * last lock is released — and the indicators' tooltip lists which plugins currently hold a lock.
- *
- * The acquirers return a {@link Disposable}, so the preferred call style is a `using` declaration
- * that releases automatically at scope exit (including on throw):
- *
- * ```ts
- * using _lock = lockEditorForPath(app, path, this.manifest.id);
- * // ... long-running work (process, processFrontMatter, merge/split) ...
- * // auto-unlocked at scope exit
- * ```
- *
- * The explicit {@link unlockEditorForPath} pair remains available for non-`using` call sites.
- */
-import type { App } from 'obsidian';
-import type { PathOrFile } from './file-system.mjs';
-import { ComponentEx } from './components/component-ex.mjs';
-/**
- * Options for {@link EditorLockComponent.lockForPath}.
- */
-export interface EditorLockComponentLockForPathOptions {
-    /**
-     * An optional {@link AbortController} associated with the lock. When the lock indicator is
-     * right-clicked and the user confirms an unlock (or {@link requestEditorUnlockForPath} is called for
-     * the path), this controller is aborted so the operation holding the lock can cancel itself and
-     * release the lock in its own cleanup.
-     */
-    readonly abortController?: AbortController;
-}
-/**
- * A per-plugin handle for note-scoped editor locking. Add it as a child of your plugin
- * (`this.addChild(new EditorLockComponent(this.app))`) so that any locks it still holds are released
- * automatically when the plugin unloads — a note can never be left stuck read-only because the
- * plugin that locked it was disabled or reloaded mid-operation.
- *
- * Locks are reference-counted and attributed to this plugin, so the lock indicators' tooltip names
- * it among the plugins currently holding a lock.
- */
-export declare class EditorLockComponent extends ComponentEx {
-    private readonly app;
-    private readonly pluginId;
-    /**
-     * Creates an editor-lock handle owned by a plugin.
-     *
-     * @param app - The Obsidian app instance.
-     * @param pluginId - The id of the owning plugin (e.g. its `manifest.id`). Locks are attributed to
-     * it for reference-counting and the indicators' "locked by" tooltip.
-     */
-    constructor(app: App, pluginId: string);
-    /**
-     * Checks whether the note at the given path is currently locked by any plugin.
-     *
-     * @param pathOrFile - The path or file of the note to check.
-     * @returns `true` if the note has at least one active lock, `false` otherwise.
-     */
-    isLockedForPath(pathOrFile: PathOrFile): boolean;
-    /**
-     * Locks the note at the given path on behalf of this plugin, making it read-only in every current
-     * and future {@link MarkdownView} until the lock is released. Reference-counted: balance each call
-     * with a dispose of the returned {@link Disposable} (ideally via `using`) or {@link unlockForPath}.
-     *
-     * @param pathOrFile - The path or file of the note to lock.
-     * @param options - Optional locking options. Pass an
-     * {@link EditorLockComponentLockForPathOptions.abortController} to make the lock cancelable via the
-     * indicator's right-click "unlock" menu or {@link requestEditorUnlockForPath}.
-     * @returns A {@link Disposable} that releases this lock when disposed. Disposing more than once is a no-op.
-     */
-    lockForPath(pathOrFile: PathOrFile, options?: EditorLockComponentLockForPathOptions): Disposable;
-    /**
-     * Releases every lock still held by this plugin when the component (and thus the plugin) unloads,
-     * so no note is left stuck read-only by an operation that never completed.
-     */
-    onunload(): void;
-    /**
-     * Releases one lock previously acquired for the note at the given path via {@link lockForPath}.
-     *
-     * @param pathOrFile - The path or file of the note to unlock.
-     */
-    unlockForPath(pathOrFile: PathOrFile): void;
-}
-/**
- * Checks whether the note at the given path is currently locked.
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to check.
- * @returns `true` if the note has at least one active lock, `false` otherwise.
- */
-export declare function isEditorLockedForPath(app: App, pathOrFile: PathOrFile): boolean;
-/**
- * Locks the note at the given path, making it read-only in every current and future
- * {@link MarkdownView} until the lock is released, and showing a lock indicator in the tab header,
- * view action bar, and (while active) the status bar. The indicators' tooltip lists the plugins
- * that currently hold a lock on the note.
- *
- * The lock is reference-counted per calling plugin: each call must be balanced by exactly one
- * release (either disposing the returned {@link Disposable} — ideally via a `using` declaration — or
- * a matching {@link unlockEditorForPath} call).
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to lock.
- * @param pluginId - The id of the locking plugin (e.g. its `manifest.id`). The lock is attributed to
- * it for reference-counting and the indicators' "locked by" tooltip.
- * @returns A {@link Disposable} that releases this lock when disposed. Disposing more than once is a no-op.
- */
-export declare function lockEditorForPath(app: App, pathOrFile: PathOrFile, pluginId: string): Disposable;
-/**
- * Requests an unlock of the note at the given path by aborting every {@link AbortController} that was
- * associated with a lock on it (via {@link EditorLockComponent.lockForPath}'s
- * {@link EditorLockComponentLockForPathOptions.abortController}). The operations holding the lock
- * observe the abort and release their own locks. A no-op when no abortable lock is registered for the
- * path.
- *
- * This lets a consuming plugin wire its own "unlock active note" command without reaching into the
- * lock manager directly.
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to request an unlock for.
- */
-export declare function requestEditorUnlockForPath(app: App, pathOrFile: PathOrFile): void;
-/**
- * Releases one lock previously acquired for the note at the given path via {@link lockEditorForPath}.
- *
- * When the last lock is released the note becomes fully editable again and its lock indicators are
- * removed. Calling this when the note is not locked is a no-op.
- *
- * @param app - The Obsidian app instance.
- * @param pathOrFile - The path or file of the note to unlock.
- * @param pluginId - The id of the plugin that holds the lock (e.g. its `manifest.id`); one of its
- * locks on the note is released.
- */
-export declare function unlockEditorForPath(app: App, pathOrFile: PathOrFile, pluginId: string): void;