@logtape/koa 2.2.0-dev.685 → 2.2.0-dev.686

package/README.md

@@ -69,6 +69,49 @@ app.use(koaLogger({
   format: "dev",                 // Predefined format (default: "combined")
   skip: (ctx) => ctx.path === "/health",  // Skip health check endpoint
   logRequest: false,             // Log after response (default: false)
+  context: true,                 // Add requestId to request-scoped logs
+}));
+~~~~
+
+
+Request context
+---------------
+
+Set `context: true` to add request-scoped correlation fields.  By default,
+the middleware reads the `x-request-id` request header, generates an ID when
+the header is missing, writes the resolved ID to the `x-request-id` response
+header, and adds `requestId` to the request log record.
+
+To make logs emitted by your route handlers inherit the same `requestId`, also
+configure LogTape with `contextLocalStorage`:
+
+~~~~ typescript
+import { AsyncLocalStorage } from "node:async_hooks";
+import { configure } from "@logtape/logtape";
+
+await configure({
+  // ... sinks and loggers ...
+  contextLocalStorage: new AsyncLocalStorage(),
+});
+
+app.use(koaLogger({ context: true }));
+~~~~
+
+The context is still established when `skip` suppresses the request log, so
+application logs inside the skipped request can keep the same request ID.
+
+You can customize request ID headers and add more request fields:
+
+~~~~ typescript
+app.use(koaLogger({
+  context: {
+    requestId: {
+      headerNames: ["x-correlation-id", "x-request-id"],
+      responseHeader: "x-request-id",
+    },
+    include: ["requestId", "method", "path", "remoteAddr"],
+    enrich: (ctx) => ({ route: ctx.path }),
+  },
 }));
 ~~~~
 

package/dist/mod.cjs

@@ -2,6 +2,65 @@ const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
 const __logtape_logtape = require_rolldown_runtime.__toESM(require("@logtape/logtape"));
 
 //#region src/mod.ts
