Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
# @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`).
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-plugin-export`. Every production code path that rai…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-plugin-export`. Every production code path that rai…
|
||||
- [csv](./src/exporters/csv/csv.md) — RFC 4180 CSV writer. This module ships three pure helpers — `escapeCsvField`, `formatCellValue`, `convertToCsv` — plus…
|
||||
- [csv](./src/exporters/csv/csv.md) — RFC 4180 CSV writer. This module ships three pure helpers — `escapeCsvField`, `formatCellValue`, `convertToCsv` — plus…
|
||||
- [json](./src/exporters/json/json.md) — JSON exporter. Projects every row to a record keyed by the column `header` (not `key`), optionally applying `column.tra…
|
||||
- [json](./src/exporters/json/json.md) — JSON exporter. Projects every row to a record keyed by the column `header` (not `key`), optionally applying `column.tra…
|
||||
- [xlsx](./src/exporters/xlsx/xlsx.md) — SpreadsheetML (XML) writer for the `xlsx` format. This is the dependency-free path inherited from the upstream package…
|
||||
- [xlsx](./src/exporters/xlsx/xlsx.md) — SpreadsheetML (XML) writer for the `xlsx` format. This is the dependency-free path inherited from the upstream package…
|
||||
- [otel](./src/otel/instruments.md) — OpenTelemetry instrument factory for `@suaveplan/api-plugin-export`. Builds a cached bundle of six instruments — five c…
|
||||
- [instruments](./src/otel/instruments.md) — OpenTelemetry instrument factory for `@suaveplan/api-plugin-export`. Builds a cached bundle of six instruments — five c…
|
||||
- [plugin](./src/plugin/plugin.md) — The plugin factory for `@suaveplan/api-plugin-export`. Construction-time it validates options through `ExportPluginOpti…
|
||||
- [plugin](./src/plugin/plugin.md) — The plugin factory for `@suaveplan/api-plugin-export`. Construction-time it validates options through `ExportPluginOpti…
|
||||
- [download](./src/routes/download/download.md) — Implements the `GET /:id/download` route on `@suaveplan/api-plugin-export`. The handler serves the rendered file body f…
|
||||
- [download](./src/routes/download/download.md) — Implements the `GET /:id/download` route on `@suaveplan/api-plugin-export`. The handler serves the rendered file body f…
|
||||
- [exports](./src/routes/exports/exports.md) — OpenAPIHono route group exposed at the configured `basePath` (default `/exports`). Wires four endpoints — `GET /`, `POS…
|
||||
- [exports](./src/routes/exports/exports.md) — OpenAPIHono route group exposed at the configured `basePath` (default `/exports`). Wires four endpoints — `GET /`, `POS…
|
||||
- [post-handler](./src/routes/exports/post-handler.md) — Implementation of the `POST /exports` handler, extracted from `exports.ts` so the route-registration file stays under t…
|
||||
- [problem-json](./src/routes/problem-json/problem-json.md) — `@suaveplan/api-plugin-export` returns RFC 7807 `application/problem+json` bodies for every failure surface on its rout…
|
||||
- [problem-json](./src/routes/problem-json/problem-json.md) — `@suaveplan/api-plugin-export` returns RFC 7807 `application/problem+json` bodies for every failure surface on its rout…
|
||||
- [services](./src/services/registry-augmentation.md) — This file is a type-only `declare module "@suaveplan/api-plugin/service-registry"` block. It adds two slots to the shar…
|
||||
- [export](./src/services/export/export-service.md) — Service-level orchestration for the export plugin. This module wires the three exporter classes (`CsvExporter`, `JsonEx…
|
||||
- [export-service](./src/services/export/export-service.md) — Service-level orchestration for the export plugin. This module wires the three exporter classes (`CsvExporter`, `JsonEx…
|
||||
- [registry-augmentation](./src/services/registry-augmentation.md) — This file is a type-only `declare module "@suaveplan/api-plugin/service-registry"` block. It adds two slots to the shar…
|
||||
- [memory](./src/store/memory/memory-store.md) — This module ships `MemoryExportJobStore`, the in-memory implementation of the `ExportJobStore` contract. It wraps a `Ma…
|
||||
- [memory-store](./src/store/memory/memory-store.md) — This module ships `MemoryExportJobStore`, the in-memory implementation of the `ExportJobStore` contract. It wraps a `Ma…
|
||||
- [surreal](./src/store/surreal/surreal-store.md) — This module ships `SurrealExportStore`, the SurrealDB-backed implementation of `ExportJobStore`. It satisfies the same…
|
||||
- [surreal-store](./src/store/surreal/surreal-store.md) — This module ships `SurrealExportStore`, the SurrealDB-backed implementation of `ExportJobStore`. It satisfies the same…
|
||||
- [types](./src/store/types/types.md) — This module declares the `ExportJobStore` interface — the formal persistence contract for export jobs. Before this modu…
|
||||
- [types](./src/store/types/types.md) — This module declares the `ExportJobStore` interface — the formal persistence contract for export jobs. Before this modu…
|
||||
- [types](./src/types/types.md) — This module holds the Zod-fronted public type surface for `@suaveplan/api-plugin-export`: the `ExportFormat` / `ExportS…
|
||||
- [types](./src/types/types.md) — This module holds the Zod-fronted public type surface for `@suaveplan/api-plugin-export`: the `ExportFormat` / `ExportS…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
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);
|
||||
}
|
||||
```
|
||||
|
||||
```http
|
||||
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`](src/plugin/plugin.md) — plugin factory + lifecycle hooks.
|
||||
- [`routes/exports/exports`](src/routes/exports/exports.md) — OpenAPIHono route group.
|
||||
- [`routes/exports/post-handler`](src/routes/exports/post-handler.md) — `POST /` handler.
|
||||
- [`services/export/export-service`](src/services/export/export-service.md) — `getExporter`, `inferColumns`, `runExport`.
|
||||
- [`exporters/csv/csv`](src/exporters/csv/csv.md) — RFC 4180 CSV writer.
|
||||
- [`exporters/json/json`](src/exporters/json/json.md) — JSON writer.
|
||||
- [`exporters/xlsx/xlsx`](src/exporters/xlsx/xlsx.md) — SpreadsheetML XML writer.
|
||||
- [`error-codes/error-codes`](src/error-codes/error-codes.md) — `EXPORT_CODES` + `ExportError`.
|
||||
- [`otel/instruments`](src/otel/instruments.md) — `ExportInstruments` bundle.
|
||||
- [`services/registry-augmentation`](src/services/registry-augmentation.md) — `ServiceRegistry` slot augmentation.
|
||||
- [`types/types`](src/types/types.md) — 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 .
|
||||
|
||||
Reference in New Issue
Block a user