@kozojs/core

🔥 Kozo - The fastest TypeScript framework that runs everywhere.

High-performance backend framework with native Zod validation, type-safe client generation, and edge runtime compatibility.

📊 Performance

• 17,510 req/s — faster than Fastify (+33%) and NestJS (+324%)
• Native C++ route matching via uWebSockets.js — zero JS dispatch overhead
• Zero overhead serialization with fast-json-stringify
• Edge-ready: Works on Node.js, Bun, Deno, and Cloudflare Workers

✨ Features

• 🎯 Type-Safe Client Generation - Auto-generate typed SDK from your API
• ⚡ Zero Config - No decorators, no boilerplate
• 🛡️ Zod Native - First-class Zod schema support
• 🌍 Universal - Runs on any JavaScript runtime
• 🚀 Fast - Optimized for performance with minimal overhead

🚀 Quick Start

npm install @kozojs/core zod

import { createKozo } from '@kozojs/core';
import { z } from 'zod';

const app = createKozo({ port: 3000 });

// Define schema
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string(),
});

// Create route with validation
app.get('/users/:id', {
  params: z.object({ id: z.string().uuid() }),
  response: UserSchema,
}, (c) => {
  return {
    id: c.params.id,
    email: '[email protected]',
    name: 'John Doe',
  };
});

await app.listen(3000);

🎯 Type-Safe Client Generation

Generate a fully typed client SDK with automatic type inference:

// server.ts
const app = createKozo();

app.get('/users', {
  query: z.object({ page: z.number() }),
  response: z.array(UserSchema),
}, handler);

// Generate client
const clientCode = app.generateClient({
  baseUrl: 'https://api.example.com',
  includeValidation: true, // Include Zod schemas for client-side validation
  validateByDefault: false, // Opt-in validation
});

// Save to file
writeFileSync('./client/api.ts', clientCode);

Usage in Frontend:

import { KozoClient } from './client/api';

const api = new KozoClient({
  baseUrl: 'https://api.example.com',
  validateRequests: true, // Enable runtime validation
});

// Fully typed! 🎉
const users = await api.users({ query: { page: 1 } });
//    ^? User[]

// TypeScript catches errors at compile time
const user = await api.usersById({ 
  params: { id: 'invalid' } // ❌ Type error: not a UUID
});

🛡️ Validation

Kozo uses Zod for schema validation with detailed error messages:

app.post('/users', {
  body: z.object({
    email: z.string().email(),
    name: z.string().min(2).max(50),
    age: z.number().min(18),
  }),
  response: UserSchema,
}, (c) => {
  // c.body is fully typed and validated
  const { email, name, age } = c.body;
  // Your logic here
});

Error Response (auto-formatted):

{
  "error": "Validation failed",
  "details": [
    {
      "path": ["email"],
      "message": "Invalid email"
    }
  ]
}

🌍 Runtime Compatibility

Kozo runs on all modern JavaScript runtimes:

// Node.js
import { createKozo } from '@kozojs/core';
const app = createKozo();
await app.listen(3000);

// Bun (faster JSON parsing)
const app = createKozo();
await app.listen(3000); // Automatically uses Bun optimizations

// Cloudflare Workers
export default {
  fetch: app.fetch,
};

// Deno
import { createKozo } from 'npm:@kozojs/core';

📈 Performance Comparison

| Framework | Req/s | Latency (GET) | |-----------|-------|---------------| | Kozo | 17,510 | 317 μs | | Fastify | 13,210 | 766 μs | | NestJS | 4,131 | 648 μs |

Benchmarked with autocannon — 10 concurrent connections, 10 seconds. Route matching done in C++ by uWS before any JS runs.

Why choose Kozo:

• If you need maximum throughput → 33% faster than Fastify
• If you want best DX + type safety → Zod-native, zero boilerplate
• If you need type-safe client generation → built-in SDK codegen
• If you need maximum portability → Works on Node.js, Bun, Deno, Edge

🔌 Middleware

app.use(async (c, next) => {
  console.log(`${c.req.method} ${c.req.url}`);
  await next();
});

🎨 Services (Dependency Injection)

const app = createKozo({
  services: {
    db: new DatabaseClient(),
    cache: new RedisClient(),
  }
});

app.get('/users', {}, (c) => {
  const users = await c.services.db.users.findMany();
  return users;
});

📚 API Reference

createKozo(config?)

Create a new Kozo application.

Options:

• port?: number - Server port (default: 3000)
• services?: Services - Dependency injection container

app.get(path, schema, handler)

Define a GET route.

Parameters:

• path: string - Route path (supports :param)
• schema: RouteSchema - Zod schemas for validation
  • params?: ZodSchema - Path parameters
  • query?: ZodSchema - Query string
  • response?: ZodSchema - Response body (enables fast serialization)
• handler: (context) => any - Route handler

app.generateClient(options?)

Generate a type-safe client SDK.

Options:

• baseUrl?: string - API base URL
• includeValidation?: boolean - Include Zod schemas (default: true)
• validateByDefault?: boolean - Enable validation by default (default: false)
• defaultHeaders?: Record<string, string> - Default request headers

🏆 When to Use Kozo

Use Kozo if you:

• ✅ Need edge deployment (Cloudflare Workers, Vercel Edge)
• ✅ Want Bun compatibility
• ✅ Love Zod and want native integration
• ✅ Need type-safe client generation
• ✅ Want zero-config DX

Don't use Kozo if you:

• ❌ Only target Node.js and need absolute maximum speed
• ❌ Already have a complex Fastify/Express setup
• ❌ Don't care about type safety

📄 License

MIT

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

Made with ⚡ by the Kozo team

Powered by uWebSockets.js — native per-route C++ matching