79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
|
# json-file
|
||
|
|
A module for reading, writing, and manipulating JSON files
|
||
|
|
|
||
|
|
## Importing the package
|
||
|
|
```js
|
||
|
|
import JsonFile from '@exponent/json-file';
|
||
|
|
```
|
||
|
|
|
||
|
|
## Promise-based async API
|
||
|
|
|
||
|
|
Everything returns `Promise`s. If you are using ES7 (or Babel), you can write code like this:
|
||
|
|
```js
|
||
|
|
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.
|
||
|
|
```js
|
||
|
|
JsonFile.readAsync('config.json', {cantReadFileDefault: {}}).then(config => {
|
||
|
|
...
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Used as an object
|
||
|
|
```js
|
||
|
|
|
||
|
|
var file = new JsonFile('config.json', {cantReadFileDefault: {}});
|
||
|
|
var somethingSaved = await file.getAsync('somethingSaved', null);
|
||
|
|
```
|
||
|
|
|
||
|
|
## Used as functions
|
||
|
|
```js
|
||
|
|
|
||
|
|
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.
|