BinarySchema & FileSchema

Helper schemas for binary response bodies (BinarySchema) and multipart upload fields (FileSchema).

Two helper schemas for non-JSON bodies, both from kizunajs/schemas.

import { BinarySchema, FileSchema } from 'kizunajs/schemas';

Sending or returning a blob of bytes, use BinarySchema. Taking a file uploaded through a form, use FileSchema.

Helper	Is	Use	Swift type
`BinarySchema`	`z.instanceof(Uint8Array)`	Binary response bodies (PDF, images) and raw binary input	`Data`
`FileSchema`	`z.instanceof(File)`	`multipart/form-data` upload fields	`MultipartFile`

The split follows what each type carries. A File has a filename and MIME type, which is what a multipart part needs. A Uint8Array is bytes alone, and a Node Buffer satisfies it.

BinarySchema

Use it as a response body and pair it with a contentType. It defaults to application/octet-stream. The body goes to the wire as raw bytes (never JSON-serialized); the OpenAPI generator emits type: string, format: binary, and the Swift client decodes it to Data.

routes/reports.ts

import { BinarySchema } from 'kizunajs/schemas';
import { k } from './k';

export const reportsRoutes = k.routes('reports', {
    downloadReport: k
        .route({
            method: 'GET',
            path: '/reports/:id.pdf',
            responses: {
                200: {
                    body: BinarySchema,
                    contentType: 'application/pdf',
                },
            },
        })
        .handler(/* ... */),
});

The handler returns the bytes, as a Buffer or Uint8Array. Set Content-Disposition as a normal response header if you want a download:

src/routes/reports.ts

downloadReport: async ({ params }) => {
    const pdf = await renderReport(params.id);
    return {
        status: 200,
        body: pdf,
        headers: {
            'content-disposition': `inline; filename="report-${params.id}.pdf"`,
        },
    };
},

FileSchema

Use it inside a multipart/form-data request body for uploaded files:

users.ts

import { FileSchema } from 'kizunajs/schemas';

uploadAvatar: k
    .route({
        method: 'POST',
        path: '/avatar',
        contentType: 'multipart/form-data',
        body: z.object({
            file: FileSchema,
            userId: z.string(),
        }),
        responses: {
            200: z.object({
                size: z.number(),
            }),
        },
    })
    .handler(/* ... */),

BinarySchema & FileSchema

BinarySchema

FileSchema

On this page