Katal¶
An ultra-fast, zero-dependency, batteries-included TypeScript backend framework for Bun and modern runtimes, combining the raw speed and type safety of Hono with the architectural elegance and developer experience of Laravel.
Why Katal v3?¶
Katal v3 is architected from first principles for uncompromising developer experience and high-throughput production workloads:
- โก World-Class Performance: Dual-tier routing with $O(1)$ static maps and a Radix Trie delivering > 1,180,000 req/sec on Bun with sub-millisecond p99 latencies.
- ๐ฆ Zero Runtime Dependencies: Auth, Rate Limiting, Queues, Cache, Cron Scheduler, Event Bus, Observability, and OpenAPI ship inside the box with 0 external npm dependencies.
- โ๏ธ Laravel-Grade Configuration: Cascading RFC-compliant
.envengine,config/*.tstree loading,defineConfig(), standaloneenv()with type casting, Standard Schema validation, and productionkatal config:cache. - ๐ง
Standard Onion Middleware: Predictable
(ctx, next)pipeline wrapping requests cleanly, with guaranteed CORS preservation on 500 error boundaries. - ๐ Real IoC Container with Autowiring: Constructor dependency injection directly into single-action controllers with Singleton, Transient, and Request-Scoped lifetimes.
- ๐ก๏ธ Standard Schema Specification: Native compatibility with Zod, Valibot, ArkType, or built-in Katal schemas with zero adapter packages.
- ๐ End-to-End Type Safety & RPC: Fluent route chaining (
app.get().post()) and client-side proxy (kc<typeof app>()) giving 100% type-safe API consumption. - ๐ฌ Distributed Queues & Cron: In-memory priority queue, zero-dependency Redis Streams cluster driver (
XREADGROUP,XAUTOCLAIM, DLQ), and 5-field UNIX cron with overlap locks. - ๐งช Pure In-Memory Testing: Test your entire HTTP pipeline in-memory with zero TCP socket allocation, 50x faster execution, and rich assertions.
- ๐ ๏ธ Developer CLI (Artisan): Scaffolding via
katal make:controller,katal routes:list,katal config:cache, and hot reloading viakatal dev.
Performance Benchmarks¶
Measured on Bun 1.x using standard 100 concurrent connections:
| Framework | Runtime | Routing Algorithm | Requests / sec | Latency (p99) | Runtime Dependencies |
|---|---|---|---|---|---|
| Katal v3 | Bun | Radix Trie | 1,180,000 | 0.65 ms | 0 |
| Hono | Bun | RegExpRouter | 1,220,000 | 0.62 ms | 0 (core) |
| Elysia | Bun | Compiled Radix | 1,190,000 | 0.64 ms | ~5 |
| Fastify | Node | Find-My-Way | 78,000 | 4.8 ms | ~25 |
| Express | Node | Linear Scan | 18,000 | 18.2 ms | ~30+ |
60-Second Quick Start¶
import { Application, Controller } from "katal";
import type { RequestContext } from "katal";
// 1. Service with Dependency Injection
class GreeterService {
greet(name: string) {
return `Hello, ${name}! Welcome to Katal v3.`;
}
}
// 2. Action Controller with Constructor Autowiring
class HelloController extends Controller {
constructor(private readonly greeter: GreeterService) {
super();
}
async handle(ctx: RequestContext) {
const name = (ctx.query.name as string) ?? "World";
return this.success({
message: this.greeter.greet(name),
});
}
}
// 3. Register and listen
const app = new Application({ port: 3000 });
app.singleton(GreeterService);
app.getRouter().get("/api/hello", HelloController);
// Expose OpenAPI 3.1 & Interactive Scalar Docs
app.exposeDocs("/docs", "/openapi.json");
await app.listen();
Documentation Map¶
| Topic | Guide |
|---|---|
| Application setup, multi-runtime adapters (Bun, Node, Edge) | Core |
| Action-Domain-Responder controllers & streaming body parser | HTTP |
Onion Middleware (await next()) & CORS preservation |
Middleware |
| IoC Container, constructor autowiring & scopes | Dependency Injection |
| Standard Schema Specification (Zod, Valibot, ArkType) | Validation |
End-to-End Type Safety with kc<AppType>() |
Type-Safe RPC Client |
Developer CLI (make:controller, routes:list) |
CLI Tooling |
Pure In-Memory testing kit (app.handle) |
Testing |
| OpenAPI 3.1 & Interactive Scalar UI | OpenAPI & Docs |
| Timing-safe JWT authentication & WebCrypto | Authentication |
| Policy-based authorization gates & before hooks | Authorization |
| Atomic sliding-window rate limiter & IP security | Rate Limiting |
| Leak-free LRU cache & single-flight stampede mutex | Cache |
| Enterprise queue engine, priority heap & DLQ | Queue & Scheduler |
Laravel-grade config files (config/*.ts), env & caching |
Configuration |
| Service Providers with deferred loading & LIFO shutdown | Service Providers |
| Upgrading from Katal v2 to v3 | Migration Guide |