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.

License: MIT npm version Bun TypeScript Zero Dependencies Performance


Why Katal v3?

Katal v3 is architected from first principles for uncompromising developer experience and high-throughput production workloads:

  1. โšก 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.
  2. ๐Ÿ“ฆ Zero Runtime Dependencies: Auth, Rate Limiting, Queues, Cache, Cron Scheduler, Event Bus, Observability, and OpenAPI ship inside the box with 0 external npm dependencies.
  3. โš™๏ธ Laravel-Grade Configuration: Cascading RFC-compliant .env engine, config/*.ts tree loading, defineConfig(), standalone env() with type casting, Standard Schema validation, and production katal config:cache.
  4. ๐Ÿง… Standard Onion Middleware: Predictable (ctx, next) pipeline wrapping requests cleanly, with guaranteed CORS preservation on 500 error boundaries.
  5. ๐Ÿ’‰ Real IoC Container with Autowiring: Constructor dependency injection directly into single-action controllers with Singleton, Transient, and Request-Scoped lifetimes.
  6. ๐Ÿ›ก๏ธ Standard Schema Specification: Native compatibility with Zod, Valibot, ArkType, or built-in Katal schemas with zero adapter packages.
  7. ๐Ÿ”„ 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.
  8. ๐Ÿ“ฌ Distributed Queues & Cron: In-memory priority queue, zero-dependency Redis Streams cluster driver (XREADGROUP, XAUTOCLAIM, DLQ), and 5-field UNIX cron with overlap locks.
  9. ๐Ÿงช Pure In-Memory Testing: Test your entire HTTP pipeline in-memory with zero TCP socket allocation, 50x faster execution, and rich assertions.
  10. ๐Ÿ› ๏ธ Developer CLI (Artisan): Scaffolding via katal make:controller, katal routes:list, katal config:cache, and hot reloading via katal 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