@donkeylabs/server 2.0.4 → 2.0.6

package/docs/logger.md

@@ -23,6 +23,7 @@ interface Logger {
   warn(message: string, data?: Record<string, any>): void;
   error(message: string, data?: Record<string, any>): void;
   child(context: Record<string, any>): Logger;
+  tag(name: string): Logger;  // Create tagged child logger
 }
 ```
 
@@ -81,23 +82,62 @@ router.route("checkout").typed({
 });
 ```
 
+### Tagged Loggers
+
+Tags add colored prefixes to log messages for visual organization. Each tag gets a consistent color.
+
+```ts
+// Create tagged logger
+const dbLog = ctx.core.logger.tag("database");
+dbLog.info("Query executed");
+// Output: 12:34:56.789 INFO  [database] Query executed
+
+// Chain multiple tags
+const queryLog = dbLog.tag("slow-query");
+queryLog.warn("Query took 5s", { table: "orders" });
+// Output: 12:34:56.790 WARN  [database] [slow-query] Query took 5s {"table":"orders"}
+```
+
+**Plugin Auto-Tagging:** Plugins automatically get a tagged logger with the plugin name:
+
+```ts
+// In plugin service - ctx.core.logger is auto-tagged with plugin name
+export const ordersPlugin = createPlugin.define({
+  name: "orders",
+  service: async (ctx) => {
+    // Logger is already tagged with [orders]
+    ctx.core.logger.info("Plugin initialized");
+    // Output: 12:34:56.789 INFO  [orders] Plugin initialized
+
+    // Add additional tags as needed
+    const paymentLog = ctx.core.logger.tag("payments");
+    paymentLog.info("Processing");
+    // Output: 12:34:56.790 INFO  [orders] [payments] Processing
+
+    return {
+      create: async (data) => {
+        ctx.core.logger.info("Creating order", { total: data.total });
+        // Output: 12:34:56.791 INFO  [orders] Creating order {"total":100}
+      },
+    };
+  },
+});
+```
+
 ### Child Loggers
 
-Child loggers inherit parent settings and add persistent context:
+Child loggers inherit parent settings and add persistent context data (not visible as tags):
 
 ```ts
 // In plugin initialization
 service: async (ctx) => {
-  // Create logger with plugin context
-  const log = ctx.core.logger.child({ plugin: "payments" });
-
   return {
     async processPayment(orderId: string) {
-      // Create request-specific logger
-      const requestLog = log.child({ orderId });
+      // Create request-specific logger with context
+      const requestLog = ctx.core.logger.child({ orderId });
 
       requestLog.info("Processing payment");
-      // Logs: { plugin: "payments", orderId: "123", ... }
+      // Output: 12:34:56.789 INFO  [payments] Processing payment {"orderId":"123"}
 
       requestLog.debug("Validating card");
       requestLog.info("Payment complete");
@@ -146,20 +186,24 @@ const requestLogger = createMiddleware(async (req, ctx, next) => {
 
 ### Pretty Format (Default)
 
-Human-readable colored output for development:
+Human-readable colored output for development. Tags appear as colored `[tag]` prefixes:
 
 ```
-[12:34:56.789] INFO  User logged in {"userId":123}
-[12:34:56.790] ERROR Payment failed {"orderId":456,"error":"Insufficient funds"}
+12:34:56.789 INFO  User logged in {"userId":123}
+12:34:56.790 ERROR [orders] Payment failed {"orderId":456,"error":"Insufficient funds"}
+12:34:56.791 WARN  [orders] [payments] Retry attempt {"attempt":3}
 ```
 
+Each tag gets a consistent color (cyan, magenta, green, yellow, blue, red) that persists across the application lifetime.
+
 ### JSON Format
 
-Structured JSON for production log aggregation:
+Structured JSON for production log aggregation. Tags are included as an array:
 
 ```json
 {"timestamp":"2024-01-15T12:34:56.789Z","level":"info","message":"User logged in","userId":123}
