Have ideas to improve npm?Join in the discussion! »

    electron-json-storage
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/electron-json-storage package

    4.5.0 • Public • Published

    electron-json-storage

    Easily write and read user settings in Electron apps

    npm version dependencies Build Status Build status

    Electron lacks an easy way to persist and read user settings for your application. electron-json-storage implements an API somewhat 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:

    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).

    Running on Electron >10 renderer processes

    When loaded in renderer processes, this module will try to make use of electron.remote in order to fetch the userData path.

    Electron 10 now defaults enableRemoteModule to false, which means that electron-json-storage will be able to calculate a data path by default.

    The solution is to manually call storage.setDataPath() before reading or writing any values or setting enableRemoteModule to true.

    Documentation

    storage.getDefaultDataPath() ⇒ String | Null

    This function will return null when running in the renderer process without support for the remote IPC mechanism. You have to explicitly set a data path using .setDataPath() in these cases.

    Kind: static method of storage
    Summary: Get the default data path
    Returns: String | Null - 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

    Param Type Description
    directory String | Undefined directory

    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

    Param Type Description
    key String key
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error, data)

    Example

    const storage = require('electron-json-storage');
    
    storage.get('foobar', function(error, data) {
      if (error) throw error;
    
      console.log(data);
    });

    storage.getSync(key, [options])

    See .get().

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

    Param Type Description
    key String key
    [options] Object options
    [options.dataPath] String data path

    Example

    const storage = require('electron-json-storage');
    
    var data = storage.getSync('foobar');
    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

    Param Type Description
    keys Array.<String> keys
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error, data)

    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

    Param Type Description
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error, data)

    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

    Param Type Description
    key String key
    json Object json object
    [options] Object options
    [options.dataPath] String data path
    [options.validate] String validate writes by reading the data back
    [options.prettyPrinting] boolean adds line breaks and spacing to the written data
    callback function callback (error)

    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

    Param Type Description
    key String key
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error, hasKey)

    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

    Param Type Description
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error, keys)

    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

    Param Type Description
    key String key
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error)

    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

    Param Type Description
    [options] Object options
    [options.dataPath] String data path
    callback function callback (error)

    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

    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.

    Install

    npm i electron-json-storage

    DownloadsWeekly Downloads

    16,186

    Version

    4.5.0

    License

    MIT

    Unpacked Size

    108 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar