End-to-End Type Safety & RPC Client (kc)

Katal provides a zero-overhead, proxy-based RPC client (katal/client) inspired by Hono RPC. Share your backend types directly with your frontend (React, Vue, Svelte, Next.js, Astro) for complete compile-time type safety with zero code generation.


1. Fluent Route Chaining & Automatic Type Accumulation

In your backend server (src/app.ts), define routes using fluent method chaining:

import { Application, Controller } from "katal";
import type { RequestContext } from "katal";
import { z } from "zod";

class GetUserController extends Controller<{ id: string; name: string }> {
    async handle(ctx: RequestContext) {
        return this.success({ id: ctx.params.id, name: "Alice" });
    }
}

class CreateUserController extends Controller<{ id: string; status: string }> {
    static schema = {
        body: z.object({
            name: z.string().min(2),
            email: z.string().email(),
        }),
    };

    async handle(ctx: RequestContext) {
        const body = ctx.valid<any>("body");
        return this.created({ id: "usr_1", status: "created" });
    }
}

// Fluent method chaining accumulates route types automatically!
export const app = new Application()
    .get("/api/users/:id", GetUserController)
    .post("/api/users", CreateUserController);

// Export application type for frontend consumption
export type AppType = typeof app;

2. Sub-Router Prefixing with .route()

You can modularize routes into sub-routers and mount them with automatic path prefixing:

import { Router } from "katal";

// Create sub-router
const authRouter = new Router()
    .post("/login", LoginController)
    .post("/register", RegisterController);

// Mount onto main application with prefix
export const app = new Application()
    .route("/api/auth", authRouter);

The RPC client automatically infers /api/auth/login and /api/auth/register with complete parameter and body typing!


3. Consuming in Frontend (React, Vue, Svelte, Next.js)

Import the typed client helper kc:

import { kc } from "katal/client";
import type { AppType } from "./backend/app";

// Initialize typed client
const client = kc<AppType>("http://localhost:3000");

// 1. GET with Path & Query parameters (Full autocomplete for paths and params)
const res = await client.api.users[":id"].$get({
    param: { id: "usr_42" },
});

if (res.ok) {
    const user = await res.json();
    console.log(user.name); // Fully typed: string
}

// 2. POST with JSON body (Validated against backend Standard Schema)
const createRes = await client.api.users.$post({
    json: {
        name: "Bob",
        email: "bob@example.com",
    },
});

const result = await createRes.json();
console.log(result.id);

4. Custom Headers & Auth Interception

You can configure base headers and dynamic authorization tokens:

const client = kc<AppType>("https://api.myapp.com", {
    headers: {
        "Authorization": `Bearer ${userJwtToken}`,
        "X-Custom-Header": "Katal-Client",
    },
});

See Also