1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
# json-parse-even-better-errors
[`json-parse-even-better-errors`](https://github.com/npm/json-parse-even-better-errors)
is a Node.js library for getting nicer errors out of `JSON.parse()`,
including context and position of the parse errors.
It also preserves the newline and indentation styles of the JSON data, by
putting them in the object or array in the `Symbol.for('indent')` and
`Symbol.for('newline')` properties.
## Install
`$ npm install --save json-parse-even-better-errors`
## Table of Contents
* [Example](#example)
* [Features](#features)
* [Contributing](#contributing)
* [API](#api)
* [`parse`](#parse)
### Example
```javascript
const parseJson = require('json-parse-even-better-errors')
parseJson('"foo"') // returns the string 'foo'
parseJson('garbage') // more useful error message
parseJson.noExceptions('garbage') // returns undefined
```
### Features
* Like JSON.parse, but the errors are better.
* Strips a leading byte-order-mark that you sometimes get reading files.
* Has a `noExceptions` method that returns undefined rather than throwing.
* Attaches the newline character(s) used to the `Symbol.for('newline')`
property on objects and arrays.
* Attaches the indentation character(s) used to the `Symbol.for('indent')`
property on objects and arrays.
## Indentation
To preserve indentation when the file is saved back to disk, use
`data[Symbol.for('indent')]` as the third argument to `JSON.stringify`, and
if you want to preserve windows `\r\n` newlines, replace the `\n` chars in
the string with `data[Symbol.for('newline')]`.
For example:
```js
const txt = await readFile('./package.json', 'utf8')
const data = parseJsonEvenBetterErrors(txt)
const indent = Symbol.for('indent')
const newline = Symbol.for('newline')
// .. do some stuff to the data ..
const string = JSON.stringify(data, null, data[indent]) + '\n'
const eolFixed = data[newline] === '\n' ? string
: string.replace(/\n/g, data[newline])
await writeFile('./package.json', eolFixed)
```
Indentation is determined by looking at the whitespace between the initial
`{` and `[` and the character that follows it. If you have lots of weird
inconsistent indentation, then it won't track that or give you any way to
preserve it. Whether this is a bug or a feature is debatable ;)
### API
#### <a name="parse"></a> `parse(txt, reviver = null, context = 20)`
Works just like `JSON.parse`, but will include a bit more information when
an error happens, and attaches a `Symbol.for('indent')` and
`Symbol.for('newline')` on objects and arrays. This throws a
`JSONParseError`.
#### <a name="parse"></a> `parse.noExceptions(txt, reviver = null)`
Works just like `JSON.parse`, but will return `undefined` rather than
throwing an error.
#### <a name="jsonparseerror"></a> `class JSONParseError(er, text, context = 20, caller = null)`
Extends the JavaScript `SyntaxError` class to parse the message and provide
better metadata.
Pass in the error thrown by the built-in `JSON.parse`, and the text being
parsed, and it'll parse out the bits needed to be helpful.
`context` defaults to 20.
Set a `caller` function to trim internal implementation details out of the
stack trace. When calling `parseJson`, this is set to the `parseJson`
function. If not set, then the constructor defaults to itself, so the
stack trace will point to the spot where you call `new JSONParseError`.
|
