Ultra-fast, zero-dependency, batteries-included TypeScript backend framework for Bun and the modern web.
Katal combines the architectural elegance and developer experience of Laravel (Action-Domain-Responder Controllers, Real IoC Container, Queues, Cron Schedulers, and Artisan CLI) with the raw throughput, web standards, and compile-time type safety of Hono.
-
β‘ World-Class Throughput: Dual-tier router (
$O(1)$ static map + Radix Trie) delivering > 1,180,000 req/sec on Bun with sub-millisecond p99 latencies. - π¦ Pure Zero Runtime Dependencies: Authentication, Rate Limiting, Queues, Cron Schedulers, LRU Cache, Event Bus, W3C Observability, and OpenAPI ship inside the box with 0 external npm dependencies.
-
βοΈ Laravel-Grade Configuration: Cascading RFC-compliant
.envengine with variable expansion (${APP_HOST}), dynamicconfig/*.tsdirectory tree loading,defineConfig(), standaloneenv<T>()with type casting, Standard Schema validation, and production serialization (katal config:cache). -
π§
Onion Middleware Pipeline: Predictable
(ctx, next)middleware lifecycle with guaranteed CORS and observability preservation on 500 error boundaries. - π Real IoC Container with Autowiring: Full constructor dependency injection directly into controllers with Singleton, Transient, and Request-Scoped child container lifetimes.
-
π‘οΈ Standard Schema Validation: Seamless native support for Standard Schema (Zod, Valibot, ArkType, or Katal built-in) with zero adapter glue, declared as
static schema = ...on controllers for zero-allocation introspection. -
π End-to-End Type Safety & RPC: Fluent route chaining (
app.get().post()) and zero-overhead client proxy (kc<typeof app>()) giving 100% type-safe API consumption for React, Vue, Svelte, Next.js, and Astro. -
π¬ Distributed Queues & Cron Scheduler: In-memory priority queue, zero-dependency native Redis Streams distributed queue 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 test runs, and rich Laravel-style fluent assertions.
-
π οΈ Developer CLI Tooling: Laravel Artisan-like CLI:
katal make:controller,katal make:middleware,katal config:cache,katal routes:list, andkatal dev.
Measured with autocannon on Bun 1.x using 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+ |
| Feature | Katal v3 | Hono | Laravel |
|---|---|---|---|
| Zero Runtime Dependencies | β | β | |
| Single-Action Controller (ADR) | β | β | |
| Real IoC Container with Autowiring | β | β | β |
| Radix Trie High-Speed Routing | β | β | β |
| Standard Schema Support (Zod/Valibot) | β | β | β |
| End-to-End Type Safety (RPC Client) | β | β | β |
Fluent Route Chaining (app.get().post()) |
β | β | β |
Laravel-Grade Config (config/*.ts + Caching) |
β | β | β |
| Pure In-Memory Testing (No Sockets) | β | β | β |
| Built-in Queue & UNIX Cron Scheduler | β | β | β |
| Native Redis Streams Queue Driver | β | β | β |
| Developer CLI Tooling (Artisan-like) | β | β | β |
| RFC 7807 Problem Details Built-in | β | β | β |
bun add katalimport { Application, Controller } from "katal";
import type { RequestContext } from "katal";
import { z } from "zod";
// 1. Define a Service with Dependency Injection
class GreeterService {
greet(name: string) {
return `Hello, ${name}! Welcome to Katal v3.`;
}
}
// 2. Define validation schema with Zod or built-in schema
const helloQuerySchema = z.object({
name: z.string().default("World"),
});
// 3. Define Action Controller with Static Schema & Constructor Autowiring
class HelloController extends Controller {
static schema = {
query: helloQuerySchema,
};
constructor(private readonly greeter: GreeterService) {
super();
}
async handle(ctx: RequestContext) {
const query = ctx.valid<z.infer<typeof helloQuerySchema>>("query");
return this.success({
message: this.greeter.greet(query.name),
});
}
}
// 4. Initialize Application & Register Services
export const app = new Application({ port: 3000 });
app.singleton(GreeterService);
// Controller route with auto-discovered static schema
app.getRouter().get("/api/hello", HelloController, {
docs: { summary: "Greet the caller" },
});
// Or fluent route chaining:
app.get("/api/ping", (ctx) => ctx.json({ pong: true }));
// Expose OpenAPI 3.1 & Interactive Scalar UI
app.exposeDocs("/docs", "/openapi.json");
await app.listen();bun run src/app.ts
# π Server running at http://localhost:3000
# π Interactive Docs available at http://localhost:3000/docsGenerate application primitives and inspect routes instantly:
# Generate single-action controller
bunx katal make:controller CreateUser
# Generate onion middleware
bunx katal make:middleware RateLimit
# Generate service provider
bunx katal make:provider Database
# Inspect all registered application routes (Static O(1) & Radix Trie)
bunx katal routes:list
# Production configuration caching & inspection
bunx katal config:cache
bunx katal config:show
bunx katal config:clear
# Start development server with hot-reloading
bunx katal devConsume your backend from React, Vue, Next.js, or Astro with full compile-time autocompletion:
import { kc } from "katal/client";
import type { app } from "./backend/app";
// Initialize type-safe client inferred from your Katal Application instance
const client = kc<typeof app>("http://localhost:3000");
// Fully typed request, params, query, and response
const response = await client.api.hello.$get({
query: { name: "Alice" },
});
const data = await response.json();
console.log(data.data.message); // Typed: stringTest your entire HTTP pipeline without binding to network ports:
import { describe, it, expect } from "bun:test";
import { app } from "./src/app";
describe("API Test Suite", () => {
it("executes in memory with zero TCP latency", async () => {
const res = await app.handle(new Request("http://localhost/api/hello?name=Katal"));
expect(res.status).toBe(200);
const body = await res.json();
expect(body.data.message).toBe("Hello, Katal! Welcome to Katal v3.");
});
});- Architecture & Core Application
- Laravel-Grade Configuration & .env Engine
- HTTP & Action Controllers
- Onion Middleware Pipeline
- IoC Container & Autowiring
- Standard Schema Validation
- End-to-End Type Safety (RPC Client)
- Developer CLI (Artisan)
- Pure In-Memory Testing
- Service Providers & Subsystem Lifecycle
- OpenAPI 3.1 & Interactive Scalar UI
- Timing-Safe Authentication
- Policy-Based Authorization
- Atomic Sliding-Window Rate Limiter
- Leak-Free LRU Cache & Stampede Protection
- Enterprise Queue & 5-Field UNIX Cron
- Migrating from Katal v2 to v3
MIT Β© Syed Najam Abbas
