@kozojs/core 0.2.2

package/README.md

@@ -0,0 +1,254 @@
+# @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
+
+- **10,503 req/s** with full Zod validation
+- **83%** of Fastify performance on Node.js
+- **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
+
+```bash
+npm install @kozojs/core zod
+```
+
+```typescript
+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: 'user@example.com',
+    name: 'John Doe',
+  };
+});
+
+await app.listen(3000);
+```
+
+## 🎯 Type-Safe Client Generation
+
+Generate a fully typed client SDK with automatic type inference:
+
+```typescript
+// 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:**
+
+```typescript
+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:
+
+```typescript
+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):**
+```json
+{
+  "error": "Validation failed",
+  "details": [
+    {
+      "path": ["email"],
+      "message": "Invalid email"
+    }
+  ]
+}
+```
+
+## 🌍 Runtime Compatibility
+
+Kozo runs on all modern JavaScript runtimes:
+
+```typescript
+// 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/Sec | Notes |
+|-----------|---------|-------|
+| **Fastify** | 12,754 | Native Node.js, no edge support |
+| **Rikta** | 11,919 | Fastify-based, no edge support |
+| **Kozo** | **10,503** | ✅ Universal (Node, Bun, Edge) |
+| **NestJS** | 8,500 | Heavy framework overhead |
+
+**Why Kozo is slower on Node.js:**
+- Built on Hono (universal runtime adapter)
+- That 17% performance gap buys you: ✅ Edge compatibility ✅ Bun support ✅ Zero config DX
+
+**Why choose Kozo:**
+- If you need **edge deployment** → Kozo is your only option
+- If you need **maximum Node.js speed** → Use Fastify/Rikta
+- If you want **best DX + portability** → Kozo is the sweet spot
+
+## 🔌 Middleware
+
+```typescript
+app.use(async (c, next) => {
+  console.log(`${c.req.method} ${c.req.url}`);
+  await next();
+});
+```
+
+## 🎨 Services (Dependency Injection)
+
+```typescript
+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](../../CONTRIBUTING.md)
+
+---
+
+**Made with ⚡ by the Kozo team**

package/lib/index.d.ts

@@ -0,0 +1,135 @@
+import * as hono from 'hono';
+import { Hono, Context } from 'hono';
+import { z } from 'zod';
+export { z } from 'zod';
+import { TSchema, Static } from '@sinclair/typebox';
+
+type SchemaType = z.ZodType<any> | TSchema;
+type RouteSchema = {
+    body?: SchemaType;
+    query?: SchemaType;
+    params?: SchemaType;
+    response?: SchemaType | Record<number, SchemaType>;
+};
+type InferSchema<T> = T extends z.ZodType<any> ? z.infer<T> : T extends TSchema ? Static<T> : unknown;
+type KozoContext<S extends RouteSchema = {}> = {
+    services: Services;
+    body: InferSchema<S['body']>;
+    query: InferSchema<S['query']>;
+    params: InferSchema<S['params']>;
+    req: any;
+    json: (data: any) => Response;
+    text: (data: string, status?: number, headers?: any) => Response;
+};
+type KozoHandler<S extends RouteSchema = {}> = (ctx: KozoContext<S>) => any | Promise<any>;
+interface Services {
+    [key: string]: unknown;
+}
+interface OpenAPIConfigRef {
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+interface KozoConfig {
+    routesDir?: string;
+    services?: Services;
+    port?: number;
+    mode?: 'safe' | 'turbo';
+    runtime?: 'node' | 'bun';
+    target?: 'node' | 'edge' | 'cloudflare' | 'vercel' | 'netlify';
+    monitoring?: {
+        enable: boolean;
+        metrics: ('req/sec' | 'latency' | 'errors')[];
+        port?: number;
+    };
+    basePath?: string;
+    openapi?: OpenAPIConfigRef;
+    onError?: (error: Error, ctx: any) => any;
+    onNotFound?: (ctx: any) => any;
+}
+
+/**
+ * Client Generator Options
+ */
+interface ClientGeneratorOptions {
+    /** Include Zod schemas for client-side validation (default: true) */
+    includeValidation?: boolean;
+    /** Base URL for the API (default: '') */
+    baseUrl?: string;
+    /** Enable runtime validation by default (default: false) */
+    validateByDefault?: boolean;
+    /** Custom headers to include in all requests */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * Route information for client generation
+ */
+interface RouteInfo {
+    method: string;
+    path: string;
+    schema: RouteSchema;
+    /** Optional: store the Zod schema instance for type extraction */
+    zodSchemas?: {
+        body?: any;
+        query?: any;
+        params?: any;
+        response?: any;
+    };
+}
+/**
+ * Generate typed client code from routes
+ */
+declare function generateTypedClient(routes: RouteInfo[], options?: ClientGeneratorOptions): string;
+
+interface Plugin {
+    name: string;
+    version?: string;
+    install: (app: Kozo) => void | Promise<void>;
+}
+/**
+ * Kozo - High-performance TypeScript framework with Zod schemas
+ */
+declare class Kozo {
+    private app;
+    private services;
+    private routes;
+    constructor(config?: KozoConfig);
+    use(plugin: Plugin): this;
+    generateClient(baseUrl?: string): string;
+    generateClient(options?: ClientGeneratorOptions): string;
+    get<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
+    post<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
+    put<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
+    patch<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
+    delete<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
+    private register;
+    listen(port?: number): Promise<void>;
+    getApp(): Hono;
+    get fetch(): (request: Request, Env?: unknown, executionCtx?: hono.ExecutionContext) => Response | Promise<Response>;
+}
+declare function createKozo(config?: KozoConfig): Kozo;
+
+type UserHandler = (c: any) => any;
+type CompiledRoute = {
+    validateBody?: (data: any) => boolean;
+    validateQuery?: (data: any) => boolean;
+    validateParams?: (data: any) => boolean;
+    serialize?: (data: any) => string;
+    errors?: any;
+};
+declare class SchemaCompiler {
+    static compile(schema: RouteSchema): CompiledRoute;
+}
+declare function compileRouteHandler(userHandler: UserHandler, schema: RouteSchema, services: any, compiled: CompiledRoute): (c: Context) => any;
+
+export { type ClientGeneratorOptions, type CompiledRoute, Kozo, type KozoConfig, type KozoContext, type KozoHandler, type RouteInfo, type RouteSchema, SchemaCompiler, type Services, compileRouteHandler, createKozo, generateTypedClient };