#jsonl API reference

JSON Lines (JSONL / NDJSON): newline-delimited JSON, one independent value per line. A thin framing layer over json - each record is a json.Value, so encode / decode compose json.encode / json.decode with a \n split / join, and the file helpers add fs. Pure Jennifer; both binaries.

encode(records) writes one compact JSON value per line (trailing newline); decode(text) parses each non-blank line back into a json.Value, so decode(encode(records)) round-trips. Whole-file readFile / writeFile / appendFile cover the common case; a streaming Reader reads one record at a time for files too large to hold in memory.

Import with import "jsonl.j" as jsonl;. See the jsonl guide for prose and examples.

#Functions

#jsonl.appendFile(path as string, records as list of json.Value)

Encode records and append them to a file (created if missing) - the common JSONL pattern of adding rows to a growing log.

Parameters

• path {string} - the file path
• records {list of json.Value} - the records to append

#jsonl.closeReader(reader as Reader)

Close a streaming reader.

Parameters

• reader {Reader} - the reader

#jsonl.closeWriter(writer as Writer)

Close a streaming writer (closes the underlying file handle).

Parameters

• writer {Writer} - the writer

#jsonl.decode(text as string)

Decode JSONL text into records, one json.Value per non-blank line. Blank and whitespace-only lines are skipped, and a trailing \r (CRLF input) is trimmed, so decode(encode(records)) round-trips.

Parameters

• text {string} - the JSONL text

Returns {list of json.Value} - the parsed records

#jsonl.encode(records as list of json.Value)

Encode records as JSONL: one compact JSON value per line, each terminated by a newline. An empty list yields the empty string.

Parameters

• records {list of json.Value} - the records to encode

Returns {string} - the JSONL text

#jsonl.hasMore(reader as Reader)

Whether the reader is not yet at end-of-file. This is a coarse check: it can report true when only trailing blank lines remain, which carry no record. Prefer looping on readRecord(...).done - the reliable end signal.

Parameters

• reader {Reader} - the reader

Returns {bool} - true if the file still has unread bytes

#jsonl.openReader(path as string)

Open a JSONL file for streaming.

Parameters

• path {string} - the file path

Returns {Reader} - the reader

#jsonl.readFile(path as string)

Read and decode a whole JSONL file.

Parameters

• path {string} - the file path

Returns {list of json.Value} - the records

#jsonl.readRecord(reader as Reader)

Read and decode the next record, skipping blank lines. Returns a Record: {value, done: false} for a record, or {done: true} once the stream is exhausted (including when only trailing blank lines remained). Loop until done rather than guarding with hasMore, which cannot see trailing blanks.

Parameters

• reader {Reader} - the reader

Returns {Record} - the next record, or a done marker at end

#jsonl.readValue(reader as Reader)

Read and decode the next record, skipping blank lines, and return the json.Value directly. At end-of-stream this returns a JSON null; guard the loop with not fs.eof(...) (JSONL written by writeValue has one value per line and no trailing blanks) or use readRecord when you need the explicit done flag to distinguish end-of-stream from a genuine null record.

Parameters

• reader {Reader} - the reader

Returns {json.Value} - the next record, or a JSON null at end

#jsonl.reader(file as fs.File)

Wrap an already-open, read-mode fs.File as a streaming reader. Use this when the caller owns the file handle (openReader opens the path for you). The file is a handle, so successive readValue calls advance the same stream.

Parameters

• file {fs.File} - an open read-mode file handle

Returns {Reader} - the reader

#jsonl.writeFile(path as string, records as list of json.Value)

Encode records and write them to a file, replacing any existing content.

Parameters

• path {string} - the file path
• records {list of json.Value} - the records to write

#jsonl.writeValue(writer as Writer, value as json.Value)

Append one record to the writer: the compact JSON encoding followed by a newline.

Parameters

• writer {Writer} - the writer
• value {json.Value} - the record to append

#jsonl.writer(file as fs.File)

Wrap an open write/append-mode fs.File as a streaming JSONL writer.

Parameters

• file {fs.File} - an open write- or append-mode file handle

Returns {Writer} - the writer

#Structs

#jsonl.Reader

A line-at-a-time reader over an open file, for JSONL too large to hold in memory. Build with openReader; the wrapped fs.File shares its read position across value copies (a handle), so successive readRecord calls advance the same stream.

#jsonl.Record

One streaming read: a decoded record, or done set once the stream is exhausted. done is the reliable end signal - a raw not eof check is not, because trailing blank lines leave the file un-exhausted yet carry no record.

#jsonl.Writer

A streaming JSONL writer over an open fs.File. Each writeValue call appends one compact JSON value terminated by a newline, so a growing log is written without building the whole text in memory.