sf201 / electron-prefs

User preferences and configuration settings persistence feature for Electron-based apps.

Electron-prefs

User preferences and configuration settings persistence feature for Electron-based apps.

Overview

As Electron doesn't provide a built-in mechanism to easily persist and retrieve user preferences and configuration settings, install and include the electron-prefs module in your Electron project and let it handle that for you, so you can focus on your app development.

You can use the electron-prefs module directly in both the main and renderer process.

All user preferences and configuration settings are stored locally in a JSON file and can be accessed using app.getPath('userData').

Installation

npm install electron-prefs

or

npm install --save electron-prefs

---

Usage

const electron = require("electron");
const ElectronPrefs = require('electron-prefs');
const prefs = new ElectronPrefs({
  fileName: "config.js",
  defaults: {
    window: {
      width: 600,
      height: 300
    }
  }
});

prefs.set('foo', 'bar');
console.log(prefs.get('foo'));
//=> bar

console.log(prefs.get("window"));
//=> { width: 600, height: 300 }

// use dot-notation to access nested properties
prefs.set('window.width', 700);
console.log(prefs.get("window"));
//=> { width: 700, height: 300 }
console.log(prefs.get('window.width'));
//=> 700

prefs.delete('foo');
console.log(prefs.get('foo'));
//=> undefined

---

API

• Constructor:

  ▸ new ElectronPrefs(mOptions)

  Creates an instance of ElectronPrefs.

  Parameters:

  Type	Name	Description
  Object	mOptions	A JSON-like object containing instance options
  String	mOptions.fileName	The name of the file where preferences are stored
  String	mOptions.sFilePath	The full path to the settings data file.
  Object	mOptions.defaults	A set of default settings and/or preferences

  ---

• Properties:

  Type	Name	Description	Read-only	Static
  Object	defaults	The default values for this instance.	Yes	No
  String	path	The full path to the configuration data file.	Yes	No
  Number	size	he number of entries in the settings file (same as length).	Yes	No
  Number	length	he number of entries in the settings file (same as size).	Yes	No
  Function	superClass	Returns a reference to the super class.	Yes	Yes

  ---

• Methods:

  ▸ ElectronPrefs.superClass.parseDataFile(sFilePath, mDefaults)

  Reads the settings data file and returns its content as a JSON object.

  Parameters:

  Type	Name	Description
  String	sFilePath	The full path to the settings data file.
  Object	mDefaults	A set of default values to return if it fails loading the settings data file.

  Returns: Object - A JSON-like object containing the settings and user preferences iub the data file.

  ---

  ▸ ElectronPrefs.superClass.flattenObject(oObj, sSeparator)

  Flattens nested objects into a single-depth object. For example:

  { foo: 'bar', baz: { foo: 'bar' } }

  will turn into:

  { foo: 'bar', 'baz.foo': 'bar' }

  Parameters:

  Type	Name	Description
  Object	oObj	The object (with nested objects) to flatten.
  String	sSeparator	A string to use as separator between the keys. By default, the separator is . (dot).

  Returns: Object - The flatten object.

  ---

  ▸ ElectronPrefs.prototype.clear()

  Removes all the settings in the settings list.

  Parameters: None

  Returns: ElectronPrefs - Self-reference for method chaining calls.

  ---

  ▸ ElectronPrefs.prototype.delete(sKey)

  Removes the specified settings item from the settings list.

  Parameters:

  Type	Name	Description
  String	sKey	The settings item to remove.

  Returns: ElectronPrefs - Self-reference for method chaining calls.

  ---

  ▸ ElectronPrefs.prototype.entries()

  Returns a array containing all the [key, value] pairs for each settings item in the settings list.

  Parameters: None

  Returns: Array - The [key, value] pairs array.

  ---

  ▸ ElectronPrefs.prototype.forEach(fCallback, thisArg)

  Executes the given function once for each key-value pair in the settings list.

  Parameters:

  Type	Name	Description
  Function	fCallback	The function to execute for each key-value pair.
  Object	thisArg	The value of this when executing the callback function.

  Returns: ElectronPrefs - Self-reference for method chaining calls.

  ---

  ▸ ElectronPrefs.prototype.has(sKey)

  Returns whether the settings list contains a settings item with the given key or not.

  Parameters:

  Type	Name	Description
  String	sKey	The key to check the settings list for.

  Returns: Boolean - true if the settings list contains a settings item with given key, or false otherwise.

  ---

  ▸ ElectronPrefs.prototype.get(sKey)

  Gets the value of the settings item referenced by the given key in the settings list, or the whole list if no key is given.

  Parameters:

  Type	Name	Description
  String	sKey	The key of a settings item in the settings list.

  Returns: any - The value of the settings item referenced by the key in the settings list, or the whole list if no key is given.

  ---

  ▸ ElectronPrefs.prototype.set(sKey, sValue)

  Sets the given value as the value of the settings item referenced by the given key in the settings list.

  Parameters:

  Type	Name	Description
  String	sKey	The key of a settings item in the settings list.
  any	sValue	The value to assign to the settings item referenced by the key in the settings list.

  Returns: ElectronPrefs - Self-reference for method chaining calls.

  ---

  ▸ ElectronPrefs.prototype.keys()

  Returns the names of all enumerable settings and preferences of this object.

  Parameters: None

  Returns: String[] - The names of the enumerable settings and preferences.

  ---

  ▸ ElectronPrefs.prototype.values()

  Returns the names of all enumerable settings and preferences of this object.

  Parameters: None

  Returns: String[] - The values of the enumerable settings and preferences.

---

Version

1.0.8

---