suaveplan/packages/api-stack/api/api-plugin-export/README.md

@suaveplan/api-plugin-export - Data-export plugin for @suaveplan/api: CSV (RFC 4180), JSON, and XLSX (SpreadsheetML XML) exporters, in-memory job store, OpenAPIHono route group at /exports, ExportError hierarchy, OTel instruments.

Data-export plugin for @suaveplan/api. Turns any registered resource into a CSV (RFC 4180), JSON, or XLSX (SpreadsheetML XML) blob through three self-contained exporter classes, a DataProvider registry, an in-memory job-lifecycle store, and an OpenAPIHono route group at the configured basePath (default /exports).

Documentation tree

• error-codes — This module owns the stable error-code registry for @suaveplan/api-plugin-export. Every production code path that rai…
  • error-codes — This module owns the stable error-code registry for @suaveplan/api-plugin-export. Every production code path that rai…
• csv — RFC 4180 CSV writer. This module ships three pure helpers — escapeCsvField, formatCellValue, convertToCsv — plus…
  • csv — RFC 4180 CSV writer. This module ships three pure helpers — escapeCsvField, formatCellValue, convertToCsv — plus…
• json — JSON exporter. Projects every row to a record keyed by the column header (not key), optionally applying `column.tra…
  • json — JSON exporter. Projects every row to a record keyed by the column header (not key), optionally applying `column.tra…
• xlsx — SpreadsheetML (XML) writer for the xlsx format. This is the dependency-free path inherited from the upstream package…
  • xlsx — SpreadsheetML (XML) writer for the xlsx format. This is the dependency-free path inherited from the upstream package…
• otel — OpenTelemetry instrument factory for @suaveplan/api-plugin-export. Builds a cached bundle of six instruments — five c…
  • instruments — OpenTelemetry instrument factory for @suaveplan/api-plugin-export. Builds a cached bundle of six instruments — five c…
• plugin — The plugin factory for @suaveplan/api-plugin-export. Construction-time it validates options through `ExportPluginOpti…
  • plugin — The plugin factory for @suaveplan/api-plugin-export. Construction-time it validates options through `ExportPluginOpti…
• download — Implements the GET /:id/download route on @suaveplan/api-plugin-export. The handler serves the rendered file body f…
  • download — Implements the GET /:id/download route on @suaveplan/api-plugin-export. The handler serves the rendered file body f…
• exports — OpenAPIHono route group exposed at the configured basePath (default /exports). Wires four endpoints — GET /, `POS…
  • exports — OpenAPIHono route group exposed at the configured basePath (default /exports). Wires four endpoints — GET /, `POS…
  • post-handler — Implementation of the POST /exports handler, extracted from exports.ts so the route-registration file stays under t…
• problem-json — @suaveplan/api-plugin-export returns RFC 7807 application/problem+json bodies for every failure surface on its rout…
  • problem-json — @suaveplan/api-plugin-export returns RFC 7807 application/problem+json bodies for every failure surface on its rout…
• services — This file is a type-only declare module "@suaveplan/api-plugin/service-registry" block. It adds two slots to the shar…
  • export — Service-level orchestration for the export plugin. This module wires the three exporter classes (CsvExporter, `JsonEx…
    • export-service — Service-level orchestration for the export plugin. This module wires the three exporter classes (CsvExporter, `JsonEx…
  • registry-augmentation — This file is a type-only declare module "@suaveplan/api-plugin/service-registry" block. It adds two slots to the shar…
• memory — This module ships MemoryExportJobStore, the in-memory implementation of the ExportJobStore contract. It wraps a `Ma…
  • memory-store — This module ships MemoryExportJobStore, the in-memory implementation of the ExportJobStore contract. It wraps a `Ma…
• surreal — This module ships SurrealExportStore, the SurrealDB-backed implementation of ExportJobStore. It satisfies the same…
  • surreal-store — This module ships SurrealExportStore, the SurrealDB-backed implementation of ExportJobStore. It satisfies the same…
• types — This module declares the ExportJobStore interface — the formal persistence contract for export jobs. Before this modu…
  • types — This module declares the ExportJobStore interface — the formal persistence contract for export jobs. Before this modu…
• types — This module holds the Zod-fronted public type surface for @suaveplan/api-plugin-export: the ExportFormat / `ExportS…
  • types — This module holds the Zod-fronted public type surface for @suaveplan/api-plugin-export: the ExportFormat / `ExportS…

Quick start

import { createPluginRegistry } from "@suaveplan/api-plugin";
import {
    createExportPlugin,
    type DataProvider,
} from "@suaveplan/api-plugin-export";

const registry = createPluginRegistry();
registry.register(createExportPlugin({ basePath: "/v1/exports" }));
await registry.init();
await registry.ready();

const providers = registry.getService("exportProviders");
if (providers) {
    const userProvider: DataProvider = {
        resource: "users",
        fetch: async () => db.select("user").get(),
    };
    providers.set(userProvider.resource, userProvider);
}

POST /v1/exports/  → { format: "csv", resource: "users" }
GET  /v1/exports/  → { items: ExportJob[], total }
GET  /v1/exports/{id}  → ExportJob
DELETE /v1/exports/{id}  → { success: true }

Modules

• plugin/plugin — plugin factory + lifecycle hooks.
• routes/exports/exports — OpenAPIHono route group.
• routes/exports/post-handler — POST / handler.
• services/export/export-service — getExporter, inferColumns, runExport.
• exporters/csv/csv — RFC 4180 CSV writer.
• exporters/json/json — JSON writer.
• exporters/xlsx/xlsx — SpreadsheetML XML writer.
• error-codes/error-codes — EXPORT_CODES + ExportError.
• otel/instruments — ExportInstruments bundle.
• services/registry-augmentation — ServiceRegistry slot augmentation.
• types/types — Zod schemas + public types.

Scope notes

This package ships the upstream §2 functional surface (CSV / JSON / SpreadsheetML XML exporters + in-memory job store + four-route Hono group). The upstream §3–§4 enhancements (streaming exporters, S3-backed blob store, auth/permissions/rate-limit/idempotency middleware, OOXML/ZIP writer, scheduled exports, signed download URLs, Parquet/Markdown formats) are deferred to follow-up changes — they require downstream plugins that have not yet landed .