1 | Node.js - jsonfile
|
2 | ================
|
3 |
|
4 | Easily read/write JSON files in Node.js. _Note: this module cannot be used in the browser._
|
5 |
|
6 | [![npm Package](https://img.shields.io/npm/v/jsonfile.svg?style=flat-square)](https://www.npmjs.org/package/jsonfile)
|
7 | [![build status](https://secure.travis-ci.org/jprichardson/node-jsonfile.svg)](http://travis-ci.org/jprichardson/node-jsonfile)
|
8 | [![windows Build status](https://img.shields.io/appveyor/ci/jprichardson/node-jsonfile/master.svg?label=windows%20build)](https://ci.appveyor.com/project/jprichardson/node-jsonfile/branch/master)
|
9 |
|
10 | <a href="https://github.com/feross/standard"><img src="https://cdn.rawgit.com/feross/standard/master/sticker.svg" alt="Standard JavaScript" width="100"></a>
|
11 |
|
12 | Why?
|
13 | ----
|
14 |
|
15 | Writing `JSON.stringify()` and then `fs.writeFile()` and `JSON.parse()` with `fs.readFile()` enclosed in `try/catch` blocks became annoying.
|
16 |
|
17 |
|
18 |
|
19 | Installation
|
20 | ------------
|
21 |
|
22 | npm install --save jsonfile
|
23 |
|
24 |
|
25 |
|
26 | API
|
27 | ---
|
28 |
|
29 | * [`readFile(filename, [options], callback)`](#readfilefilename-options-callback)
|
30 | * [`readFileSync(filename, [options])`](#readfilesyncfilename-options)
|
31 | * [`writeFile(filename, obj, [options], callback)`](#writefilefilename-obj-options-callback)
|
32 | * [`writeFileSync(filename, obj, [options])`](#writefilesyncfilename-obj-options)
|
33 |
|
34 | ----
|
35 |
|
36 | ### readFile(filename, [options], callback)
|
37 |
|
38 | `options` (`object`, default `undefined`): Pass in any [`fs.readFile`](https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback) options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
|
39 | - `throws` (`boolean`, default: `true`). If `JSON.parse` throws an error, pass this error to the callback.
|
40 | If `false`, returns `null` for the object.
|
41 |
|
42 |
|
43 | ```js
|
44 | const jsonfile = require('jsonfile')
|
45 | const file = '/tmp/data.json'
|
46 | jsonfile.readFile(file, function (err, obj) {
|
47 | if (err) console.error(err)
|
48 | console.dir(obj)
|
49 | })
|
50 | ```
|
51 |
|
52 | You can also use this method with promises. The `readFile` method will return a promise if you do not pass a callback function.
|
53 |
|
54 | ```js
|
55 | const jsonfile = require('jsonfile')
|
56 | const file = '/tmp/data.json'
|
57 | jsonfile.readFile(file)
|
58 | .then(obj => console.dir(obj))
|
59 | .catch(error => console.error(error))
|
60 | ```
|
61 |
|
62 | ----
|
63 |
|
64 | ### readFileSync(filename, [options])
|
65 |
|
66 | `options` (`object`, default `undefined`): Pass in any [`fs.readFileSync`](https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options) options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
|
67 | - `throws` (`boolean`, default: `true`). If an error is encountered reading or parsing the file, throw the error. If `false`, returns `null` for the object.
|
68 |
|
69 | ```js
|
70 | const jsonfile = require('jsonfile')
|
71 | const file = '/tmp/data.json'
|
72 |
|
73 | console.dir(jsonfile.readFileSync(file))
|
74 | ```
|
75 |
|
76 | ----
|
77 |
|
78 | ### writeFile(filename, obj, [options], callback)
|
79 |
|
80 | `options`: Pass in any [`fs.writeFile`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) options or set `replacer` for a [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Can also pass in `spaces` and override `EOL` string.
|
81 |
|
82 |
|
83 | ```js
|
84 | const jsonfile = require('jsonfile')
|
85 |
|
86 | const file = '/tmp/data.json'
|
87 | const obj = { name: 'JP' }
|
88 |
|
89 | jsonfile.writeFile(file, obj, function (err) {
|
90 | if (err) console.error(err)
|
91 | })
|
92 | ```
|
93 | Or use with promises as follows:
|
94 |
|
95 | ```js
|
96 | const jsonfile = require('jsonfile')
|
97 |
|
98 | const file = '/tmp/data.json'
|
99 | const obj = { name: 'JP' }
|
100 |
|
101 | jsonfile.writeFile(file, obj)
|
102 | .then(res => {
|
103 | console.log('Write complete')
|
104 | })
|
105 | .catch(error => console.error(error))
|
106 | ```
|
107 |
|
108 |
|
109 | **formatting with spaces:**
|
110 |
|
111 | ```js
|
112 | const jsonfile = require('jsonfile')
|
113 |
|
114 | const file = '/tmp/data.json'
|
115 | const obj = { name: 'JP' }
|
116 |
|
117 | jsonfile.writeFile(file, obj, { spaces: 2 }, function (err) {
|
118 | if (err) console.error(err)
|
119 | })
|
120 | ```
|
121 |
|
122 | **overriding EOL:**
|
123 |
|
124 | ```js
|
125 | const jsonfile = require('jsonfile')
|
126 |
|
127 | const file = '/tmp/data.json'
|
128 | const obj = { name: 'JP' }
|
129 |
|
130 | jsonfile.writeFile(file, obj, { spaces: 2, EOL: '\r\n' }, function (err) {
|
131 | if (err) console.error(err)
|
132 | })
|
133 | ```
|
134 |
|
135 | **appending to an existing JSON file:**
|
136 |
|
137 | You can use `fs.writeFile` option `{ flag: 'a' }` to achieve this.
|
138 |
|
139 | ```js
|
140 | const jsonfile = require('jsonfile')
|
141 |
|
142 | const file = '/tmp/mayAlreadyExistedData.json'
|
143 | const obj = { name: 'JP' }
|
144 |
|
145 | jsonfile.writeFile(file, obj, { flag: 'a' }, function (err) {
|
146 | if (err) console.error(err)
|
147 | })
|
148 | ```
|
149 |
|
150 | ----
|
151 |
|
152 | ### writeFileSync(filename, obj, [options])
|
153 |
|
154 | `options`: Pass in any [`fs.writeFileSync`](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) options or set `replacer` for a [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Can also pass in `spaces` and override `EOL` string.
|
155 |
|
156 | ```js
|
157 | const jsonfile = require('jsonfile')
|
158 |
|
159 | const file = '/tmp/data.json'
|
160 | const obj = { name: 'JP' }
|
161 |
|
162 | jsonfile.writeFileSync(file, obj)
|
163 | ```
|
164 |
|
165 | **formatting with spaces:**
|
166 |
|
167 | ```js
|
168 | const jsonfile = require('jsonfile')
|
169 |
|
170 | const file = '/tmp/data.json'
|
171 | const obj = { name: 'JP' }
|
172 |
|
173 | jsonfile.writeFileSync(file, obj, { spaces: 2 })
|
174 | ```
|
175 |
|
176 | **overriding EOL:**
|
177 |
|
178 | ```js
|
179 | const jsonfile = require('jsonfile')
|
180 |
|
181 | const file = '/tmp/data.json'
|
182 | const obj = { name: 'JP' }
|
183 |
|
184 | jsonfile.writeFileSync(file, obj, { spaces: 2, EOL: '\r\n' })
|
185 | ```
|
186 |
|
187 | **appending to an existing JSON file:**
|
188 |
|
189 | You can use `fs.writeFileSync` option `{ flag: 'a' }` to achieve this.
|
190 |
|
191 | ```js
|
192 | const jsonfile = require('jsonfile')
|
193 |
|
194 | const file = '/tmp/mayAlreadyExistedData.json'
|
195 | const obj = { name: 'JP' }
|
196 |
|
197 | jsonfile.writeFileSync(file, obj, { flag: 'a' })
|
198 | ```
|
199 |
|
200 | License
|
201 | -------
|
202 |
|
203 | (MIT License)
|
204 |
|
205 | Copyright 2012-2016, JP Richardson <jprichardson@gmail.com>
|