+const defaultRequestIdHeader = "x-request-id";
+/**
+* Normalize request context options.
+*/
+function normalizeRequestContextOptions(options) {
+	if (options === true) return {};
+	if (options === false || options == null) return void 0;
+	return options;
+}
+/**
+* Normalize request ID options.
+*/
+function normalizeRequestIdOptions(options) {
+	if (options === false) return void 0;
+	if (options === true || options == null) return {};
+	return options;
+}
+/**
+* Generate a request ID with Web Crypto when possible.
+*/
+function generateRequestId() {
+	if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/**
+* Normalize an incoming request ID.
+*/
+function defaultNormalizeRequestId(value) {
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
+/**
+* Resolve the request ID for a request.
+*/
+function resolveRequestId(ctx, options) {
+	const property = options.property ?? "requestId";
+	const normalize = options.normalize ?? defaultNormalizeRequestId;
+	const headerNames = options.headerNames ?? [defaultRequestIdHeader];
+	for (const headerName of headerNames) {
+		const headerValue = ctx.get(headerName);
+		if (headerValue === "") continue;
+		const normalized = normalize(headerValue);
+		if (normalized != null) {
+			const responseHeader$1 = options.responseHeader ?? defaultRequestIdHeader;
+			if (responseHeader$1 !== false) ctx.set?.(responseHeader$1, normalized);
+			return {
+				property,
+				value: normalized
+			};
+		}
+	}
+	const generated = (options.generate ?? generateRequestId)();
+	const responseHeader = options.responseHeader ?? defaultRequestIdHeader;
+	if (responseHeader !== false) ctx.set?.(responseHeader, generated);
+	return {
+		property,
+		value: generated
+	};
+}
 /**
 * Get referrer from request headers.
 * Returns undefined if the header is not present or empty.
@@ -48,6 +107,60 @@ function buildProperties(ctx, responseTime) {
 	};
 }
 /**
+* Build request context fields from a request.
+*/
+function buildIncludedContext(ctx, resolvedRequestId, include) {
+	const context = {};
+	for (const field of include) switch (field) {
+		case "requestId":
+			if (resolvedRequestId != null) context[resolvedRequestId.property] = resolvedRequestId.value;
+			break;
+		case "method":
+			context.method = ctx.method;
+			break;
+		case "url":
+			context.url = ctx.url;
+			break;
+		case "path":
+			context.path = ctx.path;
+			break;
+		case "userAgent":
+			context.userAgent = getUserAgent(ctx);
+			break;
+		case "remoteAddr":
+			context.remoteAddr = getRemoteAddr(ctx);
+			break;
+		case "referrer":
+			context.referrer = getReferrer(ctx);
+			break;
+	}
+	return context;
+}
+/**
+* Build the implicit context for a request.
+*/
+async function buildRequestContext(ctx, options) {
+	const requestIdOptions = normalizeRequestIdOptions(options.requestId);
+	const resolvedRequestId = requestIdOptions == null ? void 0 : resolveRequestId(ctx, requestIdOptions);
+	const include = options.include ?? (resolvedRequestId == null ? [] : ["requestId"]);
+	const context = buildIncludedContext(ctx, resolvedRequestId, include);
+	if (options.enrich == null) return context;
+	return {
+		...context,
+		...await options.enrich(ctx)
+	};
+}
+/**
+* Add request context fields to a request log result.
+*/
+function withRequestLogContext(result, context) {
+	if (typeof result === "string") return result;
+	return {
+		...result,
+		...context
+	};
+}
+/**
 * Combined format (Apache Combined Log Format).
 * Returns all structured properties.
 */
@@ -167,25 +280,34 @@ function koaLogger(options = {}) {
 	const formatOption = options.format ?? "combined";
 	const skip = options.skip ?? (() => false);
 	const logRequest = options.logRequest ?? false;
+	const contextOptions = normalizeRequestContextOptions(options.context);
 	const formatFn = typeof formatOption === "string" ? predefinedFormats[formatOption] : formatOption;
 	const logMethod = logger[level].bind(logger);
 	return async (ctx, next) => {
 		const startTime = Date.now();
-		if (logRequest) {
-			if (!skip(ctx)) {
-				const result$1 = formatFn(ctx, 0);
-				if (typeof result$1 === "string") logMethod(result$1);
-				else logMethod("{method} {url}", result$1);
+		const handleRequest = async (requestContext$1) => {
+			if (logRequest) {
+				if (!skip(ctx)) {
+					const result$1 = withRequestLogContext(formatFn(ctx, 0), requestContext$1);
+					if (typeof result$1 === "string") logMethod(result$1, requestContext$1);
+					else logMethod("{method} {url}", result$1);
+				}
+				await next();
+				return;
 			}
 			await next();
+			if (skip(ctx)) return;
+			const responseTime = Date.now() - startTime;
+			const result = withRequestLogContext(formatFn(ctx, responseTime), requestContext$1);
+			if (typeof result === "string") logMethod(result, requestContext$1);
+			else logMethod("{method} {url} {status} - {responseTime} ms", result);
+		};
+		if (contextOptions == null) {
+			await handleRequest({});
 			return;
 		}
-		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);
+		const requestContext = await buildRequestContext(ctx, contextOptions);
+		await (0, __logtape_logtape.withContext)(requestContext, () => handleRequest(requestContext));
 	};
 }
 

package/dist/mod.d.cts

@@ -31,6 +31,12 @@ interface KoaContext {
    * @returns The header value, or an empty string if not present.
    */
   get(field: string): string;
+  /**
+   * Set a response header field value.
+   * @param field The header field name.
+   * @param value The header field value.
+   */
+  set?(field: string, value: string): void;
 }
 /**
  * Koa middleware function type.
@@ -75,6 +81,63 @@ interface RequestLogProperties {
   /** Referrer header value */
   referrer: string | undefined;
 }
+/**
+ * Request fields that can be added to the implicit request context.
+ * @since 2.2.0
+ */
+type RequestContextField = "requestId" | "method" | "url" | "path" | "userAgent" | "remoteAddr" | "referrer";
+/**
+ * Options for extracting, generating, and propagating a request ID.
+ * @since 2.2.0
+ */
+interface RequestIdOptions {
+  /**
+   * The property name used in implicit context and request log records.
+   * @default "requestId"
+   */
+  readonly property?: string;
+  /**
+   * Incoming request headers to inspect in order.
+   * @default ["x-request-id"]
+   */
+  readonly headerNames?: readonly string[];
+  /**
+   * Response header that receives the resolved request ID.
+   * Set to `false` to disable response header propagation.
+   * @default "x-request-id"
+   */
+  readonly responseHeader?: string | false;
+  /**
+   * Generates a request ID when no incoming header is present.
+   * @default crypto.randomUUID()
+   */
+  readonly generate?: () => string;
+  /**
+   * Normalizes an incoming request ID.  Return `null` to reject the value and
+   * keep looking for another header or generate a new ID.
+   */
+  readonly normalize?: (value: string) => string | null;
+}
+/**
+ * Options for request-scoped implicit context.
+ * @since 2.2.0
+ */
+interface RequestContextOptions {
+  /**
+   * Enables request ID extraction, generation, and response propagation.
+   * @default true
+   */
+  readonly requestId?: boolean | RequestIdOptions;
+  /**
+   * Fields to add to the implicit context.
+   * @default ["requestId"]
+   */
+  readonly include?: readonly RequestContextField[];
+  /**
+   * Adds application-specific fields to the implicit request context.
+   */
+  readonly enrich?: (ctx: KoaContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+}
 /**
  * Options for configuring the Koa LogTape middleware.
  * @since 1.3.0
@@ -128,6 +191,18 @@ interface KoaLogTapeOptions {
    * @default false
    */
   readonly logRequest?: boolean;
+  /**
+   * Enables request-scoped implicit context and request ID correlation.
+   *
+   * When set to `true`, the middleware reads the `x-request-id` header,
+   * generates one when it is absent, writes it to the `x-request-id` response
+   * header, and adds `requestId` to all LogTape records emitted while handling
+   * the request.
+   *
+   * @default false
+   * @since 2.2.0
+   */
+  readonly context?: boolean | RequestContextOptions;
 }
 /**
  * Creates Koa middleware for HTTP request logging using LogTape.
@@ -188,5 +263,5 @@ interface KoaLogTapeOptions {
 declare function koaLogger(options?: KoaLogTapeOptions): KoaMiddleware;
 //# sourceMappingURL=mod.d.ts.map
 //#endregion
-export { FormatFunction, KoaContext, KoaLogTapeOptions, KoaMiddleware, LogLevel, PredefinedFormat, RequestLogProperties, koaLogger };
+export { FormatFunction, KoaContext, KoaLogTapeOptions, KoaMiddleware, LogLevel, PredefinedFormat, RequestContextField, RequestContextOptions, RequestIdOptions, RequestLogProperties, koaLogger };
 //# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.cts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;AAYA;AA2BA;;;;;AAGY;AAMA,UApCK,UAAA,CAoCW;EAUhB;EAAc,MAAA,EAAA,MAAA;EAAA;EACT,GAEH,EAAA,MAAA;EAAM;EAMH,IAAA,EAAA,MAAA;EAyBA;EAAiB,MAAA,EAAA,MAAA;EAAA;EAWP,EAAA,EAeP,MAAA;EAAgB;EAAiB,QAe7B,EAAA;IAAU,MAAA,CAAA,EAAA,MAAA;EAkNlB,CAAA;EAAS;;;AAET;;;;;;;;KAlTJ,aAAA,SACL,wBACO,kBACT;;;;;KAMO,gBAAA;;;;;;;;;KAUA,cAAA,SACL,8CAEO;;;;;UAMG,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;UAyBA,iBAAA;;;;;;;;;;mBAWE;;;;;;;;;;;;;;oBAeC,mBAAmB;;;;;;;;;;;;;;wBAef;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkNR,SAAA,WACL,oBACR"}
+{"version":3,"file":"mod.d.cts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;AAYA;AAiCA;;;;;AAGY;AAMA,UA1CK,UAAA,CA0CW;EAUhB;EAAc,MAAA,EAAA,MAAA;EAAA;EACT,GAEH,EAAA,MAAA;EAAM;EAMH,IAAA,EAAA,MAAA;EAyBL;EAaK,MAAA,EAAA,MAAA;EAqCA;EAAqB,EAAA,EAAA,MAAA;EAAA;EAKW,QAMnB,EAAA;IAMrB,MAAA,CAAA,EAAA,MAAA;EAAU,CAAA;EACN;;AAA2B;AAOxC;;EAAkC,GAWf,CAAA,KAAA,EAAA,MAAA,CAAA,EAAA,MAAA;EAAQ;;;;AAsDyB;EAkVpC,GAAA,EAAA,KAAA,EAAS,MAAA,EAAA,KAAA,EAAA,MAAA,CAAA,EAAA,IAAA;;;;AAET;;KArhBJ,aAAA,SACL,wBACO,kBACT;;;;;KAMO,gBAAA;;;;;;;;;KAUA,cAAA,SACL,8CAEO;;;;;UAMG,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;KAyBL,mBAAA;;;;;UAaK,gBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAqCA,qBAAA;;;;;iCAKgB;;;;;8BAMH;;;;0BAMrB,eACF,0BAA0B,QAAQ;;;;;;UAOxB,iBAAA;;;;;;;;;;mBAWE;;;;;;;;;;;;;;oBAeC,mBAAmB;;;;;;;;;;;;;;wBAef;;;;;;;;;;;;;;;;;;;;;;+BAwBO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkVf,SAAA,WACL,oBACR"}

package/dist/mod.d.ts

@@ -31,6 +31,12 @@ interface KoaContext {
    * @returns The header value, or an empty string if not present.
    */
   get(field: string): string;
+  /**
+   * Set a response header field value.
+   * @param field The header field name.
+   * @param value The header field value.
+   */
+  set?(field: string, value: string): void;
 }
 /**
  * Koa middleware function type.
@@ -75,6 +81,63 @@ interface RequestLogProperties {
   /** Referrer header value */
   referrer: string | undefined;
 }
