@donkeylabs/server 0.4.2 → 0.4.4

package/docs/plugins.md

@@ -4,6 +4,7 @@ Plugins are the core building blocks of this framework. Each plugin encapsulates
 
 ## Table of Contents
 
+- [When to Create a Plugin vs Route](#when-to-create-a-plugin-vs-route)
 - [Creating a Plugin](#creating-a-plugin)
 - [Plugin with Database Schema](#plugin-with-database-schema)
 - [Plugin with Configuration](#plugin-with-configuration)
@@ -16,6 +17,126 @@ Plugins are the core building blocks of this framework. Each plugin encapsulates
 
 ---
 
+## When to Create a Plugin vs Route
+
+Understanding when to create a plugin versus a route is fundamental to building maintainable applications.
+
+### The Core Principle
+
+**Plugins = Reusable Business Logic** | **Routes = App-Specific API Endpoints**
+
+Think of plugins as your application's "services layer" and routes as your "API layer".
+
+### Create a Plugin When:
+
+1. **The logic could be reused** across multiple routes or applications
+   - Example: User authentication, email sending, payment processing
+
+2. **You need database tables** for a domain concept
+   - Example: A "users" plugin that owns the users table and provides CRUD methods
+
+3. **The functionality is self-contained** with its own data and operations
+   - Example: A "notifications" plugin with its own tables, delivery logic, and scheduling
+
+4. **You want to share state or connections** (database, external APIs)
+   - Example: A "stripe" plugin that manages the Stripe SDK connection
+
+5. **You're building cross-cutting concerns** like auth middleware, rate limiting, or logging
+
+### Create a Route When:
+
+1. **Exposing plugin functionality** to the outside world via HTTP
+   - Example: A `users.create` route that calls `ctx.plugins.users.create()`
+
+2. **Combining multiple plugins** for a specific use case
+   - Example: A checkout route that uses cart, payment, and inventory plugins
+
+3. **App-specific endpoints** that don't need to be reused
+   - Example: A dashboard summary endpoint specific to your app
+
+4. **Simple operations** that don't warrant a full plugin
+   - Example: A health check endpoint
+
+### Decision Flowchart
+
+```
+Is this logic reusable across routes or apps?
+  ├── Yes → Create a Plugin
+  └── No
+       ├── Does it need its own database tables?
+       │     └── Yes → Create a Plugin (with hasSchema: true)
+       └── Is it just exposing existing functionality via HTTP?
+             └── Yes → Create a Route that uses existing plugins
+```
+
+### Example: Building a Task Management System
+
+**Step 1: Identify reusable domains → Create Plugins**
+- `tasks` plugin - owns tasks table, CRUD methods
+- `users` plugin - owns users table, auth methods
+- `notifications` plugin - handles email/push notifications
+
+**Step 2: Create app-specific routes that use plugins**
+```ts
+// routes/tasks/index.ts
+router.route("create").typed({
+  input: CreateTaskInput,
+  handle: async (input, ctx) => {
+    // Use tasks plugin for business logic
+    const task = await ctx.plugins.tasks.create(input);
+
+    // Use notifications plugin for side effects
+    await ctx.plugins.notifications.notify(
+      task.assigneeId,
+      `New task: ${task.title}`
+    );
+
+    return task;
+  },
+});
+```
+
+### Anti-Patterns to Avoid
+
+❌ **Don't put business logic in routes** - Routes should be thin; delegate to plugins
+
+```ts
+// BAD: Business logic in route
+router.route("create").typed({
+  handle: async (input, ctx) => {
+    // 50 lines of validation, database calls, notifications...
+  },
+});
+
+// GOOD: Thin route, logic in plugin
+router.route("create").typed({
+  handle: async (input, ctx) => {
+    return ctx.plugins.tasks.create(input);
+  },
+});
+```
+
+❌ **Don't create a plugin for every route** - Only for reusable logic
+
+```ts
+// BAD: Plugin just wrapping a single database call
+export const dashboardPlugin = createPlugin.define({
+  name: "dashboard",
+  service: async (ctx) => ({
+    getSummary: () => ctx.db.selectFrom("stats").execute(),
+  }),
+});
+
+// GOOD: Just make it a route
+router.route("dashboard.summary").typed({
+  handle: async (_, ctx) => {
+    return ctx.db.selectFrom("stats").execute();
+  },
+});
+```
+
+---
+
 ## Creating a Plugin
 
 The simplest plugin exports a service that becomes available to all route handlers:

package/docs/testing.md

@@ -0,0 +1,430 @@
+# Testing
+
+This guide covers testing plugins and routes using the built-in test harness.
+
+## Table of Contents
+
+- [Test Harness](#test-harness)
+- [Unit Testing Plugins](#unit-testing-plugins)
+- [Integration Testing](#integration-testing)
+- [Testing Routes](#testing-routes)
+- [Mocking Core Services](#mocking-core-services)
+- [Test Organization](#test-organization)
+- [Running Tests](#running-tests)
+
+---
+
+## Test Harness
+
+The test harness creates a fully functional in-memory testing environment with real SQLite, migrations, and all core services.
+
+```ts
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { myPlugin } from "./plugins/myPlugin";
+
+const { manager, db, core } = await createTestHarness(myPlugin);
+
+// Access plugin services
+const service = manager.getServices().myPlugin;
+
+// Access database directly
+const rows = await db.selectFrom("my_table").selectAll().execute();
+
+// Access core services
+core.logger.info("Test log");
+core.cache.set("key", "value");
+```
+
+### With Dependencies
+
+If your plugin depends on other plugins, pass them as the second argument:
+
+```ts
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { ordersPlugin } from "./plugins/orders";
+import { usersPlugin } from "./plugins/users";
+
+// ordersPlugin depends on usersPlugin
+const { manager } = await createTestHarness(ordersPlugin, [usersPlugin]);
+
+const orders = manager.getServices().orders;
+const users = manager.getServices().users;
+```
+
+---
+
+## Unit Testing Plugins
+
+Unit tests verify individual plugin methods in isolation.
+
+### Basic Plugin Test
+
+```ts
+// plugins/calculator/calculator.test.ts
+import { describe, test, expect } from "bun:test";
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { calculatorPlugin } from "./index";
+
+describe("calculatorPlugin", () => {
+  test("add() returns correct sum", async () => {
+    const { manager } = await createTestHarness(calculatorPlugin);
+    const calc = manager.getServices().calculator;
+
+    expect(calc.add(2, 3)).toBe(5);
+    expect(calc.add(-1, 1)).toBe(0);
+  });
+
+  test("divide() throws on zero", async () => {
+    const { manager } = await createTestHarness(calculatorPlugin);
+    const calc = manager.getServices().calculator;
+
+    expect(() => calc.divide(10, 0)).toThrow("Cannot divide by zero");
+  });
+});
+```
+
+### Testing Database Operations
+
+```ts
+// plugins/users/users.test.ts
+import { describe, test, expect, beforeEach } from "bun:test";
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { usersPlugin } from "./index";
+
+describe("usersPlugin", () => {
+  let users: ReturnType<typeof manager.getServices>["users"];
+  let db: Awaited<ReturnType<typeof createTestHarness>>["db"];
+
+  beforeEach(async () => {
+    const harness = await createTestHarness(usersPlugin);
+    users = harness.manager.getServices().users;
+    db = harness.db;
+  });
+
+  test("create() inserts user into database", async () => {
+    const user = await users.create({
+      email: "test@example.com",
+      name: "Test User",
+    });
+
+    expect(user.id).toBeDefined();
+    expect(user.email).toBe("test@example.com");
+
+    // Verify in database
+    const dbUser = await db
+      .selectFrom("users")
+      .where("id", "=", user.id)
+      .selectAll()
+      .executeTakeFirst();
+
+    expect(dbUser).toBeDefined();
+    expect(dbUser?.email).toBe("test@example.com");
+  });
+
+  test("findByEmail() returns null for non-existent user", async () => {
+    const user = await users.findByEmail("notfound@example.com");
+    expect(user).toBeNull();
+  });
+
+  test("findByEmail() returns user when exists", async () => {
+    await users.create({ email: "exists@example.com", name: "Exists" });
+
+    const user = await users.findByEmail("exists@example.com");
+    expect(user).not.toBeNull();
+    expect(user?.name).toBe("Exists");
+  });
+});
+```
+
+---
+
+## Integration Testing
+
+Integration tests verify multiple plugins working together.
+
+```ts
+// tests/checkout.integ.test.ts
+import { describe, test, expect, beforeEach } from "bun:test";
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { ordersPlugin } from "../plugins/orders";
+import { usersPlugin } from "../plugins/users";
+import { inventoryPlugin } from "../plugins/inventory";
+
+describe("Checkout Integration", () => {
+  let services: {
+    orders: ReturnType<typeof manager.getServices>["orders"];
+    users: ReturnType<typeof manager.getServices>["users"];
+    inventory: ReturnType<typeof manager.getServices>["inventory"];
+  };
+
+  beforeEach(async () => {
+    const { manager } = await createTestHarness(ordersPlugin, [
+      usersPlugin,
+      inventoryPlugin,
+    ]);
+    services = manager.getServices() as typeof services;
+  });
+
+  test("checkout reduces inventory and creates order", async () => {
+    // Setup: Create user and add inventory
+    const user = await services.users.create({
+      email: "buyer@example.com",
+      name: "Buyer",
+    });
+    await services.inventory.add("SKU-001", 10);
+
+    // Action: Checkout
+    const order = await services.orders.checkout({
+      userId: user.id,
+      items: [{ sku: "SKU-001", quantity: 2 }],
+    });
+
+    // Assert: Order created
+    expect(order.status).toBe("completed");
+    expect(order.items).toHaveLength(1);
+
+    // Assert: Inventory reduced
+    const stock = await services.inventory.getStock("SKU-001");
+    expect(stock).toBe(8);
+  });
+
+  test("checkout fails when insufficient inventory", async () => {
+    const user = await services.users.create({
+      email: "buyer@example.com",
+      name: "Buyer",
+    });
+    await services.inventory.add("SKU-002", 1);
+
+    await expect(
+      services.orders.checkout({
+        userId: user.id,
+        items: [{ sku: "SKU-002", quantity: 5 }],
+      })
+    ).rejects.toThrow("Insufficient inventory");
+  });
+});
+```
+
+---
+
+## Testing Routes
+
+For route testing, use Bun's built-in fetch or create a test server.
+
+### Direct Handler Testing
+
+```ts
+// routes/users/users.test.ts
+import { describe, test, expect, beforeEach } from "bun:test";
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { usersPlugin } from "../../plugins/users";
+import { CreateUserHandler } from "./handlers/create-user";
+
+describe("CreateUserHandler", () => {
+  let ctx: Awaited<ReturnType<typeof createTestHarness>>["core"] & {
+    plugins: ReturnType<typeof manager.getServices>;
+  };
+
+  beforeEach(async () => {
+    const { manager, core } = await createTestHarness(usersPlugin);
+    ctx = {
+      ...core,
+      plugins: manager.getServices(),
+    };
+  });
+
+  test("creates user with valid input", async () => {
+    const handler = new CreateUserHandler(ctx as any);
+    const result = await handler.handle({
+      email: "new@example.com",
+      name: "New User",
+    });
+
+    expect(result.id).toBeDefined();
+    expect(result.email).toBe("new@example.com");
+  });
+});
+```
+
+### Full HTTP Testing
+
+```ts
+// tests/api.test.ts
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { AppServer } from "@donkeylabs/server";
+import { usersPlugin } from "../plugins/users";
+import { usersRouter } from "../routes/users";
+
+describe("Users API", () => {
+  let server: AppServer;
+  let baseUrl: string;
+
+  beforeAll(async () => {
+    server = new AppServer({
+      db: createTestDb(),
+      port: 0, // Random available port
+    });
+    server.registerPlugin(usersPlugin);
+    server.use(usersRouter);
+    await server.start();
+    baseUrl = `http://localhost:${server.port}`;
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  test("POST /users.create creates a user", async () => {
+    const response = await fetch(`${baseUrl}/users.create`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: "api@example.com",
+        name: "API User",
+      }),
+    });
+
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.id).toBeDefined();
+    expect(data.email).toBe("api@example.com");
+  });
+
+  test("POST /users.create returns 400 for invalid email", async () => {
+    const response = await fetch(`${baseUrl}/users.create`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: "not-an-email",
+        name: "Bad User",
+      }),
+    });
+
+    expect(response.status).toBe(400);
+  });
+});
+```
+
+---
+
+## Mocking Core Services
+
+The test harness provides real implementations, but you can mock specific services:
+
+```ts
+import { describe, test, expect, mock } from "bun:test";
+import { createTestHarness } from "@donkeylabs/server/harness";
+import { notificationsPlugin } from "./index";
+
+describe("notificationsPlugin with mocked email", () => {
+  test("sendEmail() is called with correct args", async () => {
+    const { manager, core } = await createTestHarness(notificationsPlugin);
+
+    // Mock the email sending function
+    const sendEmailMock = mock(() => Promise.resolve());
+    const notifications = manager.getServices().notifications;
+    notifications.sendEmail = sendEmailMock;
+
+    await notifications.notifyUser("user-123", "Hello!");
+
+    expect(sendEmailMock).toHaveBeenCalledTimes(1);
+    expect(sendEmailMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: expect.any(String),
+        subject: expect.stringContaining("Hello"),
+      })
+    );
+  });
+});
+```
+
+---
+
+## Test Organization
+
+### Recommended Structure
+
+```
+src/
+├── plugins/
+│   └── users/
+│       ├── index.ts
+│       ├── schema.ts
+│       ├── migrations/
+│       └── tests/
+│           ├── unit.test.ts      # Unit tests for service methods
+│           └── integ.test.ts     # Integration tests with other plugins
+├── routes/
+│   └── users/
+│       ├── index.ts
+│       ├── handlers/
+│       └── tests/
+│           └── api.test.ts       # Route/API tests
+└── tests/
+    └── e2e/                      # End-to-end tests
+        └── checkout.test.ts
+```
+
+### Naming Conventions
+
+- `*.test.ts` - Unit tests (run with `bun test`)
+- `*.integ.test.ts` - Integration tests
+- `*.e2e.test.ts` - End-to-end tests
+
+---
+
+## Running Tests
+
+```sh
+# Run all tests
+bun test
+
+# Run tests for a specific plugin
+bun test plugins/users
+
+# Run tests matching a pattern
+bun test --grep "create"
+
+# Run tests in watch mode
+bun test --watch
+
+# Run with coverage
+bun test --coverage
+```
+
+### Type Checking
+
+Always run type checking before committing:
+
+```sh
+bun --bun tsc --noEmit
+```
+
+### CI Pipeline Example
+
+```yaml
+# .github/workflows/test.yml
+name: Test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: bun install
+      - run: bun --bun tsc --noEmit
+      - run: bun test
+```
+
+---
+
+## Best Practices
+
+1. **Use fresh harness per test** - Create a new harness in `beforeEach` to ensure test isolation
+2. **Test the public API** - Focus on testing service methods, not internal implementation
+3. **Use realistic data** - Create test data that resembles production data
+4. **Test edge cases** - Empty inputs, null values, boundary conditions
+5. **Test error cases** - Verify proper error throwing and handling
+6. **Keep tests fast** - In-memory SQLite is fast; avoid unnecessary delays
+7. **Run type checks** - Always run `tsc --noEmit` before committing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",
@@ -30,6 +30,7 @@
   "files": [
     "src",
     "docs",
+    "CLAUDE.md",
     "context.d.ts",
     "registry.d.ts",
     "LICENSE",