@donkeylabs/server 0.1.3 → 0.1.4

package/examples/starter/node_modules/@donkeylabs/server/src/handlers.ts

@@ -0,0 +1,87 @@
+import type { RouteDefinition, ServerContext } from "./router";
+import { z } from "zod";
+
+export interface HandlerRuntime<Fn extends Function = Function> {
+  execute(
+    req: Request,
+    def: RouteDefinition<any, any>,
+    userHandle: Fn,
+    ctx: ServerContext
+  ): Promise<Response>;
+
+  readonly __signature: Fn;  // Required for type inference
+}
+
+/**
+ * Factory function to create custom handlers without manual __signature.
+ *
+ * @example
+ * type EchoFn = (body: any, ctx: ServerContext) => Promise<{ echo: any }>;
+ *
+ * export const EchoHandler = createHandler<EchoFn>(async (req, def, handle, ctx) => {
+ *   const body = await req.json();
+ *   const result = await handle(body, ctx);
+ *   return Response.json(result);
+ * });
+ */
+export function createHandler<Fn extends Function>(
+  execute: (
+    req: Request,
+    def: RouteDefinition<any, any>,
+    handle: Fn,
+    ctx: ServerContext
+  ) => Promise<Response>
+): HandlerRuntime<Fn> {
+  return {
+    execute,
+    __signature: undefined as unknown as Fn
+  };
+}
+
+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 });
+      }
+
+      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) {
+         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 });
+      }
+  },
+  __signature: undefined as unknown as TypedFn
+};
+
+export type RawFn = (req: Request, ctx: ServerContext) => Promise<Response> | Response;
+export type RawHandler = HandlerRuntime<RawFn>;
+
+export const RawHandler: RawHandler = {
+  async execute(req, def, handle, ctx) {
+     return await handle(req, ctx);
+  },
+  __signature: undefined as unknown as RawFn
+};
+
+export const Handlers = {
+    typed: TypedHandler,
+    raw: RawHandler
+};

package/examples/starter/node_modules/@donkeylabs/server/src/harness.ts

@@ -0,0 +1,70 @@
+import { Kysely } from "kysely";
+import { BunSqliteDialect } from "kysely-bun-sqlite";
+import { Database } from "bun:sqlite";
+import { PluginManager, type Plugin, type CoreServices } from "./core";
+import {
+  createLogger,
+  createCache,
+  createEvents,
+  createCron,
+  createJobs,
+  createSSE,
+  createRateLimiter,
+  createErrors,
+} from "./core/index";
+
+/**
+ * Creates a fully functional (in-memory) testing environment for a plugin.
+ *
+ * @param targetPlugin The plugin you want to test.
+ * @param dependencies Any other plugins this plugin needs (e.g. Auth).
+ */
+export async function createTestHarness(targetPlugin: Plugin, dependencies: Plugin[] = []) {
+  // 1. Setup In-Memory DB
+  const db = new Kysely<any>({
+    dialect: new BunSqliteDialect({ database: new Database(":memory:") }),
+  });
+
+  // 2. Initialize Core Services
+  const logger = createLogger({ level: "warn" }); // Less verbose in tests
+  const cache = createCache();
+  const events = createEvents();
+  const cron = createCron();
+  const jobs = createJobs({ events });
+  const sse = createSSE();
+  const rateLimiter = createRateLimiter();
+  const errors = createErrors();
+
+  const core: CoreServices = {
+    db,
+    config: { env: "test" },
+    logger,
+    cache,
+    events,
+    cron,
+    jobs,
+    sse,
+    rateLimiter,
+    errors,
+  };
+
+  const manager = new PluginManager(core);
+
+  // 3. Register Deps + Target
+  for (const dep of dependencies) {
+    manager.register(dep);
+  }
+  manager.register(targetPlugin);
+
+  // 4. Run Migrations (Real Kysely Migrations!)
+  await manager.migrate();
+
+  // 5. Init Plugins
+  await manager.init();
+
+  return {
+    manager,
+    db,
+    core
+  };
+}

package/examples/starter/node_modules/@donkeylabs/server/src/index.ts

