csv-encoding

name	csv-encoding
description	Use when generating CSVs in APIs.

@wisemen/csv - CSV Encoding

Use @wisemen/csv when you need to turn row objects into CSV text or a readable CSV stream. The package exposes two encoding paths:

• CSV.encode(records, options) returns one CSV string.
• CSV.encodeStream(records, options) returns a Readable that yields CSV chunks.

Pick encode() for small, already-materialized arrays. Pick encodeStream() when rows come from an iterable or async iterable, or when the response should be streamed.

Encode A CSV String

import { CSV } from '@wisemen/csv'

const csv = CSV.encode(
  [
    { name: 'John Doe', age: '30' },
    { name: 'Jane Doe', age: '25' },
  ],
  { columns: ['name', 'age'] }
)

This returns:

name;age
John Doe;30
Jane Doe;25

Encode A CSV Stream

import { pipeline } from 'node:stream/promises'
import { CSV } from '@wisemen/csv'

await pipeline(
  databaseQueryStream,
  CSV.encodeTransform(), 
  uploadWritable
)

Use the transform variant when rows already come from a readable object stream and need to be piped into another writable. Use encodeStream() when the source is an iterable or async iterable and you want a Readable returned directly.

Encoding Rules To Rely On

• The default delimiter is ;.
• Set delimiter to override it, including multi-character delimiters.
• columns controls both header order and field order.
• CSV.encode() derives columns from the first record when they are omitted.
• CSV.encodeStream() also derives columns from the first emitted record when they are omitted.
• CSV.encodeTransform() derives columns from the first written record when they are omitted.
• null and undefined are encoded as empty fields.
• Values containing the delimiter, " or a newline are wrapped in quotes.
• Inner " characters are escaped as "".
• encode() does not add a trailing newline after the last row.
• encodeStream() and encodeTransform() write \n after the header and after every emitted row.

Stream-Specific Behavior

• encodeTransform() returns a Transform with object-mode input and text output.
• encodeStream() accepts both Iterable<Record<...>> and AsyncIterable<Record<...>>.
• If the iterable is empty and columns are provided, the stream emits only the header row.
• If the iterable is empty and columns are omitted, the stream emits nothing.