@donkeylabs/server 0.3.0 → 0.4.0

package/src/handlers.ts

@@ -1,101 +1,6 @@
 import type { RouteDefinition, ServerContext } from "./router";
 import { z } from "zod";
 
-// ============================================
-// Route and Handler Types for DX
-// ============================================
-
-/**
- * Route contract interface - generated routes export this shape
- */
-export interface RouteContract {
-  input: any;
-  output: any;
-}
-
-/**
- * Handler interface for model classes.
- *
- * @example
- * import type { Handler } from "@donkeylabs/server";
- * import type { Health } from "$server/routes";
- *
- * export class PingModel implements Handler<Health.Ping> {
- *   handle(input: Health.Ping.Input): Health.Ping.Output {
- *     return { status: "ok", timestamp: new Date().toISOString() };
- *   }
- * }
- */
-export interface Handler<T extends RouteContract> {
-  handle(input: T["input"]): T["output"] | Promise<T["output"]>;
-}
-
-/**
- * Typed route definition.
- * Use with generated route types: `const route: Route<Health.Ping> = { ... }`
- *
- * @example
- * import { Health } from ".@donkeylabs/server/routes";
- * import type { Route } from "@donkeylabs/server";
- *
- * export const pingRoute: Route<Health.Ping> = {
- *   input: Health.Ping.Input,
- *   output: Health.Ping.Output,
- *   handle: async (input, ctx) => new PingModel(ctx).handle(input),
- * };
- */
-export interface Route<T extends RouteContract> {
-  input: z.ZodType<T["input"]>;
-  output: z.ZodType<T["output"]>;
-  handle: (input: T["input"], ctx: ServerContext) => T["output"] | Promise<T["output"]>;
-}
-
-/**
- * Route configuration with inferred types from zod schemas.
- */
-export interface TypedRouteConfig<TInput, TOutput> {
-  input: z.ZodType<TInput>;
-  output: z.ZodType<TOutput>;
-  handle: (input: TInput, ctx: ServerContext) => TOutput | Promise<TOutput>;
-}
-
-export interface RawRouteConfig {
-  handle: (req: Request, ctx: ServerContext) => Response | Promise<Response>;
-}
-
-/**
- * Create a typed route with full type inference from zod schemas.
- *
- * @example
- * export const pingRoute = createRoute.typed({
- *   input: z.object({ echo: z.string().optional() }),
- *   output: z.object({ status: z.literal("ok"), timestamp: z.string() }),
- *   handle: async (input, ctx) => ({
- *     status: "ok",
- *     timestamp: new Date().toISOString(),
- *   }),
- * });
- */
-export const createRoute = {
-  typed<TInput, TOutput>(config: TypedRouteConfig<TInput, TOutput>) {
-    return {
-      ...config,
-      _handler: "typed" as const,
-    };
-  },
-
-  raw(config: RawRouteConfig) {
-    return {
-      ...config,
-      _handler: "raw" as const,
-    };
-  },
-};
-
-// ============================================
-// Handler Runtimes
-// ============================================
-
 export interface HandlerRuntime<Fn extends Function = Function> {
   execute(
     req: Request,
@@ -133,39 +38,37 @@ export function createHandler<Fn extends Function>(
   };
 }
 
+// ==========================================
+// 1. Typed Handler (Default)
+// ==========================================
 export type TypedFn = (input: any, ctx: ServerContext) => Promise<any> | any;
 export type TypedHandler = HandlerRuntime<TypedFn>;
 
 export const TypedHandler: TypedHandler = {
   async execute(req, def, handle, ctx) {
-      if (req.method !== "POST") {
-        return new Response("Method Not Allowed", { status: 405 });
-      }
-
-      let body: unknown = {};
-      try {
-        body = await req.json();
-      } catch {
-        return Response.json({ error: "Invalid JSON" }, { status: 400 });
-      }
+      if (req.method !== "POST") return new Response("Method Not Allowed", { status: 405 });
+      let body: any = {};
+      try { body = await req.json(); } catch(e) { return Response.json({error: "Invalid JSON"}, {status:400}); }
 
       try {
         const input = def.input ? def.input.parse(body) : body;
         const result = await handle(input, ctx);
         const output = def.output ? def.output.parse(result) : result;
         return Response.json(output);
-      } catch (e) {
+      } catch (e: any) {
          console.error(e);
          if (e instanceof z.ZodError) {
              return Response.json({ error: "Validation Failed", details: e.issues }, { status: 400 });
          }
-         const message = e instanceof Error ? e.message : "Internal Error";
-         return Response.json({ error: message }, { status: 500 });
+         return Response.json({ error: e.message || "Internal Error" }, { status: 500 });
       }
   },
   __signature: undefined as unknown as TypedFn
-};
+}
 
