Logo for jsDocs.io

electron-settings

  • Version 4.0.4
  • Published
  • 49.9 kB
  • 3 dependencies
  • MIT license

Install

npm i electron-settings
yarn add electron-settings
pnpm add electron-settings

Overview

A simple and robust settings management library for Electron.

Index

Functions

Functions

function configure

configure: (customConfig: Partial<Config>) => void;

  • Sets the configuration for Electron Settings. To reset to defaults, use [[reset|reset()]].

    Defaults:

    { atomicSave: true, fileName: 'settings.json', numSpaces: 2, prettify: false }

    Parameter customConfig

    The custom configuration to use.

    Example 1

    Update the filename to cool-settings.json and prettify the output.

    settings.configure({ fileName: 'cool-settings.json', prettify: true });

function file

file: () => string;

  • Returns the path to the settings file.

    In general, the settings file is stored in your app's user data directory in a file called settings.json. The default user data directory varies by system.

    - **macOS** - ~/Library/Application\ Support/<Your App> - **Windows** - %APPDATA%/<Your App> - **Linux** - Either $XDG_CONFIG_HOME/<Your App> or ~/.config/<Your App>

    Although it is not recommended, you may change the name or location of the settings file using [[configure|configure()]].

    Returns

    The path to the settings file.

    Example 1

    Get the path to the settings file.

    settings.file(); // => /home/nathan/.config/MyApp/settings.json

function get

get: { (): Promise<SettingsObject>; (keyPath: KeyPath): Promise<SettingsValue> };

  • Gets all settings. For sync, use [[getSync|getSync()]].

    Core

    Returns

    A promise which resolves with all settings.

    Example 1

    Gets all settings.

    const obj = await get();

  • Gets the value at the given key path. For sync, use [[getSync|getSync()]].

    Core

    Parameter keyPath

    The key path of the property.

    Returns

    A promise which resolves with the value at the given key path.

    Example 1

    Get the value at color.name.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    const value = await settings.get('color.name'); // => "cerulean"

    Example 2

    Get the value at color.hue.

    const h = 'hue'; const value = await settings.get(['color', h]); // => undefined

    Example 3

    Get the value at color.code.rgb[1].

    const h = 'hue'; const value = await settings.get('color.code.rgb[1]'); // => 179

function getSync

getSync: { (): SettingsObject; (keyPath: KeyPath): SettingsValue };

  • Gets all settings. For async, use [[get|get()]].

    Core

    Returns

    All settings.

    Example 1

    Gets all settings.

    const obj = getSync();

  • Gets the value at the given key path. For async, use [[get|get()]].

    Core

    Parameter keyPath

    The key path of the property.

    Returns

    The value at the given key path.

    Example 1

    Get the value at color.name.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    const value = settings.getSync('color.name'); // => "cerulean"

    Example 2

    Get the value at color.hue.

    const h = 'hue'; const value = settings.getSync(['color', h]); // => undefined

    Example 3

    Get the value at color.code.rgb[1].

    const h = 'hue'; const value = settings.getSync('color.code.rgb[1]'); // => 179

function has

has: (keyPath: KeyPath) => Promise<boolean>;

  • Checks if the given key path exists. For sync, use [[hasSync|hasSync()]].

    Core

    Parameter keyPath

    The key path to check.

    Returns

    A promise which resolves to true if the keyPath exists, else false.

    Example 1

    Check if the value at color.name exists.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    const exists = await settings.has('color.name'); // => true

    Example 2

    Check if the value at color.hue exists.

    const h = 'hue'; const exists = await settings.has(['color', h]); // => false

    Example 3

    Check if the value at color.code.rgb[1] exists.

    const exists = await settings.has(color.code.rgb[1]); // => true

function hasSync

hasSync: (keyPath: KeyPath) => boolean;

  • Checks if the given key path exists. For async, use [[hasSync|hasSync()]].

    Core

    Parameter keyPath

    The key path to check.

    Returns

    true if the keyPath exists, else false.

    Example 1

    Check if the value at color.name exists.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    const exists = settings.hasSync('color.name'); // => true

    Example 2

    Check if the value at color.hue exists.

    const h = 'hue'; const exists = settings.hasSync(['color', h]); // => false

    Example 3

    Check if the value at color.code.rgb[1] exists.

    const exists = settings.hasSync(color.code.rgb[1]); // => true

