NSV - Newline-Separated Values

NSV is a plain text format for sequences of sequences.

name
email

Alice
[email protected]

Bob
[email protected]

Install

npm install @nsv-format/nsv

Basic usage

const nsv = require('@nsv-format/nsv');

// Parse NSV text
const data = nsv.parse('name\nemail\n\nAlice\[email protected]\n');
// => [['name', 'email'], ['Alice', '[email protected]']]

// Serialize to NSV
const text = nsv.stringify([['name', 'email'], ['Alice', '[email protected]']]);
// => 'name\nemail\n\nAlice\[email protected]\n'

Streaming

For large files, one can use Reader and Writer to process data incrementally without loading everything into memory:

const fs = require('fs');

const reader = new nsv.Reader(fs.createReadStream('input.nsv'));
const writer = new nsv.Writer(fs.createWriteStream('output.nsv'));

for await (const row of reader) {
  const processed = row.map(cell => cell.toUpperCase());
  await writer.writeRow(processed);
}

The Reader parses incrementally as data arrives—it handles infinite streams and maintains bounded memory usage.

Stream API:

• read(stream) - read entire stream into memory as array
• write(data, stream) - write entire array to stream
• reader.readRow() - read next row (returns null when done)
• reader.readRows() - read all remaining rows into array
• writer.writeRow(row) - write a single row
• writer.writeRows(rows) - write multiple rows

Spill/unspill

Flatten/recover seqseq dimension with terminators.

const flat = nsv.spill('', [['a', 'b'], ['c']]);
// => ['a', 'b', '', 'c', '']

const structured = nsv.unspill('', flat);
// => [['a', 'b'], ['c']]

Generic — works with any sentinel type. These decompose the encode/decode pipeline:

encode = spill('\n') ∘ spill('') ∘ map(map(escape))
decode = map(map(unescape)) ∘ unspill('') ∘ unspill('\n')

TypeScript

Type definitions are included:

import * as nsv from '@nsv-format/nsv';

const data: string[][] = nsv.parse(text);

Cross-tested

This implementation is tested against:

• Python implementation
• Rust implementation

Spec

See nsv-format/nsv for the format specification.