`ndj`

Newline-delimited JSON (NDJSON / JSONL) - parse a multi-line string where each line is a JSON value into a list of objects; serialise a list back to NDJSON; map a transform function over each line; filter by predicate; append one object; count valid lines; get the nth object; and validate that every line is valid JSON.

Load with: use ndj

What this module does

NDJSON (also called JSONL) is a streaming-friendly format where each line is an independent JSON value. It's widely used for log files, event streams, and large dataset exports. ndj handles the line-splitting and JSON parsing plumbing so you work with plain ilusm lists and objects. Blank lines and lines starting with # are silently skipped.

Quick example

use ndj

raw = '{"name":"alice","score":10}\n{"name":"bob","score":7}\n{"name":"carol","score":15}'

# Parse
records = ndjpa(raw)
# [{name:"alice",score:10}, {name:"bob",score:7}, {name:"carol",score:15}]

# Serialise
prn(ndjwr(records))

# Map
names = ndjma(raw, \(r) r.name)
# ["alice", "bob", "carol"]

# Filter
top = ndjfi(raw, \(r) r.score >= 10)

# Append
raw2 = ndjap(raw, {name: "dave", score: 5})

# Count
prn(ndjcn(raw))  # 3

# Get nth (0-indexed)
prn(ndjge(raw, 1))  # {name:"bob",score:7}

# Validate
prn(ndjok(raw))  # tru

Functions

Parse and serialise

ndjpa(s)

Parses an NDJSON string. Skips blank lines and # comment lines. Returns a list of decoded ilusm values.

ndjwr(xs)

Serialises a list of values to an NDJSON string with each value on its own line (no trailing newline).

ndjap(s, obj)

Appends a single JSON-encoded object to an existing NDJSON string, adding a newline separator if needed.

Stream operations

ndjma(s, fn)

Maps fn(obj) over each valid JSON line in the stream. Returns the list of transformed values.

ndjfi(s, pred)

Filters the stream, returning a list of objects for which pred(obj) is truthy.

Inspection

ndjcn(s)

Returns the count of valid JSON lines (skipping blanks and comments).

ndjge(s, n)

Returns the nth valid JSON object (0-indexed). Returns the raw decode result ({ok, val}).

ndjok(s)

Returns tru if every non-blank, non-comment line is valid JSON.

Notes

Requires trl, txt, and jsn.