obsidian-dev-utils 55.4.0 → 56.0.0

package/dist/lib/esm/obsidian/plugin/components/plugin-settings-component.d.mts

@@ -0,0 +1,296 @@
+/**
+ * @file
+ *
+ * Component that manages plugin settings: data, persistence, validation, and events.
+ *
+ * This is the single public-facing settings API for plugin authors.
+ * All settings logic (load, save, validate, transform, clone) is handled directly
+ * by this component — no separate manager class is needed.
+ */
+import type { Promisable, ReadonlyDeep } from 'type-fest';
+import type { AsyncEventRef } from '../../../async-events.mjs';
+import type { Transformer } from '../../../transformers/transformer.mjs';
+import type { GenericObject } from '../../../type-guards.mjs';
+import type { MaybeReturn, StringKeys } from '../../../type.mjs';
+import { AsyncComponentBase } from '../../components/async-component.mjs';
+/**
+ * Component key used by {@link registerComponent} to identify settings components.
+ */
+export declare const PLUGIN_SETTINGS_COMPONENT_KEY = "PluginSettingsComponent";
+/**
+ * Params for creating a {@link PluginSettingsComponentBase}.
+ */
+export interface PluginSettingsComponentParams {
+    /**
+     * A function to load data from the plugin's data file.
+     *
+     * @returns The loaded data.
+     */
+    readonly loadData: () => Promise<unknown>;
+    /**
+     * A function to save data to the plugin's data file.
+     *
+     * @param data - The data to save.
+     */
+    readonly saveData: (data: unknown) => Promise<void>;
+}
+/**
+ * A snapshot of plugin settings state, including raw input values, effective (validated) values,
+ * and per-property validation messages.
+ *
+ * @typeParam PluginSettings - The type of the plugin settings.
+ */
+export interface PluginSettingsState<PluginSettings extends object> {
+    /**
+     * The effective settings values used by the plugin. Invalid properties are replaced with defaults.
+     */
+    effectiveValues: PluginSettings;
+    /**
+     * The raw input values as entered by the user. May contain invalid values.
+     */
+    inputValues: PluginSettings;
+    /**
+     * Per-property validation messages. Empty string means valid.
+     */
+    validationMessages: Record<StringKeys<PluginSettings>, string>;
+}
+/**
+ * Readonly version of {@link PluginSettingsState} for use in event callbacks and public getters.
+ *
+ * @typeParam PluginSettings - The type of the plugin settings.
+ */
+export type ReadonlyPluginSettingsState<PluginSettings extends object> = ReadonlyDeep<PluginSettingsState<PluginSettings>>;
+/**
+ * A validator function for a settings property.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ * @typeParam PropertyName - The property name.
+ */
+export type SettingsValidator<PluginSettings extends object, PropertyName extends StringKeys<PluginSettings> = StringKeys<PluginSettings>> = (value: PluginSettings[PropertyName], settings: PluginSettings) => Promisable<MaybeReturn<string>>;
+type PropertyNames<PluginSettings extends object> = StringKeys<PluginSettings>;
+type ValidationResult<PluginSettings extends object> = Partial<Record<StringKeys<PluginSettings>, string>>;
+/**
+ * Base class for plugin settings components.
+ *
+ * Manages settings data, persistence, validation, and events.
+ * Plugin authors extend this class and implement {@link createDefaultSettings}.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ */
+export declare abstract class PluginSettingsComponentBase<PluginSettings extends object> extends AsyncComponentBase {
+    /**
+     * Component key for {@link registerComponent} replacement.
+     */
+    static readonly COMPONENT_KEY = "PluginSettingsComponent";
+    /**
+     * Gets the readonly default settings.
+     *
+     * @returns The default settings (as a readonly object).
+     */
+    readonly defaultSettings: ReadonlyDeep<PluginSettings>;
+    /**
+     * Gets the readonly effective settings (validated, with defaults substituted for invalid values).
+     *
+     * @returns The readonly effective settings.
+     */
+    get settings(): ReadonlyDeep<PluginSettings>;
+    /**
+     * Gets the current settings state snapshot.
+     *
+     * @returns The current settings state.
+     */
+    get settingsState(): ReadonlyPluginSettingsState<PluginSettings>;
+    private readonly asyncEvents;
+    private currentState;
+    private lastSavedState;
+    private readonly legacySettingsConverters;
+    private readonly loadDataFn;
+    private readonly propertyNames;
+    private readonly saveDataFn;
+    private readonly validators;
+    /**
+     * Creates a new plugin settings component.
+     *
+     * @param params - The params for loading/saving data.
+     */
+    constructor(params: PluginSettingsComponentParams);
+    /**
+     * Edits the plugin settings and saves them.
+     *
+     * @param settingsEditor - The editor.
+     * @param context - The context.
+     * @returns A {@link Promise} that resolves when the settings are saved.
+     */
+    editAndSave(settingsEditor: (settings: PluginSettings) => Promisable<void>, context?: unknown): Promise<void>;
+    /**
+     * Ensures the settings are safe.
+     *
+     * It runs validation for each property and sets the default value if the validation fails.
+     *
+     * @param settings - The settings.
+     * @returns A {@link Promise} that resolves when the settings are safe.
+     */
+    ensureSafe(settings: PluginSettings): Promise<void>;
+    /**
+     * Gets a safe copy of the settings.
+     *
+     * @param settings - The settings.
+     * @returns A {@link Promise} that resolves to the safe copy of the settings.
+     */
+    getSafeCopy(settings: PluginSettings): Promise<PluginSettings>;
+    /**
+     * Loads the plugin settings from the file.
+     *
+     * @param isInitialLoad - Whether the settings are being loaded for the first time.
+     * @returns A {@link Promise} that resolves when the settings are loaded.
+     */
+    loadFromFile(isInitialLoad: boolean): Promise<void>;
+    /**
+     * Subscribes to the `loadSettings` event.
+     *
+     * @param name - Always `loadSettings`.
+     * @param callback - The callback.
+     * @param thisArg - The `this` context.
+     * @returns A reference to the event listener.
+     */
+    on(name: 'loadSettings', callback: (loadedState: ReadonlyPluginSettingsState<PluginSettings>, isInitialLoad: boolean) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
+    /**
+     * Subscribes to the `saveSettings` event.
+     *
+     * @param name - Always `saveSettings`.
+     * @param callback - The callback.
+     * @param thisArg - The `this` context.
+     * @returns A reference to the event listener.
+     */
+    on(name: 'saveSettings', callback: (newState: ReadonlyPluginSettingsState<PluginSettings>, oldState: ReadonlyPluginSettingsState<PluginSettings>, context: unknown) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
+    /**
+     * Called when the external settings change.
+     *
+     * @returns A {@link Promise} that resolves when the settings are reloaded.
+     */
+    onExternalSettingsChange(): Promise<void>;
+    /**
+     * Loads settings from file and registers event handlers.
+     */
+    onload(): Promise<void>;
+    /**
+     * Registers a legacy settings converter.
+     *
+     * @typeParam LegacySettings - The legacy settings class.
+     * @param legacySettingsClass - The legacy settings class.
+     * @param converter - The converter.
+     */
+    registerLegacySettingsConverter<LegacySettings extends object>(legacySettingsClass: new () => LegacySettings, converter: (legacySettings: Partial<LegacySettings> & Partial<PluginSettings>) => void): void;
+    /**
+     * Registers a validator for a property.
+     *
+     * @param propertyName - The name of the property.
+     * @param validator - The validator.
+     */
+    registerValidator<PropertyName extends PropertyNames<PluginSettings>>(propertyName: PropertyName, validator: SettingsValidator<PluginSettings, PropertyName>): void;
+    /**
+     * Revalidates the settings.
+     *
+     * @returns The validation messages.
+     */
+    revalidate(): Promise<Record<PropertyNames<PluginSettings>, string>>;
+    /**
+     * Saves the new plugin settings.
+     *
+     * @param context - The context of the save to file operation.
+     * @returns A {@link Promise} that resolves when the settings are saved.
+     */
+    saveToFile(context?: unknown): Promise<void>;
+    /**
+     * Sets the value of a property.
+     *
+     * @typeParam PropertyName - The name of the property.
+     * @param propertyName - The name of the property.
+     * @param value - The value to set.
+     * @returns A {@link Promise} that resolves to the validation message.
+     */
+    setProperty<PropertyName extends PropertyNames<PluginSettings>>(propertyName: PropertyName, value: PluginSettings[PropertyName]): Promise<string>;
+    /**
+     * Validates the settings.
+     *
+     * @param settings - The settings.
+     * @returns A {@link Promise} that resolves to the validation result.
+     */
+    validate(settings: PluginSettings): Promise<ValidationResult<PluginSettings>>;
+    /**
+     * Creates the default settings. Must be implemented by subclasses.
+     *
+     * @returns The default settings.
+     */
+    protected abstract createDefaultSettings(): PluginSettings;
+    /**
+     * Gets the transformer.
+     *
+     * @returns The transformer.
+     */
+    protected getTransformer(): Transformer;
+    /**
+     * Called when the plugin settings record is loaded from disk.
+     *
+     * @param record - The record.
+     */
+    protected onLoadRecord(record: GenericObject): Promise<void>;
+    /**
+     * Called when settings are loaded or reloaded.
+     *
+     * @param _loadedState - The loaded settings state.
+     * @param _isInitialLoad - Whether this is the initial load.
+     */
+    protected onLoadSettings(_loadedState: ReadonlyPluginSettingsState<PluginSettings>, _isInitialLoad: boolean): Promise<void>;
+    /**
+     * Called when settings are saved.
+     *
+     * @param _newState - The new settings state.
+     * @param _oldState - The old settings state.
+     * @param _context - The save context.
+     */
+    protected onSaveSettings(_newState: ReadonlyPluginSettingsState<PluginSettings>, _oldState: ReadonlyPluginSettingsState<PluginSettings>, _context: unknown): Promise<void>;
+    /**
+     * Called when the plugin settings record is about to be saved to disk.
+     *
+     * @param _record - The record.
+     */
+    protected onSavingRecord(_record: GenericObject): Promise<void>;
+    /**
+     * Registers the legacy settings converters.
+     * Override to register legacy settings converters.
+     */
+    protected registerLegacySettingsConverters(): void;
+    /**
+     * Registers the validators.
+     * Override to register validators for properties.
+     */
+    protected registerValidators(): void;
+    private cloneSettings;
+    private cloneState;
+    private createDefaultState;
+    private edit;
+    private isValidPropertyName;
+    private rawRecordToSettings;
+    private saveToFileImpl;
+    private setPropertyImpl;
+    private settingsToRawRecord;
+}
+/**
+ * A no-op settings component for plugins without settings.
+ */
+export declare class EmptyPluginSettingsComponent extends PluginSettingsComponentBase<object> {
+    /**
+     * Creates a new empty plugin settings component.
+     *
+     * @param params - The params. Uses no-op load/save by default.
+     */
+    constructor(params?: PluginSettingsComponentParams);
+    /**
+     * Creates empty default settings.
+     *
+     * @returns An empty object.
+     */
+    protected createDefaultSettings(): object;
+}
+export {};