json-file

A module for reading, writing, and manipulating JSON files

Importing the package

import JsonFile from '@exponent/json-file';

Promise-based async API

Everything returns Promises. If you are using ES7 (or Babel), you can write code like this:

let config = await JsonFile.readAsync('config.json', {cantReadFileDefault: {}});

If you are using ES6, you can just use the return values the way you normally would use Promises.

JsonFile.readAsync('config.json', {cantReadFileDefault: {}}).then(config => {
   ...
});

Used as an object

var file = new JsonFile('config.json', {cantReadFileDefault: {}});
var somethingSaved = await file.getAsync('somethingSaved', null);

Used as functions

var pkg = await JsonFile.readAsync('package.json');
var main = await JsonFile.getAsync('package.json', 'main', 'index.js');
...

Options you can set, and their default values

|Option | Description | Default Value| |-------|-------------|--------------| |space|How many spaces to use when pretty-printing, (0 for no pretty-printing)|2| |default|Catch-all default value for missing values, bad JSON, and files that can't be read|undefined| |jsonParseErrorDefault|The default value for when a file is read but it doesn't contain valid JSON|undefined| |cantReadFileDefault|The default value for when a file can't be read|undefined|

• Note that if defaults are undefined, then an Error will be thrown instead of undefined being returned

Methods

.readAsync([options])

Returns the parse of the whole file as an object

.getAsync(key, [default-value], [options])

Returns a single value from a JSON file, using lodash's _.get to query the whole object.

See https://lodash.com/docs#get

.writeAsync(data, [options])

Writes out the given data to the file

.setAsync(key, val, [options])

Updates the file, inserting or updating the value for <key> with <val>

.mergeAsync(sources, [options])

Merges the values in <sources> into the object currently encoded in the file.

.deleteKeyAsync(key, [options])

Deletes a single key from the top level of the file.

Functions

The functions available all mirror the methods above but take file (filename as a string) as their first argument.