@logtape/koa 1.3.4 → 1.4.0-dev.409

package/deno.json

@@ -0,0 +1,34 @@
+{
+  "name": "@logtape/koa",
+  "version": "1.4.0-dev.409+63c2cd45",
+  "license": "MIT",
+  "exports": "./src/mod.ts",
+  "exclude": [
+    "coverage/",
+    "npm/",
+    "dist/"
+  ],
+  "tasks": {
+    "build": "pnpm build",
+    "test": "deno test --allow-env --allow-sys --allow-net",
+    "test:node": {
+      "dependencies": [
+        "build"
+      ],
+      "command": "node --experimental-transform-types --test"
+    },
+    "test:bun": {
+      "dependencies": [
+        "build"
+      ],
+      "command": "bun test"
+    },
+    "test-all": {
+      "dependencies": [
+        "test",
+        "test:node",
+        "test:bun"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/koa",
-  "version": "1.3.4",
+  "version": "1.4.0-dev.409+63c2cd45",
   "description": "Koa adapter for LogTape logging library",
   "keywords": [
     "logging",
@@ -47,12 +47,9 @@
     "./package.json": "./package.json"
   },
   "sideEffects": false,
-  "files": [
-    "dist/"
-  ],
   "peerDependencies": {
     "koa": "^2.0.0 || ^3.0.0",
-    "@logtape/logtape": "^1.3.4"
+    "@logtape/logtape": "^1.4.0-dev.409+63c2cd45"
   },
   "devDependencies": {
     "@alinea/suite": "^0.6.3",

package/src/mod.test.ts

@@ -0,0 +1,727 @@
+import { suite } from "@alinea/suite";
+import { assert, assertEquals, assertExists } from "@std/assert";
+import { configure, type LogRecord, reset } from "@logtape/logtape";
+import { type KoaContext, koaLogger, type KoaMiddleware } from "./mod.ts";
+
+const test = suite(import.meta);
+
+// Test fixture: Collect log records, filtering out internal LogTape meta logs
+function createTestSink(): {
+  sink: (record: LogRecord) => void;
+  logs: LogRecord[];
+} {
+  const logs: LogRecord[] = [];
+  return {
+    sink: (record: LogRecord) => {
+      if (record.category[0] !== "logtape") {
+        logs.push(record);
+      }
+    },
+    logs,
+  };
+}
+
+// Setup helper
+async function setupLogtape(): Promise<{
+  logs: LogRecord[];
+  cleanup: () => Promise<void>;
+}> {
+  const { sink, logs } = createTestSink();
+  await configure({
+    sinks: { test: sink },
+    loggers: [{ category: [], sinks: ["test"] }],
+  });
+  return { logs, cleanup: () => reset() };
+}
+
+// Mock Koa context
+function createMockContext(overrides: Partial<KoaContext> = {}): KoaContext {
+  return {
+    method: "GET",
+    url: "/test",
+    path: "/test",
+    status: 200,
+    ip: "127.0.0.1",
+    response: {
+      length: undefined,
+    },
+    get: (field: string) => {
+      const headers: Record<string, string> = {
+        "user-agent": "test-agent/1.0",
+        "referer": "http://example.com",
+        "referrer": "http://example.com",
+      };
+      return headers[field.toLowerCase()] ?? "";
+    },
+    ...overrides,
+  };
+}
+
+// Helper to run middleware
+async function runMiddleware(
+  middleware: KoaMiddleware,
+  ctx: KoaContext,
+  next: () => Promise<void> = async () => {},
+): Promise<void> {
+  await middleware(ctx, next);
+}
+
+// ============================================
+// Basic Middleware Creation Tests
+// ============================================
+
+test("koaLogger(): creates a middleware function", async () => {
+  const { cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    assertEquals(typeof middleware, "function");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs request after response", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Category Configuration Tests
+// ============================================
+
+test("koaLogger(): uses default category ['koa']", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].category, ["koa"]);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): uses custom category array", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ category: ["myapp", "http"] });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].category, ["myapp", "http"]);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): accepts string category", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ category: "myapp" });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].category, ["myapp"]);
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Log Level Tests
+// ============================================
+
+test("koaLogger(): uses default log level 'info'", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].level, "info");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): uses custom log level 'debug'", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ level: "debug" });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].level, "debug");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): uses custom log level 'warning'", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ level: "warning" });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].level, "warning");
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Format Tests - Combined (default)
+// ============================================
+
+test("koaLogger(): combined format logs structured properties", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ format: "combined" });
+    const ctx = createMockContext({
+      response: { length: 123 },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    const props = logs[0].properties;
+    assertEquals(props.method, "GET");
+    assertEquals(props.url, "/test");
+    assertEquals(props.path, "/test");
+    assertEquals(props.status, 200);
+    assertExists(props.responseTime);
+    assertEquals(props.contentLength, 123);
+    assertEquals(props.remoteAddr, "127.0.0.1");
+    assertEquals(props.userAgent, "test-agent/1.0");
+    assertEquals(props.referrer, "http://example.com");
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Format Tests - Common
+// ============================================
+
+test("koaLogger(): common format excludes referrer and userAgent", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ format: "common" });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    const props = logs[0].properties;
+    assertEquals(props.method, "GET");
+    assertEquals(props.path, "/test");
+    assertEquals(props.status, 200);
+    assertEquals(props.referrer, undefined);
+    assertEquals(props.userAgent, undefined);
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Format Tests - Dev
+// ============================================
+
+test("koaLogger(): dev format returns string message", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ format: "dev" });
+    const ctx = createMockContext({
+      method: "POST",
+      path: "/api/users",
+      status: 201,
+      response: { length: 456 },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    const msg = logs[0].rawMessage;
+    assert(msg.includes("POST"));
+    assert(msg.includes("/api/users"));
+    assert(msg.includes("201"));
+    assert(msg.includes("ms"));
+    assert(msg.includes("456"));
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Format Tests - Short
+// ============================================
+
+test("koaLogger(): short format includes remote addr", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ format: "short" });
+    const ctx = createMockContext({
+      ip: "192.168.1.1",
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    const msg = logs[0].rawMessage;
+    assert(msg.includes("192.168.1.1"));
+    assert(msg.includes("GET"));
+    assert(msg.includes("/test"));
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Format Tests - Tiny
+// ============================================
+
+test("koaLogger(): tiny format is minimal", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ format: "tiny" });
+    const ctx = createMockContext({ status: 404 });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    const msg = logs[0].rawMessage;
+    assert(msg.includes("GET"));
+    assert(msg.includes("/test"));
+    assert(msg.includes("404"));
+    assert(msg.includes("ms"));
+    // Tiny format should NOT include remote addr
+    assert(!msg.includes("127.0.0.1"));
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Custom Format Function Tests
+// ============================================
+
+test("koaLogger(): custom format returning string", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({
+      format: (ctx: KoaContext, _responseTime: number) =>
+        `Custom: ${ctx.method} ${ctx.status}`,
+    });
+    const ctx = createMockContext({ method: "DELETE", status: 204 });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].rawMessage, "Custom: DELETE 204");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): custom format returning object", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({
+      format: (ctx: KoaContext, responseTime: number) => ({
+        customMethod: ctx.method,
+        customStatus: ctx.status,
+        customDuration: responseTime,
+      }),
+    });
+    const ctx = createMockContext({ method: "PATCH", status: 202 });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.customMethod, "PATCH");
+    assertEquals(logs[0].properties.customStatus, 202);
+    assertExists(logs[0].properties.customDuration);
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Skip Function Tests
+// ============================================
+
+test("koaLogger(): skip function prevents logging when returns true", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({
+      skip: () => true,
+    });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 0);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): skip function allows logging when returns false", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({
+      skip: () => false,
+    });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): skip function receives context", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({
+      skip: (ctx: KoaContext) => ctx.path === "/health",
+    });
+
+    // Health endpoint should be skipped
+    const healthCtx = createMockContext({ path: "/health" });
+    await runMiddleware(middleware, healthCtx);
+    assertEquals(logs.length, 0);
+
+    // Other endpoints should be logged
+    const testCtx = createMockContext({ path: "/test" });
+    await runMiddleware(middleware, testCtx);
+    assertEquals(logs.length, 1);
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// logRequest (Immediate) Mode Tests
+// ============================================
+
+test("koaLogger(): logRequest mode logs at request start", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ logRequest: true });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.responseTime, 0); // Zero because it's immediate
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): non-logRequest mode logs after response", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger({ logRequest: false });
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx, async () => {
+      // Small delay to ensure non-zero response time
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    });
+
+    assertEquals(logs.length, 1);
+    assert((logs[0].properties.responseTime as number) >= 0);
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Request Property Tests
+// ============================================
+
+test("koaLogger(): logs correct method", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+
+    const methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"];
+    for (const method of methods) {
+      const ctx = createMockContext({ method });
+      await runMiddleware(middleware, ctx);
+    }
+
+    assertEquals(logs.length, methods.length);
+    for (let i = 0; i < methods.length; i++) {
+      assertEquals(logs[i].properties.method, methods[i]);
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs path correctly", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({ path: "/api/v1/users" });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.path, "/api/v1/users");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs status code", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+
+    const statusCodes = [200, 201, 301, 400, 404, 500];
+    for (const status of statusCodes) {
+      const ctx = createMockContext({ status });
+      await runMiddleware(middleware, ctx);
+    }
+
+    assertEquals(logs.length, statusCodes.length);
+    for (let i = 0; i < statusCodes.length; i++) {
+      assertEquals(logs[i].properties.status, statusCodes[i]);
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs response time as number", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext();
+
+    await runMiddleware(middleware, ctx, async () => {
+      // Add small delay to ensure non-zero response time
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    assertEquals(logs.length, 1);
+    assertEquals(typeof logs[0].properties.responseTime, "number");
+    assert((logs[0].properties.responseTime as number) >= 0);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs content-length when present", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      response: { length: 1024 },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.contentLength, 1024);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs undefined contentLength when not set", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      response: { length: undefined },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.contentLength, undefined);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs remote address from ctx.ip", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      ip: "10.0.0.1",
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.remoteAddr, "10.0.0.1");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs user agent", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      get: (field: string) => {
+        if (field.toLowerCase() === "user-agent") return "TestClient/1.0";
+        return "";
+      },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.userAgent, "TestClient/1.0");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): logs referrer", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      get: (field: string) => {
+        if (field.toLowerCase() === "referer") {
+          return "https://example.com/page";
+        }
+        if (field.toLowerCase() === "referrer") {
+          return "https://example.com/page";
+        }
+        return "";
+      },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.referrer, "https://example.com/page");
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Multiple Requests Tests
+// ============================================
+
+test("koaLogger(): handles multiple sequential requests", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+
+    for (let i = 0; i < 5; i++) {
+      const ctx = createMockContext({
+        path: `/path/${i}`,
+        url: `/path/${i}`,
+        status: 200 + i,
+      });
+      await runMiddleware(middleware, ctx);
+    }
+
+    assertEquals(logs.length, 5);
+    for (let i = 0; i < 5; i++) {
+      assertEquals(logs[i].properties.path, `/path/${i}`);
+      assertEquals(logs[i].properties.status, 200 + i);
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+// ============================================
+// Edge Cases
+// ============================================
+
+test("koaLogger(): handles missing user-agent", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      get: () => "",
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.userAgent, undefined);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): handles missing referrer", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      get: (field: string) => {
+        if (field.toLowerCase() === "user-agent") return "test-agent";
+        return "";
+      },
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.referrer, undefined);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("koaLogger(): handles query parameters in url", async () => {
+  const { logs, cleanup } = await setupLogtape();
+  try {
+    const middleware = koaLogger();
+    const ctx = createMockContext({
+      path: "/search",
+      url: "/search?q=test&limit=10",
+    });
+
+    await runMiddleware(middleware, ctx);
+
+    assertEquals(logs.length, 1);
+    assertEquals(logs[0].properties.path, "/search");
+    assert((logs[0].properties.url as string).includes("q=test"));
+    assert((logs[0].properties.url as string).includes("limit=10"));
+  } finally {
+    await cleanup();
+  }
+});

