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",
},
});