streaming JSON.\+parse and stringify

\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14458}{}\doxysection{install}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14458}

\begin{DoxyCode}{0}
\DoxyCodeLine{\#\# example}
\DoxyCodeLine{}
\DoxyCodeLine{``` js}
\DoxyCodeLine{}
\DoxyCodeLine{var request = require('request')}
\DoxyCodeLine{  , JSONStream = require('JSONStream')}
\DoxyCodeLine{  , es = require('event-\/stream')}
\DoxyCodeLine{}
\DoxyCodeLine{request(\{url: 'http://isaacs.couchone.com/registry/\_all\_docs'\})}
\DoxyCodeLine{  .pipe(JSONStream.parse('rows.*'))}
\DoxyCodeLine{  .pipe(es.mapSync(function (data) \{}
\DoxyCodeLine{    console.error(data)}
\DoxyCodeLine{    return data}
\DoxyCodeLine{  \})) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14459}{}\doxysection{JSONStream.\+parse(path)}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14459}
parse stream of values that match a path


\begin{DoxyCode}{0}
\DoxyCodeLine{JSONStream.parse('rows.*.doc') }

\end{DoxyCode}


The {\ttfamily ..} operator is the recursive descent operator from \href{http://goessner.net/articles/JsonPath/}{\texttt{ JSONPath}}, which will match a child at any depth (see examples below).

If your keys have keys that include {\ttfamily .} or {\ttfamily $\ast$} etc, use an array instead. `\mbox{[}\textquotesingle{}row', true, /$^\wedge$doc/\mbox{]}\`{}.

If you use an array, {\ttfamily Reg\+Exp}s, booleans, and/or functions. The {\ttfamily ..} operator is also available in array representation, using {\ttfamily \{recurse\+: true\}}. any object that matches the path will be emitted as \textquotesingle{}data\textquotesingle{} (and {\ttfamily pipe}d down stream)

If {\ttfamily path} is empty or null, no \textquotesingle{}data\textquotesingle{} events are emitted.

If you want to have keys emitted, you can prefix your {\ttfamily $\ast$} operator with {\ttfamily \$}\+: {\ttfamily obj.\$$\ast$} -\/ in this case the data passed to the stream is an object with a {\ttfamily key} holding the key and a {\ttfamily value} property holding the data.\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14460}{}\doxysubsection{Examples}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14460}
query a couchdb view\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{curl -\/sS localhost:5984/tests/\_all\_docs\&include\_docs=true }

\end{DoxyCode}
 you will get something like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\{"{}total\_rows"{}:129,"{}offset"{}:0,"{}rows"{}:[}
\DoxyCodeLine{  \{ "{}id"{}:"{}change1\_0.6995461115147918"{}}
\DoxyCodeLine{  , "{}key"{}:"{}change1\_0.6995461115147918"{}}
\DoxyCodeLine{  , "{}value"{}:\{"{}rev"{}:"{}1-\/e240bae28c7bb3667f02760f6398d508"{}\}}
\DoxyCodeLine{  , "{}doc"{}:\{}
\DoxyCodeLine{      "{}\_id"{}:  "{}change1\_0.6995461115147918"{}}
\DoxyCodeLine{    , "{}\_rev"{}: "{}1-\/e240bae28c7bb3667f02760f6398d508"{},"{}hello"{}:1\}}
\DoxyCodeLine{  \},}
\DoxyCodeLine{  \{ "{}id"{}:"{}change2\_0.6995461115147918"{}}
\DoxyCodeLine{  , "{}key"{}:"{}change2\_0.6995461115147918"{}}
\DoxyCodeLine{  , "{}value"{}:\{"{}rev"{}:"{}1-\/13677d36b98c0c075145bb8975105153"{}\}}
\DoxyCodeLine{  , "{}doc"{}:\{}
\DoxyCodeLine{      "{}\_id"{}:"{}change2\_0.6995461115147918"{}}
\DoxyCodeLine{    , "{}\_rev"{}:"{}1-\/13677d36b98c0c075145bb8975105153"{}}
\DoxyCodeLine{    , "{}hello"{}:2}
\DoxyCodeLine{    \}}
\DoxyCodeLine{  \},}
\DoxyCodeLine{]\}}

\end{DoxyCode}


we are probably most interested in the {\ttfamily rows.$\ast$.doc}

