1# JSONStream
2
3streaming JSON.parse and stringify
4
5![](https://secure.travis-ci.org/dominictarr/JSONStream.png?branch=master)
6
7## install
8```npm install JSONStream```
9
10## example
11
12``` js
13
14var request = require('request')
15  , JSONStream = require('JSONStream')
16  , es = require('event-stream')
17
18request({url: 'http://isaacs.couchone.com/registry/_all_docs'})
19  .pipe(JSONStream.parse('rows.*'))
20  .pipe(es.mapSync(function (data) {
21    console.error(data)
22    return data
23  }))
24```
25
26## JSONStream.parse(path)
27
28parse stream of values that match a path
29
30``` js
31  JSONStream.parse('rows.*.doc')
32```
33
34The `..` operator is the recursive descent operator from [JSONPath](http://goessner.net/articles/JsonPath/), which will match a child at any depth (see examples below).
35
36If your keys have keys that include `.` or `*` etc, use an array instead.
37`['row', true, /^doc/]`.
38
39If you use an array, `RegExp`s, booleans, and/or functions. The `..` operator is also available in array representation, using `{recurse: true}`.
40any object that matches the path will be emitted as 'data' (and `pipe`d down stream)
41
42If `path` is empty or null, no 'data' events are emitted.
43
44If you want to have keys emitted, you can prefix your `*` operator with `$`: `obj.$*` - in this case the data passed to the stream is an object with a `key` holding the key and a `value` property holding the data.
45
46### Examples
47
48query a couchdb view:
49
50``` bash
51curl -sS localhost:5984/tests/_all_docs&include_docs=true
52```
53you will get something like this:
54
55``` js
56{"total_rows":129,"offset":0,"rows":[
57  { "id":"change1_0.6995461115147918"
58  , "key":"change1_0.6995461115147918"
59  , "value":{"rev":"1-e240bae28c7bb3667f02760f6398d508"}
60  , "doc":{
61      "_id":  "change1_0.6995461115147918"
62    , "_rev": "1-e240bae28c7bb3667f02760f6398d508","hello":1}
63  },
64  { "id":"change2_0.6995461115147918"
65  , "key":"change2_0.6995461115147918"
66  , "value":{"rev":"1-13677d36b98c0c075145bb8975105153"}
67  , "doc":{
68      "_id":"change2_0.6995461115147918"
69    , "_rev":"1-13677d36b98c0c075145bb8975105153"
70    , "hello":2
71    }
72  },
73]}
74
75```
76
77we are probably most interested in the `rows.*.doc`
78
79create a `Stream` that parses the documents from the feed like this:
80
81``` js
82var stream = JSONStream.parse(['rows', true, 'doc']) //rows, ANYTHING, doc
83
84stream.on('data', function(data) {
85  console.log('received:', data);
86});
87```
88awesome!
89
90In case you wanted the contents the doc emitted:
91
92``` js
93var stream = JSONStream.parse(['rows', true, 'doc', {emitKey: true}]) //rows, ANYTHING, doc, items in docs with keys
94
95stream.on('data', function(data) {
96  console.log('key:', data.key);
97  console.log('value:', data.value);
98});
99```
100
101### recursive patterns (..)
102
103`JSONStream.parse('docs..value')`
104(or `JSONStream.parse(['docs', {recurse: true}, 'value'])` using an array)
105will emit every `value` object that is a child, grand-child, etc. of the
106`docs` object. In this example, it will match exactly 5 times at various depth
107levels, emitting 0, 1, 2, 3 and 4 as results.
108
109```js
110{
111  "total": 5,
112  "docs": [
113    {
114      "key": {
115        "value": 0,
116        "some": "property"
117      }
118    },
119    {"value": 1},
120    {"value": 2},
121    {"blbl": [{}, {"a":0, "b":1, "value":3}, 10]},
122    {"value": 4}
123  ]
124}
125```
126
127## JSONStream.parse(pattern, map)
128
129provide a function that can be used to map or filter
130the json output. `map` is passed the value at that node of the pattern,
131if `map` return non-nullish (anything but `null` or `undefined`)
132that value will be emitted in the stream. If it returns a nullish value,
133nothing will be emitted.
134
135## JSONStream.stringify(open, sep, close)
136
137Create a writable stream.
138
139you may pass in custom `open`, `close`, and `seperator` strings.
140But, by default, `JSONStream.stringify()` will create an array,
141(with default options `open='[\n', sep='\n,\n', close='\n]\n'`)
142
143If you call `JSONStream.stringify(false)`
144the elements will only be seperated by a newline.
145
146If you only write one item this will be valid JSON.
147
148If you write many items,
149you can use a `RegExp` to split it into valid chunks.
150
151## JSONStream.stringifyObject(open, sep, close)
152
153Very much like `JSONStream.stringify`,
154but creates a writable stream for objects instead of arrays.
155
156Accordingly, `open='{\n', sep='\n,\n', close='\n}\n'`.
157
158When you `.write()` to the stream you must supply an array with `[ key, data ]`
159as the first argument.
160
161## unix tool
162
163query npm to see all the modules that browserify has ever depended on.
164
165``` bash
166curl https://registry.npmjs.org/browserify | JSONStream 'versions.*.dependencies'
167```
168
169## numbers
170
171There are occasional problems parsing and unparsing very precise numbers.
172
173I have opened an issue here:
174
175https://github.com/creationix/jsonparse/issues/2
176
177+1
178
179## Acknowlegements
180
181this module depends on https://github.com/creationix/jsonparse
182by Tim Caswell
183and also thanks to Florent Jaby for teaching me about parsing with:
184https://github.com/Floby/node-json-streams
185
186## license
187
188Dual-licensed under the MIT License or the Apache License, version 2.0
189