1 | Node.js - jsonfile
|
2 | ================
|
3 |
|
4 | Easily read/write JSON files.
|
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)
|
30 |
|
31 | `options` (`object`, default `undefined`): Pass in any `fs.readFile` options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
|
32 | - `throws` (`boolean`, default: `true`). If `JSON.parse` throws an error, pass this error to the callback.
|
33 | If `false`, returns `null` for the object.
|
34 |
|
35 |
|
36 | ```js
|
37 | var jsonfile = require('jsonfile')
|
38 | var file = '/tmp/data.json'
|
39 | jsonfile.readFile(file, function(err, obj) {
|
40 | console.dir(obj)
|
41 | })
|
42 | ```
|
43 |
|
44 |
|
45 | ### readFileSync(filename, [options])
|
46 |
|
47 | `options` (`object`, default `undefined`): Pass in any `fs.readFileSync` options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
|
48 | - `throws` (`boolean`, default: `true`). If an error is encountered reading or parsing the file, throw the error. If `false`, returns `null` for the object.
|
49 |
|
50 | ```js
|
51 | var jsonfile = require('jsonfile')
|
52 | var file = '/tmp/data.json'
|
53 |
|
54 | console.dir(jsonfile.readFileSync(file))
|
55 | ```
|
56 |
|
57 |
|
58 | ### writeFile(filename, obj, [options], callback)
|
59 |
|
60 | `options`: Pass in any `fs.writeFile` 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`.
|
61 |
|
62 |
|
63 | ```js
|
64 | var jsonfile = require('jsonfile')
|
65 |
|
66 | var file = '/tmp/data.json'
|
67 | var obj = {name: 'JP'}
|
68 |
|
69 | jsonfile.writeFile(file, obj, function (err) {
|
70 | console.error(err)
|
71 | })
|
72 | ```
|
73 |
|
74 | **formatting with spaces:**
|
75 |
|
76 | ```js
|
77 | var jsonfile = require('jsonfile')
|
78 |
|
79 | var file = '/tmp/data.json'
|
80 | var obj = {name: 'JP'}
|
81 |
|
82 | jsonfile.writeFile(file, obj, {spaces: 2}, function(err) {
|
83 | console.error(err)
|
84 | })
|
85 | ```
|
86 |
|
87 | **appending to an existing JSON file:**
|
88 |
|
89 | You can use `fs.writeFile` option `{flag: 'a'}` to achieve this.
|
90 |
|
91 | ```js
|
92 | var jsonfile = require('jsonfile')
|
93 |
|
94 | var file = '/tmp/mayAlreadyExistedData.json'
|
95 | var obj = {name: 'JP'}
|
96 |
|
97 | jsonfile.writeFile(file, obj, {flag: 'a'}, function (err) {
|
98 | console.error(err)
|
99 | })
|
100 | ```
|
101 |
|
102 | ### writeFileSync(filename, obj, [options])
|
103 |
|
104 | `options`: Pass in any `fs.writeFileSync` 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`.
|
105 |
|
106 | ```js
|
107 | var jsonfile = require('jsonfile')
|
108 |
|
109 | var file = '/tmp/data.json'
|
110 | var obj = {name: 'JP'}
|
111 |
|
112 | jsonfile.writeFileSync(file, obj)
|
113 | ```
|
114 |
|
115 | **formatting with spaces:**
|
116 |
|
117 | ```js
|
118 | var jsonfile = require('jsonfile')
|
119 |
|
120 | var file = '/tmp/data.json'
|
121 | var obj = {name: 'JP'}
|
122 |
|
123 | jsonfile.writeFileSync(file, obj, {spaces: 2})
|
124 | ```
|
125 |
|
126 | **appending to an existing JSON file:**
|
127 |
|
128 | You can use `fs.writeFileSync` option `{flag: 'a'}` to achieve this.
|
129 |
|
130 | ```js
|
131 | var jsonfile = require('jsonfile')
|
132 |
|
133 | var file = '/tmp/mayAlreadyExistedData.json'
|
134 | var obj = {name: 'JP'}
|
135 |
|
136 | jsonfile.writeFileSync(file, obj, {flag: 'a'})
|
137 | ```
|
138 |
|
139 | ### spaces
|
140 |
|
141 | Global configuration to set spaces to indent JSON files.
|
142 |
|
143 | **default:** `null`
|
144 |
|
145 | ```js
|
146 | var jsonfile = require('jsonfile')
|
147 |
|
148 | jsonfile.spaces = 4
|
149 |
|
150 | var file = '/tmp/data.json'
|
151 | var obj = {name: 'JP'}
|
152 |
|
153 | // json file has four space indenting now
|
154 | jsonfile.writeFile(file, obj, function (err) {
|
155 | console.error(err)
|
156 | })
|
157 | ```
|
158 |
|
159 | Note, it's bound to `this.spaces`. So, if you do this:
|
160 |
|
161 | ```js
|
162 | var myObj = {}
|
163 | myObj.writeJsonSync = jsonfile.writeFileSync
|
164 | // => this.spaces = null
|
165 | ```
|
166 |
|
167 | Could do the following:
|
168 |
|
169 | ```js
|
170 | var jsonfile = require('jsonfile')
|
171 | jsonfile.spaces = 4
|
172 | jsonfile.writeFileSync(file, obj) // will have 4 spaces indentation
|
173 |
|
174 | var myCrazyObj = {spaces: 32}
|
175 | myCrazyObj.writeJsonSync = jsonfile.writeFileSync
|
176 | myCrazyObj.writeJsonSync(file, obj) // will have 32 space indentation
|
177 | myCrazyObj.writeJsonSync(file, obj, {spaces: 2}) // will have only 2
|
178 | ```
|
179 |
|
180 |
|
181 | License
|
182 | -------
|
183 |
|
184 | (MIT License)
|
185 |
|
186 | Copyright 2012-2016, JP Richardson <jprichardson@gmail.com>
|