function reset

reset: () => void;

  • Resets the Electron Settings configuration to defaults.

    Example 1

    Reset configuration to defaults.

    settings.reset();

function set

set: {
    (obj: SettingsObject): Promise<void>;
    (keyPath: KeyPath, obj: SettingsValue): Promise<void>;
};

  • Sets all settings. For sync, use [[setSync|setSync()]].

    Core

    Parameter obj

    The new settings.

    Returns

    A promise which resolves when the settings have been set.

    Example 1

    Set all settings.

    await settings.set({ aqpw: 'nice' });

  • Sets the value at the given key path. For sync, use [[setSync|setSync()]].

    Core

    Parameter keyPath

    The key path of the property.

    Parameter value

    The value to set.

    Returns

    A promise which resolves when the setting has been set.

    Example 1

    Change the value at color.name to sapphire.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    await settings.set('color.name', 'sapphire');

    Example 2

    Set the value of color.hue to blue-ish.

    const h = 'hue'; await settings.set(['color', h], 'blue-ish);

    Example 3

    Change the value of color.code.

    await settings.set('color.code', { rgb: [16, 31, 134], hex: '#101F86' });

function setSync

setSync: {
    (obj: SettingsObject): void;
    (keyPath: KeyPath, value: SettingsValue): void;
};

  • Sets all settings. For async, use [[set|set()]].

    Core

    Parameter obj

    The new settings.

    Example 1

    Set all settings.

    settings.setSync({ aqpw: 'nice' });

  • Sets the value at the given key path. For async, use [[set|set()]].

    Core

    Parameter keyPath

    The key path of the property.

    Parameter value

    The value to set.

    Example 1

    Change the value at color.name to sapphire.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    settings.setSync('color.name', 'sapphire');

    Example 2

    Set the value of color.hue to blue-ish.

    const h = 'hue'; settings.setSync(['color', h], 'blue-ish);

    Example 3

    Change the value of color.code.

    settings.setSync('color.code', { rgb: [16, 31, 134], hex: '#101F86' });

function unset

unset: { (): Promise<void>; (keyPath: KeyPath): Promise<void> };

  • Unsets all settings. For sync, use [[unsetSync|unsetSync()]].

    Core

    Returns

    A promise which resolves when the settings have been unset.

    Example 1

    Unsets all settings.

    await settings.unset();

  • Unsets the property at the given key path. For sync, use [[unsetSync|unsetSync()]].

    Core

    Parameter keyPath

    The key path of the property.

    Returns

    A promise which resolves when the setting has been unset.

    Example 1

    Unset the property color.name.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    await settings.unset('color.name');

    await settings.get('color.name'); // => undefined

    Example 2

    Unset the property color.code.rgba[1].

    await settings.unset('color.code.rgba[1]');

    await settings.get('color.code.rgb'); // => [0, null, 230]

function unsetSync

unsetSync: { (): void; (keyPath: KeyPath): void };

  • Unsets all settings. For async, use [[unset|unset()]].

    Core

    Example 1

    Unsets all settings.

    settings.unsetSync();

  • Unsets the property at the given key path. For async, use [[unset|unset()]].

    Core

    Parameter keyPath

    The key path of the property.

    Example 1

    Unset the property color.name.

    // Given: // // { // "color": { // "name": "cerulean", // "code": { // "rgb": [0, 179, 230], // "hex": "#003BE6" // } // } // }

    settings.unsetSync('color.name');

    settings.getSync('color.name'); // => undefined

    Example 2

    Unset the property color.code.rgba[1].

    settings.unsetSync('color.code.rgba[1]');

    settings.getSync('color.code.rgb'); // => [0, null, 230]

Package Files (1)

Dependencies (3)

Dev Dependencies (20)

Peer Dependencies (1)

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/electron-settings.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/electron-settings)
  • HTML
    <a href="https://www.jsdocs.io/package/electron-settings"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>