Skip to content
Eugene Lazutkin edited this page Oct 27, 2026 · 4 revisions

Signature: tokens → file — Node-only output edge

(Since 3.3.0) stringerToFile() is a Node-only, file-based output-edge sink stage for stream-json pipelines. Drop it at the tail of a gen([…]) chain and the pipeline writes its token stream straight to disk via fs/promises. The merged write path avoids the Node Duplex boundary that the idiomatic chain([…, stringer()]).pipe(createWriteStream) pays.

Introduction

import {parseFile} from 'stream-json/file/parser.js';
import {stringerToFile} from 'stream-json/file/stringer.js';
import {pipe} from 'stream-chain/utils/pipe.js';
import {drain} from 'stream-chain/utils/drain.js';

// file → tokens → file (verbatim)
await drain(pipe(parseFile(), stringerToFile('out.json'))('in.json'));

JSONC variant (round-trips comments and trailing commas):

import {stringerToFile} from 'stream-json/file/jsonc/stringer.js';

How it works

stringerToFile(path, options) returns gen(stringer(options), asyncBlockWriter(path, options)) — an fList that drops as the last stage in a gen([…]) chain. The asyncBlockWriter is a flushable: it accumulates the stringer's per-token string output into an in-memory buffer and writes whole writeBlockSize-sized blocks to a FileHandle via fh.write. The handle is closed on the writer's final() — which is signaled by passing none through the pipe — or, when the pipeline ends without a flush, by the writer's close(). pipe(...) from stream-chain/utils/pipe.js does the flush after the data pass so the file terminates cleanly without ceremony.

stringerToFile(path, options?)

  • path — the output file. Created if missing, truncated if it exists.
  • Returns an fList usable as a chain stage.

Options (combined stringer + write-block):

  • writeBlockSize — write-block size in bytes. Default 1048576 (1 MB). A memory/syscall knob.
  • All stringer() options pass through: useValues, useKeyValues, useStringValues, useNumberValues, makeArray.

Also exported as stringer (matching the file name file/stringer.js), so import {stringer} from 'stream-json/file/stringer.js' works too.

Driving the chain — pipe is required for flush

gen doesn't flush on its own. Sink stages like stringerToFile's writer need a none signal to write their remaining buffer and close the file. pipe(...) is the one-shot driver that does the data pass AND the flush; drain(...) consumes the resulting async generator and resolves to undefined (the writer yields nothing).

const c = pipe(parseFile(), pick({filter: 'items'}), streamArray(), stringerToFile('out.json'));
await drain(c('in.json'));

When the pipeline ends without a flush

If the pipeline ends without the flush (another stage throws, an early break), the pipeline closes the file without writing the buffered tail. A stop before the sink is a clean end: the sink is flushed, so the output it buffered reaches the file. The returned function also has a close() method that does the same; it does nothing after a clean flush, and every call to the sink after it throws. Call it yourself when you drive the sink some other way, or when something outside the pipeline can fail while it is suspended:

const sink = stringerToFile('out.json');
try {
  await drain(pipe(parseFile(), sink)('in.json'));
} finally {
  await sink.close();
}

For how a gen() pipeline ends, see Ending a pipeline in the stream-chain wiki.

Performance

See bench/file-roundtrip.js. The merged round-trip (pipe(parseFile(), stringerToFile())) is roughly 1.6× faster than the idiomatic chain([createReadStream, parser(), stringer()]).pipe(createWriteStream) (≈30 ms vs ≈50 ms median for a 100 KB fixture on Intel i3‑10110U, Node 26). The win comes from avoiding the Node Duplex boundary between the stringer and the file write side.

Related

  • parseFile — symmetric input-edge source.
  • Stringer — the underlying token-to-text flushable.

Clone this wiki locally