file components

File components

Node-only file-edge stages that turn a file path into a CSV token stream and back. They compose stream-chain's async block reader/writer with the core parser / stringer, and use node:fs/promises (Node-only).

Import

import parseFile from 'stream-csv-as-json/file/parser.js';
import stringerToFile from 'stream-csv-as-json/file/stringer.js';

Driving a file pipeline

File components are driven with pipe + drain from stream-chain/utils. pipe runs the flush after the data pass — required so stringerToFile closes its file handle.

import pipe from 'stream-chain/utils/pipe.js';
import drain from 'stream-chain/utils/drain.js';

// Parse a file into tokens:
await drain(
  pipe(parseFile(), token => {
    /* … */ return null;
  })('in.csv')
);

// Round-trip a file (parse → write):
await drain(pipe(parseFile(), stringerToFile('out.csv', {useValues: true}))('in.csv'));

parseFile

parseFile(options) — input-edge stage: gen(asyncBlockReader(options), parser(options)). Pass the file path as the input value; produces the CSV token stream. The async block reader reads 64 KB blocks via fs/promises.open and decodes them through StringDecoder (which buffers a UTF-8 sequence split across blocks).

Options: the parser options plus readBlockSize (bytes, default 65536).

stringerToFile

stringerToFile(path, options) — output-edge sink: gen(stringer(options), asyncBlockWriter(path, options)). Writes the token stream to path (opened with 'w'). The async block writer buffers output and flushes in 1 MB blocks; it opens the file lazily and closes the handle on the flush signal, so the pipeline must be flushed (use pipe + drain).

Options: the stringer options plus writeBlockSize (bytes, default 1048576). Use {useValues: true} for a clean round-trip (smart quoting from packed values).

API summary

Name	Returns	Description
parseFile(options)	(path) => AsyncGenerator<Token>	Path → CSV token stream
stringerToFile(path, options)	(token) => AsyncGenerator<never>	CSV token stream → file

Both are also exported under the aliases parser / stringer respectively. Node-only — there is no Web-Streams file edge (the browser has no filesystem).