`schemas/schemas` — public Zod request/response surface

(no submodules)

Purpose

Carries the full public Zod surface used by the route handlers and any external client (CLI tool, integration test, browser app) that wants to validate or generate import requests / responses without depending on the route module itself. Every body, query, and response shape that crosses the HTTP boundary is declared here so the OpenAPI document and the runtime validators stay in lockstep.

Keeping these schemas in their own module means consumers can import them without pulling in the Hono/OpenAPI route builder, which is important for browser clients and shared validation libraries.

Features

ImportFormatSchema / ImportStatusSchema — Zod enums mirroring the cross-module type unions.
ColumnMappingSchema — wire-form of a column mapping (functions intentionally omitted; transforms are server-side only).
PreviewRequestSchema / PreviewResponseSchema — POST /preview.
CreateImportJobSchema — POST / body.
ImportJobResponseSchema — every job-shape response.
ImportJobListQuerySchema — GET / querystring with z.coerce for the numeric fields so query strings parse without hand-rolling.

Usage: Basic Example

import { CreateImportJobSchema } from "@suaveplan/api-plugin-import";

const result = CreateImportJobSchema.safeParse({
    format: "csv",
    data: "name\nAda",
    mappings: [{ sourceColumn: "name", targetField: "displayName" }],
});
if (!result.success) throw new Error(result.error.message);

Usage: Advanced Example

import { ImportJobResponseSchema, type ImportJobResponseShape } from "@suaveplan/api-plugin-import";

async function fetchJob(id: string): Promise<ImportJobResponseShape> {
    const res = await fetch(`/imports/${id}`);
    const json = await res.json();
    return ImportJobResponseSchema.parse(json);
}

API Reference

ImportFormatSchema, type ImportFormatInput
ImportStatusSchema, type ImportStatusInput
ColumnMappingSchema, type ColumnMappingInput
PreviewRequestSchema, type PreviewRequestInput
PreviewResponseSchema, type PreviewResponseShape
CreateImportJobSchema, type CreateImportJobInput
ImportJobResponseSchema, type ImportJobResponseShape
ImportJobListQuerySchema, type ImportJobListQueryInput
RowErrorSchema

Implementation Notes

ColumnMappingSchema omits the transform callback — transforms are authored in TypeScript on the server, not over the wire. Wire-form mappings are pure renames + required flags.
PreviewResponseSchema.sampleRows uses z.record(z.string(), z.unknown()) so heterogeneous row shapes survive validation.
ImportJobListQuerySchema uses z.coerce.number() because Hono delivers query parameters as strings — the coerce ensures ?limit=20 parses to a number without manual parseInt.
CreateImportJobSchema.mappings requires min(1) because zero mappings is the service-layer IMPORT.VALIDATION failure; rejecting it at the Zod boundary saves a service round-trip.

3.1 KiB Raw Blame History

schemas/schemas — public Zod request/response surface