@donkeylabs/server 0.3.0 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 DonkeyLabs
+Copyright (c) 2025 DonkeyLabs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/docs/api-client.md

@@ -9,7 +9,7 @@ Code-generated, fully-typed API client for consuming routes with TypeScript. Sup
 // bun run gen:client server.ts
 
 // Import and use
-import { createApiClient } from "@donkeylabs/server/client";
+import { createApiClient } from "./client";
 
 const api = createApiClient({ baseUrl: "http://localhost:3000" });
 
@@ -159,14 +159,14 @@ const blob = await response.blob();
 ## Error Handling
 
 ```ts
-import { ApiError, ValidationError } from "@donkeylabs/server/client";
+import { ApiError, ValidationError } from "./client";
 
 try {
   const user = await api.users.create({ email: "invalid" });
 } catch (error) {
   if (error instanceof ValidationError) {
     // Zod validation failed (400)
-    console.log("Validation errors:", error.validationDetails);
+    console.log("Validation errors:", error.details);
     // [{ path: ["email"], message: "Invalid email" }]
   } else if (error instanceof ApiError) {
     // HTTP error
@@ -324,7 +324,7 @@ The generator merges all plugin client configs to determine defaults.
 Works out of the box with native `fetch` and `EventSource`:
 
 ```ts
-import { createApiClient } from "@donkeylabs/server/client";
+import { createApiClient } from "./client";
 const api = createApiClient({ baseUrl: "http://localhost:3000" });
 ```
 
@@ -333,7 +333,7 @@ const api = createApiClient({ baseUrl: "http://localhost:3000" });
 Native fetch is available in Bun and Node.js 18+:
 
 ```ts
