ResourceLockComponent

A per-plugin handle for path-scoped resource locking (editor read-only, optional vault-mutation blocking, and external-change detection — see the file overview). Add it as a child of your plugin (this.addChild(new ResourceLockComponent(this.app))) so that any locks it still holds are released automatically when the plugin unloads — a resource can never be left stuck locked 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.

Import:

import { ResourceLockComponent } from 'obsidian-dev-utils/obsidian/resource-lock';

Signature:

export class ResourceLockComponent extends ComponentEx

Extends: ComponentEx

Constructor

new ResourceLockComponent(app: App, pluginId: string)

Creates an resource-lock handle owned by a plugin.

Properties

Property	Type	Description
app	App	The Obsidian app instance.
pluginId	string	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.

Methods

Method	Returns	Description
[Symbol.dispose]()	void	Disposes of the component. (Inherited from ComponentEx)
addChild(component)	TComponent	Adds a child component. Mirrors the native `Component.addChild` contract: if this component is already loaded, the child is loaded immediately, so `child._loaded` is set before this method returns even when this component has async load logic. The child's async tail (if any) is sequenced into the load promise so a later `loadWithPromises` call awaits it. Adding a child BEFORE the first load is legitimate: the child is queued and loaded when this component loads. Adding one AFTER this component has been unloaded is not — the child would never be loaded and never unloaded (a leak), so it is refused with a SilentError. The typical source of such a call is an `async` method that was suspended on an `await` when the component got unloaded and then resumed on the dead component; the SilentError unwinds it quietly (see `isUnloaded`). (Inherited from ComponentEx)
bypassBlockedMutations(pathsOrFiles)	Disposable	Opens an ambient bypass scope: while the returned `Disposable` is not disposed, this plugin's own mutations of the given paths (and, for a folder, its whole subtree) pass through the mutation blocker instead of throwing ResourceLockedError. Any mutation of a blocked path NOT covered by an active bypass scope is still rejected. Use it with a `using` declaration around the operation that legitimately mutates resources it has locked with ResourceLockComponentLockForPathParams.shouldBlockMutations: ```ts using _bypass = component.bypassBlockedMutations([sourceFile, targetFile]); // ... the operation's own vault mutations of those paths are allowed ... // scope end: the paths are enforced again```
ensureLoaded()	void	Ensures the component is loaded, throwing if it is not. Use this to guard public methods that register teardown-bearing resources (via `Component.register`, `Component.registerEvent`, `Component.registerDomEvent`, etc.). Registering before load is unsafe: `Component.unload` is a no-op while the component is not loaded, so any teardown registered beforehand would never run if the component is unloaded without first being loaded. The two not-loaded cases are deliberately distinguished. A component that was NEVER loaded is a genuine programming error, so it throws a loud `Error`. A component that has ALREADY been unloaded is not — it is the expected outcome of work that outlived its component (e.g. an `async` method suspended on an `await` while the component was unloaded, then resumed) — so it throws a SilentError, which `handleSilentError` suppresses, letting such work unwind quietly instead of reporting an async error. (Inherited from ComponentEx)
getInFlightLoadPromise()	null \| Promise<void>	Returns the component's in-flight load `Promise` (its `onloadAsync` plus children), or `null` when nothing is loading — either the component loaded fully synchronously or its async load has already settled. Lets a caller scheduled while the component is still loading await the async load tail before acting, instead of racing it. The motivating case is a layout-ready handler (see `LayoutReadyComponent`) that fires because the component was loaded after the workspace layout was already ready: `Component.onload` has run (so `_loaded` is set) but `onloadAsync` may not have finished. (Inherited from ComponentEx)
hasLoadErrors()	boolean	Returns whether the most recent load recorded any failure. Reflects the outcome of the last `load` / `loadWithPromises`: `true` when `onloadAsync` or any child's load threw (synchronously or asynchronously). Unlike `loadWithPromises`, reading this does NOT re-raise the collected errors — it lets a bystander (e.g. a layout-ready handler awaiting the in-flight load) tell whether the load succeeded without adopting a failure that the load's owner is already responsible for. (Inherited from ComponentEx)
isLockedByAncestorForPath(pathOrFile)	boolean	Checks whether the path is locked directly or lies under a `subtree`-locked ancestor folder.
isLockedForPath(pathOrFile)	boolean	Checks whether the note at the given path is currently locked by any plugin.
isMutationBlockedByAncestorForPath(pathOrFile)	boolean	Checks whether a vault mutation of the path is currently blocked by a `shouldBlockMutations` lock on the path itself or on a `subtree`-locked ancestor folder.
isUnloaded()	boolean	Returns whether the component has already been unloaded, as opposed to simply not having been loaded yet. Both states leave `_loaded` false, but they mean opposite things: a component that was never loaded is still ahead of its lifecycle (queueing children before load is legitimate), while an unloaded one is behind it and must not be used any further. The distinction is tracked by a flag set in `load`, NOT by an `Component.onunload` override, because subclasses override `onunload` and may not call `super`. Use it in a long-running `async` method to abandon work whose component was unloaded mid-flight, when unwinding via the SilentError thrown by ensureLoaded / `addChild` is not desired. (Inherited from ComponentEx)
load()	void	Loads the component. (Inherited from ComponentEx)
loadWithPromises()	null \| Promise<void>	Loads the component with promises. Unlike `load`, this method never rejects with an individual error: every failure raised by `onloadAsync` or a child's load is collected, and once everything settles the returned `Promise` rejects with a single `AggregateError` holding all of them. Non-`Error` throwables are normalized via ErrorWrapper.create. (Inherited from ComponentEx)
lockForPath(params)	Disposable	Locks the note at the given path on behalf of this plugin, making it read-only in every current and future `MarkdownView` until the lock is released. Reference-counted: balance each call with a dispose of the returned `Disposable` (ideally via `using`) or `unlockForPath`.
onloadAsync()	Promise<void>	Asynchronously loads the component. Override to add async load logic, which is executed after `Component.onload`. (Inherited from ComponentEx)
onunload()	void	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.
registerDisposable(disposable)	TDisposable	Registers a `Disposable` so it is disposed when this component unloads, and returns it unchanged. The recurring "tie a disposable to the component's lifecycle, then keep using it" idiom: the disposable is disposed on `Component.unload` (or earlier, if the caller disposes it directly — dispose is expected to be idempotent). Guard with ensureLoaded at the call site when registering before load would be unsafe. (Inherited from ComponentEx)
removeChild(component)	TComponent	Removes a child component. (Inherited from ComponentEx)
requestUnlockForPath(pathOrFile)	void	Fully unlocks the note at the given path: resolves the lock covering it (the path itself when directly locked, otherwise a `subtree`-locked ancestor folder), cancels the operation(s) that took the lock by aborting their `AbortController`s, and releases the lock so the note becomes editable — regardless of which plugin holds the lock. Powers the "Unlock active note" command. A no-op when nothing covers the path.
unlockForPath(pathOrFile)	void	Releases one lock previously acquired for the note at the given path via `lockForPath`.

Links to this page: