@donkeylabs/server 0.3.0 → 0.4.0

package/docs/middleware.md

@@ -5,7 +5,7 @@ Request/response middleware for cross-cutting concerns like authentication, rate
 ## Quick Start
 
 ```ts
-import { createMiddleware } from "@donkeylabs/server";
+import { createMiddleware } from "./middleware";
 
 // Create middleware with config
 const authMiddleware = createMiddleware<{ required: boolean }>(
@@ -66,7 +66,7 @@ function createMiddleware<TConfig = void>(
 
 ```ts
 // middleware/auth.ts
-import { createMiddleware } from "@donkeylabs/server";
+import { createMiddleware } from "../middleware";
 
 interface AuthConfig {
   required?: boolean;

package/docs/plugins.md

@@ -22,7 +22,7 @@ The simplest plugin exports a service that becomes available to all route handle
 
 ```ts
 // plugins/greeter/index.ts
-import { createPlugin } from "@donkeylabs/server";
+import { createPlugin } from "../../core";
 
 export const greeterPlugin = createPlugin.define({
   name: "greeter",
@@ -88,7 +88,7 @@ This creates `plugins/users/schema.ts` with Kysely types.
 
 ```ts
 // plugins/users/index.ts
-import { createPlugin } from "@donkeylabs/server";
+import { createPlugin } from "../../core";
 import type { DB as UsersSchema } from "./schema";
 
 export const usersPlugin = createPlugin
@@ -131,7 +131,7 @@ Plugins can accept configuration at registration time using the factory pattern:
 
 ```ts
 // plugins/email/index.ts
-import { createPlugin } from "@donkeylabs/server";
+import { createPlugin } from "../../core";
 
 export interface EmailConfig {
   apiKey: string;
@@ -193,7 +193,7 @@ Plugins can depend on other plugins. Dependencies are resolved automatically in
 
 ```ts
 // plugins/notifications/index.ts
-import { createPlugin } from "@donkeylabs/server";
+import { createPlugin } from "../../core";
 
 export const notificationsPlugin = createPlugin.define({
   name: "notifications",
@@ -242,8 +242,9 @@ Plugins can define custom request handlers for specialized processing:
 
 ```ts
 // plugins/api/index.ts
-import { createPlugin, createHandler } from "@donkeylabs/server";
-import type { ServerContext } from "@donkeylabs/server";
+import { createPlugin } from "../../core";
+import { createHandler } from "../../handlers";
+import type { ServerContext } from "../../router";
 
 // Define handler signature
 type XMLHandler = (xmlBody: string, ctx: ServerContext) => Promise<string>;
@@ -369,16 +370,12 @@ The `PluginContext` passed to the service function provides:
 
 ```ts
 interface PluginContext<Deps, Schema, Config> {
-  // Convenience getters (auto-namespaced for this plugin)
-  logger: Logger;           // Auto-namespaced with { plugin: "pluginName" }
-  cache: NamespacedCache;   // Auto-prefixed with "pluginName:"
-
   // Core services (always available)
   core: {
     db: Kysely<any>;
     config: Record<string, any>;
-    logger: Logger;         // Root logger (use ctx.logger for plugin-scoped)
-    cache: Cache;           // Root cache (use ctx.cache for plugin-scoped)
+    logger: Logger;
+    cache: Cache;
     events: Events;
     cron: Cron;
     jobs: Jobs;
@@ -397,42 +394,6 @@ interface PluginContext<Deps, Schema, Config> {
 }
 ```
 
-**Example using convenience getters:**
-
-```ts
-export const paymentsPlugin = createPlugin.define({
-  name: "payments",
-  service: async (ctx) => {
-    // ctx.logger is auto-namespaced with { plugin: "payments" }
-    const logger = ctx.logger;
-
-    // ctx.cache is auto-prefixed with "payments:"
-    const cache = ctx.cache;
-
-    logger.info("Payment plugin initialized");
-    // Output: [14:30:45.123 CST][payments][INFO] Payment plugin initialized
-
-    return {
-      async processPayment(orderId: string) {
-        // Check cache (key becomes "payments:order:123")
-        const cached = await cache.get(`order:${orderId}`);
-        if (cached) {
-          logger.debug("Cache hit", { orderId });
-          return cached;
-        }
-
-        logger.info("Processing payment", { orderId });
-        // Output: [14:30:45.456 CST][payments][INFO] Processing payment orderId=123
-
-        const result = await chargeCard(orderId);
-        await cache.set(`order:${orderId}`, result, 60000);
-        return result;
-      },
-    };
-  },
-});
-```
-
 **Example using all context features:**
 
 ```ts
@@ -443,13 +404,9 @@ export const analyticsPlugin = createPlugin
     name: "analytics",
     dependencies: ["users"] as const,
     service: async (ctx) => {
-      // Use plugin-scoped logger and cache
-      const logger = ctx.logger;
-      const cache = ctx.cache;
-
       // Schedule daily report
       ctx.core.cron.schedule("0 0 * * *", async () => {
-        logger.info("Running daily analytics");
+        ctx.core.logger.info("Running daily analytics");
         // ...
       });
 
@@ -462,16 +419,8 @@ export const analyticsPlugin = createPlugin
       });
 
       return {
-        async track(event: string, data: any) {
-          // Cache recent events to dedupe
-          const cacheKey = `event:${event}:${JSON.stringify(data)}`;
-          if (await cache.has(cacheKey)) {
-            logger.debug("Duplicate event ignored", { event });
-            return;
-          }
-          await cache.set(cacheKey, true, 5000);
-
-          await ctx.core.events.emit(`analytics.${event}`, {
+        track(event: string, data: any) {
+          ctx.core.events.emit(`analytics.${event}`, {
             trackingId: ctx.config.trackingId,
             ...data,
           });
@@ -495,7 +444,7 @@ import {
   InferMiddleware,
   InferDependencies,
   InferConfig,
-} from "@donkeylabs/server";
+} from "./core";
 
 import { usersPlugin } from "./plugins/users";
 

package/docs/project-structure.md

@@ -94,7 +94,7 @@ plugins/<name>/
 
 ```ts
 // plugins/<name>/index.ts
-import { createPlugin } from "@donkeylabs/server";
+import { createPlugin } from "../../core";
 import type { DB } from "./schema";  // If using database
 
 // Configuration type (if plugin is configurable)
@@ -144,7 +144,7 @@ routes/
 
 ```ts
 // routes/users.ts
-import { createRouter } from "@donkeylabs/server";
+import { createRouter } from "../router";
 import { z } from "zod";
 
 export const usersRouter = createRouter("users")
@@ -173,144 +173,6 @@ export const usersRouter = createRouter("users")
 
 ---
 
-## Advanced Route Organization
-
-For larger projects, the starter template provides a more structured route organization:
-
-```
-routes/<namespace>/<route>/
-├── index.ts           # Route definition
-├── schema.ts          # Zod schemas (Input, Output)
-├── models/
-│   └── model.ts       # Handler class
-└── tests/
-    ├── unit.test.ts   # Unit tests
-    └── integ.test.ts  # Integration tests
-```
-
-### Handler Class Pattern
-
-Instead of inline handlers, use the `Handler<T>` interface with model classes:
-
-```ts
-// routes/health/ping/schema.ts
-import { z } from "zod";
-
-export const Input = z.object({ message: z.string() });
-export const Output = z.object({ response: z.string() });
-
-export type Input = z.infer<typeof Input>;
-export type Output = z.infer<typeof Output>;
-```
-
-```ts
-// routes/health/ping/models/model.ts
-import type { Handler } from "@donkeylabs/server";
-import type { Health } from "$server/routes";  // Generated types
-import type { AppContext } from "$server/context";
-
-export class PingModel implements Handler<Health.Ping> {
-  private ctx: AppContext;
-
-  constructor(ctx: AppContext) {
-    this.ctx = ctx;
-  }
-
-  handle(input: Health.Ping.Input): Health.Ping.Output {
-    return { response: "pong" };
-  }
-}
-```
-
-```ts
-// routes/health/ping/index.ts
-import { createRoute } from "@donkeylabs/server";
-import { Input, Output } from "./schema";
-import { PingModel } from "./models/model";
-
-export const pingRoute = createRoute.typed({
-  input: Input,
-  output: Output,
-  handle: async (input, ctx) => new PingModel(ctx).handle(input),
-});
-```
-
-This pattern separates concerns and makes testing easier.
-
----
-
-## Path Aliases
-
-Configure tsconfig.json path aliases for cleaner imports:
-
-```json
-{
-  "compilerOptions": {
-    "paths": {
-      "$server/*": [".@donkeylabs/server/*"],
-      "$api": [".@donkeylabs/server/client"]
-    }
-  }
-}
-```
-
-**Usage:**
-
-```ts
-// Instead of relative paths
-import type { AppContext } from "../../../.@donkeylabs/server/context";
-
-// Use path aliases
-import type { AppContext } from "$server/context";
-import type { Health } from "$server/routes";
-import { api } from "$api";
-```
-
----
-
-## Generated Files
-
-The framework generates type definition files in `.@donkeylabs/server/`:
-
-| File | Purpose |
-|------|---------|
-| `registry.d.ts` | Plugin handlers and middleware types |
-| `context.d.ts` | Merged `AppContext` with all plugin schemas |
-| `routes.d.ts` | Route type definitions for `Handler<T>` |
-| `client.ts` | Type-safe API client |
-
-**Important:**
-- These files are auto-generated by `donkeylabs generate`
-- Add `.@donkeylabs/` to `.gitignore`
-- Regenerate after any plugin or route changes
-- Never edit these files manually
-
----
-
-## AppContext vs ServerContext
-
-The framework provides two context types:
-
-| Type | Source | Use When |
-|------|--------|----------|
-| `ServerContext` | Library export | Generic library code |
-| `AppContext` | Generated | Application code with full typing |
-
-```ts
-// ServerContext - library type, uses PluginRegistry
-import type { ServerContext } from "@donkeylabs/server";
-
-// AppContext - generated, includes merged schemas
-import type { AppContext } from "$server/context";
-
-// In your handlers/models, prefer AppContext for full typing
-export class MyModel {
-  constructor(private ctx: AppContext) {}
-}
-```
-
----
-
 ## Do's and Don'ts
 
 ### DO: Use the Plugin System
@@ -554,7 +416,7 @@ export async function down(db: Kysely<any>): Promise<void> {
 
 ```ts
 // test/plugins/auth.test.ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "../../harness";
 import { authPlugin } from "../../plugins/auth";
 
 describe("Auth Plugin", () => {
@@ -580,7 +442,7 @@ describe("Auth Plugin", () => {
 
 ```ts
 // test/integration.test.ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "../harness";
 import { authPlugin } from "../plugins/auth";
 import { ordersPlugin } from "../plugins/orders";
 

package/docs/rate-limiter.md

@@ -24,16 +24,8 @@ if (!result.allowed) {
 
 ```ts
 interface RateLimiter {
-  // Manual rate limiting
   check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
   reset(key: string): Promise<void>;
-
-  // Declarative rules (auto-enforced)
-  registerRule(pattern: string, rule: RateLimitRule): void;
-  registerRules(rules: Record<string, RateLimitRule>): void;
-  matchRoute(route: string): RateLimitRule | undefined;
-  checkRoute(route: string, ctx: { ip: string; user?: any }): Promise<RateLimitResult | null>;
-  listRules(): Array<{ pattern: string; limit: number; window: string | number }>;
 }
 
 interface RateLimitResult {
@@ -43,14 +35,6 @@ interface RateLimitResult {
   resetAt: Date;          // When window resets
   retryAfter?: number;    // Seconds until retry (if blocked)
 }
-
-interface RateLimitRule {
-  limit: number;
-  window: string | number;  // "1m", "10s", or milliseconds
-  keyFn?: (ctx: { ip: string; route: string; user?: any }) => string;
-  skip?: (ctx: { ip: string; route: string; user?: any }) => boolean;
-  message?: string;
-}
 ```
 
 ### Methods
@@ -59,11 +43,6 @@ interface RateLimitRule {
 |--------|-------------|
 | `check(key, limit, windowMs)` | Check and increment counter for key |
 | `reset(key)` | Reset counter for key |
-| `registerRule(pattern, rule)` | Register declarative rate limit rule |
-| `registerRules(rules)` | Register multiple rules at once |
-| `matchRoute(route)` | Get rule matching a route |
-| `checkRoute(route, ctx)` | Check rate limit for route (auto-uses registered rules) |
-| `listRules()` | List all registered rules |
 
 ---
 
@@ -87,117 +66,6 @@ router.route("protected").typed({
 
 ---
 
-## Declarative Rate Limits
-
-Register rate limit rules declaratively and let the framework enforce them automatically.
-
-### Server-Level Registration
-
-```ts
-const server = new AppServer({ db });
-
-// Register individual rules
-server.registerRateLimit("auth.login", { limit: 5, window: "15m" });
-server.registerRateLimit("api.*", { limit: 100, window: "1m" });
-server.registerRateLimit("billing.*", { limit: 10, window: "1h" });
-
-// Register multiple at once
-server.registerRateLimits({
-  "uploads.create": { limit: 10, window: "1h" },
-  "exports.*": { limit: 5, window: "1h" },
-});
-```
-
-### Pattern Matching
-
-Rules support glob patterns:
-
-```ts
-// Exact match
-server.registerRateLimit("auth.login", { limit: 5, window: "15m" });
-
-// Wildcard - matches api.users.list, api.posts.create, etc.
-server.registerRateLimit("api.*", { limit: 100, window: "1m" });
-
-// Exact matches take precedence over patterns
-server.registerRateLimit("api.search", { limit: 20, window: "1m" }); // More restrictive for search
-```
-
-### Skip Function
-
-Bypass rate limits for certain requests:
-
-```ts
-server.registerRateLimit("api.*", {
-  limit: 100,
-  window: "1m",
-  skip: (ctx) => {
-    // Skip for admins
-    return ctx.user?.role === "admin";
-  },
-});
-
-server.registerRateLimit("webhooks.*", {
-  limit: 1000,
-  window: "1m",
-  skip: (ctx) => {
-    // Skip for internal IPs
-    return ctx.ip.startsWith("10.0.");
-  },
-});
-```
-
-### Custom Key Function
-
-Control how rate limits are grouped:
-
-```ts
-server.registerRateLimit("api.*", {
-  limit: 100,
-  window: "1m",
-  keyFn: (ctx) => {
-    // Rate limit per user instead of per IP
-    return ctx.user?.id ? `user:${ctx.user.id}` : `ip:${ctx.ip}`;
-  },
-});
-```
-
-### Auto-Enforcement
-
-Registered rules are automatically checked before route handlers. If a request exceeds the limit, a 429 response is returned:
-
-```json
-{
-  "error": "TOO_MANY_REQUESTS",
-  "retryAfter": 45
-}
-```
-
-With headers:
-```
-Retry-After: 45
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 0
-X-RateLimit-Reset: 2024-01-15T12:35:00.000Z
-```
-
-### Introspection
-
-```ts
-// Check which rule applies to a route
-const rule = ctx.core.rateLimiter.matchRoute("api.users.list");
-// { limit: 100, window: "1m", ... }
-
-// List all registered rules
-const rules = ctx.core.rateLimiter.listRules();
-// [
-//   { pattern: "auth.login", limit: 5, window: "15m" },
-//   { pattern: "api.*", limit: 100, window: "1m" },
-// ]
-```
-
----
-
 ## Usage Examples
 
 ### Basic Rate Limiting
@@ -379,7 +247,7 @@ router.middleware
 Convert duration strings to milliseconds:
 
 ```ts
-import { parseDuration } from "@donkeylabs/server";
+import { parseDuration } from "./core/rate-limiter";
 
 parseDuration("100ms");  // 100
 parseDuration("30s");    // 30000
@@ -393,7 +261,7 @@ parseDuration("1d");     // 86400000
 Build consistent rate limit keys:
 
 ```ts
-import { createRateLimitKey } from "@donkeylabs/server";
+import { createRateLimitKey } from "./core/rate-limiter";
 
 const key = createRateLimitKey("api.users.list", "192.168.1.1");
 // "ratelimit:api.users.list:192.168.1.1"
@@ -404,7 +272,7 @@ const key = createRateLimitKey("api.users.list", "192.168.1.1");
 Manual IP extraction if needed:
 
 ```ts
-import { extractClientIP } from "@donkeylabs/server";
+import { extractClientIP } from "./core/rate-limiter";
 
 const ip = extractClientIP(req, socketAddr);
 ```
@@ -555,7 +423,7 @@ interface RateLimitAdapter {
 ### Redis Adapter Example
 
 ```ts
-import { createRateLimiter, type RateLimitAdapter } from "@donkeylabs/server";
+import { createRateLimiter, type RateLimitAdapter } from "./core/rate-limiter";
 import Redis from "ioredis";
 
 class RedisRateLimitAdapter implements RateLimitAdapter {

package/docs/router.md

@@ -5,7 +5,7 @@ Fluent API for defining type-safe routes with handler selection and middleware c
 ## Quick Start
 
 ```ts
-import { createRouter } from "@donkeylabs/server";
+import { createRouter } from "./router";
 import { z } from "zod";
 
 const router = createRouter("api")
@@ -166,18 +166,10 @@ router.route("example").typed({
     // Plugin services
     const data = await ctx.plugins.myPlugin.getData();
 
-    // Core services (logger, cache, events, cron, jobs, sse, rateLimiter)
+    // Core services
     ctx.core.logger.info("Processing request", { input });
     const cached = await ctx.core.cache.get("key");
 
-    // Error factories
-    if (!users.length) {
-      throw ctx.errors.NotFound("No users found");
-    }
-
-    // Application config
-    console.log(ctx.config.env);  // "development" | "production"
-
     // Request info
     console.log(ctx.ip);         // Client IP
     console.log(ctx.requestId);  // Unique request ID
@@ -475,18 +467,18 @@ router.route("stream").raw({
 Register routes with the server:
 
 ```ts
-import { AppServer } from "@donkeylabs/server";
+import { AppServer } from "./server";
 import { userRouter } from "./routes/users";
 import { orderRouter } from "./routes/orders";
 
 const server = new AppServer({ db, port: 3000 });
 
 // Register single router
-server.router(userRouter);
+server.use(userRouter);
 
 // Register multiple routers
-server.router(userRouter);
-server.router(orderRouter);
+server.use(userRouter);
+server.use(orderRouter);
 
 await server.start();
 ```