Create a Generator

createGenerator from @ts-kizuna/core/generator lets you walk your contract and produce any output, such as a typed client for another language, documentation, or a route manifest. The OpenAPI and Swift generators are both built on it.

New first-party generator PRs will be declined, because we can't maintain what we don't know well. The generator API is public so you can build your own.

How it works

You provide a factory function that receives your options and returns two methods:

• processRoute is called once for every route in the contract
• finalize is called after all routes are processed and returns your output

createGenerator handles walking the contract, flattening nested route groups, and resolving /** @deprecated */ annotations automatically.

createGenerator

import { createGenerator, type GeneratorRouteContext } from '@ts-kizuna/core/generator';
import { contract } from './contract';

interface MyOptions {
    prefix?: string;
}

const generateRouteList = createGenerator((options: MyOptions) => {
    const lines: string[] = [];

    return {
        processRoute({ routeKey, route, deprecated }: GeneratorRouteContext) {
            const prefix = options.prefix ?? '';
            const tag = deprecated ? ' (deprecated)' : '';
            lines.push(`${prefix}${route.method} ${route.path}${tag}`);
        },
        finalize() {
            return lines;
        },
    };
});

const list = generateRouteList(contract, {
    prefix: '> ',
});

GeneratorRouteContext

Each processRoute call receives:

Deprecation

Deprecation data resolves automatically. When .kizuna/deprecations.json exists, produced by kizuna deprecations (see Deprecations), each processRoute call gets deprecated, deprecationMessage, and fieldDeprecations filled in for the matching route. Without that file, deprecated is always false and fieldDeprecations is always undefined.

Publishing

ts-kizuna does not maintain third-party generators. Build yours and publish it as its own package.