-import { createApiClient } from "@donkeylabs/server/client";
+import { createApiClient } from "./client";
 
 const api = createApiClient({
   baseUrl: "http://localhost:3000",
@@ -355,7 +355,7 @@ api.connect();
 ## Complete Example
 
 ```ts
-import { createApiClient, ApiError, ValidationError } from "@donkeylabs/server/client";
+import { createApiClient, ApiError, ValidationError } from "./client";
 
 // Create client
 const api = createApiClient({ baseUrl: "http://localhost:3000" });
@@ -390,7 +390,7 @@ async function main() {
 
   } catch (error) {
     if (error instanceof ValidationError) {
-      console.error("Validation failed:", error.validationDetails);
+      console.error("Validation failed:", error.details);
     } else if (error instanceof ApiError) {
       console.error(`API error ${error.status}:`, error.body);
     } else {

package/docs/cache.md

@@ -30,19 +30,6 @@ interface Cache {
   clear(): Promise<void>;
   keys(pattern?: string): Promise<string[]>;
   getOrSet<T>(key: string, factory: () => Promise<T>, ttlMs?: number): Promise<T>;
-  namespace(prefix: string): NamespacedCache;
-}
-
-interface NamespacedCache {
-  readonly prefix: string;
-  get<T>(key: string): Promise<T | null>;
-  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
-  delete(key: string): Promise<boolean>;
-  has(key: string): Promise<boolean>;
-  clear(): Promise<void>;
-  keys(pattern?: string): Promise<string[]>;
-  getOrSet<T>(key: string, factory: () => Promise<T>, ttlMs?: number): Promise<T>;
-  clearNamespace(): Promise<void>;  // Clear only keys in this namespace
 }
 ```
 
@@ -57,7 +44,6 @@ interface NamespacedCache {
 | `clear()` | Remove all keys |
 | `keys(pattern?)` | List keys matching glob pattern |
 | `getOrSet(key, factory, ttl?)` | Get existing or compute and cache |
-| `namespace(prefix)` | Create namespaced cache with auto-prefixed keys |
 
 ---
 
@@ -185,65 +171,6 @@ const allKeys = await cache.keys();
 
 ---
 
-## Namespaced Cache
-
-Create isolated cache namespaces for plugins or features:
-
-```ts
-// Create namespaced caches
-const authCache = cache.namespace("auth");
-const userCache = cache.namespace("users");
-
-// Keys are automatically prefixed
-await authCache.set("token:123", { userId: 1 });  // Stored as "auth:token:123"
-await userCache.set("profile:1", { name: "Alice" });  // Stored as "users:profile:1"
-
-// Each namespace is isolated
-await authCache.get("token:123");  // Returns token
-await userCache.get("token:123");  // Returns null (different namespace)
-```
-
-### Plugin Cache (Recommended)
-
-Plugins get an auto-namespaced cache via `ctx.cache`:
-
-```ts
-service: async (ctx) => {
-  // ctx.cache is automatically namespaced with plugin name
-  const cache = ctx.cache;  // prefix: "pluginName:"
-
-  return {
-    async getUser(id: number) {
-      return cache.getOrSet(`user:${id}`, async () => {
-        return ctx.db.selectFrom("users").where("id", "=", id).executeTakeFirst();
-      }, 60000);
-    },
-  };
-};
-```
-
-### Clear Namespace
-
-Clear all keys in a namespace without affecting other namespaces:
-
-```ts
-const sessionCache = cache.namespace("sessions");
-
-// Store many sessions
-await sessionCache.set("user:1", session1);
-await sessionCache.set("user:2", session2);
-await sessionCache.set("user:3", session3);
-
-// Clear only session cache, leave other caches intact
-await sessionCache.clearNamespace();
-
-// Verify
-await sessionCache.keys();  // []
-await cache.keys("users:*");  // Still has user data
-```
-
----
-
 ## Real-World Examples
 
 ### User Session Caching
@@ -398,7 +325,7 @@ interface CacheAdapter {
 ### Redis Adapter Example
 
 ```ts
-import { createCache, type CacheAdapter } from "@donkeylabs/server";
+import { createCache, type CacheAdapter } from "./core/cache";
 import Redis from "ioredis";
 
 class RedisCacheAdapter implements CacheAdapter {

package/docs/core-services.md

@@ -112,7 +112,7 @@ interface CoreServices {
 Configure services when creating the server:
 
 ```ts
-import { AppServer } from "@donkeylabs/server";
+import { AppServer } from "./server";
 
 const server = new AppServer({
   db: database,
@@ -126,7 +126,7 @@ const server = new AppServer({
 
   cache: {
     defaultTtlMs: 300000,  // 5 minutes
-    maxSize: 1000,         // LRU max items (default: 1000)
+    maxSize: 10000,        // LRU max items
   },
 
   events: {
@@ -156,118 +156,6 @@ const server = new AppServer({
 
 ---
 
-## Server Introspection
-
-Get a complete overview of your server's configuration with `server.inspect()`:
-
-```ts
-const info = server.inspect();
-
-console.log(info);
-// {
-//   port: 3000,
-//   plugins: [
-//     { name: "auth", hasMigrations: true, dependencies: [] },
-//     { name: "notifications", hasMigrations: false, dependencies: ["auth"] },
-//   ],
-//   routes: [
-//     { name: "api.auth.login", handler: "typed" },
-//     { name: "api.users.list", handler: "typed" },
-//   ],
-//   handlers: ["typed", "raw", "xml"],
-//   events: ["user.created", "user.updated", "order.paid"],
-//   sseChannels: ["notifications", "dashboard", "user:*"],
-//   jobs: [
-//     { name: "sendEmail", pluginName: "notifications", description: "Send email" },
-//   ],
-//   cronTasks: [
-//     { name: "daily-cleanup", pluginName: "maintenance", expression: "0 0 * * *" },
-//   ],
-//   rateLimitRules: [
-//     { pattern: "auth.login", limit: 5, window: "15m" },
-//     { pattern: "api.*", limit: 100, window: "1m" },
-//   ],
-// }
-```
-
-### ServerInspection Interface
-
-```ts
-interface ServerInspection {
-  port: number;
-  plugins: Array<{
-    name: string;
-    hasMigrations: boolean;
-    dependencies: string[];
-  }>;
-  routes: Array<{
-    name: string;
-    handler: string;
-  }>;
-  handlers: string[];
-  events: string[];
-  sseChannels: string[];
-  jobs: Array<{
-    name: string;
-    pluginName?: string;
-    description?: string;
-  }>;
-  cronTasks: Array<{
-    name: string;
-    pluginName?: string;
-    expression: string;
-    description?: string;
-    enabled: boolean;
-  }>;
-  rateLimitRules: Array<{
-    pattern: string;
-    limit: number;
-    window: string | number;
-  }>;
-}
-```
-
-### Use Cases
-
-**Debug Route:** Expose server info for debugging:
-
-```ts
-router.route("admin.debug").typed({
-  handle: async (input, ctx) => {
-    // Only in development
-    if (process.env.NODE_ENV === "production") {
-      throw ctx.errors.NotFound();
-    }
-    return server.inspect();
-  },
-});
-```
-
-**Documentation Generation:** Generate API docs from inspection:
-
-```ts
-const info = server.inspect();
-const markdown = generateDocs(info.routes, info.events);
-```
-
-**Health Checks:** Include server stats in health endpoints:
-
-```ts
-router.route("health").typed({
-  handle: async (input, ctx) => {
-    const info = server.inspect();
-    return {
-      status: "healthy",
-      plugins: info.plugins.length,
-      routes: info.routes.length,
-      uptime: process.uptime(),
-    };
-  },
-});
-```
-
----
-
 ## Service Lifecycle
 
 ### Startup
@@ -406,7 +294,7 @@ router.route("upload").typed({
 The test harness automatically creates all core services:
 
 ```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "./harness";
 
 const { core } = await createTestHarness(myPlugin);
 
@@ -428,7 +316,7 @@ core.cron.start();
 Each service supports custom adapters for different backends:
 
 ```ts
-import { createCache, type CacheAdapter } from "@donkeylabs/server";
+import { createCache, type CacheAdapter } from "./core/cache";
 
 // Implement custom adapter (e.g., Redis)
 class RedisCacheAdapter implements CacheAdapter {

package/docs/cron.md

@@ -359,7 +359,7 @@ ctx.core.cron.schedule("0 * * * *", async () => {
 ## Testing Cron Tasks
 
 ```ts
-import { createCron } from "@donkeylabs/server";
+import { createCron } from "./core/cron";
 
 describe("Cron Tasks", () => {
   it("should execute task on trigger", async () => {

package/docs/errors.md

@@ -164,7 +164,7 @@ declare module "../core/errors" {
 For Zod validation failures, use `createValidationError`:
 
 ```ts
-import { createValidationError } from "@donkeylabs/server";
+import { createValidationError } from "./core/errors";
 
 // Convert Zod errors to HTTP error
 const result = schema.safeParse(data);
@@ -193,7 +193,7 @@ Response format:
 The API client provides typed error handling:
 
 ```ts
-import { createApiClient, ApiError, ValidationError, ErrorCodes } from "@donkeylabs/server/client";
+import { createApiClient, ApiError, ValidationError, ErrorCodes } from "./client";
 
 const api = createApiClient("http://localhost:3000");
 

package/docs/events.md

@@ -5,114 +5,23 @@ Asynchronous pub/sub event system with pattern matching, history tracking, and s
 ## Quick Start
 
 ```ts
-// Register events with schemas (required)
-ctx.core.events.register("user.created", z.object({
-  id: z.number(),
-  email: z.string().email(),
-}));
-
 // Subscribe to events
 ctx.core.events.on("user.created", async (user) => {
   console.log("New user:", user.email);
 });
 
-// Emit events (validates against schema)
+// Emit events
 await ctx.core.events.emit("user.created", { id: 1, email: "alice@example.com" });
 ```
 
 ---
 
-## Event Registration
-
-**Events must be registered before they can be emitted.** This ensures type safety and validates data at runtime.
-
-### Server-Level Registration
-
-```ts
-import { z } from "zod";
-
-const server = new AppServer({ db });
-
-// Register individual events
-server.registerEvent("user.created", z.object({
-  id: z.number(),
-  email: z.string().email(),
-}));
-
-server.registerEvent("order.paid", z.object({
-  orderId: z.string(),
-  amount: z.number(),
-  currency: z.string(),
-}));
-```
-
-### Bulk Registration
-
-```ts
-// Register multiple events at once
-ctx.core.events.registerMany({
-  "user.created": z.object({ id: z.number(), email: z.string() }),
-  "user.updated": z.object({ id: z.number(), changes: z.record(z.any()) }),
-  "user.deleted": z.object({ id: z.number() }),
-});
-```
-
-### Plugin Events
-
-Plugins can declare their events in the plugin definition:
-
-```ts
-export const ordersPlugin = createPlugin.define({
-  name: "orders",
-  events: {
-    "order.created": z.object({ id: z.string(), total: z.number() }),
-    "order.paid": z.object({ id: z.string(), paidAt: z.string() }),
-    "order.shipped": z.object({ id: z.string(), trackingNumber: z.string() }),
-  },
-  service: async (ctx) => ({ /* ... */ }),
-});
-```
-
-### Validation
-
-Emitting unregistered events or invalid data throws an error:
-
-```ts
-// Throws: Event 'unknown.event' is not registered
-await ctx.core.events.emit("unknown.event", { data: 1 });
-
-// Throws: Event 'user.created' validation failed
-await ctx.core.events.emit("user.created", { id: "not-a-number" });
-```
-
-### Introspection
-
-```ts
-// Check if event is registered
-if (ctx.core.events.isRegistered("user.created")) {
-  await ctx.core.events.emit("user.created", userData);
-}
-
-// List all registered events
-const events = ctx.core.events.listRegistered();
-// ["user.created", "user.updated", "order.paid", ...]
-```
-
----
-
 ## API Reference
 
 ### Interface
 
 ```ts
 interface Events {
-  // Registration (required before emitting)
-  register<T>(event: string, schema: z.ZodType<T>): void;
-  registerMany(schemas: Record<string, z.ZodType<any>>): void;
-  isRegistered(event: string): boolean;
-  listRegistered(): string[];
-
-  // Pub/Sub
   emit<T = any>(event: string, data: T): Promise<void>;
   on<T = any>(event: string, handler: EventHandler<T>): Subscription;
   once<T = any>(event: string, handler: EventHandler<T>): Subscription;
@@ -135,11 +44,7 @@ interface EventRecord {
 
 | Method | Description |
 |--------|-------------|
-| `register(event, schema)` | Register event with Zod schema (required before emit) |
-| `registerMany(schemas)` | Register multiple events at once |
-| `isRegistered(event)` | Check if event is registered |
-| `listRegistered()` | List all registered event names |
-| `emit(event, data)` | Emit event to all subscribers (validates against schema) |
+| `emit(event, data)` | Emit event to all subscribers |
 | `on(event, handler)` | Subscribe to event, returns subscription |
 | `once(event, handler)` | Subscribe to single occurrence |
 | `off(event, handler?)` | Unsubscribe handler or all handlers |
@@ -452,7 +357,7 @@ interface EventAdapter {
 ### Redis Pub/Sub Adapter
 
 ```ts
-import { createEvents, type EventAdapter } from "@donkeylabs/server";
+import { createEvents, type EventAdapter } from "./core/events";
 import Redis from "ioredis";
 
 class RedisEventAdapter implements EventAdapter {

package/docs/handlers.md

@@ -5,8 +5,8 @@ Request handlers define how routes process HTTP requests. Built-in handlers cove
 ## Quick Start
 
 ```ts
-import { createHandler } from "@donkeylabs/server";
-import type { ServerContext } from "@donkeylabs/server";
+import { createHandler } from "./handlers";
+import type { ServerContext } from "./router";
 
 // Define handler function signature
 type MyFn = (data: MyInput, ctx: ServerContext) => Promise<MyOutput>;
@@ -133,7 +133,7 @@ type EchoFn = (body: any, ctx: ServerContext) => Promise<{ echo: any }>;
 ### Step 2: Create Handler
 
 ```ts
-import { createHandler } from "@donkeylabs/server";
+import { createHandler } from "./handlers";
 
 export const EchoHandler = createHandler<EchoFn>(async (req, def, handle, ctx) => {
   // 1. Process the request
@@ -150,7 +150,7 @@ export const EchoHandler = createHandler<EchoFn>(async (req, def, handle, ctx) =
 ### Step 3: Register in Plugin
 
 ```ts
-import { createPlugin } from "@donkeylabs/server";
+import { createPlugin } from "./core";
 import { EchoHandler } from "./handlers/echo";
 
 export const echoPlugin = createPlugin.define({
@@ -188,7 +188,7 @@ router.route("test").echo({
 Accept and return XML:
 
 ```ts
-import { createHandler } from "@donkeylabs/server";
+import { createHandler } from "./handlers";
 import { parseXML, buildXML } from "./utils/xml";
 
 type XMLFn = (data: object, ctx: ServerContext) => Promise<object>;
@@ -404,53 +404,18 @@ TypedHandler returns structured validation errors:
 
 ---
 
-## Server-Level Handler Registration
-
-Register custom handlers directly on the server without creating a plugin:
-
-```ts
-import { AppServer, createHandler, type ServerContext } from "@donkeylabs/server";
-
-// Define custom handler
-type EchoFn = (body: any, ctx: ServerContext) => Promise<{ echo: any }>;
-const EchoHandler = createHandler<EchoFn>(async (req, def, handle, ctx) => {
-  const body = await req.json();
-  const result = await handle(body, ctx);
-  return Response.json(result);
-});
-
-// Register on server
-const server = new AppServer({ db, port: 3000 });
-server.registerHandler("echo", EchoHandler);
-
-// Use in routes
-router.route("test").echo({
-  handle: async (body, ctx) => ({ echo: body }),
-});
-```
-
-**Note:** For typed autocomplete on custom handlers registered this way, you'll need to manually extend the `HandlerRegistry` type or use plugin-based registration which auto-generates types.
-
----
-
 ## Handler Resolution
 
-The server resolves handlers at runtime in this order:
+The server resolves handlers at runtime:
 
-1. **Built-in handlers** (`typed`, `raw`)
-2. **User-registered handlers** (`server.registerHandler()`)
-3. **Plugin handlers** (`plugin.handlers`)
-
-When a route specifies a handler name, the server looks it up in this order until found:
+1. Route specifies handler name (e.g., `"typed"`, `"raw"`, `"echo"`)
+2. Server looks up handler in merged registry (built-in + plugin handlers)
+3. Handler's `execute()` method is called with request, definition, user handle, and context
 
 ```ts
-// Route specifies handler
-router.route("test").echo({ handle: ... });
-
-// Server resolves "echo" by checking:
-// 1. Handlers.echo (built-in) - not found
-// 2. customHandlers.get("echo") (user-registered) - found or not
-// 3. plugin.handlers.echo (from plugins) - found or not
+// In server.ts (simplified)
+const handler = handlers[route.handler];
+const response = await handler.execute(req, route, route.handle, ctx);
 ```
 
 ---
@@ -482,7 +447,7 @@ bun run gen:registry
 This generates `registry.d.ts` which augments `IRouteBuilder`:
 
 ```ts
-declare module "@donkeylabs/server" {
+declare module "./router" {
   interface IRouteBuilder<TRouter> {
     echo(config: { handle: EchoFn }): TRouter;
     // ... other handlers

package/docs/logger.md

@@ -47,36 +47,11 @@ const server = new AppServer({
   logger: {
     level: "info",       // Minimum level to log (default: "info")
     format: "pretty",    // "pretty" or "json" (default: "pretty")
-    timezone: "America/Chicago",  // Timezone for timestamps (optional)
     transports: [],      // Custom transports (optional)
   },
 });
 ```
 
-### Timezone Support
-
-Configure timezone for log timestamps:
-
-```ts
-const server = new AppServer({
-  db,
-  logger: {
-    timezone: "America/New_York",  // EST/EDT
-  },
-});
-// Output: [14:30:45.123 EST][INFO] Server started
-
-const server = new AppServer({
-  db,
-  logger: {
-    timezone: "UTC",
-  },
-});
-// Output: [19:30:45.123 UTC][INFO] Server started
-```
-
-Without timezone config, timestamps use local time.
-
 ---
 
 ## Usage Examples
@@ -131,29 +106,6 @@ service: async (ctx) => {
 };
 ```
 
-### Plugin Logger (Recommended)
-
-Plugins get an auto-namespaced logger via `ctx.logger`:
-
-```ts
-service: async (ctx) => {
-  // ctx.logger is automatically namespaced with { plugin: "pluginName" }
-  const logger = ctx.logger;
-
-  logger.info("Plugin initialized");
-  // Output: [14:30:45.123 CST][payments][INFO] Plugin initialized
-
-  return {
-    async process() {
-      logger.info("Processing request");
-      // Output: [14:30:45.456 CST][payments][INFO] Processing request
-    },
-  };
-};
-```
-
-This is cleaner than manually creating child loggers with plugin context.
-
 ### Request Logging Middleware
 
 ```ts
@@ -197,15 +149,8 @@ const requestLogger = createMiddleware(async (req, ctx, next) => {
 Human-readable colored output for development:
 
 ```
-[12:34:56.789][INFO] User logged in userId=123
-[12:34:56.790][ERROR] Payment failed orderId=456 error="Insufficient funds"
-```
-
-With plugin context and timezone:
-
-```
-[12:34:56.789 CST][payments][INFO] Payment processed route=api.checkout duration=45.23ms
-[12:34:56.790 CST][auth][WARN] Invalid token attempt ip=192.168.1.1
+[12:34:56.789] INFO  User logged in {"userId":123}
+[12:34:56.790] ERROR Payment failed {"orderId":456,"error":"Insufficient funds"}
 ```
 
 ### JSON Format
@@ -224,7 +169,7 @@ Structured JSON for production log aggregation:
 Create custom transports to send logs to external services:
 
 ```ts
-import { createLogger, type LogTransport, type LogEntry } from "@donkeylabs/server";
+import { createLogger, type LogTransport, type LogEntry } from "./core/logger";
 
 // Custom transport for external service
 class DatadogTransport implements LogTransport {