jsonlines

![GitHub package.json dependency version (dev dep on branch)]()

a Node.js library to parse, stringify jsonlines files as streams

Install

``shell
npm install @jsonlines/core
yarn add @jsonlines/core
`

Features Guide

Usage

$3

`js
const { stringify } = require("@jsonlines/core");
// or import from sub-module
const { stringify } = require("@jsonlines/core/stringify");

// or import with es module
import { stringify } from "@jsonlines/core";
import { stringify } from "@jsonlines/core/stringify";

require("stream")
.Readable.from([
// objects
{ v: "object1" },
{ name: "Lady Gaga", records: ["Chromatica"] },
// arrays
[1, 2, 3, 4],
// booleans
true,
false,
// numbers
2020,
-1,
// null
// Note that single null value can't be written to node streams,
// so @jsonlines/core provides a helper value to represent null
require("@jsonlines/core").nullValue,
require("@jsonlines/core/null-value").nullValue,
// note that it not necessary to use this helper value when null is in an array or object
{ value: null },
[null, null],
])
.pipe(
// create a stringify stream, which is a duplex stream
stringify(),
)
.pipe(process.stdout);
`

the output will be:

`jsonlines
{"v":"object1"}
{"name":"Lady Gaga","records":["Chromatica"]}
[1,2,3,4]
true
false
2020
-1
null
null
{"value":null}
[null,null]
`

#### stringify API

`ts
// prettier-ignore
function stringify(options?: JsonLinesStringifyOptions): JsonLinesStringifyStream;
`

stringify function accepts an optional object as options and returns an instance of JsonLinesStringifyStream.

Note that JsonLinesStringifyStream extends Duplex.

options:

`ts
export interface JsonLinesStringifyOptions {
/**
* specify the encoding to encode string to buffer
*
* NOTE that the standard jsonlines
* requires utf8 as file encoding
*
* Defaults to Buffer.from default encoding,
* which is utf8.
*/
encoding?: BufferEncoding;

/**
* specify a function to stringify values.
* It accepts a value as parameter,
* and should return a string or a Promise.
*
* Defaults to JSON.stringify
*/
stringify?: (v: V) => string | Promise;

/**
* specify whether to gzip the output
*
* Omit or use false to disable gzip.
* Use true to gzip with default options.
* Or use an object as params for require('zlib').createGzip
*/
gzip?: JsonLinesGzipOption;

/**
* specify the line ending to be used in the output
*
* NOTE that the standard jsonlines
* requires \n as line separator
*
* Defaults to \n
*/
lineSep?: "lf" | "\n" | "crlf" | "\r\n";
}
`

$3

`js
const { parse } = require("@jsonlines/core");
// or import from sub-module
const { parse } = require("@jsonlines/core/parse");

// or import with es module
import { parse } from "@jsonlines/core";
import { parse } from "@jsonlines/core/parse";

const source = require("stream").Readable.from({"v":"object1"}
{"name":"Lady Gaga","records":["Chromatica"]}
[1,2,3,4]
true
false
2020
-1
null
null
{"value":null}
[null,null]
);

// create a parse stream, which is a duplex stream
const parseStream = parse();

source.pipe(parseStream);

// you can also consume it with for await ... of
parseStream.on("data", (value) => {
if (value === require("@jsonlines/core/null-value").nullValue)
console.log(--- The following value is nullValue ---);

console.log(value);
});
`

the output will be:

`
{ v: 'object1' }
{ name: 'Lady Gaga', records: [ 'Chromatica' ] }
[ 1, 2, 3, 4 ]
true
false
2020
-1
--- The following value is nullValue ---
[Object: null prototype] [Null] {}
--- The following value is nullValue ---
[Object: null prototype] [Null] {}
{ value: null }
[ null, null ]
`

#### parse API

`ts
function parse(options?: JsonLinesParseOptions): JsonLinesParseStream;
`

parse function accepts an optional object as options
and returns an instance of JsonLinesParseStream.

Note that JsonLinesParseStream extends Duplex.

options:

`ts
export interface JsonLinesParseOptions {
/**
* specify the encoding to decode buffer to string
*
* NOTE that the standard jsonlines
* requires utf8 as file encoding
*
* Defaults to utf8
*/
encoding?: BufferEncoding;

/**
* specify a function to parse json line.
* It accepts a string as parameter,
* and should return a value or a Promise.
*
* Defaults to JSON.parse
*/
parse?: (line: string) => V | Promise;

/**
* specify whether to gunzip the source
*
* Omit or use false to disable gunzip.
* Use true to gunzip with default options.
* Or use an object as params for require('zlib').createGunzip
*/
gzip?: JsonLinesGzipOption;

/**
* specify the line ending to be parsed
*
* NOTE that the standard jsonlines
* requires \n as line separator
*
* If set to auto, both \n and \r\n will be accepted
*
* Defaults to \n
*/
lineSep?: "lf" | "\n" | "crlf" | "\r\n" | "auto";
}
``