README.md
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 [](https://www.npmjs.org/package/jsonfile) 7 [](http://travis-ci.org/jprichardson/node-jsonfile) 8 [](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`, or override `EOL` string or set `finalEOL` flag as `false` to not save the file with `EOL` at the end. 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 136 **disabling the EOL at the end of file:** 137 138 ```js 139 const jsonfile = require('jsonfile') 140 141 const file = '/tmp/data.json' 142 const obj = { name: 'JP' } 143 144 jsonfile.writeFile(file, obj, { spaces: 2, finalEOL: false }, function (err) { 145 if (err) console.log(err) 146 }) 147 ``` 148 149 **appending to an existing JSON file:** 150 151 You can use `fs.writeFile` option `{ flag: 'a' }` to achieve this. 152 153 ```js 154 const jsonfile = require('jsonfile') 155 156 const file = '/tmp/mayAlreadyExistedData.json' 157 const obj = { name: 'JP' } 158 159 jsonfile.writeFile(file, obj, { flag: 'a' }, function (err) { 160 if (err) console.error(err) 161 }) 162 ``` 163 164 ---- 165 166 ### writeFileSync(filename, obj, [options]) 167 168 `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`, or override `EOL` string or set `finalEOL` flag as `false` to not save the file with `EOL` at the end. 169 170 ```js 171 const jsonfile = require('jsonfile') 172 173 const file = '/tmp/data.json' 174 const obj = { name: 'JP' } 175 176 jsonfile.writeFileSync(file, obj) 177 ``` 178 179 **formatting with spaces:** 180 181 ```js 182 const jsonfile = require('jsonfile') 183 184 const file = '/tmp/data.json' 185 const obj = { name: 'JP' } 186 187 jsonfile.writeFileSync(file, obj, { spaces: 2 }) 188 ``` 189 190 **overriding EOL:** 191 192 ```js 193 const jsonfile = require('jsonfile') 194 195 const file = '/tmp/data.json' 196 const obj = { name: 'JP' } 197 198 jsonfile.writeFileSync(file, obj, { spaces: 2, EOL: '\r\n' }) 199 ``` 200 201 **disabling the EOL at the end of file:** 202 203 ```js 204 const jsonfile = require('jsonfile') 205 206 const file = '/tmp/data.json' 207 const obj = { name: 'JP' } 208 209 jsonfile.writeFileSync(file, obj, { spaces: 2, finalEOL: false }) 210 ``` 211 212 **appending to an existing JSON file:** 213 214 You can use `fs.writeFileSync` option `{ flag: 'a' }` to achieve this. 215 216 ```js 217 const jsonfile = require('jsonfile') 218 219 const file = '/tmp/mayAlreadyExistedData.json' 220 const obj = { name: 'JP' } 221 222 jsonfile.writeFileSync(file, obj, { flag: 'a' }) 223 ``` 224 225 License 226 ------- 227 228 (MIT License) 229 230 Copyright 2012-2016, JP Richardson <jprichardson@gmail.com>