electron-json-storage

Easily write and read user settings in Electron apps

Electron lacks an easy way to persist and read user settings for your application. electron-json-storage implements an API somehow similar to localStorage to write and read JSON objects to/from the operating system application data directory, as defined by app.getPath('userData').

Related modules:

• electron-settings
• electron-store
• electron-storage

Installation

Install electron-json-storage by running:

$ npm install --save electron-json-storage

You can require this module from either the main or renderer process (with and without remote).

Documentation

• storage
  • .getDefaultDataPath() ⇒ String
  • .setDataPath(directory)
  • .getDataPath() ⇒ String
  • .get(key, [options], callback)
  • .getMany(keys, [options], callback)
  • .getAll([options], callback)
  • .set(key, json, [options], callback)
  • .has(key, [options], callback)
  • .keys([options], callback)
  • .remove(key, [options], callback)
  • .clear([options], callback)

storage.getDefaultDataPath() ⇒ String

Kind: static method of storage
Summary: Get the default data path
Returns: String - default data path
Access: public
Example

const defaultDataPath = storage.getDefaultDataPath()

storage.setDataPath(directory)

The default value will be used if the directory is undefined.

Kind: static method of storage
Summary: Set current data path
Access: public

Example

const os = require('os');
const storage = require('electron-json-storage');

storage.setDataPath(os.tmpdir());

storage.getDataPath() ⇒ String

Returns the current data path. It defaults to a directory called "storage" inside Electron's userData path.

Kind: static method of storage
Summary: Get current user data path
Returns: String - the user data path
Access: public
Example

const storage = require('electron-json-storage');

const dataPath = storage.getDataPath();
console.log(dataPath);

storage.get(key, [options], callback)

If the key doesn't exist in the user data, an empty object is returned. Also notice that the .json extension is added automatically, but it's ignored if you pass it yourself.

Passing an extension other than .json will result in a file created with both extensions. For example, the key foo.data will result in a file called foo.data.json.

Kind: static method of storage
Summary: Read user data
Access: public

Example

const storage = require('electron-json-storage');

storage.get('foobar', function(error, data) {
  if (error) throw error;

  console.log(data);
});

storage.getMany(keys, [options], callback)

This function returns an object with the data of all the passed keys. If one of the keys doesn't exist, an empty object is returned for it.

Kind: static method of storage
Summary: Read many user data keys
Access: public

Example

const storage = require('electron-json-storage');

storage.getMany([ 'foobar', 'barbaz' ], function(error, data) {
  if (error) throw error;

  console.log(data.foobar);
  console.log(data.barbaz);
});

storage.getAll([options], callback)

This function returns an empty object if there is no data to be read.

Kind: static method of storage
Summary: Read all user data
Access: public

Example

const storage = require('electron-json-storage');

storage.getAll(function(error, data) {
  if (error) throw error;

  console.log(data);
});

storage.set(key, json, [options], callback)

Kind: static method of storage
Summary: Write user data
Access: public

Example

const storage = require('electron-json-storage');

storage.set('foobar', { foo: 'bar' }, function(error) {
  if (error) throw error;
});

storage.has(key, [options], callback)

Kind: static method of storage
Summary: Check if a key exists
Access: public

Example

const storage = require('electron-json-storage');

storage.has('foobar', function(error, hasKey) {
  if (error) throw error;

  if (hasKey) {
    console.log('There is data stored as `foobar`');
  }
});

storage.keys([options], callback)

Kind: static method of storage
Summary: Get the list of saved keys
Access: public

Example

const storage = require('electron-json-storage');

storage.keys(function(error, keys) {
  if (error) throw error;

  for (var key of keys) {
    console.log('There is a key called: ' + key);
  }
});

storage.remove(key, [options], callback)

Notice this function does nothing, nor throws any error if the key doesn't exist.

Kind: static method of storage
Summary: Remove a key
Access: public

Example

const storage = require('electron-json-storage');

storage.remove('foobar', function(error) {
  if (error) throw error;
});

storage.clear([options], callback)

Kind: static method of storage
Summary: Clear all stored data in the current user data path
Access: public

Example

const storage = require('electron-json-storage');

storage.clear(function(error) {
  if (error) throw error;
});

Support

If you're having any problem, please raise an issue on GitHub and we'll be happy to help.

Tests

Run the test suite by doing:

$ npm test

Contribute

• Issue Tracker: github.com/electron-userland/electron-json-storage/issues
• Source Code: github.com/electron-userland/electron-json-storage

Before submitting a PR, please make sure that you include tests, and that jshint runs without any warning:

$ npm run-script lint

License

The project is licensed under the MIT license.

Change Log

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.

4.1.6 - 2019-01-26

• Implement atomic writes

4.1.5 - 2018-12-02

• Retry on EPERM when locking and reading

4.1.4 - 2018-10-09

Changed

• Set electron as a devDependency

4.1.3 - 2018-10-01

Changed

• Retry lock release if OS reports EPERM

4.1.2 - 2018-08-26

Changed

• Set electron as a peerDependency

4.1.1 - 2018-07-11

Changed

• Ensure parallel writes from multiple processes don't corrupt data

4.1.0 - 2018-04-15

Changed

• Support spaces in keys

4.0.3 - 2018-04-07

Changed

• Remove unnecessary ES6 features from the code base to keep it ES5

4.0.2 - 2017-10-20

Changed

• Ensure the options argument always defaults to an empty object.

4.0.1 - 2017-10-19

Changed

• Don't throw if the user doesn't pass a callback function.

4.0.0 - 2017-10-18

Changed

• React to external changes to the userData path.
• Replace storage.DEFAULT_DATA_PATH with storage.getDefaultDataPath().

3.2.0 - 2017-10-07

Added

• Add dataPath options to every function.

3.1.1 - 2017-09-27

Changed

• Replace asterisks with hyphens in file names to avoid Windows path problems.

3.1.0 - 2017-08-29

Added

• Support storing values in a custom directory.

3.0.7 - 2017-07-27

Changed

• Decode URI encoded file names on .keys()

3.0.6 - 2017-06-29

Changed

• Ensure parallel writes don't corrupt the data.

3.0.5 - 2017-04-14

Changed

• Make the module work on Spectron tests.

3.0.4 - 2017-03-30

Changed

• Get rid of exists-file, which is known to cause UglifyJS issues.

3.0.3 - 2017-03-30

Changed

• Remove ES6 features from the codebase.

3.0.2 - 2017-03-24

Changed

• Ignore .DS_Store in settings directory
• Include the invalid error object on "invalid data" errors

3.0.1 - 2017-01-30

Changed

• Don't throw ENOENT on .getAll() if the user data path directory doesn't exist.

3.0.0 - 2017-01-08

Changed

• Store settings inside a storage/ directory inside userPath.

2.1.1 - 2017-01-08

Changed

• Don't throw ENOENT on .set() if userPath doesn't exist.

2.1.0 - 2016-11-13

Added

• Implement .getAll().
• Implement .getMany().

2.0.3 - 2016-10-27

Changed

• Change let to var for compatibility purposes.

2.0.2 - 2016-10-24

Changed

• Fix "Callback has already been called" error in .get().

2.0.1 - 2016-10-05

Changed

• Prevent errors when using reserved characters in keys in Windows.

2.0.0 - 2016-02-26

Changed

• Ignore GPUCache key, saved by Electron.

Removed

• Remove promises support.

1.1.0 - 2016-02-17

Added

• Implement .keys() function.

Changed

• Fix error when requiring this module from the renderer process.