Package reference
Mirrors the package README (single source). Install @basaltkit/exports v1.3.0 — npm · source.
<p align="center"> <a href="https://basaltkit-docs.pages.dev"> <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440"> </a> </p>
@basaltkit/exports
Data export for Basalt: turns typed export definitions into CSV / TSV / JSON / NDJSON files (native, zero dependencies), through a formatter seam where XLSX/PDF plug in later. Large datasets can be streamed (stream(), CSV/TSV/JSON/NDJSON). Designed to run asynchronously with @basaltkit/queue and store the result with @basaltkit/files/@basaltkit/storage. You need this module when users export data or generate reports.
What this module solves
Exporting well involves: mapping records to columns, escaping correctly (commas, quotes, line breaks), supporting multiple formats, and — for large volumes — running outside the request. This module gives you typed export definitions, native formatters with correct escaping (RFC 4180), and a seam for adding formats (XLSX, PDF) without changing the definitions.
Installation
pnpm add @basaltkit/exportsOnly depends on @basaltkit/core. The CSV/TSV/JSON/NDJSON formats need nothing else.
Get started in 5 minutes
import { createApp } from '@basaltkit/core'
import { exportsPlugin, EXPORTS, defineExport } from '@basaltkit/exports'
const usersExport = defineExport<{ name: string; email: string; joinedAt: Date }>({
name: 'users',
columns: [
{ header: 'Name', value: (u) => u.name },
{ header: 'Email', value: (u) => u.email },
{ header: 'Joined', value: (u) => u.joinedAt },
],
})
const app = await createApp({ plugins: [exportsPlugin()] }).boot()
const exports = app.container.get(EXPORTS)
const result = await exports.run(usersExport, users, 'csv')
// { content: Buffer, contentType: 'text/csv', filename: 'users.csv', format, rowCount }Dates become ISO; fields with commas/quotes/line breaks are quoted correctly.
Large volumes: asynchronous via queue + storage
run is pure and returns the whole file as one Buffer. For large reports, run it inside a job and store the file:
const GenerateReport = defineJob<{ tenantId: string; requestedBy: string }>({
name: 'reports.users', queue: 'reports',
async handle({ tenantId, requestedBy }) {
const rows = queryUsers(tenantId) // an array or an AsyncIterable
const { content, filename, contentType } = await exports.run(usersExport, rows, 'csv')
const file = await files.upload(content, { name: filename, contentType, tenantId, uploadedBy: requestedBy })
await notifier.notify({ id: requestedBy }, ReportReady, { fileId: file.id }) // a defineNotification(...)
},
})run accepts an array or an AsyncIterable, but it buffers: every row is collected and the whole file is built in memory before it returns. That is fine for thousands of rows; for large datasets use stream().
Streaming large exports: stream()
exports.stream(definition, data, format) renders incrementally: rows are pulled from data (an array or an AsyncIterable, e.g. a cursor over the database) one at a time, and the file comes out as an AsyncIterable<Buffer> in chunks of about 64 KiB — memory stays bounded by one chunk, not by the dataset. The bytes are identical to run()'s content.
import { createWriteStream } from 'node:fs'
import { Readable } from 'node:stream'
import { pipeline } from 'node:stream/promises'
const out = exports.stream(usersExport, queryUsers(tenantId), 'csv')
out.contentType // 'text/csv' — known up front, for response headers
out.filename // 'users.csv'
await pipeline(Readable.from(out), createWriteStream(`/tmp/${out.filename}`))
out.rowCount // final once the stream has been consumedIt also works as a web Response body (new Response(ReadableStream.from(out))) or as the body of an S3 multipart upload. The stream is single-use.
| Format | run() | stream() |
|---|---|---|
csv, tsv, json, ndjson | ✅ buffered | ✅ incremental |
xlsx (@basaltkit/exports-xlsx), PDF and other formatters without renderStream | ✅ buffered | ❌ ExportNotStreamableError — the container format needs all the data up front |
files.upload() from @basaltkit/files accepts the stream directly, but note that it buffers the upload (up to its size limit) before writing to the disk — to keep memory flat end to end, pipe to a sink that streams (a file, an HTTP response, a multipart upload).
Formats
| Format | Content-Type | Extension |
|---|---|---|
csv | text/csv | .csv |
tsv | text/tab-separated-values | .tsv |
json | application/json | .json |
ndjson | application/x-ndjson | .ndjson |
CSV for Excel/ERP in pt locales
createCsvFormatter({ delimiter, bom, locale, format }) builds a configured CSV formatter: a UTF-8 BOM so Excel on Windows reads accents correctly, ; as delimiter, and numbers/dates rendered by a LocaleSpec:
import { createCsvFormatter } from '@basaltkit/exports'
exportsPlugin({
formatters: [createCsvFormatter({ delimiter: ';', bom: true, locale: { decimal: ',', thousands: ' ', date: 'dd/mm/yyyy' } })],
})
// 1408278.55 → 1 408 278,55 · -12 → -12 (still a number, not guard-quoted) · Date → 14/03/2026The locale applies only to primitive numbers and Dates, after the formula-injection guard decides — strings are guarded exactly as before.
Adding a format (XLSX, PDF…)
A formatter implements render(headers, rows, columns?) → Buffer, and optionally renderStream(headers, rows: AsyncIterable<unknown[]>, columns?) → AsyncIterable<string | Buffer> to support stream() (its concatenated output must equal render()'s). columns carries each column's header and optional type/format/width hints. Bring your own library and register it:
const xlsx: ExportFormatter = {
format: 'xlsx',
contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
extension: 'xlsx',
render: (headers, rows) => buildXlsx(headers, rows), // with the library of your choice
}
exportsPlugin({ formatters: [xlsx] })Importing CSV: defineImport / readImport
The reverse path — reading what an ERP exports. Declare the columns once, read a file (string, bytes or an async iterable of chunks), and get typed rows plus a per-line error report; it never throws on bad data and fails closed (no rows) on a malformed file.
import { defineImport, readImport } from '@basaltkit/exports'
const orders = defineImport<{ number: string; unitPrice: number; dueDate: Date | null }>({
name: 'purchase-orders',
delimiter: ';',
locale: { decimal: ',', thousands: ' ', date: 'dd/mm/yyyy' },
maxRows: 2000,
columns: [
{ key: 'number', headers: ['Número', 'Nº'], required: true },
{ key: 'unitPrice', headers: ['Preço unitário'], required: true, parse: 'decimal' },
{ key: 'dueDate', headers: ['Data de entrega'], parse: 'date' },
],
})
const { rows, errors, warnings } = await readImport(orders, file)
// errors: [{ line: 7, column: 'unitPrice', code: 'AMBIGUOUS_DECIMAL', message: … }]Headers match by name ignoring case/accents/whitespace; with a comma decimal 1.250,50 is 1250.5 but 12.5 is AMBIGUOUS_DECIMAL (never guessed); dates are calendar-validated. The RFC 4180 reader underneath is exported as parseDelimited(input, { delimiter, quote, bom, maxRows, maxFieldLength }) → async iterator of { line, cells } (throws DelimitedParseError).
API reference
| API | Description |
|---|---|
defineExport<T>({ name, columns }) | Defines a typed export; each column has header and value(row), plus optional type ('text' | 'number' | 'date'), format and width hints for formatters. |
exportsPlugin({ formatters? }) | Registers the EXPORTS token with the native formats plus yours. |
EXPORTS | DI token → the Exports service. |
exports.run(def, data, format) | Renders the whole file in memory; returns { content: Buffer, contentType, filename, format, rowCount }. data is an array or AsyncIterable (collected). |
exports.stream(def, data, format, { chunkSize? }) | Renders incrementally; returns an ExportStream — an AsyncIterable<Buffer> with contentType, filename, format and a live rowCount. chunkSize defaults to 64 KiB. Throws ExportNotStreamableError for formatters without renderStream. |
exports.formats() | Available formats. |
exports.streamableFormats() | Formats stream() accepts. |
UnknownExportFormatError / ExportNotStreamableError | EXPORT_UNKNOWN_FORMAT / EXPORT_NOT_STREAMABLE, both HTTP 400. |
csvFormatter, tsvFormatter, jsonFormatter, ndjsonFormatter | Native formatters. |
createCsvFormatter({ delimiter?, bom?, locale?, format? }) | A configured CSV formatter (BOM, delimiter, LocaleSpec number/date rendering). |
defineImport<T>({ name, columns, locale?, delimiter?, bom?, maxRows?, maxFieldLength?, unknownColumns?, maxErrors? }) | Declares a typed CSV import; each column has key, headers (synonyms), required? and parse? ('text' | 'integer' | 'decimal' | 'date' | fn). |
readImport(def, input) | Reads a file → { rows: { line, value }[], errors, warnings }; issues are { line, column?, code, message }. Never throws on bad data. |
parseDelimited(input, options?) | RFC 4180 async iterator of { line, cells }; throws DelimitedParseError (CSV_<reason>). |
How it connects to other modules
@basaltkit/queue— runs large exports outside the request.@basaltkit/files/@basaltkit/storage— stores the generated file (with a signed URL for download).@basaltkit/notifications— notifies when the report is ready.