@@ -0,0 +1,38 @@
+// @donkeylabs/server - Main exports
+
+// Server
+export { AppServer, type ServerConfig } from "./server";
+
+// Router
+export { createRouter, type Router, type RouteBuilder } from "./router";
+
+// Handlers
+export { createHandler, TypedHandler, RawHandler } from "./handlers";
+
+// Core Plugin System
+export {
+  createPlugin,
+  PluginManager,
+  PluginContext,
+  type PluginRegistry,
+  type PluginHandlerRegistry,
+  type PluginMiddlewareRegistry,
+  type CoreServices,
+  type Register,
+} from "./core";
+
+// Middleware
+export { createMiddleware } from "./middleware";
+
+// Config helper
+export function defineConfig(config: {
+  plugins: string[];
+  outDir: string;
+  routes?: string;
+  client?: { output: string };
+}) {
+  return config;
+}
+
+// Re-export HttpError for custom error creation
+export { HttpError } from "./core/errors";

package/examples/starter/node_modules/@donkeylabs/server/src/middleware.ts

@@ -0,0 +1,34 @@
+import type { ServerContext } from "./router";
+
+// The next function - calls the next middleware or handler
+export type NextFn = () => Promise<Response>;
+
+// Middleware function signature (what plugins implement)
+export type MiddlewareFn<TConfig = void> = (
+  req: Request,
+  ctx: ServerContext,
+  next: NextFn,
+  config: TConfig
+) => Promise<Response>;
+
+// Runtime middleware structure (mirrors HandlerRuntime pattern)
+export interface MiddlewareRuntime<TConfig = void> {
+  execute: MiddlewareFn<TConfig>;
+  readonly __config: TConfig; // Phantom type for config inference
+}
+
+// Factory to create middleware (mirrors createHandler pattern)
+export function createMiddleware<TConfig = void>(
+  execute: MiddlewareFn<TConfig>
+): MiddlewareRuntime<TConfig> {
+  return {
+    execute,
+    __config: undefined as unknown as TConfig,
+  };
+}
+
+// Stored middleware definition (attached to routes)
+export interface MiddlewareDefinition {
+  name: string;
+  config: any;
+}

package/examples/starter/node_modules/@donkeylabs/server/src/registry.ts

@@ -0,0 +1,13 @@
+// Auto-generated by scripts/generate-registry.ts
+// Runtime registration of custom handler and middleware methods
+/// <reference path="../registry.d.ts" />
+import { RouteBuilder, MiddlewareBuilder } from "./router";
+
+// Handler registrations
+
+
+// Middleware registrations
+// Register "authRequired" middleware method from authPlugin
+(MiddlewareBuilder.prototype as any).authRequired = function(config: any = {}) {
+  return this.addMiddleware("authRequired", config);
+};

package/examples/starter/node_modules/@donkeylabs/server/src/router.ts

