k.route

k.route(definition) takes a route and hands back its handler. body, params, query and headers are typed from what the route declares, and the return is checked against its responses.

import { z } from 'zod';
import { ProblemDetailsSchema } from 'kizunajs/schemas';
import { k } from '../k';
import { UserSchema } from './schemas';

export const createUser = k
    .route({
        method: 'POST',
        path: '/users',
        auth: 'user',
        body: z.object({
            name: z.string().min(1),
            email: z.email(),
        }),
        responses: {
            201: UserSchema,
            400: ProblemDetailsSchema,
        },
    })
    .handler(async ({ body }) => ({
        status: 201,
        body: await db.users.create(body),
    }));

Group routes with k.routes, which takes the routes k.route returns:

import { k } from '../k';
import { createUser } from './create-user';
import { getUser } from './get-user';

export const usersRoutes = k.routes('users', {
    createUser,
    getUser,
});

Fields

Every field of a route definition, plus auth. See k.routes for the rest.

auth

defineConfig resolves it onto the route's security, roles and requires, which the OpenAPI document and the generated clients read. A role or permission the route names must be one the identity declares, so a typo does not compile.

An instance that declares no identities has nothing to state, so auth is optional there and every route is public.

Nothing runs at import

kizuna generate imports your route files to read them, so whatever a module does at the top level, it does on every generate. Importing a database client is fine. Opening a connection, reading a file, or throwing on a missing environment variable is not, so keep that inside the handler.

Reference

• k.routes
• defineConfig
• Access control