create a {\ttfamily Stream} that parses the documents from the feed like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var stream = JSONStream.parse(['rows', true, 'doc']) //rows, ANYTHING, doc}
\DoxyCodeLine{}
\DoxyCodeLine{stream.on('data', function(data) \{}
\DoxyCodeLine{  console.log('received:', data);}
\DoxyCodeLine{\});}
\DoxyCodeLine{//emits anything from \_before\_ the first match}
\DoxyCodeLine{stream.on('header', function (data) \{}
\DoxyCodeLine{  console.log('header:', data) // => \{"{}total\_rows"{}:129,"{}offset"{}:0\}}
\DoxyCodeLine{\})}

\end{DoxyCode}
 awesome!

In case you wanted the contents the doc emitted\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var stream = JSONStream.parse(['rows', true, 'doc', \{emitKey: true\}]) //rows, ANYTHING, doc, items in docs with keys}
\DoxyCodeLine{}
\DoxyCodeLine{stream.on('data', function(data) \{}
\DoxyCodeLine{  console.log('key:', data.key);}
\DoxyCodeLine{  console.log('value:', data.value);}
\DoxyCodeLine{\});}

\end{DoxyCode}


You can also emit the path\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var stream = JSONStream.parse(['rows', true, 'doc', \{emitPath: true\}]) //rows, ANYTHING, doc, items in docs with keys}
\DoxyCodeLine{}
\DoxyCodeLine{stream.on('data', function(data) \{}
\DoxyCodeLine{  console.log('path:', data.path);}
\DoxyCodeLine{  console.log('value:', data.value);}
\DoxyCodeLine{\});}

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14461}{}\doxysubsection{recursive patterns (..)}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14461}
`JSONStream.\+parse(\textquotesingle{}docs..value'){\ttfamily  (or}JSONStream.\+parse(\mbox{[}\textquotesingle{}docs\textquotesingle{}, \{recurse\+: true\}, \textquotesingle{}value\textquotesingle{}\mbox{]}){\ttfamily using an array) will emit every}value{\ttfamily object that is a child, grand-\/child, etc. of the }docs\`{} object. In this example, it will match exactly 5 times at various depth levels, emitting 0, 1, 2, 3 and 4 as results.


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  "{}total"{}: 5,}
\DoxyCodeLine{  "{}docs"{}: [}
\DoxyCodeLine{    \{}
\DoxyCodeLine{      "{}key"{}: \{}
\DoxyCodeLine{        "{}value"{}: 0,}
\DoxyCodeLine{        "{}some"{}: "{}property"{}}
\DoxyCodeLine{      \}}
\DoxyCodeLine{    \},}
\DoxyCodeLine{    \{"{}value"{}: 1\},}
\DoxyCodeLine{    \{"{}value"{}: 2\},}
\DoxyCodeLine{    \{"{}blbl"{}: [\{\}, \{"{}a"{}:0, "{}b"{}:1, "{}value"{}:3\}, 10]\},}
\DoxyCodeLine{    \{"{}value"{}: 4\}}
\DoxyCodeLine{  ]}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14462}{}\doxysection{JSONStream.\+parse(pattern, map)}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14462}
provide a function that can be used to map or filter the json output. {\ttfamily map} is passed the value at that node of the pattern, if {\ttfamily map} return non-\/nullish (anything but {\ttfamily null} or {\ttfamily undefined}) that value will be emitted in the stream. If it returns a nullish value, nothing will be emitted.

{\ttfamily JSONStream} also emits `\textquotesingle{}header'{\ttfamily and}\textquotesingle{}footer\textquotesingle{}{\ttfamily events, the}\textquotesingle{}header\textquotesingle{}{\ttfamily event contains anything in the output that was before the first match, and the}\textquotesingle{}footer\textquotesingle{}\`{}, is anything after the last match.\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14463}{}\doxysection{JSONStream.\+stringify(open, sep, close)}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14463}
Create a writable stream.

you may pass in custom {\ttfamily open}, {\ttfamily close}, and {\ttfamily seperator} strings. But, by default, {\ttfamily JSONStream.\+stringify()} will create an array, (with default options `open='\mbox{[}~\newline
\textquotesingle{}, sep=\textquotesingle{}~\newline
,~\newline
\textquotesingle{}, close=\textquotesingle{}~\newline
\mbox{]}~\newline
\textquotesingle{}\`{})

If you call {\ttfamily JSONStream.\+stringify(false)} the elements will only be seperated by a newline.

If you only write one item this will be valid JSON.

If you write many items, you can use a {\ttfamily Reg\+Exp} to split it into valid chunks.\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14464}{}\doxysection{JSONStream.\+stringify\+Object(open, sep, close)}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14464}
Very much like {\ttfamily JSONStream.\+stringify}, but creates a writable stream for objects instead of arrays.

Accordingly, `open='\{~\newline
\textquotesingle{}, sep=\textquotesingle{}~\newline
,~\newline
\textquotesingle{}, close=\textquotesingle{}~\newline
\}~\newline
\textquotesingle{}\`{}.

When you {\ttfamily .write()} to the stream you must supply an array with {\ttfamily \mbox{[} key, data \mbox{]}} as the first argument.\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14465}{}\doxysection{unix tool}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14465}
query npm to see all the modules that browserify has ever depended on.


\begin{DoxyCode}{0}
\DoxyCodeLine{curl https://registry.npmjs.org/browserify | JSONStream 'versions.*.dependencies' }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14466}{}\doxysection{numbers}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14466}
numbers will be emitted as numbers. huge numbers that cannot be represented in memory as javascript numbers will be emitted as strings. cf \href{https://github.com/creationix/jsonparse/commit/044b268f01c4b8f97fb936fc85d3bcfba179e5bb}{\texttt{ https\+://github.\+com/creationix/jsonparse/commit/044b268f01c4b8f97fb936fc85d3bcfba179e5bb}} for details.\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14467}{}\doxysection{Acknowlegements}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14467}
this module depends on \href{https://github.com/creationix/jsonparse}{\texttt{ https\+://github.\+com/creationix/jsonparse}} by Tim Caswell and also thanks to Florent Jaby for teaching me about parsing with\+: \href{https://github.com/Floby/node-json-streams}{\texttt{ https\+://github.\+com/\+Floby/node-\/json-\/streams}}\hypertarget{md_sfcode_node_modules_JSONStream_readme_autotoc_md14468}{}\doxysection{license}\label{md_sfcode_node_modules_JSONStream_readme_autotoc_md14468}
Dual-\/licensed under the MIT License or the Apache License, version 2.\+0 