obsidian-dev-utils/dist/lib/cjs/obsidian/Plugin/PluginSettingsManagerBase.d.cts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * Plugin settings manager base class.
 */
import type { App } from 'obsidian';
import type { Promisable, ReadonlyDeep } from 'type-fest';
import type { AsyncEventRef } from '../../AsyncEvents.cjs';
import type { GenericObject } from '../../ObjectUtils.cjs';
import type { Transformer } from '../../Transformers/Transformer.cjs';
import type { MaybeReturn, StringKeys } from '../../Type.cjs';
import type { ExtractPlugin, ExtractPluginSettings, ExtractPluginSettingsPropertyNames, ExtractReadonlyPluginSettingsWrapper, PluginTypesBase } from './PluginTypesBase.cjs';
import { AsyncEvents } from '../../AsyncEvents.cjs';
type ValidationResult<PluginSettings extends object> = Partial<Record<StringKeys<PluginSettings>, string>>;
type Validator<PluginSettings extends object, PropertyName extends StringKeys<PluginSettings> = StringKeys<PluginSettings>> = (value: PluginSettings[PropertyName], settings: PluginSettings) => Promisable<MaybeReturn<string>>;
/**
 * Base class for managing plugin settings.
 *
 * @typeParam PluginTypes - Plugin-specific types.
 */
export declare abstract class PluginSettingsManagerBase<PluginTypes extends PluginTypesBase> extends AsyncEvents {
    readonly plugin: ExtractPlugin<PluginTypes>;
    /**
     * Gets the app.
     *
     * @returns The app.
     */
    readonly app: App;
    /**
     * Gets the readonly default settings.
     *
     * @returns The default settings (as a readonly object).
     */
    readonly defaultSettings: ReadonlyDeep<ExtractPluginSettings<PluginTypes>>;
    /**
     * Gets the current settings wrapper.
     *
     * @returns The current settings wrapper.
     */
    get settingsWrapper(): ExtractReadonlyPluginSettingsWrapper<PluginTypes>;
    private currentSettingsWrapper;
    private lastSavedSettingsWrapper;
    private readonly legacySettingsConverters;
    private readonly propertyNames;
    private readonly validators;
    /**
     * Creates a new plugin settings manager.
     *
     * @param plugin - The plugin.
     */
    constructor(plugin: ExtractPlugin<PluginTypes>);
    /**
     * 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: ExtractPluginSettings<PluginTypes>) => 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: ExtractPluginSettings<PluginTypes>): 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: ExtractPluginSettings<PluginTypes>): Promise<ExtractPluginSettings<PluginTypes>>;
    /**
     * 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 to call when the event is triggered.
     * @param thisArg - The context passed as `this` to the `callback`.
     * @returns A reference to the event listener.
     */
    on(name: 'loadSettings', callback: (loadedSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, isInitialLoad: boolean) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
    /**
     * Subscribes to the `saveSettings` event.
     *
     * @param name - Always `saveSettings`.
     * @param callback - The callback to call when the event is triggered.
     * @param thisArg - The context passed as `this` to the `callback`.
     * @returns A reference to the event listener.
     */
    on(name: 'saveSettings', callback: (newSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, oldSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, context: unknown) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
    /**
     * Revalidates the settings.
     *
     * @returns The validation messages.
     */
    revalidate(): Promise<Record<ExtractPluginSettingsPropertyNames<PluginTypes>, 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 ExtractPluginSettingsPropertyNames<PluginTypes>>(propertyName: PropertyName, value: ExtractPluginSettings<PluginTypes>[PropertyName]): Promise<string>;
    /**
     * Validates the settings.
     *
     * @param settings - The settings.
     * @returns A {@link Promise} that resolves to the validation result.
     */
    validate(settings: ExtractPluginSettings<PluginTypes>): Promise<ValidationResult<ExtractPluginSettings<PluginTypes>>>;
    protected abstract createDefaultSettings(): ExtractPluginSettings<PluginTypes>;
    /**
     * Gets the transformer.
     *
     * @returns The transformer.
     */
    protected getTransformer(): Transformer;
    /**
     * Called when the plugin settings are loaded.
     *
     * @param record - The record.
     */
    protected onLoadRecord(record: GenericObject): Promise<void>;
    /**
     * Called when the plugin settings are saving.
     *
     * @param _record - The record.
     */
    protected onSavingRecord(_record: GenericObject): Promise<void>;
    /**
     * Registers a legacy settings converter.
     *
     * @typeParam LegacySettings - The legacy settings class.
     * @param legacySettingsClass - The legacy settings class.
     * @param converter - The converter.
     */
    protected registerLegacySettingsConverter<LegacySettings extends object>(legacySettingsClass: new () => LegacySettings, converter: (legacySettings: Partial<ExtractPluginSettings<PluginTypes>> & Partial<LegacySettings>) => void): void;
    /**
     * Registers the legacy settings converters.
     *
     * This method can be overridden by subclasses to register legacy settings converters.
     */
    protected registerLegacySettingsConverters(): void;
    /**
     * Registers a validator for a property.
     *
     * @param propertyName - The name of the property.
     * @param validator - The validator.
     */
    protected registerValidator<PropertyName extends ExtractPluginSettingsPropertyNames<PluginTypes>>(propertyName: PropertyName, validator: Validator<ExtractPluginSettings<PluginTypes>, PropertyName>): void;
    /**
     * Registers the validators.
     *
     * This method can be overridden by subclasses to register validators for properties.
     */
    protected registerValidators(): void;
    private cloneSettings;
    private cloneSettingsWrapper;
    private createDefaultSettingsWrapper;
    private edit;
    private isValidPropertyName;
    private rawRecordToSettings;
    private saveToFileImpl;
    private setPropertyImpl;
    private settingsToRawRecord;
}
export {};