SettingsFacetComponent<T>
Provides a plugin’s settings to a settings facet in every open editor and in every editor opened later.
Import:
import { SettingsFacetComponent } from '@mnaoumov/obsidian-lib/components/settings-facet-component';Example:
const settingsFacet = createSettingsFacet<MySettings>(DEFAULT_SETTINGS);const settingsFacetComponent = this.addChild(new SettingsFacetComponent({ app: this.app, editorExtensionRegistrar: new PluginEditorExtensionRegistrar(this), facet: settingsFacet, settings: this.settings}));// After the settings change:settingsFacetComponent.setSettings(this.settings);Signature:
export class SettingsFacetComponent<T> extends ReconfigurableEditorExtensionComponentExtends: ReconfigurableEditorExtensionComponent
Constructor
new SettingsFacetComponent(params: SettingsFacetComponentConstructorParams<T>)Creates a new instance of the SettingsFacetComponent class.
Properties
| Property | Type | Description |
|---|---|---|
| app | App | The Obsidian app instance. (Inherited from ReconfigurableEditorExtensionComponent) |
| compartment | Compartment | The compartment the extension lives in, in every editor. (Inherited from ReconfigurableEditorExtensionComponent) |
| editorExtensionRegistrar | EditorExtensionRegistrar | The registrar the extension is registered through, once, on the first load. (Inherited from ReconfigurableEditorExtensionComponent) |
| facet | Facet<T, T> | The facet the settings are provided to. |
Methods
| Method | Returns | Description |
|---|---|---|
| [Symbol.dispose]() | void | Disposes of the component. (Inherited from ReconfigurableEditorExtensionComponent) |
| 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 ReconfigurableEditorExtensionComponent) |
| 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 ReconfigurableEditorExtensionComponent) |
| getInFlightAncestryLoadPromise() | null | Promise<void> | Returns a Promise that settles once neither this component nor any ComponentEx ancestor has a load in flight, or null when none of them has one right now.getInFlightLoadPromise covers this component's OWN load only. A sibling this component depends on — most often the owning plugin's settings component, which reads data.json asynchronously — is outside it, but it is inside the load of a shared ancestor. Waiting for every ancestor therefore waits for the whole tree the component was loaded as part of: under PluginBase the chain ends at the plugin's universal wrapper, whose load covers the dependency gate, the feature surface and onloadImpl.The chain is followed through ComponentEx parents only. A plain Component anywhere between this component and an ancestor ends it, because a plain component records no parent and exposes no load promise. Never await this from inside a load step of one of those ancestors: the ancestor's load would then be waiting for itself. It is meant for work scheduled OUTSIDE the load, such as a layout-ready handler. (Inherited from ReconfigurableEditorExtensionComponent) |
| 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: Component.onload has run (so _loaded is set) but onloadAsync may not have finished.It covers this component's OWN load only. A caller that also depends on a sibling's state — a layout-ready handler reading settings is the common one — wants getInFlightAncestryLoadPromise, which LayoutReadyComponent uses.(Inherited from ReconfigurableEditorExtensionComponent) |
| hasChild(component) | boolean | Checks whether a component is a direct child of this one. Only DIRECT children are reported — this is an ownership question, not a containment one. The caller that needs it is one holding several parents and deciding which of them a component belongs to, and for that a grandchild is the wrong answer: removing it from the parent that merely contains its parent would fail. (Inherited from ReconfigurableEditorExtensionComponent) |
| 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 ReconfigurableEditorExtensionComponent) |
| 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 ReconfigurableEditorExtensionComponent) |
| load() | void | Loads the component. (Inherited from ReconfigurableEditorExtensionComponent) |
| 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.The AggregateError is built by createAggregateError, so its own message names the failure rather than being empty: a lone failure lends its message to every aggregate above it, which is what lets a caller assert on the sentence that was actually thrown without walking errors to find it.(Inherited from ReconfigurableEditorExtensionComponent) |
| onload() | void | Registers the extension on the first load, or restores it into every editor on a later one. (Inherited from ReconfigurableEditorExtensionComponent) |
| onloadAsync() | Promise<void> | Asynchronously loads the component. Override to add async load logic, which is executed after Component.onload.(Inherited from ReconfigurableEditorExtensionComponent) |
| onunload() | void | Empties the extension in every editor, since Obsidian cannot unregister it. (Inherited from ReconfigurableEditorExtensionComponent) |
| reconfigure(extension) | void | Swaps the extension in every open editor and in every editor opened later. Before the component loads, this only records the extension the editors will start with. (Inherited from ReconfigurableEditorExtensionComponent) |
| registerAsyncDisposable(asyncDisposable) | TAsyncDisposable | Registers an AsyncDisposable so its disposal starts when this component unloads, and returns it unchanged.Obsidian's unload is synchronous, so nothing awaits the disposal: it runs detached, and a failure is reported, never rethrown. See the free function registerAsyncDisposable, which this delegates to. (Inherited from ReconfigurableEditorExtensionComponent) |
| 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 ReconfigurableEditorExtensionComponent) |
| removeChild(component) | TComponent | Removes a child component. (Inherited from ReconfigurableEditorExtensionComponent) |
| setSettings(settings) | void | Provides new settings to every open editor and to every editor opened later. |
Links to this page: