The parser is compatibile with aeson and its FromJSON class.
It is possible to use aeson monadic parsing when appropriate.

The parser supports constant-space safe incremental parsing regardless
of the input data. In addition to performance-critical parts written in C,
a lot of performance is gained by being less memory intensive especially
when used for stream parsing.

Maintainer's Corner

Readme for json-stream-0.4.2.0

json-stream - Applicative incremental JSON parser for Haskell

Most haskellers use the excellent aeson library
to decode and encode JSON structures. Unfortunately, although very fast, this parser
must read the whole structure into memory. At a first sight it seemed that creating
an incremental JSON parser would be very hard thing to do; it turned out to be
remarkable easy. Just wondering, why nobody came with this earlier...

Parsing performance is generally better than aeson, sometimes significantly better.
Json-stream uses a small and fast C lexer to parse the JSON into tokens. This results
in quite significant performance gain. Ideal scenario is parsing large files
where not all information is required; json-stream parses only what is really needed.

Standard aeson library reads the whole input, creates an object in memory representing
the JSON structure which is then converted into proper values using FromJSON instances.
This library is compatible with aeson - you can immediately use FromJSON instances almost without
any change in code and enjoy incremental parsing. The real strength is in the applicative interface
which allows to parse only those parts of JSON that are of interest while skipping what is not needed.

The parsing process uses the least amount of memory possible and is completely lazy. It does not perfectly
check for JSON syntax and the behaviour on incorrect JSON input is undefined (it cheats quite a lot;
but this is needed for constant-space parsing). The result on badly formed input is undefined,
the parser does not guarantee failing on bad input.

The parser generally does not fail. If the data does not match, the parser silently ignores it.
The failures should be only syntax errors in JSON.

The ',' and ':' characters in the lexer are treated as white-space.

When a value is not needed to be parsed, it is parsed by a parser counting braces and brackets.
Anything can happen, the parser just waits for the sum of openings to equal sum of closings.

The length of an object key is limited to ~64K, records with longer keys are ignored.

Motivation

Result of ElasticSearch bulk operations is a large JSON with this structure:

We want the parser to return an empty list immediately when it encounters the errors key
and the value is false. If the value is true, we want the parser to return a list of
_id keys with an error status.

Performance

Json-stream is fast. The crude lexing is done by a C-optimized code in batches, the
lexed pieces are then parsed using the user-specified parser. Compared to aeson, parsing
can be easily twice as fast, especially on larger structures.
Json-stream is in streaming mode much friendlier to the GC,
which makes the performance difference even bigger; however even when json-stream is used
as an aeson replacement (value parser), there can be a performance gain (running aeson benchmarks
has shown that json-stream is generally about twice as fast).

Using json-stream parser instead of aeson value evades the need to build the structure
using aeson Value and then converting it to the user-requested structure. Instead
the structure is built on the fly directly during the parsing phase.

Json-stream can optimize certain scenarios. If not all data from the input stream is
required, it is skipped by the parsers. Using integer parser
with bounded integer types (not Integer) avoids converting all numbers to
Scientific type.

Constant space parsing

If the matching parser follows certain rules and the input chunks have limited size,
the parsing should run in constant space. If you have a large JSON structure but need
only small pieces, the parsing can be very fast - when the data does not match what
is expected, it is parsed only by the lexical parser and ignored. The object key
length is limited to 64K, maximum length of a string can be limited with safeString
parser. The number of digits in a number is limited to 200.000, longer number will
make the parser fail.