ComponentEx

Extended Component

Import:

import { ComponentEx } from 'obsidian-dev-utils/obsidian/components/component-ex';

Signature:

export class ComponentEx extends Component implements Disposable

Extends: Component

Implements: Disposable

Methods

Method	Returns	Description
[Symbol.dispose]()	void	Disposes of the component.
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`).
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.
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.
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.
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.
load()	void	Loads the component.
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.
onloadAsync()	Promise<void>	Asynchronously loads the component. Override to add async load logic, which is executed after `Component.onload`.
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.
removeChild(component)	TComponent	Removes a child component.

Links to this page: