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 schemacontinues 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.envlookups or custom config objects. - New (v3.2): Dynamic
config/*.tsdirectory tree loading,defineConfig(), standaloneenv<T>()with Laravel-style type-casting, cascading RFC-compliant.envengine with variable expansion (${APP_PORT}), and production compilation viakatal 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
ValidationRulesyntax 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, andheadersindependently 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)orAppFactory.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!