@@ -0,0 +1,155 @@
+/// <reference path="../registry.d.ts" />
+import { z } from "zod";
+import type { GlobalContext } from "../context";
+import type { PluginHandlerRegistry } from "./core";
+import type { MiddlewareDefinition } from "./middleware";
+
+export type ServerContext = GlobalContext;
+
+export interface HandlerRegistry extends PluginHandlerRegistry {
+    typed: {
+        execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
+        readonly __signature: (input: any, ctx: ServerContext) => Promise<any> | any;
+    };
+    raw: {
+        execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
+        readonly __signature: (req: Request, ctx: ServerContext) => Promise<Response> | Response;
+    };
+}
+
+export type RouteDefinition<
+    T extends keyof HandlerRegistry = "typed",
+    I = any,
+    O = any
+> = {
+  name: string;
+  handler: T;
+  input?: z.ZodType<I>;
+  output?: z.ZodType<O>;
+  middleware?: MiddlewareDefinition[];
+  handle: T extends "typed"
+    ? (input: I, ctx: ServerContext) => Promise<O> | O
+    : T extends "raw"
+    ? (req: Request, ctx: ServerContext) => Promise<Response> | Response
+    : HandlerRegistry[T]["__signature"];
+};
+
+export interface TypedRouteConfig<I = any, O = any> {
+  input?: z.ZodType<I>;
+  output?: z.ZodType<O>;
+  handle: (input: I, ctx: ServerContext) => Promise<O> | O;
+}
+
+export interface RouteMetadata {
+  name: string;
+  handler: string;
+  inputSchema?: z.ZodType<any>;
+  outputSchema?: z.ZodType<any>;
+}
+
+export interface RawRouteConfig {
+  handle: (req: Request, ctx: ServerContext) => Promise<Response> | Response;
+}
+
+export interface IRouteBuilderBase<TRouter> {
+  typed<I, O>(config: TypedRouteConfig<I, O>): TRouter;
+  raw(config: RawRouteConfig): TRouter;
+}
+
+export interface IRouteBuilder<TRouter> extends IRouteBuilderBase<TRouter> {}
+
+export interface IMiddlewareBuilderBase<TRouter> {
+  route(name: string): IRouteBuilder<TRouter>;
+}
+
+export interface IMiddlewareBuilder<TRouter> extends IMiddlewareBuilderBase<TRouter> {}
+
+export class MiddlewareBuilder<TRouter extends Router> implements IMiddlewareBuilderBase<TRouter> {
+  private _middleware: MiddlewareDefinition[] = [];
+
+  constructor(private router: TRouter) {}
+
+  route(name: string): IRouteBuilder<TRouter> {
+    return new RouteBuilder(this.router, name, this._middleware) as unknown as IRouteBuilder<TRouter>;
+  }
+
+  addMiddleware(name: string, config: any): this {
+    this._middleware.push({ name, config });
+    return this;
+  }
+}
+
+export class RouteBuilder<TRouter extends Router> implements IRouteBuilderBase<TRouter> {
+  constructor(
+    private router: TRouter,
+    private name: string,
+    private _middleware: MiddlewareDefinition[] = []
+  ) {}
+
+  typed<I, O>(config: TypedRouteConfig<I, O>): TRouter {
+    return this.router.addRoute(this.name, "typed", config, this._middleware);
+  }
+
+  raw(config: RawRouteConfig): TRouter {
+    return this.router.addRoute(this.name, "raw", config, this._middleware);
+  }
+
+  addHandler(handler: string, config: any): TRouter {
+    return this.router.addRoute(this.name, handler, config, this._middleware);
+  }
+}
+
+export interface IRouter {
+  route(name: string): IRouteBuilder<this>;
+  middleware: IMiddlewareBuilder<this>;
+  getRoutes(): RouteDefinition<any, any, any>[];
+  getMetadata(): RouteMetadata[];
+  getPrefix(): string;
+}
+
+export class Router implements IRouter {
+  private routes: Map<string, RouteDefinition<any, any, any>> = new Map();
+  private prefix: string;
+
+  constructor(prefix: string = "") {
+    this.prefix = prefix;
+  }
+
+  route(name: string): IRouteBuilder<this> {
+    return new RouteBuilder(this, name) as unknown as IRouteBuilder<this>;
+  }
+
+  get middleware(): IMiddlewareBuilder<this> {
+    return new MiddlewareBuilder(this) as unknown as IMiddlewareBuilder<this>;
+  }
+
+  addRoute(name: string, handler: string, config: any, middleware: MiddlewareDefinition[] = []): this {
+    const fullName = this.prefix ? `${this.prefix}.${name}` : name;
+    this.routes.set(fullName, {
+      name: fullName,
+      handler,
+      middleware: middleware.length > 0 ? middleware : undefined,
+      ...config
+    });
+    return this;
+  }
+
+  getRoutes(): RouteDefinition<any, any, any>[] {
+    return Array.from(this.routes.values());
+  }
+
+  getMetadata(): RouteMetadata[] {
+    return this.getRoutes().map(route => ({
+      name: route.name,
+      handler: route.handler,
+      inputSchema: route.input,
+      outputSchema: route.output,
+    }));
+  }
+
+  getPrefix(): string {
+    return this.prefix;
+  }
+}
+
+export const createRouter = (prefix?: string): IRouter => new Router(prefix);

package/examples/starter/node_modules/@donkeylabs/server/src/server.ts

