Bourne again JSON
Supports stringifying for async generators, Node.js object streams and promises.
Big-friendly asynchronous JSON stringifying. Doesn't block the event loop.
- Why would I want this?
- Is it fast?
- What functions does it implement?
- What kind of async values does it support?
- Is it compatible with
JSON.stringify
? - How do I write a JSON file?
- How do I response with JSON by http?
- Can I lazily stringify data from MongoDB?
- How do I create a JSON string?
- Why does
stringify
emit binary chunks instead of strings?
Why would I want this?
The main feature is that stringify
resolves promises and stringify async iterables, including streams, into arrays on the fly. There's no need to collect their data in an array beforehand, and neither it does that.
bajson
also does not monopolize the event loop and emits limited chunks so it doesn't lead to out-of-memory exceptions on large datasets.
It's considerably faster comparing to other non-blocking package bfj
, although bfj
seems to be more efficient in memory usage. Pick the one that best suits your needs.
Is it fast?
Kind of.
stringify
is about 10 times faster than bfj
package while still avoiding monopolizing the event loop, though it's still 3-4 times slower than the native implementation of JSON.stringify
.
What functions does it implement?
It currently implements stringification, with parsing planned for the future.
import { pipeline } from "node:stream/promises"
import { stringify } from "bajson"
await pipeline(stringify(data), stream)
What kind of async values does it support?
It supports promises and async and sync iterables.
async function createData() {
yield "text"
yield 777
}
stringify(createData())
//-> ["text",777]
stringify({ a: Promise.resolve(42), b: createData() })
//-> {"a":42,"b":["text",777]}
Is it compatible with JSON.stringify?
Yes, it accepts the same arguments and returns the same results in all practical scenarios.
However, there is one difference: stringify
emits 'null'
in cases where JSON.stringify
would return undefined
. This distinction is due to the fact that stringify
cannot return undefined
since it always returns a stream.
JSON.stringify(() => {})
// undefined
JSON.stringify({ a: () => {} })
// "{}"
JSON.stringify([() => {}])
// "[null]"
stringify(() => {})
// "null"
stringify({ a: () => {} })
// "{}"
stringify([() => {}])
// "[null]"
How do I write a JSON file?
import { createWriteStream } from "node:fs"
import { pipeline } from "node:stream/promises"
import { stringify } from "bajson"
await pipeline(stringify(data), createWriteStream(path))
How do I response with JSON by http?
import express from "express"
import { pipeline } from "node:stream/promises"
import { stringify } from "bajson"
const app = express()
app.get("/get-json", async (request, response) => {
response.setHeader("Content-Type", "application/json")
await pipeline(stringify(data), response)
})
Can I lazily stringify data from MongoDB?
Sure.
import express from "express"
import { pipeline } from "node:stream/promises"
import { stringify } from "bajson"
import { Book } from "@/models/book.model"
import { Author } from "@/models/author.model"
import { Publisher } from "@/models/publisher.model"
const app = express()
app.get("/give-me-it-all", async (request, response) => {
response.setHeader("Content-Type", "application/json")
await pipeline(
stringify({
books: Book.find().cursor(),
authors: Author.find().cursor(),
publishers: Publisher.find().cursor(),
}),
response,
)
// {
// "books": [{ "name": "book1", ... }, { "name": "book2", ... }, ...],
// "authors": [{ "name": "author1", ... }, { "name": "author2", ... }, ...],
// "publishers": [{ "name": "publisher1", ... }, { "name": "publisher2", ... }, ...]
// }
})
How do I create a JSON string?
I'm not sure you really want that, but
import { stringify } from "bajson"
import fromAsync from "array-from-async"
await new Blob(await fromAsync(stringify(data))).text()
stringify
emit binary chunks instead of strings?
Why does For practical reasons.
There are scenarios where people need to store stringified JSON within a string field. For example:
const data = {
number: 42,
anotherData: JSON.stringify({ anotherNumber: 24 }),
}
JSON.stringify(data)
With this module, it transforms into:
const data = {
number: 42,
anotherData: stringify({ anotherNumber: 24 }),
}
stringify(data)
If stringify
emitted strings, it would be impossible to distinguish between such stringified data and an asynchronous array of strings, which is more commonly used than stringifying an asynchronous array of binaries to JSON.
If the first value of a stream is binary (including zero length), then stringify
treats the entire stream as a binary representation of a string; otherwise, it's treated as an array.