package/src/mod.ts

@@ -0,0 +1,392 @@
+import { getLogger, type LogLevel } from "@logtape/logtape";
+
+export type { LogLevel } from "@logtape/logtape";
+
+/**
+ * Minimal Koa Context interface for compatibility across Koa 2.x and 3.x.
+ *
+ * This interface includes common aliases available on the Koa context object.
+ * See https://koajs.com/#context for the full API.
+ *
+ * @since 1.3.0
+ */
+export interface KoaContext {
+  /** HTTP request method (alias for ctx.request.method) */
+  method: string;
+  /** Request URL (alias for ctx.request.url) */
+  url: string;
+  /** Request pathname (alias for ctx.request.path) */
+  path: string;
+  /** HTTP response status code (alias for ctx.response.status) */
+  status: number;
+  /** Remote client IP address (alias for ctx.request.ip) */
+  ip: string;
+  /** Koa Response object */
+  response: {
+    length?: number;
+  };
+  /**
+   * Get a request header field value (case-insensitive).
+   * @param field The header field name.
+   * @returns The header value, or an empty string if not present.
+   */
+  get(field: string): string;
+}
+
+/**
+ * Koa middleware function type.
+ * @since 1.3.0
+ */
+export type KoaMiddleware = (
+  ctx: KoaContext,
+  next: () => Promise<void>,
+) => Promise<void>;
+
+/**
+ * Predefined log format names compatible with Morgan.
+ * @since 1.3.0
+ */
+export type PredefinedFormat = "combined" | "common" | "dev" | "short" | "tiny";
+
+/**
+ * Custom format function for request logging.
+ *
+ * @param ctx The Koa context object.
+ * @param responseTime The response time in milliseconds.
+ * @returns A string message or an object with structured properties.
+ * @since 1.3.0
+ */
+export type FormatFunction = (
+  ctx: KoaContext,
+  responseTime: number,
+) => string | Record<string, unknown>;
+
+/**
+ * Structured log properties for HTTP requests.
+ * @since 1.3.0
+ */
+export interface RequestLogProperties {
+  /** HTTP request method */
+  method: string;
+  /** Request URL */
+  url: string;
+  /** Request path */
+  path: string;
+  /** HTTP response status code */
+  status: number;
+  /** Response time in milliseconds */
+  responseTime: number;
+  /** Response content-length */
+  contentLength: number | undefined;
+  /** Remote client address */
+  remoteAddr: string | undefined;
+  /** User-Agent header value */
+  userAgent: string | undefined;
+  /** Referrer header value */
+  referrer: string | undefined;
+}
+
+/**
+ * Options for configuring the Koa LogTape middleware.
+ * @since 1.3.0
+ */
+export interface KoaLogTapeOptions {
+  /**
+   * The LogTape category to use for logging.
+   * @default ["koa"]
+   */
+  readonly category?: string | readonly string[];
+
+  /**
+   * The log level to use for request logging.
+   * @default "info"
+   */
+  readonly level?: LogLevel;
+
+  /**
+   * The format for log output.
+   * Can be a predefined format name or a custom format function.
+   *
+   * Predefined formats:
+   * - `"combined"` - Apache Combined Log Format (structured, default)
+   * - `"common"` - Apache Common Log Format (structured, no referrer/userAgent)
+   * - `"dev"` - Concise colored output for development (string)
+   * - `"short"` - Shorter than common (string)
+   * - `"tiny"` - Minimal output (string)
+   *
+   * @default "combined"
+   */
+  readonly format?: PredefinedFormat | FormatFunction;
+
+  /**
+   * Function to determine whether logging should be skipped.
+   * Return `true` to skip logging for a request.
+   *
+   * @example Skip logging for health check endpoint
+   * ```typescript
+   * app.use(koaLogger({
+   *   skip: (ctx) => ctx.path === "/health",
+   * }));
+   * ```
+   *
+   * @default () => false
+   */
+  readonly skip?: (ctx: KoaContext) => boolean;
+
+  /**
+   * If `true`, logs are written immediately when the request is received.
+   * If `false` (default), logs are written after the response is sent.
+   *
+   * Note: When `logRequest` is `true`, response-related properties
+   * (status, responseTime, contentLength) will not be available.
+   *
+   * @default false
+   */
+  readonly logRequest?: boolean;
+}
+
+/**
+ * Get referrer from request headers.
+ * Returns undefined if the header is not present or empty.
+ */
+function getReferrer(ctx: KoaContext): string | undefined {
+  const referrer = ctx.get("referrer") || ctx.get("referer");
+  return referrer !== "" ? referrer : undefined;
+}
+
+/**
+ * Get user agent from request headers.
+ * Returns undefined if the header is not present or empty.
+ */
+function getUserAgent(ctx: KoaContext): string | undefined {
+  const userAgent = ctx.get("user-agent");
+  return userAgent !== "" ? userAgent : undefined;
+}
+
+/**
+ * Get remote address from context.
+ * Returns undefined if not available.
+ */
+function getRemoteAddr(ctx: KoaContext): string | undefined {
+  return ctx.ip !== "" ? ctx.ip : undefined;
+}
+
+/**
+ * Get content length from response.
+ */
+function getContentLength(ctx: KoaContext): number | undefined {
+  return ctx.response.length;
+}
+
+/**
+ * Build structured log properties from context.
+ */
+function buildProperties(
+  ctx: KoaContext,
+  responseTime: number,
+): RequestLogProperties {
+  return {
+    method: ctx.method,
+    url: ctx.url,
+    path: ctx.path,
+    status: ctx.status,
+    responseTime,
+    contentLength: getContentLength(ctx),
+    remoteAddr: getRemoteAddr(ctx),
+    userAgent: getUserAgent(ctx),
+    referrer: getReferrer(ctx),
+  };
+}
+
+/**
+ * Combined format (Apache Combined Log Format).
+ * Returns all structured properties.
+ */
+function formatCombined(
+  ctx: KoaContext,
+  responseTime: number,
+): Record<string, unknown> {
+  return { ...buildProperties(ctx, responseTime) };
+}
+
+/**
+ * Common format (Apache Common Log Format).
+ * Like combined but without referrer and userAgent.
+ */
+function formatCommon(
+  ctx: KoaContext,
+  responseTime: number,
+): Record<string, unknown> {
+  const props = buildProperties(ctx, responseTime);
+  const { referrer: _referrer, userAgent: _userAgent, ...rest } = props;
+  return rest;
+}
+
+/**
+ * Dev format (colored output for development).
+ * :method :path :status :response-time ms - :res[content-length]
+ */
+function formatDev(
+  ctx: KoaContext,
+  responseTime: number,
+): string {
+  const contentLength = getContentLength(ctx) ?? "-";
+  return `${ctx.method} ${ctx.path} ${ctx.status} ${
+    responseTime.toFixed(3)
+  } ms - ${contentLength}`;
+}
+
+/**
+ * Short format.
+ * :remote-addr :method :url :status :res[content-length] - :response-time ms
+ */
+function formatShort(
+  ctx: KoaContext,
+  responseTime: number,
+): string {
+  const remoteAddr = getRemoteAddr(ctx) ?? "-";
+  const contentLength = getContentLength(ctx) ?? "-";
+  return `${remoteAddr} ${ctx.method} ${ctx.url} ${ctx.status} ${contentLength} - ${
+    responseTime.toFixed(3)
+  } ms`;
+}
+
+/**
+ * Tiny format (minimal output).
+ * :method :path :status :res[content-length] - :response-time ms
+ */
+function formatTiny(
+  ctx: KoaContext,
+  responseTime: number,
+): string {
+  const contentLength = getContentLength(ctx) ?? "-";
+  return `${ctx.method} ${ctx.path} ${ctx.status} ${contentLength} - ${
+    responseTime.toFixed(3)
+  } ms`;
+}
+
+/**
+ * Map of predefined format functions.
+ */
+const predefinedFormats: Record<PredefinedFormat, FormatFunction> = {
+  combined: formatCombined,
+  common: formatCommon,
+  dev: formatDev,
+  short: formatShort,
+  tiny: formatTiny,
+};
+
+/**
+ * Normalize category to array format.
+ */
+function normalizeCategory(
+  category: string | readonly string[],
+): readonly string[] {
+  return typeof category === "string" ? [category] : category;
+}
+
+/**
+ * Creates Koa middleware for HTTP request logging using LogTape.
+ *
+ * This middleware provides Morgan-compatible request logging with LogTape
+ * as the backend, supporting structured logging and customizable formats.
+ * It serves as an alternative to koa-logger with structured logging support.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import Koa from "koa";
+ * import { configure, getConsoleSink } from "@logtape/logtape";
+ * import { koaLogger } from "@logtape/koa";
+ *
+ * await configure({
+ *   sinks: { console: getConsoleSink() },
+ *   loggers: [
+ *     { category: ["koa"], sinks: ["console"], lowestLevel: "info" }
+ *   ],
+ * });
+ *
+ * const app = new Koa();
+ * app.use(koaLogger());
+ *
+ * app.use((ctx) => {
+ *   ctx.body = { hello: "world" };
+ * });
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * app.use(koaLogger({
+ *   category: ["myapp", "http"],
+ *   level: "debug",
+ *   format: "dev",
+ *   skip: (ctx) => ctx.path === "/health",
+ * }));
+ * ```
+ *
+ * @example With custom format function
+ * ```typescript
+ * app.use(koaLogger({
+ *   format: (ctx, responseTime) => ({
+ *     method: ctx.method,
+ *     path: ctx.path,
+ *     status: ctx.status,
+ *     duration: responseTime,
+ *   }),
+ * }));
+ * ```
+ *
+ * @param options Configuration options for the middleware.
+ * @returns Koa middleware function.
+ * @since 1.3.0
+ */
+export function koaLogger(
+  options: KoaLogTapeOptions = {},
+): KoaMiddleware {
+  const category = normalizeCategory(options.category ?? ["koa"]);
+  const logger = getLogger(category);
+  const level = options.level ?? "info";
+  const formatOption = options.format ?? "combined";
+  const skip = options.skip ?? (() => false);
+  const logRequest = options.logRequest ?? false;
+
+  // Resolve format function
+  const formatFn: FormatFunction = typeof formatOption === "string"
+    ? predefinedFormats[formatOption]
+    : formatOption;
+
+  const logMethod = logger[level].bind(logger);
+
+  return async (ctx: KoaContext, next: () => Promise<void>): Promise<void> => {
+    const startTime = Date.now();
+
+    // For immediate logging, log when request arrives
+    if (logRequest) {
+      if (!skip(ctx)) {
+        const result = formatFn(ctx, 0);
+        if (typeof result === "string") {
+          logMethod(result);
+        } else {
+          logMethod("{method} {url}", result);
+        }
+      }
+      await next();
+      return;
+    }
+
+    // Log after response is sent
+    await next();
+
+    if (skip(ctx)) return;
+
+    const responseTime = Date.now() - startTime;
+    const result = formatFn(ctx, responseTime);
+
+    if (typeof result === "string") {
+      logMethod(result);
+    } else {
+      logMethod("{method} {url} {status} - {responseTime} ms", result);
+    }
+  };
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: "src/mod.ts",
+  dts: {
+    sourcemap: true,
+  },
+  format: ["esm", "cjs"],
+  platform: "node",
+  unbundle: true,
+});