@@ -0,0 +1,234 @@
+import { z } from "zod";
+import { PluginManager, type CoreServices, type ConfiguredPlugin } from "./core";
+import { type IRouter, type RouteDefinition, type ServerContext } from "./router";
+import { Handlers } from "./handlers";
+import type { MiddlewareRuntime, MiddlewareDefinition } from "./middleware";
+import {
+  createLogger,
+  createCache,
+  createEvents,
+  createCron,
+  createJobs,
+  createSSE,
+  createRateLimiter,
+  createErrors,
+  extractClientIP,
+  HttpError,
+  type LoggerConfig,
+  type CacheConfig,
+  type EventsConfig,
+  type CronConfig,
+  type JobsConfig,
+  type SSEConfig,
+  type RateLimiterConfig,
+  type ErrorsConfig,
+} from "./core/index";
+
+export interface ServerConfig {
+  port?: number;
+  db: CoreServices["db"];
+  config?: Record<string, any>;
+  logger?: LoggerConfig;
+  cache?: CacheConfig;
+  events?: EventsConfig;
+  cron?: CronConfig;
+  jobs?: JobsConfig;
+  sse?: SSEConfig;
+  rateLimiter?: RateLimiterConfig;
+  errors?: ErrorsConfig;
+}
+
+export class AppServer {
+  private port: number;
+  private manager: PluginManager;
+  private routers: IRouter[] = [];
+  private routeMap: Map<string, RouteDefinition> = new Map();
+  private coreServices: CoreServices;
+
+  constructor(options: ServerConfig) {
+    this.port = options.port ?? 3000;
+
+    const logger = createLogger(options.logger);
+    const cache = createCache(options.cache);
+    const events = createEvents(options.events);
+    const cron = createCron(options.cron);
+    const jobs = createJobs({ ...options.jobs, events });
+    const sse = createSSE(options.sse);
+    const rateLimiter = createRateLimiter(options.rateLimiter);
+    const errors = createErrors(options.errors);
+
+    this.coreServices = {
+      db: options.db,
+      config: options.config ?? {},
+      logger,
+      cache,
+      events,
+      cron,
+      jobs,
+      sse,
+      rateLimiter,
+      errors,
+    };
+
+    this.manager = new PluginManager(this.coreServices);
+  }
+
+  registerPlugin(plugin: ConfiguredPlugin): this {
+    this.manager.register(plugin);
+    return this;
+  }
+
+  use(router: IRouter): this {
+    this.routers.push(router);
+    return this;
+  }
+
+  getServices(): any {
+    return this.manager.getServices();
+  }
+
+  getDb(): CoreServices["db"] {
+    return this.manager.getCore().db;
+  }
+
+  private resolveMiddleware(name: string): MiddlewareRuntime<any> | undefined {
+    for (const plugin of this.manager.getPlugins()) {
+      if (plugin.middleware && plugin.middleware[name]) {
+        return plugin.middleware[name] as MiddlewareRuntime<any>;
+      }
+    }
+    return undefined;
+  }
+
+  private async executeMiddlewareChain(
+    req: Request,
+    ctx: ServerContext,
+    stack: MiddlewareDefinition[],
+    finalHandler: () => Promise<Response>
+  ): Promise<Response> {
+    let next = finalHandler;
+
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const mwDef = stack[i];
+      if (!mwDef) continue;
+
+      const mwRuntime = this.resolveMiddleware(mwDef.name);
+
+      if (!mwRuntime) {
+        console.warn(`[Server] Middleware '${mwDef.name}' not found, skipping`);
+        continue;
+      }
+
+      const currentNext = next;
+      const config = mwDef.config;
+      next = () => mwRuntime.execute(req, ctx, currentNext, config);
+    }
+
+    return next();
+  }
+
+  getCore(): CoreServices {
+    return this.coreServices;
+  }
+
+  async start(): Promise<void> {
+    const { logger } = this.coreServices;
+
+    await this.manager.migrate();
+    await this.manager.init();
+
+    this.coreServices.cron.start();
+    this.coreServices.jobs.start();
+    logger.info("Background services started (cron, jobs)");
+
+    for (const router of this.routers) {
+      for (const route of router.getRoutes()) {
+        if (this.routeMap.has(route.name)) {
+          logger.warn(`Duplicate route detected`, { route: route.name });
+        }
+        this.routeMap.set(route.name, route);
+      }
+    }
+    logger.info(`Loaded ${this.routeMap.size} RPC routes`);
+
+    Bun.serve({
+      port: this.port,
+      fetch: async (req, server) => {
+        const url = new URL(req.url);
+        const ip = extractClientIP(req, server.requestIP(req)?.address);
+
+        if (req.method !== "POST") {
+          return new Response("Method Not Allowed", { status: 405 });
+        }
+
+        const actionName = url.pathname.slice(1);
+        const route = this.routeMap.get(actionName);
+
+        if (!route) {
+          return new Response("Not Found", { status: 404 });
+        }
+
+        const type = route.handler || "typed";
+        let handler = Handlers[type as keyof typeof Handlers];
+
+        if (!handler) {
+          for (const plugin of this.manager.getPlugins()) {
+            if (plugin.handlers && plugin.handlers[type]) {
+              handler = plugin.handlers[type] as any;
+              break;
+            }
+          }
+        }
+
+        if (!handler) {
+          logger.error("Handler not found", { handler: type, route: actionName });
+          return new Response("Handler Not Found", { status: 500 });
+        }
+
+        const ctx: ServerContext = {
+          db: this.coreServices.db,
+          plugins: this.manager.getServices(),
+          core: this.coreServices,
+          errors: this.coreServices.errors,
+          config: this.coreServices.config,
+          ip,
+          requestId: crypto.randomUUID(),
+        };
+
+        const middlewareStack = route.middleware || [];
+        const finalHandler = async () => handler.execute(req, route, route.handle, ctx);
+
+        try {
+          if (middlewareStack.length > 0) {
+            return await this.executeMiddlewareChain(req, ctx, middlewareStack, finalHandler);
+          }
+          return await finalHandler();
+        } catch (error) {
+          if (error instanceof HttpError) {
+            logger.warn("HTTP error thrown", {
+              route: actionName,
+              status: error.status,
+              code: error.code,
+              message: error.message,
+            });
+            return Response.json(error.toJSON(), { status: error.status });
+          }
+          throw error;
+        }
+      }
+    });
+
+    logger.info(`Server running at http://localhost:${this.port}`);
+  }
+
+  async shutdown(): Promise<void> {
+    const { logger } = this.coreServices;
+    logger.info("Shutting down server...");
+
+    this.coreServices.sse.shutdown();
+    await this.coreServices.jobs.stop();
+    await this.coreServices.cron.stop();
+
+    logger.info("Server shutdown complete");
+  }
+}

