electron-data

An easy way to save data, settings or anything else as JSON file in an application folder, using a simple localStorage-like API, but promisified.

For version 1.x see the v1.x branch

Primary developed to work with Electron, but also works in any node application.

Table of Contents

• Installation
• Usage
• API
• Examples
• Development
• Release Notes

Installation

$ npm install --save electron-data

That´s all. You´re done. But wait...You want to use it, too?

Usage

const electron_data = require('electron-data');
 
electron_data.config({/* Your config */});

Without any configuration, the file will be automatically created in your home directory like that: $HOME/.electron-app/data.json.

API

Methods

electron_data.config(options)

• options Object (required)
  • filename String - Name for the file that will be stored and used. Default is data
  • path String - When using Electron, use app.getPath('userData') as value. Absolute path to your application directory. Will be created if not already exists. Default is home-dir-of-os/.electron-app/
  • autosave Boolean - If true, the file will be updated on every data change. Default is false
  • prettysave Boolean - If true, the content of the file will be in a more human readable format. Default is false
  • lastUpdate Boolean - If "true", a property is set, which contains the last update datetime.

electron_data.getOptions()

Resolves the options as object.

electron_data.has(key)

Checks if the data file has a property named key. Resolves boolean.

• key String (required) - Key name

electron_data.keys()

Resolves an array of all presented keys in the data object.

electron_data.get(key)

If the data file has an property named key, resolves the value of given key.

• key String (required) - Key name

electron_data.getMany(keys)

Resolves an object containing given keys and their values. If one or more keys aren´t presented at the data object, they will be skipped.

• keys Array (required) - Array of key names.

electron_data.getAll()

Resolves the whole data object, even if it´s empty.

electron_data.set(key, value)

Sets the given value to the given key in the data file. If one of both is missing, the key isn´t a string or the value isn´t a valid JSON value, the promise rejects an error. For an overview of allowed value types, have a look at json.org.

• key String - Property name
• value ? - Property value. Can be any JSON conform data.

electron_data.setMany(object)

Sets all key => value pairs from given object to the data object. Overrides previous values with the same key.

• object Object (required) - A valid JSON object.

electron_data.unset(key)

Deletes the key => value pair @key.

• key String - Key name

electron_data.clear()

Clears all data. Be careful, the data can´t be restored.

electron_data.save(callback)

Saves the data to the specified file.

Examples

const electron_data = require('electron-data');
 
electron_data.config({
  filename: 'example',
  path: '/my/awesome/directory'
});
 
electron_data.getOptions()
  .then(options => {
    console.log(options);
    /*
    {
      filename: 'example',
      path: '/my/awesome/directory',
      autosave: false,
      prettysave: false,
      lastUpdate: false
    }
    */
  });
 
// Store a key => value
electron_data.set('my-prop', {'awesome': 'module'})
  .then(data => {
    console.log(data); // {'awesome': 'module'}
  }); 
 
// Save the data to a JSON file
electron_data.save()
  .then(error => {
    console.log(error); // undefined
  });
 
// Check if the data has a value for "my-prop"
electron_data.has('my-prop')
  .then(has_key => {
    console.log(has_key); // true
  });
 
// Get the value for "my-prop"
electron_data.get('my-prop')
  .then(value => {
    console.log(value); // {'awesome': 'module'}
  });
 
// Remove "my-prop"
electron_data.unset('my-prop')
  .then(deleted => {
    console.log(deleted); // true
  });
 
// Clear all data
electron_data.clear()
  .then(data => {
    console.log(data); // {}
  });

You can enable autosave, so you don´t have to explicit save your data.

electron_data.config({autosave: true});

To save the data more readable, set the prettysave option.

electron_data.config({prettysave: true});

To save a lastUpdate value , set the lastUpdateoption.

electron_data.config({lastUpdate: true});

Development

Run test:

npm test

Release Notes

• 2.1.2
  • Security Update
    • Update acorn to ^7.1.1
    • Update lodash to ^4.17.12
    • Update mixin-deep to ^1.3.2
    • Update set-value to ^2.0.1
    • Update sshpk to ^1.13.2
• 2.1.1
  • Switch to fs-extra, because fs-promise is deprecated
  • Upgrade dependencies
  • Update tests
• 2.1.0
  • Add new methods (getMany, getAll, setMany, keys). For more informations, read the API-Section
  • Some bugfixes
• 2.0.1
  • Some bugfixes
• 2.0.0
  • Promisify all methods
  • Not using the object-oriented notation anymore. For more informations have a look @Usage
• 1.2.2
  • Reload the data on ElectronData.get()
• 1.2.1
  • Fixed: silent error on non-valid JSON values (Issue #1). For an overview of allowed value types, have a look at json.org.
• 1.2
  • removed Object.observe polyfill and added an elegant Proxy solution.
  • added lastUpdate option. Read Usage for further informations.
• 1.1.1
  • added Object.observe polyfill, because is removed in future V8 releases
• 1.1
  • removed dirname from constructor options
  • added autosave
  • added prettysave
  • added callback to save function
• 1.0 - Initial release