Skip to content
najamcodesPublic

About

A Laravel-inspired web framework for Bun with TypeScript. Build modern web applications with decorators, controllers, middleware, validation, and authentication.

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

41 Commits

Folders and files

Repository files navigation

Katal Logo

Katal

Ultra-fast, zero-dependency, batteries-included TypeScript backend framework for Bun and the modern web.

License: MIT npm version Bun TypeScript Zero Dependencies Throughput

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.


⚑ Core Value Propositions

  • ⚑ 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 .env engine with variable expansion (${APP_HOST}), dynamic config/*.ts directory tree loading, defineConfig(), standalone env<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, and katal dev.

πŸ“Š Benchmark Comparison

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 Matrix (Katal vs Hono vs Laravel)

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 βœ… ❌ ❌

πŸš€ 60-Second Quick Start

1. Installation

bun add katal

2. Create Your Application (src/app.ts)

import { 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();

3. Run the Server

bun run src/app.ts
# πŸš€ Server running at http://localhost:3000
# πŸ“– Interactive Docs available at http://localhost:3000/docs

πŸ› οΈ Developer CLI (katal)

Generate 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 dev

πŸ”„ End-to-End Type Safety & RPC Client (kc)

Consume 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: string

πŸ§ͺ Pure In-Memory Testing

Test 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.");
    });
});

πŸ“š Complete Documentation


πŸ“„ License

MIT Β© Syed Najam Abbas

About

A Laravel-inspired web framework for Bun with TypeScript. Build modern web applications with decorators, controllers, middleware, validation, and authentication.

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages