Exportação de dados
@basaltkit/exports transforma definições de exportação tipadas em ficheiros — CSV, TSV, JSON e NDJSON de raiz (zero dependências), com uma junção de formatador plugável para XLSX/PDF. Foi feito para correr de forma assíncrona via @basaltkit/queue e armazenar o resultado com @basaltkit/files. Também lê CSV: o defineImport/readImport lê um ficheiro com números e datas estritos por locale e um relatório de erros por linha.
Definir e correr
// src/exports/users.ts
import { defineExport } from '@basaltkit/exports'
export 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 },
],
})Regista o serviço com exportsPlugin e resolve-o sob o token EXPORTS:
// src/app.ts
import { createApp } from '@basaltkit/core'
import { EXPORTS, exportsPlugin } from '@basaltkit/exports'
import { usersExport } from './exports/users.js'
export const app = await createApp({
plugins: [exportsPlugin()],
}).boot()
const exports = app.container.get(EXPORTS)
const users = [{ name: 'Ada', email: 'ada@example.com', joinedAt: new Date() }]
const result = await exports.run(usersExport, users, 'csv')
// { content: Buffer, contentType: 'text/csv', filename: 'users.csv', format: 'csv', rowCount: 1 }CSV/TSV fazem quoting corretamente (RFC 4180), as datas renderizam como ISO (vê locales pt para um BOM, ; e 1 408 278,55), e run aceita um array ou um AsyncIterable. O run faz sempre buffer — recolhe todas as linhas e devolve o ficheiro inteiro num único Buffer; para grandes volumes de dados usa o stream().
As células CSV/TSV estão também protegidas contra injeção de fórmulas: qualquer célula cujo texto final comece por =, +, -, @ (ou as suas formas de largura total = + - @, também depois de espaços iniciais), um tab, um carriage return ou um line feed recebe o prefixo ', para que a folha de cálculo a mostre como texto em vez de a avaliar. A proteção aplica-se ao texto final de todos os valores (strings, arrays, objetos, strings encapsuladas e datas depois de renderizadas); só números, bigints e booleanos primitivos ficam isentos, pelo que um número negativo continua numérico.
Relatórios grandes: queue + storage
run é puro e devolve um único Buffer. Para exportações grandes, corre-o dentro de um job de queue e armazena o ficheiro com @basaltkit/files para download (para volumes muito grandes, troca o run pelo stream()):
// src/jobs/generate-report.ts
import { defineJob } from '@basaltkit/queue'
import { EXPORTS } from '@basaltkit/exports'
import { FILES } from '@basaltkit/files'
import { NOTIFIER, defineNotification } from '@basaltkit/notifications'
import { z } from 'zod'
import { app } from '../app.js'
import { usersExport } from '../exports/users.js'
import { queryUsers } from '../db.js' // returns an AsyncIterable<User>
const exports = app.container.get(EXPORTS)
const files = app.container.get(FILES)
const notifier = app.container.get(NOTIFIER)
const ReportReady = defineNotification({
name: 'report.ready',
schema: z.object({ fileId: z.string() }),
channels: ['inApp'],
via: { inApp: ({ fileId }) => ({ title: 'Your export is ready', data: { fileId } }) },
})
export const GenerateReport = defineJob<{ tenantId: string; requestedBy: string }>({
name: 'reports.users',
queue: 'reports',
async handle({ tenantId, requestedBy }) {
const { content, filename, contentType } = await exports.run(usersExport, queryUsers(tenantId), 'csv')
const file = await files.upload(content, { name: filename, contentType, tenantId, uploadedBy: requestedBy })
await notifier.notify({ id: requestedBy }, ReportReady, { fileId: file.id })
},
})
// enqueue it from a route or command:
await GenerateReport.dispatch({ tenantId: 'acme', requestedBy: 'u1' })Exportações grandes em stream
O exports.stream(definition, data, format) renderiza incrementalmente: as linhas são lidas de data (um array ou um AsyncIterable, p.ex. um cursor da base de dados) uma a uma e o ficheiro sai como um AsyncIterable<Buffer> em blocos de ~64 KiB ({ chunkSize } para ajustar), por isso a memória fica limitada a um bloco e não ao volume de dados. Os bytes são idênticos ao content do run().
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' — conhecido à partida, para os headers da resposta
out.filename // 'users.csv'
await pipeline(Readable.from(out), createWriteStream(`/tmp/${out.filename}`))
out.rowCount // final depois de o stream ser consumidoO stream só pode ser consumido uma vez; também serve como body de uma Response web (new Response(ReadableStream.from(out))) ou de um upload multipart para S3.
| Formato | run() | stream() |
|---|---|---|
csv, tsv, json, ndjson | em buffer | incremental |
xlsx, PDF, qualquer formatador sem renderStream | em buffer | ExportNotStreamableError (EXPORT_NOT_STREAMABLE, 400) |
O exports.streamableFormats() lista o que o stream() aceita.
Mantém o destino também em stream
O files.upload() aceita o stream, mas faz buffer do upload (até ao seu limite de tamanho) antes de escrever no disco. Para manter a memória estável de ponta a ponta, encaminha para um destino que faça stream — um ficheiro, uma resposta HTTP, um upload multipart.
XLSX
Adiciona @basaltkit/exports-xlsx — um .xlsx válido com um escritor ZIP embutido, ainda sem dependências:
import { xlsxFormatter } from '@basaltkit/exports-xlsx'
exportsPlugin({ formatters: [xlsxFormatter] })
await exports.run(usersExport, users, 'xlsx') // users.xlsxO texto das células é escapado para XML, e os caracteres que o XML 1.0 proíbe por completo (0x00–0x08, 0x0B, 0x0C, 0x0E–0x1F — facilmente presentes em dados vindos do utilizador) são escritos com o escape _xHHHH_ do OOXML em vez de passarem tal e qual, o que tornaria a folha impossível de ler e faria o Excel recusar-se a abrir o ficheiro. Tab, newline e carriage return são XML legal e ficam intactos.
O formatador XLSX funciona só em buffer: um .xlsx é um ZIP cujas entradas precisam dos tamanhos e CRCs, por isso a folha inteira é construída em memória — usa o run(), não o stream().
Para adicionar outro formato (PDF, ODS…), implementa ExportFormatter.render(headers, rows, columns?) → Buffer e regista-o da mesma forma — sem alterações à definição de exportação. Implementa também o renderStream(headers, rows: AsyncIterable<unknown[]>, columns?) → AsyncIterable<string | Buffer> opcional (com bytes idênticos ao render) para tornar o formato streamable. O columns traz o header de cada coluna e as dicas opcionais type, format e width; um formatador pode ignorá-lo.
Exportar para Excel/ERP em locales pt
Um ficheiro que uma folha de cálculo ou um ERP num locale de língua portuguesa abra sem retoques precisa de três coisas que os valores por omissão não fazem: um BOM UTF-8 (sem ele o Excel em Windows lê Número como Número), ; como separador, e números/datas escritos à maneira local (1 408 278,55, 14/03/2026). O createCsvFormatter faz as três:
import { createCsvFormatter, exportsPlugin } from '@basaltkit/exports'
const ptCsv = createCsvFormatter({
delimiter: ';',
bom: true,
locale: { decimal: ',', thousands: ' ', date: 'dd/mm/yyyy' },
})
exportsPlugin({ formatters: [ptCsv] }) // regista-se como 'csv', substituindo o de omissão
// 1408278.55 → 1 408 278,55 · -1408278.55 → -1 408 278,55 · Date → 14/03/2026Passa números e Dates, não strings já formatadas: o locale só muda a forma como um número primitivo é escrito depois de a proteção contra injeção de fórmulas o ter isentado, por isso o -1 408 278,55 de uma nota de crédito continua a ser um número, enquanto uma string como '-1408278,55' continua protegida ('-1408278,55) — a proteção não é configurável. O 'dd/mm/yyyy' usa o dia do calendário UTC; passa uma função (date: (d) => …) para outra coisa qualquer. Com format: 'csv-pt' regista-se ao lado do de omissão em vez de o substituir. O stream() emite os mesmos bytes, BOM incluído.
Para XLSX, o createXlsxFormatter escreve células de data verdadeiras (números de série do Excel com um formato de data, a partir do instante UTC; uma data anterior a 1900-03-01, que os números de série do Excel não representam correctamente, fica como texto ISO) e aplica formatos de número por coluna, larguras, um nome de folha e um cabeçalho fixo. As dicas ficam na definição da exportação:
import { createXlsxFormatter } from '@basaltkit/exports-xlsx'
const invoicesExport = defineExport<Invoice>({
name: 'invoices',
columns: [
{ header: 'Número', value: (i) => i.number, width: 16 },
{ header: 'Data', value: (i) => i.issuedAt, type: 'date' },
{ header: 'Total', value: (i) => i.total, type: 'number', format: '#,##0.00', width: 14 },
],
})
exportsPlugin({
formatters: [ptCsv, createXlsxFormatter({ sheetName: 'Facturas', freezeHeader: true, dateFormat: 'dd/mm/yyyy' })],
})Opção do createXlsxFormatter | Omissão | Efeito |
|---|---|---|
sheetName | 'Sheet1' | Nome da folha; 1–31 caracteres, nenhum de [ ] : * ? / \, sem começar/acabar em ' (caso contrário lança TypeError) |
freezeHeader | false | Mantém a linha de cabeçalho visível ao fazer scroll |
dateFormat | 'yyyy-mm-dd' | Formato das células de data cuja coluna não tem format |
widths | — | Larguras das colunas por índice; sobrepõem-se ao width das colunas |
format | 'xlsx' | Nome do formato com que se regista |
O xlsxFormatter simples não muda (datas como texto ISO, sem estilos). Os formatos de número são formatos de apresentação: a célula guarda o número em bruto, por isso o Excel mostra-o com o separador decimal de quem o abre.
Importar CSV
O caminho inverso — ler o que um ERP ou uma folha de cálculo exporta — vem no mesmo pacote. O defineImport declara as colunas uma vez; o readImport lê um ficheiro (uma string, um Uint8Array ou um AsyncIterable de pedaços, por exemplo o stream de um upload) e devolve as linhas lidas e um relatório de erros por linha para um ecrã de pré-visualização. Nunca lança por causa de dados maus.
import { defineImport, readImport } from '@basaltkit/exports'
const purchaseOrders = defineImport<{ number: string; quantity: number; 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: 'quantity', headers: ['Quantidade', 'Qtd'], required: true, parse: 'integer' },
{ 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(purchaseOrders, file)
// rows: [{ line: 2, value: { number: 'PO-1', quantity: 1000, unitPrice: 1250.5, dueDate: Date } }, …]
// errors: [{ line: 7, column: 'unitPrice', code: 'AMBIGUOUS_DECIMAL', message: '"12.5" is ambiguous: …' }]- Cabeçalhos por nome, em qualquer ordem, com sinónimos; a comparação ignora maiúsculas, acentos e espaços repetidos (
PREÇO UNITÁRIOcorresponde aPreço unitário). Uma colunarequiredem falta, ou dois cabeçalhos para a mesma coluna, falham o ficheiro; um cabeçalho desconhecido é um aviso (unknownColumns: 'error'para o recusar). - Números estritos. O separador que não é o decimal só é aceite como separador de milhares, em grupos de três. Com vírgula decimal,
1.250,50é 1250,5 e1 408 278,55é 1408278,55, mas12.5éAMBIGUOUS_DECIMAL— nunca lido em silêncio como 125 ou 12,5, que é como um preço acaba errado por um factor de 1 000. Um grupo nunca começa por0(0.250também é ambíguo, não 250). O'integer'recusa casas decimais. - Datas em
'dd/mm/yyyy'ou ISO (yyyy-mm-dd, ou um timestamp com offset), validadas contra o calendário (31/02/2026éINVALID_DATE), e devolvidas como meia-noite UTC. Para outra coisa qualquer passa uma função emparse; um throw passa aINVALID_VALUEcom a sua mensagem. - Erros por linha. As células são aparadas (trim); uma célula opcional vazia é
null, uma obrigatória vazia éREQUIRED. Uma linha com algum erro, ou com o número errado de campos (COLUMN_COUNT), fica fora derows, e cada célula má tem o seu{ line, column, code, message }—lineé a linha física do ficheiro, contada também através das quebras de linha dentro de campos entre aspas. OmaxErrors(por omissão 1 000) limita o relatório. - Falha fechado num ficheiro malformado. Umas aspas que nunca fecham, texto depois de umas aspas de fecho, umas aspas dentro de um campo sem aspas, UTF-8 inválido, um campo maior que
maxFieldLength, ou mais demaxRowslinhas de dados (por omissão 10 000, verificado durante o stream, antes de ler o resto) devolvem esse único erro e nenhuma linha — um ficheiro truncado nunca é importado a meio.
O leitor de baixo nível também é exportado: parseDelimited(input, { delimiter, quote, bom, maxRows, maxFieldLength }) é um iterador assíncrono RFC 4180 de { line, cells } que lança DelimitedParseError (codeCSV_UNTERMINATED_QUOTE, …, com reason e line). Um BOM inicial é removido (bom: 'forbid' recusa-o). O que o createCsvFormatter escreve volta a ser lido com o mesmo delimiter e locale: números e datas dão os mesmos valores, e o texto a que a protecção contra fórmulas acrescentou um ' mantém-no.