package/examples/starter/node_modules/@donkeylabs/server/templates/init/donkeylabs.config.ts.template

@@ -0,0 +1,14 @@
+import { defineConfig } from "@donkeylabs/server";
+
+export default defineConfig({
+  // Glob patterns for plugin files
+  plugins: ["./src/plugins/**/index.ts"],
+
+  // Generated types output (hidden directory)
+  outDir: ".@donkeylabs/server",
+
+  // Optional: Client generation
+  // client: {
+  //   output: "./src/client/api.ts",
+  // },
+});

package/examples/starter/node_modules/@donkeylabs/server/templates/init/index.ts.template

@@ -0,0 +1,41 @@
+import {
+  Kysely,
+  DummyDriver,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+} from "kysely";
+import { AppServer, createRouter } from "@donkeylabs/server";
+import { z } from "zod";
+
+// Setup Database (replace with your actual database)
+const db = new Kysely<any>({
+  dialect: {
+    createAdapter: () => new SqliteAdapter(),
+    createDriver: () => new DummyDriver(),
+    createIntrospector: (db) => new SqliteIntrospector(db),
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+  },
+});
+
+// Create Server
+const server = new AppServer({
+  port: 3000,
+  db,
+  config: { env: process.env.NODE_ENV || "development" },
+});
+
+// Define Routes
+const router = createRouter("api")
+  .route("hello").typed({
+    input: z.object({ name: z.string().optional() }),
+    output: z.object({ message: z.string() }),
+    handle: async (input, ctx) => {
+      return { message: `Hello, ${input.name || "World"}!` };
+    },
+  });
+
+server.use(router);
+
+// Start Server
+await server.start();