@donkeylabs/server 0.3.0 → 0.4.0

package/README.md

@@ -1,254 +0,0 @@
-# @donkeylabs/server
-
-A **type-safe plugin system** for building RPC-style APIs with Bun. Features automatic dependency resolution, database schema merging, middleware chains, and built-in core services.
-
-```ts
-// Define a plugin
-const notesPlugin = createPlugin.define({
-  name: "notes",
-  service: async (ctx) => ({
-    create: (title: string) => ctx.db.insertInto("notes").values({ title }).execute(),
-    list: () => ctx.db.selectFrom("notes").selectAll().execute(),
-  }),
-});
-
-// Create routes
-const api = server.router("api");
-api.route("notes.create").typed({
-  input: z.object({ title: z.string() }),
-  handle: async (input, ctx) => ctx.plugins.notes.create(input.title),
-});
-
-// Full type safety end-to-end
-```
-
-## Features
-
-- **Plugin System** - Encapsulate business logic with automatic dependency resolution
-- **Type-Safe Routes** - Zod validation with full TypeScript inference
-- **Schema Merging** - Plugin database schemas automatically merge into global context
-- **Core Services** - Logger, Cache, Events, Jobs, Cron, SSE, Rate Limiter built-in
-- **CLI Tools** - Project scaffolding, type generation, plugin creation
-- **Client Generation** - Auto-generate typed API clients for your frontend
-
-## Quick Start
-
-### Install
-
-```sh
-bun add @donkeylabs/server kysely zod
-```
-
-### Create a Project
-
-```sh
-bunx @donkeylabs/server init my-app
-cd my-app
-bun run dev
-```
-
-### Or Start from Scratch
-
-```ts
-// src/index.ts
-import { AppServer, createPlugin } from "@donkeylabs/server";
-import { z } from "zod";
-import Database from "bun:sqlite";
-import { Kysely, SqliteDialect } from "kysely";
-
-// Database setup
-const db = new Kysely({ dialect: new SqliteDialect({ database: new Database("app.db") }) });
-
-// Create plugin
-const greeterPlugin = createPlugin.define({
-  name: "greeter",
-  service: async () => ({
-    greet: (name: string) => `Hello, ${name}!`,
-  }),
-});
-
-// Create server
-const server = new AppServer({ db, port: 3000 });
-server.registerPlugin(greeterPlugin);
-
-// Define routes
-server.router("api")
-  .route("greet").typed({
-    input: z.object({ name: z.string() }),
-    output: z.object({ message: z.string() }),
-    handle: async (input, ctx) => ({
-      message: ctx.plugins.greeter.greet(input.name),
-    }),
-  });
-
-await server.start();
-// Server running at http://localhost:3000
-```
-
-### Make a Request
-
-```sh
-curl -X POST http://localhost:3000/api.greet \
-  -H "Content-Type: application/json" \
-  -d '{"name": "World"}'
-
-# {"message": "Hello, World!"}
-```
-
-## Core Services
-
-Every route handler has access to built-in services via `ctx.core`:
-
-```ts
-handle: async (input, ctx) => {
-  // Logging
-  ctx.core.logger.info("Processing request", { input });
-
-  // Caching
-  const cached = await ctx.core.cache.getOrSet("key", async () => {
-    return await expensiveOperation();
-  }, 60000);
-
-  // Events
-  await ctx.core.events.emit("user.created", { id: user.id });
-
-  // Background jobs
-  await ctx.core.jobs.enqueue("sendEmail", { to: user.email });
-
-  // Rate limiting
-  const result = await ctx.core.rateLimiter.check(`api:${ctx.ip}`, 100, 60000);
-
-  // Real-time updates
-  ctx.core.sse.broadcast(`user:${userId}`, "notification", { message: "Hello" });
-}
-```
-
-| Service | Purpose |
-|---------|---------|
-| `logger` | Structured logging with levels |
-| `cache` | Key-value store with TTL |
-| `events` | Pub/sub event system |
-| `jobs` | Background job queue |
-| `cron` | Scheduled tasks |
-| `sse` | Server-Sent Events |
-| `rateLimiter` | Request throttling |
-
-## Plugins with Database
-
-Plugins can define their own database tables with full type safety:
-
-```ts
-// plugins/users/index.ts
-import { createPlugin } from "@donkeylabs/server";
-import type { DB as UsersSchema } from "./schema";
-
-export const usersPlugin = createPlugin
-  .withSchema<UsersSchema>()
-  .define({
-    name: "users",
-    service: async (ctx) => ({
-      create: async (email: string, name: string) => {
-        return ctx.db
-          .insertInto("users")
-          .values({ email, name })
-          .returningAll()
-          .executeTakeFirstOrThrow();
-      },
-      findByEmail: (email: string) => {
-        return ctx.db
-          .selectFrom("users")
-          .selectAll()
-          .where("email", "=", email)
-          .executeTakeFirst();
-      },
-    }),
-  });
-```
-
-## Middleware
-
-Add authentication, logging, or other cross-cutting concerns:
-
-```ts
-// In plugin
-export const authPlugin = createPlugin.define({
-  name: "auth",
-  service: async (ctx) => ({
-    validateToken: async (token: string) => { /* ... */ },
-  }),
-  middleware: (ctx, service) => ({
-    requireAuth: createMiddleware(async (req, reqCtx, next) => {
-      const token = req.headers.get("Authorization")?.replace("Bearer ", "");
-      if (!token) return Response.json({ error: "Unauthorized" }, { status: 401 });
-
-      reqCtx.user = await service.validateToken(token);
-      return next();
-    }),
-  }),
-});
-
-// In routes
-server.router("api")
-  .middleware.requireAuth()
-  .route("protected")
-  .typed({ handle: (input, ctx) => ({ user: ctx.user }) });
-```
-
-## CLI Commands
-
-```sh
-donkeylabs              # Interactive menu
-donkeylabs init         # Create new project
-donkeylabs generate     # Generate types
-donkeylabs plugin       # Create new plugin
-donkeylabs dev          # Dev server with hot reload
-```
-
-## Client Generation
-
-Generate a fully-typed API client for your frontend:
-
-```sh
-bun run gen:client --output ./frontend/src/lib/api.ts
-```
-
-```ts
-// Frontend usage
-import { createClient } from "./lib/api";
-
-const api = createClient({ baseUrl: "http://localhost:3000" });
-
-const result = await api.greet({ name: "World" });
-// result is typed as { message: string }
-```
-
-## Testing
-
-```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
-import { myPlugin } from "./plugins/myPlugin";
-
-const { manager, db, core } = await createTestHarness(myPlugin);
-
-// Test with real in-memory SQLite + all core services
-const service = manager.getServices().myPlugin;
-expect(service.greet("Test")).toBe("Hello, Test!");
-```
-
-## Documentation
-
-- [Plugins](docs/plugins.md) - Creating plugins with schemas and dependencies
-- [Router](docs/router.md) - Defining routes and handlers
-- [Middleware](docs/middleware.md) - Authentication and cross-cutting concerns
-- [Core Services](docs/core-services.md) - Logger, Cache, Events, Jobs, Cron, SSE
-- [Testing](docs/testing.md) - Test harness and patterns
-- [API Client](docs/api-client.md) - Client generation and usage
-
-## Requirements
-
-- [Bun](https://bun.sh) v1.0+
-- TypeScript 5+
-
-## License
-
-MIT

package/cli/commands/dev.ts

@@ -1,134 +0,0 @@
-/**
- * Dev Command
- *
- * Start development server with auto-regeneration on file changes
- *
- * Usage:
- *   donkeylabs dev
- */
-
-import { watch } from "node:fs";
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-import { spawn, type Subprocess } from "bun";
-import pc from "picocolors";
-
-let generateTimeout: Timer | null = null;
-let serverProcess: Subprocess | null = null;
-
-export async function devCommand(_args: string[]): Promise<void> {
-  console.log(pc.magenta(pc.bold("\n  @donkeylabs/server dev\n")));
-
-  const cwd = process.cwd();
-  const configPath = join(cwd, "donkeylabs.config.ts");
-
-  if (!existsSync(configPath)) {
-    console.error(pc.red("donkeylabs.config.ts not found. Run 'donkeylabs init' first."));
-    process.exit(1);
-  }
-
-  // Initial generate
-  console.log(pc.dim("Running initial type generation..."));
-  await runGenerate();
-
-  // Start the server
-  startServer();
-
-  // Watch directories
-  const watchPaths = [
-    join(cwd, "src/routes"),
-    join(cwd, "src/plugins"),
-  ];
-
-  console.log(pc.cyan("\nWatching for changes..."));
-  console.log(pc.gray("  - src/routes/"));
-  console.log(pc.gray("  - src/plugins/"));
-  console.log(pc.gray("\nPress Ctrl+C to stop.\n"));
-
-  for (const watchPath of watchPaths) {
-    if (!existsSync(watchPath)) continue;
-
-    watchRecursive(watchPath, (eventType, filename) => {
-      if (!filename) return;
-      if (filename.includes(".@donkeylabs") || filename.includes("node_modules")) return;
-      if (!filename.endsWith(".ts")) return;
-
-      if (generateTimeout) clearTimeout(generateTimeout);
-
-      generateTimeout = setTimeout(async () => {
-        console.log(pc.dim(`\n[${filename}]`));
-        await runGenerate();
-      }, 300);
-    });
-  }
-
-  // Keep process alive
-  await new Promise(() => {});
-}
-
-async function runGenerate(): Promise<void> {
-  try {
-    const { generateCommand } = await import("./generate");
-    await generateCommand([]);
-  } catch (error: any) {
-    console.error(pc.red("Generate failed:"), error.message);
-  }
-}
-
-function startServer(): void {
-  const cwd = process.cwd();
-  const entryPoint = join(cwd, "src/index.ts");
-
-  if (!existsSync(entryPoint)) {
-    console.log(pc.yellow("No src/index.ts found, skipping server start."));
-    return;
-  }
-
-  console.log(pc.green("Starting server..."));
-
-  serverProcess = spawn({
-    cmd: ["bun", "--watch", entryPoint],
-    cwd,
-    stdout: "inherit",
-    stderr: "inherit",
-    env: { ...process.env, NODE_ENV: "development" },
-  });
-}
-
-function restartServer(): void {
-  if (serverProcess) {
-    console.log(pc.yellow("Restarting server..."));
-    serverProcess.kill();
-  }
-  startServer();
-}
-
-function watchRecursive(
-  dir: string,
-  callback: (eventType: string, filename: string | null) => void
-): void {
-  try {
-    watch(dir, { recursive: true }, (eventType, filename) => {
-      callback(eventType, filename);
-    });
-  } catch (error: any) {
-    // Fallback for systems that don't support recursive watch
-    console.log(pc.yellow(`Warning: Could not watch ${dir} recursively`));
-  }
-}
-
-// Handle graceful shutdown
-process.on("SIGINT", () => {
-  console.log(pc.gray("\n\nShutting down..."));
-  if (serverProcess) {
-    serverProcess.kill();
-  }
-  process.exit(0);
-});
-
-process.on("SIGTERM", () => {
-  if (serverProcess) {
-    serverProcess.kill();
-  }
-  process.exit(0);
-});