-{"timestamp":"2024-01-15T12:34:56.790Z","level":"error","message":"Payment failed","orderId":456,"error":"Insufficient funds"}
+{"timestamp":"2024-01-15T12:34:56.790Z","level":"error","message":"Payment failed","tags":["orders"],"orderId":456,"error":"Insufficient funds"}
+{"timestamp":"2024-01-15T12:34:56.791Z","level":"warn","message":"Retry attempt","tags":["orders","payments"],"attempt":3}
 ```
 
 ---
@@ -296,6 +340,7 @@ interface LogEntry {
   timestamp: Date;
   level: "debug" | "info" | "warn" | "error";
   message: string;
+  tags?: string[];                // From tag() - displayed as colored prefixes
   data?: Record<string, any>;     // Per-call data
   context?: Record<string, any>;  // From child logger
 }

package/package.json

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

package/src/core/logger.ts

@@ -1,5 +1,7 @@
 // Core Logger Service
-// Structured logging with levels and child loggers
+// Structured logging with levels, tags, and child loggers
+
+import pc from "picocolors";
 
 export type LogLevel = "debug" | "info" | "warn" | "error";
 
@@ -7,6 +9,7 @@ export interface LogEntry {
   timestamp: Date;
   level: LogLevel;
   message: string;
+  tags?: string[];
   data?: Record<string, any>;
   context?: Record<string, any>;
 }
@@ -27,6 +30,8 @@ export interface Logger {
   warn(message: string, data?: Record<string, any>): void;
   error(message: string, data?: Record<string, any>): void;
   child(context: Record<string, any>): Logger;
+  /** Create a tagged child logger with colored prefix */
+  tag(name: string): Logger;
 }
 
 const LOG_LEVELS: Record<LogLevel, number> = {
@@ -36,14 +41,39 @@ const LOG_LEVELS: Record<LogLevel, number> = {
   error: 3,
 };
 
-const LEVEL_COLORS: Record<LogLevel, string> = {
-  debug: "\x1b[90m", // gray
-  info: "\x1b[36m",  // cyan
-  warn: "\x1b[33m",  // yellow
-  error: "\x1b[31m", // red
-};
+// Tag color palette - cycles through these for auto-assigned colors
+const TAG_COLORS: ((s: string) => string)[] = [
+  pc.cyan,
+  pc.magenta,
+  pc.green,
+  pc.yellow,
+  pc.blue,
+  pc.red,
+];
+
+// Cache for consistent tag colors across the app
+const tagColorCache = new Map<string, (s: string) => string>();
+let colorIndex = 0;
+
+/**
+ * Get a consistent color for a tag name.
+ * Same tag always gets the same color within a process.
+ */
+function getTagColor(tag: string): (s: string) => string {
+  if (!tagColorCache.has(tag)) {
+    tagColorCache.set(tag, TAG_COLORS[colorIndex % TAG_COLORS.length]!);
+    colorIndex++;
+  }
+  return tagColorCache.get(tag)!;
+}
 
-const RESET = "\x1b[0m";
+// Level colors using picocolors
+const LEVEL_COLORS: Record<LogLevel, (s: string) => string> = {
+  debug: pc.gray,
+  info: pc.blue,
+  warn: pc.yellow,
+  error: pc.red,
+};
 
 // Console transport with pretty or JSON formatting
 export class ConsoleTransport implements LogTransport {
@@ -55,19 +85,30 @@ export class ConsoleTransport implements LogTransport {
         timestamp: entry.timestamp.toISOString(),
         level: entry.level,
         message: entry.message,
+        tags: entry.tags,
         ...entry.data,
         ...entry.context,
       }));
     } else {
-      const color = LEVEL_COLORS[entry.level];
-      const time = entry.timestamp.toISOString().slice(11, 23);
-      const level = entry.level.toUpperCase().padEnd(5);
+      const levelColor = LEVEL_COLORS[entry.level];
+      const time = pc.dim(entry.timestamp.toISOString().slice(11, 23));
+      const level = levelColor(entry.level.toUpperCase().padEnd(5));
+
+      // Build tag prefix with colors
+      let tagPrefix = "";
+      if (entry.tags && entry.tags.length > 0) {
+        const tagParts = entry.tags.map(tag => {
+          const colorFn = getTagColor(tag);
+          return colorFn(`[${tag}]`);
+        });
+        tagPrefix = tagParts.join(" ") + " ";
+      }
 
-      let output = `${color}[${time}] ${level}${RESET} ${entry.message}`;
+      let output = `${time} ${level} ${tagPrefix}${entry.message}`;
 
       const extra = { ...entry.data, ...entry.context };
       if (Object.keys(extra).length > 0) {
-        output += ` ${"\x1b[90m"}${JSON.stringify(extra)}${RESET}`;
+        output += ` ${pc.dim(JSON.stringify(extra))}`;
       }
 
       console.log(output);
@@ -79,11 +120,17 @@ class LoggerImpl implements Logger {
   private minLevel: number;
   private transports: LogTransport[];
   private context: Record<string, any>;
+  private tags: string[];
 
-  constructor(config: LoggerConfig = {}, context: Record<string, any> = {}) {
+  constructor(
+    config: LoggerConfig = {},
+    context: Record<string, any> = {},
+    tags: string[] = []
+  ) {
     this.minLevel = LOG_LEVELS[config.level ?? "info"];
     this.transports = config.transports ?? [new ConsoleTransport(config.format ?? "pretty")];
     this.context = context;
+    this.tags = tags;
   }
 
   private log(level: LogLevel, message: string, data?: Record<string, any>): void {
@@ -93,6 +140,7 @@ class LoggerImpl implements Logger {
       timestamp: new Date(),
       level,
       message,
+      tags: this.tags.length > 0 ? this.tags : undefined,
       data,
       context: Object.keys(this.context).length > 0 ? this.context : undefined,
     };
@@ -119,9 +167,24 @@ class LoggerImpl implements Logger {
   }
 
   child(context: Record<string, any>): Logger {
+    const levelKey = Object.keys(LOG_LEVELS).find(
+      k => LOG_LEVELS[k as LogLevel] === this.minLevel
+    ) as LogLevel;
+    return new LoggerImpl(
+      { level: levelKey, transports: this.transports },
+      { ...this.context, ...context },
+      [...this.tags]
+    );
+  }
+
+  tag(name: string): Logger {
+    const levelKey = Object.keys(LOG_LEVELS).find(
+      k => LOG_LEVELS[k as LogLevel] === this.minLevel
+    ) as LogLevel;
     return new LoggerImpl(
-      { level: Object.keys(LOG_LEVELS).find(k => LOG_LEVELS[k as LogLevel] === this.minLevel) as LogLevel, transports: this.transports },
-      { ...this.context, ...context }
+      { level: levelKey, transports: this.transports },
+      { ...this.context },
+      [...this.tags, name]
     );
   }
 }

package/src/core/sse.ts

@@ -58,6 +58,10 @@ class SSEImpl implements SSE {
         // Send retry interval to client
         const retryMsg = `retry: ${this.retryInterval}\n\n`;
         controller.enqueue(this.encoder.encode(retryMsg));
+
+        // Send immediate heartbeat to establish connection and prevent early timeout
+        const heartbeat = `: heartbeat ${Date.now()}\n\n`;
+        controller.enqueue(this.encoder.encode(heartbeat));
       },
       cancel: () => {
         this.removeClient(id);

package/src/core.ts

@@ -157,14 +157,34 @@ export interface GlobalContext {
 }
 
 export class PluginContext<Deps = any, Schema = any, Config = void> {
+  private _core: CoreServices;
+  private _taggedCore?: CoreServices;
+  private _pluginName?: string;
+
   constructor(
-    public readonly core: CoreServices,
+    core: CoreServices,
     public readonly deps: Deps,
-    public readonly config: Config
-  ) {}
+    public readonly config: Config,
+    pluginName?: string
+  ) {
+    this._core = core;
+    this._pluginName = pluginName;
+  }
+
+  /** Core services with auto-tagged logger for the plugin */
+  get core(): CoreServices {
+    // Lazily create tagged core services
+    if (!this._taggedCore && this._pluginName) {
+      this._taggedCore = {
+        ...this._core,
+        logger: this._core.logger.tag(this._pluginName),
+      };
+    }
+    return this._taggedCore || this._core;
+  }
 
   get db(): Kysely<Schema> {
-    return this.core.db as unknown as Kysely<Schema>;
+    return this._core.db as unknown as Kysely<Schema>;
   }
 }
 
@@ -676,7 +696,7 @@ export class PluginManager {
         }
 
         const pluginConfig = (plugin as ConfiguredPlugin)._boundConfig;
-        const ctx = new PluginContext(this.core, pluginDeps, pluginConfig);
+        const ctx = new PluginContext(this.core, pluginDeps, pluginConfig, plugin.name);
         const service = await plugin.service(ctx);
 
         if (service) {