+// ==========================================
+// 2. Raw Handler
+// ==========================================
 export type RawFn = (req: Request, ctx: ServerContext) => Promise<Response> | Response;
 export type RawHandler = HandlerRuntime<RawFn>;
 
@@ -174,9 +77,10 @@ export const RawHandler: RawHandler = {
      return await handle(req, ctx);
   },
   __signature: undefined as unknown as RawFn
-};
+}
 
 export const Handlers = {
     typed: TypedHandler,
     raw: RawHandler
 };
+

package/src/index.ts

@@ -1,21 +1,32 @@
 // @donkeylabs/server - Main exports
 
 // Server
-export { AppServer, type ServerConfig, type ServerInspection } from "./server";
+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 and Route types
+// Handlers
 export {
   createHandler,
-  createRoute,
   TypedHandler,
   RawHandler,
-  type Handler,
+  Handlers,
   type HandlerRuntime,
-  type Route,
-  type RouteContract,
+  type TypedFn,
+  type TypedHandler as TypedHandlerType,
+  type RawFn,
+  type RawHandler as RawHandlerType,
 } from "./handlers";
 
 // Core Plugin System
@@ -40,29 +51,24 @@ export {
 export { createMiddleware } from "./middleware";
 
 // Config helper
-export function defineConfig(config: {
+export interface DonkeylabsConfig {
+  /** Glob patterns for plugin files */
   plugins: string[];
+  /** Output directory for generated types */
   outDir: string;
+  /** Server entry file for route extraction */
+  entry?: string;
+  /** Route files pattern */
   routes?: string;
+  /** Client generation options */
   client?: { output: string };
-}) {
+  /** Adapter package for framework-specific generation (e.g., "@donkeylabs/adapter-sveltekit") */
+  adapter?: string;
+}
+
+export function defineConfig(config: DonkeylabsConfig): DonkeylabsConfig {
   return config;
 }
 
 // Re-export HttpError for custom error creation
 export { HttpError } from "./core/errors";
-
-// Re-export SSE types for channel configuration
-export { type SSEChannelConfig } from "./core/sse";
-
-// Re-export Rate Limiter types for rule configuration
-export { type RateLimitRule, type RateLimitResult } from "./core/rate-limiter";
-
-// Re-export Job types for job registration
-export { type JobDefinition, type RegisteredJob } from "./core/jobs";
-
-// Re-export Cron types for cron task registration
-export { type CronTaskDefinition, type CronTask } from "./core/cron";
-
-// Re-export Cache types for namespacing
-export { type NamespacedCache } from "./core/cache";

package/src/middleware.ts

@@ -3,8 +3,7 @@ import type { ServerContext } from "./router";
 // The next function - calls the next middleware or handler
 export type NextFn = () => Promise<Response>;
 
-// Middleware function signature
-// ctx is ServerContext (request-time context with db, plugins, etc.)
+// Middleware function signature (what plugins implement)
 export type MiddlewareFn<TConfig = void> = (
   req: Request,
   ctx: ServerContext,
@@ -18,9 +17,7 @@ export interface MiddlewareRuntime<TConfig = void> {
   readonly __config: TConfig; // Phantom type for config inference
 }
 
-// Factory to create middleware
-// Note: For typed plugin access, use the middleware function pattern in createPlugin.define()
-// which gives you PluginContext in the closure
+// Factory to create middleware (mirrors createHandler pattern)
 export function createMiddleware<TConfig = void>(
   execute: MiddlewareFn<TConfig>
 ): MiddlewareRuntime<TConfig> {

package/src/registry.ts

@@ -0,0 +1,4 @@
+// Runtime registry - placeholder for user projects
+// This file is re-generated by `donkeylabs generate` in user projects
+// to register custom handlers and middleware at runtime.
+/// <reference path="../registry.d.ts" />

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;
+}
+