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 with promises and callback support somehow similar to localStorage to write and read JSON objects to/from the operating system application data directory, as defined by app.getPath('userData').

Installation

Install electron-json-storage by running:

$ npm install --save electron-json-storage

Renderer process

This module is meant to be used from the main process. You can still remotely require it with:

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

Documentation

• storage
  • .get(key) ⇒ Promise
  • .set(key, json) ⇒ Promise
  • .has(key) ⇒ Promise
  • .keys() ⇒ Promise
  • .remove(key) ⇒ Promise
  • .clear() ⇒ Promise

storage.get(key) ⇒ Promise

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
Fulfil: Object - contents

Param	Type	Description
key	String	key

Example

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

storage.get('foobar').then(function(data) {
  console.log(data);
});

Example

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

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

  console.log(data);
});

storage.set(key, json) ⇒ Promise

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

Param	Type	Description
key	String	key
json	Object	json object

Example

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

storage.set('foobar', { foo: 'bar' });

Example

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

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

storage.has(key) ⇒ Promise

Kind: static method of storage
Summary: Check if a key exists
Access: public
Fulfil: Boolean - whether the key exists

Param	Type	Description
key	String	key

Example

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

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

Example

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

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

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

storage.keys() ⇒ Promise

Kind: static method of storage
Summary: Get the list of saved keys
Access: public
Fulfil: String[] - saved keys
Example

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

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

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) ⇒ Promise

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

Param	Type	Description
key	String	key

Example

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

storage.remove('foobar');

Example

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

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

storage.clear() ⇒ Promise

Kind: static method of storage
Summary: Clear all stored data
Access: public
Example

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

storage.clear();

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 I'll be happy to help.

Tests

Run the test suite by doing:

$ npm test

Contribute

• Issue Tracker: github.com/jviotti/electron-json-storage/issues
• Source Code: github.com/jviotti/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.