@logtape/koa 1.3.0-dev.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024–2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+<!-- deno-fmt-ignore-file -->
+
+@logtape/koa: Koa adapter for LogTape
+=====================================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+This package provides [Koa] middleware for HTTP request logging using [LogTape]
+as the backend. It serves as an alternative to [koa-logger] with structured
+logging support.
+
+[JSR]: https://jsr.io/@logtape/koa
+[JSR badge]: https://jsr.io/badges/@logtape/koa
+[npm]: https://www.npmjs.com/package/@logtape/koa
+[npm badge]: https://img.shields.io/npm/v/@logtape/koa?logo=npm
+[Koa]: https://koajs.com/
+[LogTape]: https://logtape.org/
+[koa-logger]: https://github.com/koajs/logger
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@logtape/koa  # Deno
+npm add @logtape/koa       # npm
+pnpm add @logtape/koa      # pnpm
+yarn add @logtape/koa      # Yarn
+bun add @logtape/koa       # Bun
+~~~~
+
+
+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();
+
+// Basic usage - should be used near the top of middleware stack
+app.use(koaLogger());
+
+app.use((ctx) => {
+  ctx.body = { hello: "world" };
+});
+
+app.listen(3000);
+~~~~
+
+
+Options
+-------
+
+~~~~ typescript
+app.use(koaLogger({
+  category: ["myapp", "http"],  // Custom category (default: ["koa"])
+  level: "debug",                // Log level (default: "info")
+  format: "dev",                 // Predefined format (default: "combined")
+  skip: (ctx) => ctx.path === "/health",  // Skip health check endpoint
+  logRequest: false,             // Log after response (default: false)
+}));
+~~~~
+
+
+Predefined Formats
+------------------
+
+- `"combined"` - Apache Combined Log Format with all properties (default)
+- `"common"` - Apache Common Log Format (without referrer/userAgent)
+- `"dev"` - Concise output for development
+- `"short"` - Shorter format with remote address
+- `"tiny"` - Minimal output
+
+
+Custom Format
+-------------
+
+~~~~ typescript
+app.use(koaLogger({
+  format: (ctx, responseTime) => ({
+    method: ctx.method,
+    path: ctx.path,
+    status: ctx.status,
+    duration: responseTime,
+  }),
+}));
+~~~~
+
+
+License
+-------
+
+Distributed under the MIT License.  See the *LICENSE* file for details.

package/deno.json

@@ -0,0 +1,34 @@
+{
+  "name": "@logtape/koa",
+  "version": "1.3.0",
+  "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/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/mod.cjs

@@ -0,0 +1,193 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __logtape_logtape = require_rolldown_runtime.__toESM(require("@logtape/logtape"));
+
+//#region src/mod.ts
+/**
+* Get referrer from request headers.
+* Returns undefined if the header is not present or empty.
+*/
+function getReferrer(ctx) {
+	const referrer = ctx.get("referrer") || ctx.get("referer");
+	return referrer !== "" ? referrer : void 0;
+}
+/**
+* Get user agent from request headers.
+* Returns undefined if the header is not present or empty.
+*/
+function getUserAgent(ctx) {
+	const userAgent = ctx.get("user-agent");
+	return userAgent !== "" ? userAgent : void 0;
+}
+/**
+* Get remote address from context.
+* Returns undefined if not available.
+*/
+function getRemoteAddr(ctx) {
+	return ctx.ip !== "" ? ctx.ip : void 0;
+}
+/**
+* Get content length from response.
+*/
+function getContentLength(ctx) {
+	return ctx.response.length;
+}
+/**
+* Build structured log properties from context.
+*/
+function buildProperties(ctx, responseTime) {
+	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, responseTime) {
+	return { ...buildProperties(ctx, responseTime) };
+}
+/**
+* Common format (Apache Common Log Format).
+* Like combined but without referrer and userAgent.
+*/
+function formatCommon(ctx, responseTime) {
+	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, responseTime) {
+	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, responseTime) {
+	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, responseTime) {
+	const contentLength = getContentLength(ctx) ?? "-";
+	return `${ctx.method} ${ctx.path} ${ctx.status} ${contentLength} - ${responseTime.toFixed(3)} ms`;
+}
+/**
+* Map of predefined format functions.
+*/
+const predefinedFormats = {
+	combined: formatCombined,
+	common: formatCommon,
+	dev: formatDev,
+	short: formatShort,
+	tiny: formatTiny
+};
+/**
+* Normalize category to array format.
+*/
+function normalizeCategory(category) {
+	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
+*/
+function koaLogger(options = {}) {
+	const category = normalizeCategory(options.category ?? ["koa"]);
+	const logger = (0, __logtape_logtape.getLogger)(category);
+	const level = options.level ?? "info";
+	const formatOption = options.format ?? "combined";
+	const skip = options.skip ?? (() => false);
+	const logRequest = options.logRequest ?? false;
+	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);
+			}
+			await next();
+			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);
+	};
+}
+
+//#endregion
+exports.koaLogger = koaLogger;

package/dist/mod.d.cts

@@ -0,0 +1,192 @@
+import { LogLevel, LogLevel as LogLevel$1 } from "@logtape/logtape";
+
+//#region src/mod.d.ts
+
+/**
+ * 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
+ */
+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
+ */
+type KoaMiddleware = (ctx: KoaContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Predefined log format names compatible with Morgan.
+ * @since 1.3.0
+ */
+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
+ */
+type FormatFunction = (ctx: KoaContext, responseTime: number) => string | Record<string, unknown>;
+/**
+ * Structured log properties for HTTP requests.
+ * @since 1.3.0
+ */
+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
+ */
+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$1;
+  /**
+   * 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;
+}
+/**
+ * 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
+ */
+declare function koaLogger(options?: KoaLogTapeOptions): KoaMiddleware;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { FormatFunction, KoaContext, KoaLogTapeOptions, KoaMiddleware, LogLevel, PredefinedFormat, RequestLogProperties, koaLogger };
+//# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -0,0 +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"}