@donkeylabs/server 1.1.18 → 1.1.19

package/CLAUDE.md

@@ -150,4 +150,8 @@ bun --bun tsc --noEmit    # Type check
 `get_project_info`, `create_plugin`, `add_migration`, `add_service_method`, `create_router`, `add_route`, `generate_types`, `list_plugins`, `scaffold_feature`
 
 ## Detailed Docs
-See `docs/` for: handlers, middleware, database, plugins, testing, jobs, external-jobs, processes, cron, sse, workflows, router, errors, sveltekit-adapter.
+**For comprehensive documentation, see the `docs/` directory.** Each service has its own detailed guide:
+- Core: logger, cache, events, cron, jobs, external-jobs, processes, workflows, sse, rate-limiter, errors
+- API: router, handlers, middleware
+- Server: lifecycle-hooks, services (custom services)
+- Infrastructure: database, plugins, testing, sveltekit-adapter, api-client

package/docs/core-services.md

@@ -339,3 +339,10 @@ See individual service documentation for adapter interfaces:
 - [Events Adapters](events.md#custom-adapters)
 - [Jobs Adapters](jobs.md#custom-adapters)
 - [Rate Limiter Adapters](rate-limiter.md#custom-adapters)
+
+---
+
+## Related Documentation
+
+- [Custom Services](services.md) - Register app-specific services with `defineService()`
+- [Lifecycle Hooks](lifecycle-hooks.md) - `onReady`, `onShutdown`, `onError` hooks

package/docs/lifecycle-hooks.md

@@ -0,0 +1,348 @@
+# Server Lifecycle Hooks
+
+Lifecycle hooks allow you to execute code at specific points in the server's lifecycle: after initialization, during shutdown, and when errors occur.
+
+## Overview
+
+| Hook | When Called | Use Case |
+|------|-------------|----------|
+| `onReady` | After server starts, plugins initialized | Initialize app-specific services, warm caches |
+| `onShutdown` | Before server stops | Cleanup connections, flush buffers |
+| `onError` | On unhandled errors | Error reporting, alerts |
+
+## onReady Hook
+
+Called after the server is fully initialized, plugins are ready, and the server is accepting requests.
+
+```typescript
+import { AppServer } from "@donkeylabs/server";
+
+const server = new AppServer({ db, port: 3000 });
+
+server.onReady(async (ctx) => {
+  console.log("Server is ready!");
+
+  // Access all services
+  ctx.core.logger.info("Server started", { port: 3000 });
+
+  // Initialize app-specific classes
+  const dashboard = new AdminDashboard(ctx.plugins.auth);
+  await dashboard.initialize();
+
+  // Register as a service for use in routes
+  ctx.setService("dashboard", dashboard);
+
+  // Warm caches
+  await ctx.core.cache.set("config", await loadConfig());
+
+  // Start background tasks
+  ctx.core.cron.schedule("0 * * * *", async () => {
+    await ctx.plugins.reports.generateHourly();
+  });
+});
+
+await server.start();
+```
+
+### HookContext
+
+The `onReady` callback receives a `HookContext` with:
+
+```typescript
+interface HookContext {
+  /** Database instance (Kysely) */
+  db: Kysely<any>;
+
+  /** Core services */
+  core: {
+    logger: Logger;
+    cache: Cache;
+    events: Events;
+    cron: Cron;
+    jobs: Jobs;
+    sse: SSE;
+    rateLimiter: RateLimiter;
+    errors: Errors;
+    workflows: Workflows;
+    processes: Processes;
+  };
+
+  /** Plugin services */
+  plugins: Record<string, any>;
+
+  /** Server configuration */
+  config: Record<string, any>;
+
+  /** Custom registered services */
+  services: Record<string, any>;
+
+  /** Register a service at runtime */
+  setService: <T>(name: string, service: T) => void;
+}
+```
+
+### Multiple onReady Handlers
+
+You can register multiple handlers - they execute in registration order:
+
+```typescript
+server.onReady(async (ctx) => {
+  // First: Initialize core dependencies
+  await initializeDatabase(ctx.db);
+});
+
+server.onReady(async (ctx) => {
+  // Second: Warm caches
+  await warmCaches(ctx);
+});
+
+server.onReady(async (ctx) => {
+  // Third: Start background jobs
+  ctx.core.jobs.start();
+});
+```
+
+## onShutdown Hook
+
+Called when the server is shutting down. Use for cleanup operations.
+
+```typescript
+server.onShutdown(async () => {
+  console.log("Server shutting down...");
+
+  // Close external connections
+  await externalApi.disconnect();
+
+  // Flush pending data
+  await analytics.flush();
+
+  // Save state
+  await saveCheckpoint();
+});
+```
+
+### Graceful Shutdown
+
+Enable automatic graceful shutdown on SIGTERM/SIGINT:
+
+```typescript
+server
+  .onShutdown(async () => {
+    await cleanup();
+  })
+  .enableGracefulShutdown(); // Handles SIGTERM and SIGINT
+
+await server.start();
+```
+
+With `enableGracefulShutdown()`:
+1. SIGTERM/SIGINT triggers shutdown
+2. Server stops accepting new requests
+3. Running requests complete (with timeout)
+4. `onShutdown` handlers execute
+5. Core services shut down (jobs, cron, SSE, processes)
+6. Process exits
+
+### Manual Shutdown
+
+You can also trigger shutdown programmatically:
+
+```typescript
+// Somewhere in your code
+await server.shutdown();
+```
+
+## onError Hook
+
+Called when an unhandled error occurs during request handling or in background tasks.
+
+```typescript
+server.onError(async (error, ctx) => {
+  // Log the error
+  ctx?.core.logger.error("Unhandled error", {
+    message: error.message,
+    stack: error.stack,
+  });
+
+  // Send to error tracking service
+  await errorTracker.capture(error, {
+    tags: { environment: process.env.NODE_ENV },
+  });
+
+  // Alert on critical errors
+  if (isCritical(error)) {
+    await ctx?.plugins.notifications.sendAlert({
+      channel: "ops",
+      message: `Critical error: ${error.message}`,
+    });
+  }
+});
+```
+
+**Note:** `ctx` may be undefined if the error occurs outside of a request context.
+
+## SvelteKit Adapter Usage
+
+Lifecycle hooks are especially useful with the SvelteKit adapter where you don't call `server.start()` directly:
+
+```typescript
+// src/server/index.ts
+import { AppServer } from "@donkeylabs/server";
+import { db } from "./db";
+
+export const server = new AppServer({ db })
+  .use(authPlugin)
+  .use(usersPlugin)
+  .router(usersRouter)
+
+  // Initialize app-specific services after plugins are ready
+  .onReady(async (ctx) => {
+    // This runs when SvelteKit starts
+    const nvr = new NVR(ctx.plugins.auth);
+    await nvr.connect();
+    ctx.setService("nvr", nvr);
+  })
+
+  // Cleanup when SvelteKit stops
+  .onShutdown(async () => {
+    await cleanup();
+  })
+
+  // Handle errors
+  .onError(async (error, ctx) => {
+    await reportError(error);
+  });
+
+// Export for SvelteKit adapter
+export type AppContext = typeof server extends AppServer<infer C> ? C : never;
+```
+
+## Complete Example
+
+```typescript
+import { AppServer, defineService } from "@donkeylabs/server";
+
+// Define services
+const cacheWarmerService = defineService("cacheWarmer", (ctx) => ({
+  warm: async () => {
+    const users = await ctx.db.selectFrom("users").selectAll().execute();
+    for (const user of users) {
+      await ctx.core.cache.set(`user:${user.id}`, user, 3600000);
+    }
+  },
+}));
+
+// Create server
+const server = new AppServer({
+  db,
+  port: 3000,
+  config: {
+    environment: process.env.NODE_ENV,
+  },
+});
+
+// Register plugins and services
+server
+  .use(authPlugin)
+  .use(usersPlugin)
+  .registerService(cacheWarmerService);
+
+// Lifecycle hooks
+server.onReady(async (ctx) => {
+  ctx.core.logger.info("Server ready", {
+    port: 3000,
+    environment: ctx.config.environment,
+  });
+
+  // Warm caches on startup
+  await ctx.services.cacheWarmer.warm();
+
+  // Schedule periodic cache warming
+  ctx.core.cron.schedule("*/30 * * * *", async () => {
+    await ctx.services.cacheWarmer.warm();
+  });
+});
+
+server.onShutdown(async () => {
+  console.log("Graceful shutdown initiated");
+  // Cleanup happens automatically for core services
+});
+
+server.onError(async (error, ctx) => {
+  console.error("Unhandled error:", error);
+  // Report to monitoring service
+});
+
+// Enable graceful shutdown and start
+server.enableGracefulShutdown();
+await server.start();
+
+console.log("Server running on http://localhost:3000");
+```
+
+## Best Practices
+
+### 1. Keep onReady Fast
+Don't block startup with heavy operations:
+
+```typescript
+// Good - async initialization
+server.onReady(async (ctx) => {
+  // Fire and forget for non-critical warmup
+  ctx.services.cacheWarmer.warm().catch(console.error);
+});
+
+// Avoid - blocking startup
+server.onReady(async (ctx) => {
+  // This delays server readiness
+  await heavyInitialization(); // 30 seconds...
+});
+```
+
+### 2. Handle Shutdown Timeouts
+Don't let shutdown hang indefinitely:
+
+```typescript
+server.onShutdown(async () => {
+  const timeout = setTimeout(() => {
+    console.error("Shutdown timeout - forcing exit");
+    process.exit(1);
+  }, 30000);
+
+  try {
+    await gracefulCleanup();
+  } finally {
+    clearTimeout(timeout);
+  }
+});
+```
+
+### 3. Order Matters
+Hooks execute in registration order. Register dependencies first:
+
+```typescript
+// First: Initialize the connection
+server.onReady(async (ctx) => {
+  const conn = await createConnection();
+  ctx.setService("conn", conn);
+});
+
+// Second: Use the connection
+server.onReady(async (ctx) => {
+  await ctx.services.conn.ping(); // conn is available
+});
+```
+
+### 4. Error Handling in Hooks
+Errors in hooks can prevent startup or cleanup:
+
+```typescript
+server.onReady(async (ctx) => {
+  try {
+    await riskyOperation();
+  } catch (error) {
+    ctx.core.logger.error("Non-critical init failed", { error });
+    // Don't rethrow - allow server to start
+  }
+});
+```

package/docs/services.md

@@ -0,0 +1,256 @@
+# Custom Services
+
+Custom services allow you to register application-specific dependencies that integrate with the server's context system. Services are available in route handlers via `ctx.services` with full type inference.
+
+## Overview
+
+Use custom services when you need to:
+- Initialize app-specific classes that depend on plugins
+- Share stateful instances across route handlers
+- Integrate third-party SDKs with type safety
+- Create domain-specific facades over core services
+
+## Defining a Service
+
+Use `defineService()` to create a type-safe service definition:
+
+```typescript
+// src/server/services/nvr.ts
+import { defineService } from "@donkeylabs/server";
+import { NVRClient } from "./nvr-client";
+
+export const nvrService = defineService("nvr", async (ctx) => {
+  // Access plugins, db, core services during initialization
+  const nvr = new NVRClient({
+    authProvider: ctx.plugins.auth,
+    logger: ctx.core.logger,
+  });
+
+  await nvr.connect();
+  return nvr;
+});
+```
+
+The factory function receives `HookContext` which provides:
+- `ctx.db` - Database instance (Kysely)
+- `ctx.core` - Core services (logger, cache, events, jobs, etc.)
+- `ctx.plugins` - Plugin services
+- `ctx.config` - Server configuration
+- `ctx.services` - Other registered services
+
+## Registering Services
+
+Register services with the server before starting:
+
+```typescript
+// src/server/index.ts
+import { AppServer } from "@donkeylabs/server";
+import { nvrService } from "./services/nvr";
+import { analyticsService } from "./services/analytics";
+
+const server = new AppServer({ db, port: 3000 });
+
+// Register using service definition (recommended)
+server.registerService(nvrService);
+server.registerService(analyticsService);
+
+// Or register inline
+server.registerService("cache-warmer", async (ctx) => {
+  return new CacheWarmer(ctx.core.cache);
+});
+
+await server.start();
+```
+
+## Using Services in Routes
+
+Services are available via `ctx.services` in route handlers:
+
+```typescript
+router.route("recordings").typed({
+  input: z.object({ cameraId: z.string() }),
+  output: recordingsSchema,
+  handle: async (input, ctx) => {
+    // Fully typed - ctx.services.nvr has proper type inference
+    return ctx.services.nvr.getRecordings(input.cameraId);
+  },
+});
+```
+
+## Type Generation
+
+When you run `donkeylabs generate`, the CLI scans for `defineService()` calls and generates types automatically. The generated `ServiceRegistry` interface includes all your services:
+
+```typescript
+// Generated in context.d.ts
+declare module "@donkeylabs/server" {
+  interface ServiceRegistry {
+    nvr: NVRClient;
+    analytics: AnalyticsService;
+  }
+}
+```
+
+### Service Definition Locations
+
+The CLI scans these locations for service definitions:
+- `src/server/services/*.ts`
+- `src/lib/services/*.ts`
+- Server entry file (e.g., `src/server/index.ts`)
+
+## Runtime Registration
+
+You can also register services at runtime in `onReady` hooks:
+
+```typescript
+server.onReady(async (ctx) => {
+  // Initialize something that needs the full context
+  const dashboard = new AdminDashboard(ctx.plugins, ctx.core);
+  await dashboard.initialize();
+
+  // Register it as a service
+  ctx.setService("dashboard", dashboard);
+});
+```
+
+Services registered via `setService()` are immediately available but won't have generated types (use `defineService()` for type generation).
+
+## Service Dependencies
+
+Services can depend on other services by accessing them in the factory:
+
+```typescript
+export const reportService = defineService("reports", async (ctx) => {
+  // Depend on another service (must be registered first)
+  const analytics = ctx.services.analytics;
+
+  return new ReportGenerator(analytics, ctx.core.cache);
+});
+```
+
+**Important:** Register services in dependency order. If service B depends on service A, register A first.
+
+## Best Practices
+
+### 1. Keep Services Focused
+Each service should have a single responsibility:
+
+```typescript
+// Good - focused service
+export const emailService = defineService("email", (ctx) => ({
+  send: (to, subject, body) => sendEmail(to, subject, body),
+  sendTemplate: (to, template, data) => sendTemplate(to, template, data),
+}));
+
+// Avoid - too many responsibilities
+export const everythingService = defineService("everything", (ctx) => ({
+  sendEmail: ...,
+  processPayment: ...,
+  generateReport: ...,
+}));
+```
+
+### 2. Handle Cleanup
+If your service needs cleanup, use `onShutdown`:
+
+```typescript
+export const connectionPoolService = defineService("pool", async (ctx) => {
+  const pool = await createPool();
+
+  // Register cleanup
+  // Note: You'll need to handle this in your server setup
+  return pool;
+});
+
+// In server setup
+server.registerService(connectionPoolService);
+server.onShutdown(async () => {
+  await server.getServices().pool?.close();
+});
+```
+
+### 3. Use Plugins for Reusable Logic
+Services are app-specific. For reusable business logic, use plugins instead:
+
+```typescript
+// Use a plugin for reusable auth logic
+export const authPlugin = createPlugin.define({
+  name: "auth",
+  service: (ctx) => ({ ... }),
+});
+
+// Use a service for app-specific integrations
+export const myAppService = defineService("myApp", (ctx) => {
+  // Uses the auth plugin
+  return new MyAppIntegration(ctx.plugins.auth);
+});
+```
+
+## Example: Full Service Setup
+
+```typescript
+// services/analytics.ts
+import { defineService } from "@donkeylabs/server";
+import { AnalyticsSDK } from "analytics-sdk";
+
+export class AnalyticsService {
+  private sdk: AnalyticsSDK;
+
+  constructor(apiKey: string, logger: Logger) {
+    this.sdk = new AnalyticsSDK(apiKey);
+    this.logger = logger;
+  }
+
+  track(event: string, properties: Record<string, any>) {
+    this.logger.debug("Tracking event", { event, properties });
+    return this.sdk.track(event, properties);
+  }
+
+  identify(userId: string, traits: Record<string, any>) {
+    return this.sdk.identify(userId, traits);
+  }
+}
+
+export const analyticsService = defineService("analytics", (ctx) => {
+  const apiKey = ctx.config.analyticsApiKey;
+  if (!apiKey) {
+    ctx.core.logger.warn("Analytics API key not configured");
+    return null;
+  }
+
+  return new AnalyticsService(apiKey, ctx.core.logger);
+});
+```
+
+```typescript
+// server/index.ts
+import { AppServer } from "@donkeylabs/server";
+import { analyticsService } from "./services/analytics";
+
+const server = new AppServer({
+  db,
+  port: 3000,
+  config: {
+    analyticsApiKey: process.env.ANALYTICS_API_KEY,
+  },
+});
+
+server.registerService(analyticsService);
+
+// Use in routes
+router.route("signup").typed({
+  input: signupSchema,
+  output: userSchema,
+  handle: async (input, ctx) => {
+    const user = await ctx.plugins.users.create(input);
+
+    // Track signup event
+    ctx.services.analytics?.track("user.signup", {
+      userId: user.id,
+      email: user.email,
+    });
+
+    return user;
+  },
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "1.1.18",
+  "version": "1.1.19",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",