@donkeylabs/server 0.3.1 → 0.4.0

package/package.json

@@ -1,13 +1,10 @@
 {
   "name": "@donkeylabs/server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
-  "bin": {
-    "donkeylabs-mcp": "./mcp/server.ts"
-  },
   "exports": {
     ".": {
       "types": "./src/index.ts",
@@ -27,11 +24,11 @@
     },
     "./context": {
       "types": "./context.d.ts"
-    }
+    },
+    "./docs/*": "./docs/*"
   },
   "files": [
     "src",
-    "mcp",
     "docs",
     "context.d.ts",
     "registry.d.ts",

package/src/generator/index.ts

@@ -312,30 +312,38 @@ export function generateClientFromRoutes(
 ): string {
   const opts = { ...defaultGeneratorOptions, ...options };
 
+  // Check if all routes share a common prefix (e.g., "api.") - if so, skip it
+  // Common prefix stripping is disabled to respect explicit router nesting
+  const routesToProcess = routes;
+
   // Group routes by namespace
   const tree = new Map<string, Map<string, { method: string; fullName: string }[]>>();
 
-  for (const route of routes) {
+  for (const route of routesToProcess) {
+    // Find original route name for the actual request
+    const originalRoute = routes.find(r => r.name.endsWith(route.name));
+    const fullName = originalRoute?.name || route.name;
+
     const parts = route.name.split(".");
     if (parts.length < 2) {
       const ns = "";
       if (!tree.has(ns)) tree.set(ns, new Map());
       const rootMethods = tree.get(ns)!;
       if (!rootMethods.has("")) rootMethods.set("", []);
-      rootMethods.get("")!.push({ method: parts[0]!, fullName: route.name });
+      rootMethods.get("")!.push({ method: parts[0]!, fullName });
     } else if (parts.length === 2) {
       const [ns, method] = parts;
       if (!tree.has(ns!)) tree.set(ns!, new Map());
       const nsMethods = tree.get(ns!)!;
       if (!nsMethods.has("")) nsMethods.set("", []);
-      nsMethods.get("")!.push({ method: method!, fullName: route.name });
+      nsMethods.get("")!.push({ method: method!, fullName });
     } else {
       const [ns, sub, ...rest] = parts;
       const method = rest.join(".");
       if (!tree.has(ns!)) tree.set(ns!, new Map());
       const nsMethods = tree.get(ns!)!;
       if (!nsMethods.has(sub!)) nsMethods.set(sub!, []);
-      nsMethods.get(sub!)!.push({ method: method || sub!, fullName: route.name });
+      nsMethods.get(sub!)!.push({ method: method || sub!, fullName });
     }
   }
 
@@ -435,8 +443,12 @@ export function generateClientCode(
       .map((r) => {
         const inputType = zodToTypeScript(r.inputSource);
         const outputType = zodToTypeScript(r.outputSource);
-        return `    export type ${toPascalCase(r.routeName)}Input = ${inputType};
-    export type ${toPascalCase(r.routeName)}Output = ${outputType};`;
+        const routeNs = toPascalCase(r.routeName);
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+      export type Output = ${outputType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
       });
 
     if (typeEntries.length > 0) {
@@ -448,8 +460,8 @@ ${typeEntries.join("\n\n")}
     const methodEntries = prefixRoutes
       .filter((r) => r.handler === "typed")
       .map((r) => {
-        const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}Input`;
-        const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}Output`;
+        const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
+        const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
         return `    ${toCamelCase(r.routeName)}: (input: ${inputType}, options?: RequestOptions): Promise<${outputType}> =>
       this.request("${r.name}", input, options)`;
       });
@@ -549,3 +561,6 @@ export function createApiClient(config: ApiClientConfig): ApiClient {
 export { ApiError, ValidationError, type RequestOptions, type SSEOptions };
 `;
 }
+
+// Re-export runtime Zod to TypeScript converter
+export { zodSchemaToTs } from "./zod-to-ts";

package/src/generator/zod-to-ts.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+
+/**
+ * Convert a Zod schema to TypeScript type string at runtime
+ * Uses Zod's internal _def to introspect the schema
+ */
+export function zodSchemaToTs(schema: z.ZodType<any>): string {
+  return convertZodType(schema);
+}
+
+function convertZodType(schema: z.ZodType<any>): string {
+  const def = (schema as any)._def;
+  const typeName = def?.typeName;
+
+  switch (typeName) {
+    case "ZodString":
+      return "string";
+
+    case "ZodNumber":
+      return "number";
+
+    case "ZodBoolean":
+      return "boolean";
+
+    case "ZodDate":
+      return "Date";
+
+    case "ZodUndefined":
+      return "undefined";
+
+    case "ZodNull":
+      return "null";
+
+    case "ZodAny":
+      return "any";
+
+    case "ZodUnknown":
+      return "unknown";
+
+    case "ZodVoid":
+      return "void";
+
+    case "ZodNever":
+      return "never";
+
+    case "ZodLiteral":
+      const value = def.value;
+      return typeof value === "string" ? `"${value}"` : String(value);
+
+    case "ZodArray":
+      const itemType = convertZodType(def.type);
+      return `${itemType}[]`;
+
+    case "ZodObject":
+      const shape = def.shape();
+      const props = Object.entries(shape).map(([key, value]) => {
+        const propSchema = value as z.ZodType<any>;
+        const isOptional = (propSchema as any)._def?.typeName === "ZodOptional";
+        const innerType = isOptional
+          ? convertZodType((propSchema as any)._def.innerType)
+          : convertZodType(propSchema);
+        return `  ${key}${isOptional ? "?" : ""}: ${innerType};`;
+      });
+      return `{\n${props.join("\n")}\n}`;
+
+    case "ZodOptional":
+      return convertZodType(def.innerType);
+
+    case "ZodNullable":
+      return `${convertZodType(def.innerType)} | null`;
+
+    case "ZodDefault":
+      return convertZodType(def.innerType);
+
+    case "ZodUnion":
+      const options = def.options.map((opt: z.ZodType<any>) => convertZodType(opt));
+      return options.join(" | ");
+
+    case "ZodEnum":
+      return def.values.map((v: string) => `"${v}"`).join(" | ");
+
+    case "ZodNativeEnum":
+      return "number | string"; // Simplified
+
+    case "ZodRecord":
+      const keyType = def.keyType ? convertZodType(def.keyType) : "string";
+      const valueType = convertZodType(def.valueType);
+      return `Record<${keyType}, ${valueType}>`;
+
+    case "ZodTuple":
+      const items = def.items.map((item: z.ZodType<any>) => convertZodType(item));
+      return `[${items.join(", ")}]`;
+
+    case "ZodPromise":
+      return `Promise<${convertZodType(def.type)}>`;
+
+    case "ZodEffects":
+      // .transform(), .refine(), etc - use the inner schema
+      return convertZodType(def.schema);
+
+    case "ZodLazy":
+      // Lazy schemas - try to resolve
+      return convertZodType(def.getter());
+
+    case "ZodIntersection":
+      const left = convertZodType(def.left);
+      const right = convertZodType(def.right);
+      return `${left} & ${right}`;
+
+    default:
+      // Fallback for unknown types
+      return "unknown";
+  }
+}

package/src/index.ts

@@ -4,7 +4,17 @@
 export { AppServer, type ServerConfig } from "./server";
 
 // Router
-export { createRouter, type Router, type RouteBuilder, type ServerContext, type IRouter, type IRouteBuilder, type IMiddlewareBuilder } from "./router";
+export {
+  createRouter,
+  defineRoute,
+  type Router,
+  type RouteBuilder,
+  type ServerContext,
+  type IRouter,
+  type IRouteBuilder,
+  type IMiddlewareBuilder,
+  type TypedRouteConfig,
+} from "./router";
 
 // Handlers
 export {

package/src/router.ts

@@ -36,10 +36,18 @@ export type RouteDefinition<
     : HandlerRegistry[T]["__signature"];
 };
 
+export interface HandlerClass<I = any, O = any> {
+  new (ctx: ServerContext): { handle(input: I): Promise<O> | O };
+}
+
+function isHandlerClass(fn: any): fn is HandlerClass {
+  return typeof fn === 'function' && fn.prototype && typeof fn.prototype.handle === 'function';
+}
+
 export interface TypedRouteConfig<I = any, O = any> {
   input?: z.ZodType<I>;
   output?: z.ZodType<O>;
-  handle: (input: I, ctx: ServerContext) => Promise<O> | O;
+  handle: ((input: I, ctx: ServerContext) => Promise<O> | O) | HandlerClass<I, O>;
 }
 
 export interface RouteMetadata {
@@ -69,6 +77,10 @@ export class RouteBuilder<TRouter extends Router> implements IRouteBuilderBase<T
   ) {}
 
   typed<I, O>(config: TypedRouteConfig<I, O>): TRouter {
+    if (isHandlerClass(config.handle)) {
+        const HandlerClass = config.handle;
+        config.handle = (input, ctx) => new HandlerClass(ctx).handle(input);
+    }
     return this.router.addRoute(this.name, "typed", config, this._middleware);
   }
 
@@ -156,6 +168,23 @@ export class Router implements IRouter {
     }));
   }
 
+  /** Get route metadata with TypeScript type strings for code generation */
+  getTypedMetadata(): Array<{
+    name: string;
+    handler: string;
+    inputType?: string;
+    outputType?: string;
+  }> {
+    // Dynamic import to avoid circular deps
+    const { zodSchemaToTs } = require("./generator/zod-to-ts");
+    return this.getRoutes().map(route => ({
+      name: route.name,
+      handler: route.handler,
+      inputType: route.input ? zodSchemaToTs(route.input) : undefined,
+      outputType: route.output ? zodSchemaToTs(route.output) : undefined,
+    }));
+  }
+
   getPrefix(): string {
     return this.prefix;
   }
@@ -177,3 +206,20 @@ function createMiddlewareBuilderProxy<TRouter extends Router>(router: TRouter):
 }
 
 export const createRouter = (prefix?: string): IRouter => new Router(prefix);
+
+/**
+ * Define a route with type inference for input/output schemas.
+ *
+ * @example
+ * export const myRoute = defineRoute({
+ *   input: z.object({ name: z.string() }),
+ *   output: z.object({ greeting: z.string() }),
+ *   handle: async ({ name }, ctx) => {
+ *     return { greeting: `Hello ${name}` };
+ *   }
+ * });
+ */
+export function defineRoute<I, O>(config: TypedRouteConfig<I, O>): TypedRouteConfig<I, O> {
+  return config;
+}
+

package/src/server.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import { PluginManager, type CoreServices, type ConfiguredPlugin } from "./core";
 import { type IRouter, type RouteDefinition, type ServerContext } from "./router";
 import { Handlers } from "./handlers";
@@ -23,11 +25,29 @@ import {
   type RateLimiterConfig,
   type ErrorsConfig,
 } from "./core/index";
+import { zodSchemaToTs } from "./generator/zod-to-ts";
+
+export interface TypeGenerationConfig {
+  /** Output path for generated client types (e.g., "./src/lib/api.ts") */
+  output: string;
+  /** Custom base import for the client */
+  baseImport?: string;
+  /** Custom base class name */
+  baseClass?: string;
+  /** Constructor signature (e.g., "baseUrl: string, options?: ApiClientOptions") */
+  constructorSignature?: string;
+  /** Constructor body (e.g., "super(baseUrl, options);") */
+  constructorBody?: string;
+  /** Factory function code (optional, replaces default createApi) */
+  factoryFunction?: string;
+}
 
 export interface ServerConfig {
   port?: number;
   db: CoreServices["db"];
   config?: Record<string, any>;
+  /** Auto-generate client types on startup in dev mode */
+  generateTypes?: TypeGenerationConfig;
   // Core service configurations
   logger?: LoggerConfig;
   cache?: CacheConfig;
@@ -45,6 +65,7 @@ export class AppServer {
   private routers: IRouter[] = [];
   private routeMap: Map<string, RouteDefinition> = new Map();
   private coreServices: CoreServices;
+  private typeGenConfig?: TypeGenerationConfig;
 
   constructor(options: ServerConfig) {
     this.port = options.port ?? 3000;
@@ -73,6 +94,7 @@ export class AppServer {
     };
 
     this.manager = new PluginManager(this.coreServices);
+    this.typeGenConfig = options.generateTypes;
   }
 
   /**
@@ -169,6 +191,247 @@ export class AppServer {
     return this.routeMap.has(routeName);
   }
 
+  /**
+   * Generate client types from registered routes.
+   * Called automatically on startup in dev mode if generateTypes config is provided.
+   */
+  private async generateTypes(): Promise<void> {
+    if (!this.typeGenConfig) return;
+
+    const { logger } = this.coreServices;
+    const isDev = process.env.NODE_ENV !== "production";
+
+    if (!isDev) {
+      logger.debug("Skipping type generation in production mode");
+      return;
+    }
+
+    // Collect all route metadata
+    const routes: Array<{
+      name: string;
+      prefix: string;
+      routeName: string;
+      handler: "typed" | "raw";
+      inputSource?: string;
+      outputSource?: string;
+    }> = [];
+
+    for (const router of this.routers) {
+      for (const route of router.getRoutes()) {
+        const parts = route.name.split(".");
+        const routeName = parts[parts.length - 1] || route.name;
+        const prefix = parts.slice(0, -1).join(".");
+
+        routes.push({
+          name: route.name,
+          prefix,
+          routeName,
+          handler: (route.handler || "typed") as "typed" | "raw",
+          inputSource: route.input ? zodSchemaToTs(route.input) : undefined,
+          outputSource: route.output ? zodSchemaToTs(route.output) : undefined,
+        });
+      }
+    }
+
+    // Generate the client code
+    const code = this.generateClientCode(routes);
+
+    // Write to output file
+    const outputDir = dirname(this.typeGenConfig.output);
+    await mkdir(outputDir, { recursive: true });
+    await writeFile(this.typeGenConfig.output, code);
+
+    logger.info(`Generated API client types`, { output: this.typeGenConfig.output, routes: routes.length });
+  }
+
+  /**
+   * Generate client code from route metadata.
+   */
+  private generateClientCode(
+    routes: Array<{
+      name: string;
+      prefix: string;
+      routeName: string;
+      handler: "typed" | "raw";
+      inputSource?: string;
+      outputSource?: string;
+    }>
+  ): string {
+    const baseImport =
+      this.typeGenConfig?.baseImport ??
+      'import { UnifiedApiClientBase, type ClientOptions } from "@donkeylabs/adapter-sveltekit/client";';
+    const baseClass = this.typeGenConfig?.baseClass ?? "UnifiedApiClientBase";
+    const constructorSignature =
+      this.typeGenConfig?.constructorSignature ?? "options?: ClientOptions";
+    const constructorBody =
+      this.typeGenConfig?.constructorBody ?? "super(options);";
+    const defaultFactory = `/**
+ * Create an API client instance
+ */
+export function createApi(options?: ClientOptions) {
+  return new ApiClient(options);
+}`;
+    const factoryFunction = this.typeGenConfig?.factoryFunction ?? defaultFactory;
+
+    // Helper functions
+    const toPascalCase = (str: string): string =>
+      str
+        .split(/[._-]/)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join("");
+
+    const toCamelCase = (str: string): string => {
+      const pascal = toPascalCase(str);
+      return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    };
+
+    // Common prefix stripping is disabled to respect explicit router nesting (e.g. api.health)
+    const routesToProcess = routes;
+    const commonPrefix = "";
+
+    // Build recursive tree for nested routes
+    type RouteNode = {
+      children: Map<string, RouteNode>;
+      routes: typeof routes;
+    };
+    const rootNode: RouteNode = { children: new Map(), routes: [] };
+
+    for (const route of routesToProcess) {
+      const parts = route.name.split(".");
+      let currentNode = rootNode;
+      // Navigate/Build tree
+      for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i]!;
+        if (!currentNode.children.has(part)) {
+          currentNode.children.set(part, { children: new Map(), routes: [] });
+        }
+        currentNode = currentNode.children.get(part)!;
+      }
+      // Add route to the leaf node (last part is the method name)
+      currentNode.routes.push({
+        ...route,
+        routeName: parts[parts.length - 1]! // precise method name
+      });
+    }
+
+    // Recursive function to generate Type definitions
+    function generateTypeBlock(node: RouteNode, indent: string): string {
+      const blocks: string[] = [];
+      
+      // 1. Valid Input/Output types for routes at this level
+      if (node.routes.length > 0) {
+        const routeTypes = node.routes.map(r => {
+           if (r.handler !== "typed") return "";
+           const routeNs = toPascalCase(r.routeName);
+           const inputType = r.inputSource ?? "Record<string, never>";
+           const outputType = r.outputSource ?? "unknown";
+           return `${indent}export namespace ${routeNs} {
+${indent}  export type Input = Expand<${inputType}>;
+${indent}  export type Output = Expand<${outputType}>;
+${indent}}
+${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
+        }).filter(Boolean);
+        if (routeTypes.length) blocks.push(routeTypes.join("\n\n"));
+      }
+
+      // 2. Nested namespaces
+      for (const [name, child] of node.children) {
+        const nsName = toPascalCase(name);
+        blocks.push(`${indent}export namespace ${nsName} {\n${generateTypeBlock(child, indent + "  ")}\n${indent}}`);
+      }
+      return blocks.join("\n\n");
+    }
+
+    // Recursive function to generate Client Methods
+    function generateMethodBlock(node: RouteNode, indent: string, parentPath: string, isTopLevel: boolean): string {
+      const blocks: string[] = [];
+
+      // 1. Methods at this level
+      const methods = node.routes.map(r => {
+         const methodName = toCamelCase(r.routeName);
+         // r.name is the full path e.g. "api.v1.users.get"
+         
+         if (r.handler === "typed") {
+            const pathParts = r.name.split(".");
+            const typePath = ["Routes", ...pathParts.slice(0, -1).map(toPascalCase), toPascalCase(r.routeName)];
+            const inputType = typePath.join(".") + ".Input";
+            const outputType = typePath.join(".") + ".Output";
+            
+            return `${indent}${methodName}: (input: ${inputType}): Promise<${outputType}> => this.request("${r.name}", input)`;
+         } else {
+            return `${indent}${methodName}: (init?: RequestInit): Promise<Response> => this.rawRequest("${r.name}", init)`;
+         }
+      });
+      if (methods.length) blocks.push(methods.join(",\n"));
+
+      // 2. Nested Objects
+      for (const [name, child] of node.children) {
+         const camelName = toCamelCase(name); 
+         const separator = isTopLevel ? " = " : ": ";
+         const terminator = isTopLevel ? ";" : "";
+         // For top level, we output `name = { ... };` 
+         // For nested, we output `name: { ... }` (comma handled by join)
+         
+         blocks.push(`${indent}${camelName}${separator}{\n${generateMethodBlock(child, indent + "  ", "", false)}\n${indent}}${terminator}`);
+      }
+      // Top level blocks are separated by nothing (class members). Nested by comma.
+      // Wait, blocks.join needs care.
+      // If isTopLevel, join with "\n\n". If nested, join with ",\n".
+      return blocks.join(isTopLevel ? "\n\n" : ",\n");
+    }
+
+    const typeBlocks: string[] = [generateTypeBlock(rootNode, "  ")];
+    // rootNode children are top-level namespaces (api, health) -> Top Level Class Properties
+    const methodBlocks: string[] = [generateMethodBlock(rootNode, "  ", "", true)];
+
+    return `// Auto-generated by @donkeylabs/server
+// DO NOT EDIT MANUALLY
+
+${baseImport}
+
+// Utility type that forces TypeScript to expand types on hover
+type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
+
+/**
+ * Handler interface for implementing route handlers in model classes.
+ * @example
+ * class CounterModel implements Handler<Routes.Counter.get> {
+ *   handle(input: Routes.Counter.get.Input): Routes.Counter.get.Output {
+ *     return { count: 0 };
+ *   }
+ * }
+ */
+export interface Handler<T extends { Input: any; Output: any }> {
+  handle(input: T["Input"]): T["Output"] | Promise<T["Output"]>;
+}
+
+// Re-export server context for model classes
+export { type ServerContext as AppContext } from "@donkeylabs/server";
+
+// ============================================
+// Route Types
+// ============================================
+
+export namespace Routes {
+${typeBlocks.join("\n\n") || "  // No typed routes found"}
+}
+
+// ============================================
+// API Client
+// ============================================
+
+export class ApiClient extends ${baseClass} {
+  constructor(${constructorSignature}) {
+    ${constructorBody}
+  }
+
+${methodBlocks.join("\n\n") || "  // No routes defined"}
+}
+
+${factoryFunction}
+`;
+  }
+
   /**
    * Initialize server without starting HTTP server.
    * Used by adapters (e.g., SvelteKit) that manage their own HTTP server.
@@ -176,6 +439,9 @@ export class AppServer {
   async initialize(): Promise<void> {
     const { logger } = this.coreServices;
 
+    // Auto-generate types in dev mode if configured
+    await this.generateTypes();
+
     await this.manager.migrate();
     await this.manager.init();
 
@@ -387,6 +653,9 @@ export class AppServer {
   async start() {
     const { logger } = this.coreServices;
 
+    // Auto-generate types in dev mode if configured
+    await this.generateTypes();
+
     // 1. Run migrations
     await this.manager.migrate();