+/**
+ * Request fields that can be added to the implicit request context.
+ * @since 2.2.0
+ */
+type RequestContextField = "requestId" | "method" | "url" | "path" | "userAgent" | "remoteAddr" | "referrer";
+/**
+ * Options for extracting, generating, and propagating a request ID.
+ * @since 2.2.0
+ */
+interface RequestIdOptions {
+  /**
+   * The property name used in implicit context and request log records.
+   * @default "requestId"
+   */
+  readonly property?: string;
+  /**
+   * Incoming request headers to inspect in order.
+   * @default ["x-request-id"]
+   */
+  readonly headerNames?: readonly string[];
+  /**
+   * Response header that receives the resolved request ID.
+   * Set to `false` to disable response header propagation.
+   * @default "x-request-id"
+   */
+  readonly responseHeader?: string | false;
+  /**
+   * Generates a request ID when no incoming header is present.
+   * @default crypto.randomUUID()
+   */
+  readonly generate?: () => string;
+  /**
+   * Normalizes an incoming request ID.  Return `null` to reject the value and
+   * keep looking for another header or generate a new ID.
+   */
+  readonly normalize?: (value: string) => string | null;
+}
+/**
+ * Options for request-scoped implicit context.
+ * @since 2.2.0
+ */
+interface RequestContextOptions {
+  /**
+   * Enables request ID extraction, generation, and response propagation.
+   * @default true
+   */
+  readonly requestId?: boolean | RequestIdOptions;
+  /**
+   * Fields to add to the implicit context.
+   * @default ["requestId"]
+   */
+  readonly include?: readonly RequestContextField[];
+  /**
+   * Adds application-specific fields to the implicit request context.
+   */
+  readonly enrich?: (ctx: KoaContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+}
 /**
  * Options for configuring the Koa LogTape middleware.
  * @since 1.3.0
@@ -128,6 +191,18 @@ interface KoaLogTapeOptions {
    * @default false
    */
   readonly logRequest?: boolean;
+  /**
+   * Enables request-scoped implicit context and request ID correlation.
+   *
+   * When set to `true`, the middleware reads the `x-request-id` header,
+   * generates one when it is absent, writes it to the `x-request-id` response
+   * header, and adds `requestId` to all LogTape records emitted while handling
+   * the request.
+   *
+   * @default false
+   * @since 2.2.0
+   */
+  readonly context?: boolean | RequestContextOptions;
 }
 /**
  * Creates Koa middleware for HTTP request logging using LogTape.
@@ -188,5 +263,5 @@ interface KoaLogTapeOptions {
 declare function koaLogger(options?: KoaLogTapeOptions): KoaMiddleware;
 //# sourceMappingURL=mod.d.ts.map
 //#endregion
-export { FormatFunction, KoaContext, KoaLogTapeOptions, KoaMiddleware, LogLevel, PredefinedFormat, RequestLogProperties, koaLogger };
+export { FormatFunction, KoaContext, KoaLogTapeOptions, KoaMiddleware, LogLevel, PredefinedFormat, RequestContextField, RequestContextOptions, RequestIdOptions, RequestLogProperties, koaLogger };
 //# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;AAYA;AA2BA;;;;;AAGY;AAMA,UApCK,UAAA,CAoCW;EAUhB;EAAc,MAAA,EAAA,MAAA;EAAA;EACT,GAEH,EAAA,MAAA;EAAM;EAMH,IAAA,EAAA,MAAA;EAyBA;EAAiB,MAAA,EAAA,MAAA;EAAA;EAWP,EAAA,EAeP,MAAA;EAAgB;EAAiB,QAe7B,EAAA;IAAU,MAAA,CAAA,EAAA,MAAA;EAkNlB,CAAA;EAAS;;;AAET;;;;;;;;KAlTJ,aAAA,SACL,wBACO,kBACT;;;;;KAMO,gBAAA;;;;;;;;;KAUA,cAAA,SACL,8CAEO;;;;;UAMG,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;UAyBA,iBAAA;;;;;;;;;;mBAWE;;;;;;;;;;;;;;oBAeC,mBAAmB;;;;;;;;;;;;;;wBAef;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkNR,SAAA,WACL,oBACR"}
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;AAYA;AAiCA;;;;;AAGY;AAMA,UA1CK,UAAA,CA0CW;EAUhB;EAAc,MAAA,EAAA,MAAA;EAAA;EACT,GAEH,EAAA,MAAA;EAAM;EAMH,IAAA,EAAA,MAAA;EAyBL;EAaK,MAAA,EAAA,MAAA;EAqCA;EAAqB,EAAA,EAAA,MAAA;EAAA;EAKW,QAMnB,EAAA;IAMrB,MAAA,CAAA,EAAA,MAAA;EAAU,CAAA;EACN;;AAA2B;AAOxC;;EAAkC,GAWf,CAAA,KAAA,EAAA,MAAA,CAAA,EAAA,MAAA;EAAQ;;;;AAsDyB;EAkVpC,GAAA,EAAA,KAAA,EAAS,MAAA,EAAA,KAAA,EAAA,MAAA,CAAA,EAAA,IAAA;;;;AAET;;KArhBJ,aAAA,SACL,wBACO,kBACT;;;;;KAMO,gBAAA;;;;;;;;;KAUA,cAAA,SACL,8CAEO;;;;;UAMG,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;KAyBL,mBAAA;;;;;UAaK,gBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAqCA,qBAAA;;;;;iCAKgB;;;;;8BAMH;;;;0BAMrB,eACF,0BAA0B,QAAQ;;;;;;UAOxB,iBAAA;;;;;;;;;;mBAWE;;;;;;;;;;;;;;oBAeC,mBAAmB;;;;;;;;;;;;;;wBAef;;;;;;;;;;;;;;;;;;;;;;+BAwBO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkVf,SAAA,WACL,oBACR"}

package/dist/mod.js

@@ -1,6 +1,65 @@
-import { getLogger } from "@logtape/logtape";
+import { getLogger, withContext } from "@logtape/logtape";
 
 //#region src/mod.ts
+const defaultRequestIdHeader = "x-request-id";
+/**
+* Normalize request context options.
+*/
+function normalizeRequestContextOptions(options) {
+	if (options === true) return {};
+	if (options === false || options == null) return void 0;
+	return options;
+}
+/**
+* Normalize request ID options.
+*/
+function normalizeRequestIdOptions(options) {
+	if (options === false) return void 0;
+	if (options === true || options == null) return {};
+	return options;
+}
+/**
+* Generate a request ID with Web Crypto when possible.
+*/
+function generateRequestId() {
+	if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/**
+* Normalize an incoming request ID.
+*/
+function defaultNormalizeRequestId(value) {
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
+/**
+* Resolve the request ID for a request.
+*/
+function resolveRequestId(ctx, options) {
+	const property = options.property ?? "requestId";
+	const normalize = options.normalize ?? defaultNormalizeRequestId;
+	const headerNames = options.headerNames ?? [defaultRequestIdHeader];
+	for (const headerName of headerNames) {
+		const headerValue = ctx.get(headerName);
+		if (headerValue === "") continue;
+		const normalized = normalize(headerValue);
+		if (normalized != null) {
+			const responseHeader$1 = options.responseHeader ?? defaultRequestIdHeader;
+			if (responseHeader$1 !== false) ctx.set?.(responseHeader$1, normalized);
+			return {
+				property,
+				value: normalized
+			};
+		}
+	}
+	const generated = (options.generate ?? generateRequestId)();
+	const responseHeader = options.responseHeader ?? defaultRequestIdHeader;
+	if (responseHeader !== false) ctx.set?.(responseHeader, generated);
+	return {
+		property,
+		value: generated
+	};
+}
 /**
 * Get referrer from request headers.
 * Returns undefined if the header is not present or empty.
@@ -47,6 +106,60 @@ function buildProperties(ctx, responseTime) {
 	};
 }
 /**
+* Build request context fields from a request.
+*/
+function buildIncludedContext(ctx, resolvedRequestId, include) {
+	const context = {};
+	for (const field of include) switch (field) {
+		case "requestId":
+			if (resolvedRequestId != null) context[resolvedRequestId.property] = resolvedRequestId.value;
+			break;
+		case "method":
+			context.method = ctx.method;
+			break;
+		case "url":
+			context.url = ctx.url;
+			break;
+		case "path":
+			context.path = ctx.path;
+			break;
+		case "userAgent":
+			context.userAgent = getUserAgent(ctx);
+			break;
+		case "remoteAddr":
+			context.remoteAddr = getRemoteAddr(ctx);
+			break;
+		case "referrer":
+			context.referrer = getReferrer(ctx);
+			break;
+	}
+	return context;
+}
+/**
+* Build the implicit context for a request.
+*/
+async function buildRequestContext(ctx, options) {
+	const requestIdOptions = normalizeRequestIdOptions(options.requestId);
+	const resolvedRequestId = requestIdOptions == null ? void 0 : resolveRequestId(ctx, requestIdOptions);
+	const include = options.include ?? (resolvedRequestId == null ? [] : ["requestId"]);
+	const context = buildIncludedContext(ctx, resolvedRequestId, include);
+	if (options.enrich == null) return context;
+	return {
+		...context,
+		...await options.enrich(ctx)
+	};
+}
+/**
+* Add request context fields to a request log result.
+*/
+function withRequestLogContext(result, context) {
+	if (typeof result === "string") return result;
+	return {
+		...result,
+		...context
+	};
+}
+/**
 * Combined format (Apache Combined Log Format).
 * Returns all structured properties.
 */
@@ -166,25 +279,34 @@ function koaLogger(options = {}) {
 	const formatOption = options.format ?? "combined";
 	const skip = options.skip ?? (() => false);
 	const logRequest = options.logRequest ?? false;
+	const contextOptions = normalizeRequestContextOptions(options.context);
 	const formatFn = typeof formatOption === "string" ? predefinedFormats[formatOption] : formatOption;
 	const logMethod = logger[level].bind(logger);
 	return async (ctx, next) => {
 		const startTime = Date.now();
-		if (logRequest) {
-			if (!skip(ctx)) {
-				const result$1 = formatFn(ctx, 0);
-				if (typeof result$1 === "string") logMethod(result$1);
-				else logMethod("{method} {url}", result$1);
+		const handleRequest = async (requestContext$1) => {
+			if (logRequest) {
+				if (!skip(ctx)) {
+					const result$1 = withRequestLogContext(formatFn(ctx, 0), requestContext$1);
+					if (typeof result$1 === "string") logMethod(result$1, requestContext$1);
+					else logMethod("{method} {url}", result$1);
+				}
+				await next();
+				return;
 			}
 			await next();
+			if (skip(ctx)) return;
+			const responseTime = Date.now() - startTime;
+			const result = withRequestLogContext(formatFn(ctx, responseTime), requestContext$1);
+			if (typeof result === "string") logMethod(result, requestContext$1);
+			else logMethod("{method} {url} {status} - {responseTime} ms", result);
+		};
+		if (contextOptions == null) {
+			await handleRequest({});
 			return;
 		}
-		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);
+		const requestContext = await buildRequestContext(ctx, contextOptions);
+		await withContext(requestContext, () => handleRequest(requestContext));
 	};
 }
 

package/dist/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","names":["ctx: KoaContext","responseTime: number","predefinedFormats: Record<PredefinedFormat, FormatFunction>","category: string | readonly string[]","options: KoaLogTapeOptions","formatFn: FormatFunction","next: () => Promise<void>","result"],"sources":["../src/mod.ts"],"sourcesContent":["import { getLogger, type LogLevel } from \"@logtape/logtape\";\n\nexport type { LogLevel } from \"@logtape/logtape\";\n\n/**\n * Minimal Koa Context interface for compatibility across Koa 2.x and 3.x.\n *\n * This interface includes common aliases available on the Koa context object.\n * See https://koajs.com/#context for the full API.\n *\n * @since 1.3.0\n */\nexport interface KoaContext {\n  /** HTTP request method (alias for ctx.request.method) */\n  method: string;\n  /** Request URL (alias for ctx.request.url) */\n  url: string;\n  /** Request pathname (alias for ctx.request.path) */\n  path: string;\n  /** HTTP response status code (alias for ctx.response.status) */\n  status: number;\n  /** Remote client IP address (alias for ctx.request.ip) */\n  ip: string;\n  /** Koa Response object */\n  response: {\n    length?: number;\n  };\n  /**\n   * Get a request header field value (case-insensitive).\n   * @param field The header field name.\n   * @returns The header value, or an empty string if not present.\n   */\n  get(field: string): string;\n}\n\n/**\n * Koa middleware function type.\n * @since 1.3.0\n */\nexport type KoaMiddleware = (\n  ctx: KoaContext,\n  next: () => Promise<void>,\n) => Promise<void>;\n\n/**\n * Predefined log format names compatible with Morgan.\n * @since 1.3.0\n */\nexport type PredefinedFormat = \"combined\" | \"common\" | \"dev\" | \"short\" | \"tiny\";\n\n/**\n * Custom format function for request logging.\n *\n * @param ctx The Koa context object.\n * @param responseTime The response time in milliseconds.\n * @returns A string message or an object with structured properties.\n * @since 1.3.0\n */\nexport type FormatFunction = (\n  ctx: KoaContext,\n  responseTime: number,\n) => string | Record<string, unknown>;\n\n/**\n * Structured log properties for HTTP requests.\n * @since 1.3.0\n */\nexport interface RequestLogProperties {\n  /** HTTP request method */\n  method: string;\n  /** Request URL */\n  url: string;\n  /** Request path */\n  path: string;\n  /** HTTP response status code */\n  status: number;\n  /** Response time in milliseconds */\n  responseTime: number;\n  /** Response content-length */\n  contentLength: number | undefined;\n  /** Remote client address */\n  remoteAddr: string | undefined;\n  /** User-Agent header value */\n  userAgent: string | undefined;\n  /** Referrer header value */\n  referrer: string | undefined;\n}\n\n/**\n * Options for configuring the Koa LogTape middleware.\n * @since 1.3.0\n */\nexport interface KoaLogTapeOptions {\n  /**\n   * The LogTape category to use for logging.\n   * @default [\"koa\"]\n   */\n  readonly category?: string | readonly string[];\n\n  /**\n   * The log level to use for request logging.\n   * @default \"info\"\n   */\n  readonly level?: LogLevel;\n\n  /**\n   * The format for log output.\n   * Can be a predefined format name or a custom format function.\n   *\n   * Predefined formats:\n   * - `\"combined\"` - Apache Combined Log Format (structured, default)\n   * - `\"common\"` - Apache Common Log Format (structured, no referrer/userAgent)\n   * - `\"dev\"` - Concise colored output for development (string)\n   * - `\"short\"` - Shorter than common (string)\n   * - `\"tiny\"` - Minimal output (string)\n   *\n   * @default \"combined\"\n   */\n  readonly format?: PredefinedFormat | FormatFunction;\n\n  /**\n   * Function to determine whether logging should be skipped.\n   * Return `true` to skip logging for a request.\n   *\n   * @example Skip logging for health check endpoint\n   * ```typescript\n   * app.use(koaLogger({\n   *   skip: (ctx) => ctx.path === \"/health\",\n   * }));\n   * ```\n   *\n   * @default () => false\n   */\n  readonly skip?: (ctx: KoaContext) => boolean;\n\n  /**\n   * If `true`, logs are written immediately when the request is received.\n   * If `false` (default), logs are written after the response is sent.\n   *\n   * Note: When `logRequest` is `true`, response-related properties\n   * (status, responseTime, contentLength) will not be available.\n   *\n   * @default false\n   */\n  readonly logRequest?: boolean;\n}\n\n/**\n * Get referrer from request headers.\n * Returns undefined if the header is not present or empty.\n */\nfunction getReferrer(ctx: KoaContext): string | undefined {\n  const referrer = ctx.get(\"referrer\") || ctx.get(\"referer\");\n  return referrer !== \"\" ? referrer : undefined;\n}\n\n/**\n * Get user agent from request headers.\n * Returns undefined if the header is not present or empty.\n */\nfunction getUserAgent(ctx: KoaContext): string | undefined {\n  const userAgent = ctx.get(\"user-agent\");\n  return userAgent !== \"\" ? userAgent : undefined;\n}\n\n/**\n * Get remote address from context.\n * Returns undefined if not available.\n */\nfunction getRemoteAddr(ctx: KoaContext): string | undefined {\n  return ctx.ip !== \"\" ? ctx.ip : undefined;\n}\n\n/**\n * Get content length from response.\n */\nfunction getContentLength(ctx: KoaContext): number | undefined {\n  return ctx.response.length;\n}\n\n/**\n * Build structured log properties from context.\n */\nfunction buildProperties(\n  ctx: KoaContext,\n  responseTime: number,\n): RequestLogProperties {\n  return {\n    method: ctx.method,\n    url: ctx.url,\n    path: ctx.path,\n    status: ctx.status,\n    responseTime,\n    contentLength: getContentLength(ctx),\n    remoteAddr: getRemoteAddr(ctx),\n    userAgent: getUserAgent(ctx),\n    referrer: getReferrer(ctx),\n  };\n}\n\n/**\n * Combined format (Apache Combined Log Format).\n * Returns all structured properties.\n */\nfunction formatCombined(\n  ctx: KoaContext,\n  responseTime: number,\n): Record<string, unknown> {\n  return { ...buildProperties(ctx, responseTime) };\n}\n\n/**\n * Common format (Apache Common Log Format).\n * Like combined but without referrer and userAgent.\n */\nfunction formatCommon(\n  ctx: KoaContext,\n  responseTime: number,\n): Record<string, unknown> {\n  const props = buildProperties(ctx, responseTime);\n  const { referrer: _referrer, userAgent: _userAgent, ...rest } = props;\n  return rest;\n}\n\n/**\n * Dev format (colored output for development).\n * :method :path :status :response-time ms - :res[content-length]\n */\nfunction formatDev(\n  ctx: KoaContext,\n  responseTime: number,\n): string {\n  const contentLength = getContentLength(ctx) ?? \"-\";\n  return `${ctx.method} ${ctx.path} ${ctx.status} ${\n    responseTime.toFixed(3)\n  } ms - ${contentLength}`;\n}\n\n/**\n * Short format.\n * :remote-addr :method :url :status :res[content-length] - :response-time ms\n */\nfunction formatShort(\n  ctx: KoaContext,\n  responseTime: number,\n): string {\n  const remoteAddr = getRemoteAddr(ctx) ?? \"-\";\n  const contentLength = getContentLength(ctx) ?? \"-\";\n  return `${remoteAddr} ${ctx.method} ${ctx.url} ${ctx.status} ${contentLength} - ${\n    responseTime.toFixed(3)\n  } ms`;\n}\n\n/**\n * Tiny format (minimal output).\n * :method :path :status :res[content-length] - :response-time ms\n */\nfunction formatTiny(\n  ctx: KoaContext,\n  responseTime: number,\n): string {\n  const contentLength = getContentLength(ctx) ?? \"-\";\n  return `${ctx.method} ${ctx.path} ${ctx.status} ${contentLength} - ${\n    responseTime.toFixed(3)\n  } ms`;\n}\n\n/**\n * Map of predefined format functions.\n */\nconst predefinedFormats: Record<PredefinedFormat, FormatFunction> = {\n  combined: formatCombined,\n  common: formatCommon,\n  dev: formatDev,\n  short: formatShort,\n  tiny: formatTiny,\n};\n\n/**\n * Normalize category to array format.\n */\nfunction normalizeCategory(\n  category: string | readonly string[],\n): readonly string[] {\n  return typeof category === \"string\" ? [category] : category;\n}\n\n/**\n * Creates Koa middleware for HTTP request logging using LogTape.\n *\n * This middleware provides Morgan-compatible request logging with LogTape\n * as the backend, supporting structured logging and customizable formats.\n * It serves as an alternative to koa-logger with structured logging support.\n *\n * @example Basic usage\n * ```typescript\n * import Koa from \"koa\";\n * import { configure, getConsoleSink } from \"@logtape/logtape\";\n * import { koaLogger } from \"@logtape/koa\";\n *\n * await configure({\n *   sinks: { console: getConsoleSink() },\n *   loggers: [\n *     { category: [\"koa\"], sinks: [\"console\"], lowestLevel: \"info\" }\n *   ],\n * });\n *\n * const app = new Koa();\n * app.use(koaLogger());\n *\n * app.use((ctx) => {\n *   ctx.body = { hello: \"world\" };\n * });\n *\n * app.listen(3000);\n * ```\n *\n * @example With custom options\n * ```typescript\n * app.use(koaLogger({\n *   category: [\"myapp\", \"http\"],\n *   level: \"debug\",\n *   format: \"dev\",\n *   skip: (ctx) => ctx.path === \"/health\",\n * }));\n * ```\n *\n * @example With custom format function\n * ```typescript\n * app.use(koaLogger({\n *   format: (ctx, responseTime) => ({\n *     method: ctx.method,\n *     path: ctx.path,\n *     status: ctx.status,\n *     duration: responseTime,\n *   }),\n * }));\n * ```\n *\n * @param options Configuration options for the middleware.\n * @returns Koa middleware function.\n * @since 1.3.0\n */\nexport function koaLogger(\n  options: KoaLogTapeOptions = {},\n): KoaMiddleware {\n  const category = normalizeCategory(options.category ?? [\"koa\"]);\n  const logger = getLogger(category);\n  const level = options.level ?? \"info\";\n  const formatOption = options.format ?? \"combined\";\n  const skip = options.skip ?? (() => false);\n  const logRequest = options.logRequest ?? false;\n\n  // Resolve format function\n  const formatFn: FormatFunction = typeof formatOption === \"string\"\n    ? predefinedFormats[formatOption]\n    : formatOption;\n\n  const logMethod = logger[level].bind(logger);\n\n  return async (ctx: KoaContext, next: () => Promise<void>): Promise<void> => {\n    const startTime = Date.now();\n\n    // For immediate logging, log when request arrives\n    if (logRequest) {\n      if (!skip(ctx)) {\n        const result = formatFn(ctx, 0);\n        if (typeof result === \"string\") {\n          logMethod(result);\n        } else {\n          logMethod(\"{method} {url}\", result);\n        }\n      }\n      await next();\n      return;\n    }\n\n    // Log after response is sent\n    await next();\n\n    if (skip(ctx)) return;\n\n    const responseTime = Date.now() - startTime;\n    const result = formatFn(ctx, responseTime);\n\n    if (typeof result === \"string\") {\n      logMethod(result);\n    } else {\n      logMethod(\"{method} {url} {status} - {responseTime} ms\", result);\n    }\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"mod.js","names":["options: boolean | RequestContextOptions | undefined","options: boolean | RequestIdOptions | undefined","value: string","ctx: KoaContext","options: RequestIdOptions","responseHeader","responseTime: number","resolvedRequestId: { property: string; value: string } | undefined","include: readonly RequestContextField[]","context: Record<string, unknown>","options: RequestContextOptions","result: string | Record<string, unknown>","predefinedFormats: Record<PredefinedFormat, FormatFunction>","category: string | readonly string[]","options: KoaLogTapeOptions","formatFn: FormatFunction","next: () => Promise<void>","requestContext: Record<string, unknown>","result","requestContext"],"sources":["../src/mod.ts"],"sourcesContent":["import { getLogger, type LogLevel, withContext } from \"@logtape/logtape\";\n\nexport type { LogLevel } from \"@logtape/logtape\";\n\n/**\n * Minimal Koa Context interface for compatibility across Koa 2.x and 3.x.\n *\n * This interface includes common aliases available on the Koa context object.\n * See https://koajs.com/#context for the full API.\n *\n * @since 1.3.0\n */\nexport interface KoaContext {\n  /** HTTP request method (alias for ctx.request.method) */\n  method: string;\n  /** Request URL (alias for ctx.request.url) */\n  url: string;\n  /** Request pathname (alias for ctx.request.path) */\n  path: string;\n  /** HTTP response status code (alias for ctx.response.status) */\n  status: number;\n  /** Remote client IP address (alias for ctx.request.ip) */\n  ip: string;\n  /** Koa Response object */\n  response: {\n    length?: number;\n  };\n  /**\n   * Get a request header field value (case-insensitive).\n   * @param field The header field name.\n   * @returns The header value, or an empty string if not present.\n   */\n  get(field: string): string;\n  /**\n   * Set a response header field value.\n   * @param field The header field name.\n   * @param value The header field value.\n   */\n  set?(field: string, value: string): void;\n}\n\n/**\n * Koa middleware function type.\n * @since 1.3.0\n */\nexport type KoaMiddleware = (\n  ctx: KoaContext,\n  next: () => Promise<void>,\n) => Promise<void>;\n\n/**\n * Predefined log format names compatible with Morgan.\n * @since 1.3.0\n */\nexport type PredefinedFormat = \"combined\" | \"common\" | \"dev\" | \"short\" | \"tiny\";\n\n/**\n * Custom format function for request logging.\n *\n * @param ctx The Koa context object.\n * @param responseTime The response time in milliseconds.\n * @returns A string message or an object with structured properties.\n * @since 1.3.0\n */\nexport type FormatFunction = (\n  ctx: KoaContext,\n  responseTime: number,\n) => string | Record<string, unknown>;\n\n/**\n * Structured log properties for HTTP requests.\n * @since 1.3.0\n */\nexport interface RequestLogProperties {\n  /** HTTP request method */\n  method: string;\n  /** Request URL */\n  url: string;\n  /** Request path */\n  path: string;\n  /** HTTP response status code */\n  status: number;\n  /** Response time in milliseconds */\n  responseTime: number;\n  /** Response content-length */\n  contentLength: number | undefined;\n  /** Remote client address */\n  remoteAddr: string | undefined;\n  /** User-Agent header value */\n  userAgent: string | undefined;\n  /** Referrer header value */\n  referrer: string | undefined;\n}\n\n/**\n * Request fields that can be added to the implicit request context.\n * @since 2.2.0\n */\nexport type RequestContextField =\n  | \"requestId\"\n  | \"method\"\n  | \"url\"\n  | \"path\"\n  | \"userAgent\"\n  | \"remoteAddr\"\n  | \"referrer\";\n\n/**\n * Options for extracting, generating, and propagating a request ID.\n * @since 2.2.0\n */\nexport interface RequestIdOptions {\n  /**\n   * The property name used in implicit context and request log records.\n   * @default \"requestId\"\n   */\n  readonly property?: string;\n\n  /**\n   * Incoming request headers to inspect in order.\n   * @default [\"x-request-id\"]\n   */\n  readonly headerNames?: readonly string[];\n\n  /**\n   * Response header that receives the resolved request ID.\n   * Set to `false` to disable response header propagation.\n   * @default \"x-request-id\"\n   */\n  readonly responseHeader?: string | false;\n\n  /**\n   * Generates a request ID when no incoming header is present.\n   * @default crypto.randomUUID()\n   */\n  readonly generate?: () => string;\n\n  /**\n   * Normalizes an incoming request ID.  Return `null` to reject the value and\n   * keep looking for another header or generate a new ID.\n   */\n  readonly normalize?: (value: string) => string | null;\n}\n\n/**\n * Options for request-scoped implicit context.\n * @since 2.2.0\n */\nexport interface RequestContextOptions {\n  /**\n   * Enables request ID extraction, generation, and response propagation.\n   * @default true\n   */\n  readonly requestId?: boolean | RequestIdOptions;\n\n  /**\n   * Fields to add to the implicit context.\n   * @default [\"requestId\"]\n   */\n  readonly include?: readonly RequestContextField[];\n\n  /**\n   * Adds application-specific fields to the implicit request context.\n   */\n  readonly enrich?: (\n    ctx: KoaContext,\n  ) => Record<string, unknown> | Promise<Record<string, unknown>>;\n}\n\n/**\n * Options for configuring the Koa LogTape middleware.\n * @since 1.3.0\n */\nexport interface KoaLogTapeOptions {\n  /**\n   * The LogTape category to use for logging.\n   * @default [\"koa\"]\n   */\n  readonly category?: string | readonly string[];\n\n  /**\n   * The log level to use for request logging.\n   * @default \"info\"\n   */\n  readonly level?: LogLevel;\n\n  /**\n   * The format for log output.\n   * Can be a predefined format name or a custom format function.\n   *\n   * Predefined formats:\n   * - `\"combined\"` - Apache Combined Log Format (structured, default)\n   * - `\"common\"` - Apache Common Log Format (structured, no referrer/userAgent)\n   * - `\"dev\"` - Concise colored output for development (string)\n   * - `\"short\"` - Shorter than common (string)\n   * - `\"tiny\"` - Minimal output (string)\n   *\n   * @default \"combined\"\n   */\n  readonly format?: PredefinedFormat | FormatFunction;\n\n  /**\n   * Function to determine whether logging should be skipped.\n   * Return `true` to skip logging for a request.\n   *\n   * @example Skip logging for health check endpoint\n   * ```typescript\n   * app.use(koaLogger({\n   *   skip: (ctx) => ctx.path === \"/health\",\n   * }));\n   * ```\n   *\n   * @default () => false\n   */\n  readonly skip?: (ctx: KoaContext) => boolean;\n\n  /**\n   * If `true`, logs are written immediately when the request is received.\n   * If `false` (default), logs are written after the response is sent.\n   *\n   * Note: When `logRequest` is `true`, response-related properties\n   * (status, responseTime, contentLength) will not be available.\n   *\n   * @default false\n   */\n  readonly logRequest?: boolean;\n\n  /**\n   * Enables request-scoped implicit context and request ID correlation.\n   *\n   * When set to `true`, the middleware reads the `x-request-id` header,\n   * generates one when it is absent, writes it to the `x-request-id` response\n   * header, and adds `requestId` to all LogTape records emitted while handling\n   * the request.\n   *\n   * @default false\n   * @since 2.2.0\n   */\n  readonly context?: boolean | RequestContextOptions;\n}\n\nconst defaultRequestIdHeader = \"x-request-id\";\n\n/**\n * Normalize request context options.\n */\nfunction normalizeRequestContextOptions(\n  options: boolean | RequestContextOptions | undefined,\n): RequestContextOptions | undefined {\n  if (options === true) return {};\n  if (options === false || options == null) return undefined;\n  return options;\n}\n\n/**\n * Normalize request ID options.\n */\nfunction normalizeRequestIdOptions(\n  options: boolean | RequestIdOptions | undefined,\n): RequestIdOptions | undefined {\n  if (options === false) return undefined;\n  if (options === true || options == null) return {};\n  return options;\n}\n\n/**\n * Generate a request ID with Web Crypto when possible.\n */\nfunction generateRequestId(): string {\n  if (typeof globalThis.crypto?.randomUUID === \"function\") {\n    return globalThis.crypto.randomUUID();\n  }\n  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;\n}\n\n/**\n * Normalize an incoming request ID.\n */\nfunction defaultNormalizeRequestId(value: string): string | null {\n  const trimmed = value.trim();\n  return trimmed === \"\" ? null : trimmed;\n}\n\n/**\n * Resolve the request ID for a request.\n */\nfunction resolveRequestId(\n  ctx: KoaContext,\n  options: RequestIdOptions,\n): { property: string; value: string } {\n  const property = options.property ?? \"requestId\";\n  const normalize = options.normalize ?? defaultNormalizeRequestId;\n  const headerNames = options.headerNames ?? [defaultRequestIdHeader];\n  for (const headerName of headerNames) {\n    const headerValue = ctx.get(headerName);\n    if (headerValue === \"\") continue;\n    const normalized = normalize(headerValue);\n    if (normalized != null) {\n      const responseHeader = options.responseHeader ?? defaultRequestIdHeader;\n      if (responseHeader !== false) ctx.set?.(responseHeader, normalized);\n      return { property, value: normalized };\n    }\n  }\n  const generated = (options.generate ?? generateRequestId)();\n  const responseHeader = options.responseHeader ?? defaultRequestIdHeader;\n  if (responseHeader !== false) ctx.set?.(responseHeader, generated);\n  return { property, value: generated };\n}\n\n/**\n * Get referrer from request headers.\n * Returns undefined if the header is not present or empty.\n */\nfunction getReferrer(ctx: KoaContext): string | undefined {\n  const referrer = ctx.get(\"referrer\") || ctx.get(\"referer\");\n  return referrer !== \"\" ? referrer : undefined;\n}\n\n/**\n * Get user agent from request headers.\n * Returns undefined if the header is not present or empty.\n */\nfunction getUserAgent(ctx: KoaContext): string | undefined {\n  const userAgent = ctx.get(\"user-agent\");\n  return userAgent !== \"\" ? userAgent : undefined;\n}\n\n/**\n * Get remote address from context.\n * Returns undefined if not available.\n */\nfunction getRemoteAddr(ctx: KoaContext): string | undefined {\n  return ctx.ip !== \"\" ? ctx.ip : undefined;\n}\n\n/**\n * Get content length from response.\n */\nfunction getContentLength(ctx: KoaContext): number | undefined {\n  return ctx.response.length;\n}\n\n/**\n * Build structured log properties from context.\n */\nfunction buildProperties(\n  ctx: KoaContext,\n  responseTime: number,\n): RequestLogProperties {\n  return {\n    method: ctx.method,\n    url: ctx.url,\n    path: ctx.path,\n    status: ctx.status,\n    responseTime,\n    contentLength: getContentLength(ctx),\n    remoteAddr: getRemoteAddr(ctx),\n    userAgent: getUserAgent(ctx),\n    referrer: getReferrer(ctx),\n  };\n}\n\n/**\n * Build request context fields from a request.\n */\nfunction buildIncludedContext(\n  ctx: KoaContext,\n  resolvedRequestId: { property: string; value: string } | undefined,\n  include: readonly RequestContextField[],\n): Record<string, unknown> {\n  const context: Record<string, unknown> = {};\n  for (const field of include) {\n    switch (field) {\n      case \"requestId\":\n        if (resolvedRequestId != null) {\n          context[resolvedRequestId.property] = resolvedRequestId.value;\n        }\n        break;\n      case \"method\":\n        context.method = ctx.method;\n        break;\n      case \"url\":\n        context.url = ctx.url;\n        break;\n      case \"path\":\n        context.path = ctx.path;\n        break;\n      case \"userAgent\":\n        context.userAgent = getUserAgent(ctx);\n        break;\n      case \"remoteAddr\":\n        context.remoteAddr = getRemoteAddr(ctx);\n        break;\n      case \"referrer\":\n        context.referrer = getReferrer(ctx);\n        break;\n    }\n  }\n  return context;\n}\n\n/**\n * Build the implicit context for a request.\n */\nasync function buildRequestContext(\n  ctx: KoaContext,\n  options: RequestContextOptions,\n): Promise<Record<string, unknown>> {\n  const requestIdOptions = normalizeRequestIdOptions(options.requestId);\n  const resolvedRequestId = requestIdOptions == null\n    ? undefined\n    : resolveRequestId(ctx, requestIdOptions);\n  const include = options.include ??\n    (resolvedRequestId == null ? [] : [\"requestId\"] as const);\n  const context = buildIncludedContext(ctx, resolvedRequestId, include);\n  if (options.enrich == null) return context;\n  return {\n    ...context,\n    ...await options.enrich(ctx),\n  };\n}\n\n/**\n * Add request context fields to a request log result.\n */\nfunction withRequestLogContext(\n  result: string | Record<string, unknown>,\n  context: Record<string, unknown>,\n): string | Record<string, unknown> {\n  if (typeof result === \"string\") return result;\n  return { ...result, ...context };\n}\n\n/**\n * Combined format (Apache Combined Log Format).\n * Returns all structured properties.\n */\nfunction formatCombined(\n  ctx: KoaContext,\n  responseTime: number,\n): Record<string, unknown> {\n  return { ...buildProperties(ctx, responseTime) };\n}\n\n/**\n * Common format (Apache Common Log Format).\n * Like combined but without referrer and userAgent.\n */\nfunction formatCommon(\n  ctx: KoaContext,\n  responseTime: number,\n): Record<string, unknown> {\n  const props = buildProperties(ctx, responseTime);\n  const { referrer: _referrer, userAgent: _userAgent, ...rest } = props;\n  return rest;\n}\n\n/**\n * Dev format (colored output for development).\n * :method :path :status :response-time ms - :res[content-length]\n */\nfunction formatDev(\n  ctx: KoaContext,\n  responseTime: number,\n): string {\n  const contentLength = getContentLength(ctx) ?? \"-\";\n  return `${ctx.method} ${ctx.path} ${ctx.status} ${\n    responseTime.toFixed(3)\n  } ms - ${contentLength}`;\n}\n\n/**\n * Short format.\n * :remote-addr :method :url :status :res[content-length] - :response-time ms\n */\nfunction formatShort(\n  ctx: KoaContext,\n  responseTime: number,\n): string {\n  const remoteAddr = getRemoteAddr(ctx) ?? \"-\";\n  const contentLength = getContentLength(ctx) ?? \"-\";\n  return `${remoteAddr} ${ctx.method} ${ctx.url} ${ctx.status} ${contentLength} - ${\n    responseTime.toFixed(3)\n  } ms`;\n}\n\n/**\n * Tiny format (minimal output).\n * :method :path :status :res[content-length] - :response-time ms\n */\nfunction formatTiny(\n  ctx: KoaContext,\n  responseTime: number,\n): string {\n  const contentLength = getContentLength(ctx) ?? \"-\";\n  return `${ctx.method} ${ctx.path} ${ctx.status} ${contentLength} - ${\n    responseTime.toFixed(3)\n  } ms`;\n}\n\n/**\n * Map of predefined format functions.\n */\nconst predefinedFormats: Record<PredefinedFormat, FormatFunction> = {\n  combined: formatCombined,\n  common: formatCommon,\n  dev: formatDev,\n  short: formatShort,\n  tiny: formatTiny,\n};\n\n/**\n * Normalize category to array format.\n */\nfunction normalizeCategory(\n  category: string | readonly string[],\n): readonly string[] {\n  return typeof category === \"string\" ? [category] : category;\n}\n\n/**\n * Creates Koa middleware for HTTP request logging using LogTape.\n *\n * This middleware provides Morgan-compatible request logging with LogTape\n * as the backend, supporting structured logging and customizable formats.\n * It serves as an alternative to koa-logger with structured logging support.\n *\n * @example Basic usage\n * ```typescript\n * import Koa from \"koa\";\n * import { configure, getConsoleSink } from \"@logtape/logtape\";\n * import { koaLogger } from \"@logtape/koa\";\n *\n * await configure({\n *   sinks: { console: getConsoleSink() },\n *   loggers: [\n *     { category: [\"koa\"], sinks: [\"console\"], lowestLevel: \"info\" }\n *   ],\n * });\n *\n * const app = new Koa();\n * app.use(koaLogger());\n *\n * app.use((ctx) => {\n *   ctx.body = { hello: \"world\" };\n * });\n *\n * app.listen(3000);\n * ```\n *\n * @example With custom options\n * ```typescript\n * app.use(koaLogger({\n *   category: [\"myapp\", \"http\"],\n *   level: \"debug\",\n *   format: \"dev\",\n *   skip: (ctx) => ctx.path === \"/health\",\n * }));\n * ```\n *\n * @example With custom format function\n * ```typescript\n * app.use(koaLogger({\n *   format: (ctx, responseTime) => ({\n *     method: ctx.method,\n *     path: ctx.path,\n *     status: ctx.status,\n *     duration: responseTime,\n *   }),\n * }));\n * ```\n *\n * @param options Configuration options for the middleware.\n * @returns Koa middleware function.\n * @since 1.3.0\n */\nexport function koaLogger(\n  options: KoaLogTapeOptions = {},\n): KoaMiddleware {\n  const category = normalizeCategory(options.category ?? [\"koa\"]);\n  const logger = getLogger(category);\n  const level = options.level ?? \"info\";\n  const formatOption = options.format ?? \"combined\";\n  const skip = options.skip ?? (() => false);\n  const logRequest = options.logRequest ?? false;\n  const contextOptions = normalizeRequestContextOptions(options.context);\n\n  // Resolve format function\n  const formatFn: FormatFunction = typeof formatOption === \"string\"\n    ? predefinedFormats[formatOption]\n    : formatOption;\n\n  const logMethod = logger[level].bind(logger);\n\n  return async (ctx: KoaContext, next: () => Promise<void>): Promise<void> => {\n    const startTime = Date.now();\n\n    const handleRequest = async (\n      requestContext: Record<string, unknown>,\n    ): Promise<void> => {\n      // For immediate logging, log when request arrives\n      if (logRequest) {\n        if (!skip(ctx)) {\n          const result = withRequestLogContext(\n            formatFn(ctx, 0),\n            requestContext,\n          );\n          if (typeof result === \"string\") {\n            logMethod(result, requestContext);\n          } else {\n            logMethod(\"{method} {url}\", result);\n          }\n        }\n        await next();\n        return;\n      }\n\n      // Log after response is sent\n      await next();\n\n      if (skip(ctx)) return;\n\n      const responseTime = Date.now() - startTime;\n      const result = withRequestLogContext(\n        formatFn(ctx, responseTime),\n        requestContext,\n      );\n\n      if (typeof result === \"string\") {\n        logMethod(result, requestContext);\n      } else {\n        logMethod(\"{method} {url} {status} - {responseTime} ms\", result);\n      }\n    };\n\n    if (contextOptions == null) {\n      await handleRequest({});\n      return;\n    }\n\n    const requestContext = await buildRequestContext(ctx, contextOptions);\n    await withContext(requestContext, () => handleRequest(requestContext));\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/koa",
-  "version": "2.2.0-dev.685+1c03a9fb",
+  "version": "2.2.0-dev.686+61fa5e1a",
   "description": "Koa adapter for LogTape logging library",
   "keywords": [
     "logging",
@@ -52,7 +52,7 @@
   ],
   "peerDependencies": {
     "koa": "^2.0.0 || ^3.0.0",
-    "@logtape/logtape": "^2.2.0-dev.685+1c03a9fb"
+    "@logtape/logtape": "^2.2.0-dev.686+61fa5e1a"
   },
   "devDependencies": {
     "@alinea/suite": "^0.6.3",