Migrating to Katal v3 & v3.2

Katal v3 is a major leap forward, modernizing the framework to rival Hono in raw throughput and web standards while preserving the developer ergonomics and enterprise features of Laravel.


Key Breaking Changes & Upgrades

1. Static Schema Declarations on Controllers

  • Old (v2): Schemas were declared as instance properties (protected schema = { ... }). This required the router and OpenAPI generator to instantiate every controller—which caused crashes if controllers required constructor DI parameters.
  • New (v3.2): Schemas are declared as static schema = { body: ..., query: ..., params: ..., headers: ... }.
  • Benefit: Zero controller instantiation during route discovery and OpenAPI spec generation. Instance protected schema continues to work with zero-argument constructors for backward compatibility.
// v2 (Legacy)
class UserController extends Controller {
    protected schema = { name: { type: "string", required: true } };
}

// v3.2 (Modern)
class UserController extends Controller {
    static schema = {
        body: z.object({ name: z.string().min(1) }),
    };
}

2. Laravel-Grade Configuration System

  • Old (v2): Ad-hoc process.env lookups or custom config objects.
  • New (v3.2): Dynamic config/*.ts directory tree loading, defineConfig(), standalone env<T>() with Laravel-style type-casting, cascading RFC-compliant .env engine with variable expansion (${APP_PORT}), and production compilation via katal config:cache.
// config/app.ts
import { defineConfig, env } from "katal";

export default defineConfig({
    name: env("APP_NAME", "Katal API"),
    port: env<number>("APP_PORT", 3000),
    debug: env<boolean>("APP_DEBUG", false),
});

// Access anywhere via global facade:
import { config } from "katal";
const appName = config("app.name");

3. Fluent Route Chaining & Automatic RPC Inference

  • Old (v2): Routes had to be defined exclusively via app.getRouter().get(...).
  • New (v3.2): Hono-style fluent chaining directly on app.get().post().put() with automatic RPC client type accumulation (AppWithRoutes<..., TRoutes>).
// Backend (app.ts)
export const app = new Application({ port: 3000 })
    .get("/api/users", () => ({ users: ["Alice", "Bob"] }))
    .post("/api/echo", async (ctx) => ctx.json({ received: ctx.body }));

// Frontend (client.ts)
import { kc } from "katal/client";
import type { app } from "./app";

const client = kc<typeof app>("http://localhost:3000");
const res = await client.api.users.$get(); // 100% compile-time autocomplete!

4. Distributed Redis Streams Queue Driver

  • Old (v2): In-memory priority queue only.
  • New (v3.2): Zero-dependency native Redis Streams distributed queue driver (app.useRedisQueue()) with Redis consumer groups (XREADGROUP), stalled worker reclamation (XAUTOCLAIM), and dead-letter queues (${stream}:dlq).
// Switch from in-memory to Redis Streams cluster
await app.useRedisQueue("redis://localhost:6379", {
    stream: "katal:jobs",
    group: "api-workers",
});

5. Onion Middleware Pipeline (await next())

  • Old (v2): Middleware implemented { before(ctx), after(ctx) } methods on an object.
  • New (v3): Standard Web onion middleware: async (context, next) => { ... return await next(); }.
  • Backward Compatibility: Legacy { before, after } object middlewares are automatically adapted and supported, but upgrading to standard functions is recommended.
// Modern Onion Middleware
app.use(async (ctx, next) => {
    const start = performance.now();
    const response = await next();
    response.headers.set("X-Response-Time", `${(performance.now() - start).toFixed(2)}ms`);
    return response;
});

6. Standard Schema Specification Validation

  • Old (v2): Required Katal's proprietary ValidationRule syntax exclusively.
  • New (v3): Native support for Zod, Valibot, ArkType, or Katal schemas via the Standard Schema Specification.
  • Multi-Target Validation: You can validate body, query, params, and headers independently or all at once.

7. Controller Constructor Dependency Injection

  • Controllers are now instantiated via container.make(ControllerClass).
  • Inject any container-registered dependency directly into the constructor:
class UsersController extends Controller {
    constructor(private readonly db: DatabaseConnection) {
        super();
    }

    async handle(ctx: RequestContext) {
        return this.success(await this.db.findUsers());
    }
}

8. Pure In-Memory Testing (app.handle(req))

  • Tests no longer require opening real TCP server ports.
  • Direct in-memory request execution via app.handle(request) or AppFactory.createTestClient(app):
const app = new Application();
const res = await app.handle(new Request("http://localhost/api/health"));
expect(res.status).toBe(200);

9. Interactive OpenAPI 3.1 & Scalar UI

  • OpenAPI 3.1 specifications and modern interactive documentation (powered by Scalar) are built in with 0 npm dependencies:
app.exposeDocs("/docs", "/openapi.json");

Visit /docs in your browser for a complete interactive API explorer!