@logtape/express 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/express
+================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+*@logtape/express* is an [Express] middleware adapter that provides HTTP
+request logging using [LogTape] as the backend, as an alternative to [Morgan].
+
+[JSR]: https://jsr.io/@logtape/express
+[JSR badge]: https://jsr.io/badges/@logtape/express
+[npm]: https://www.npmjs.com/package/@logtape/express
+[npm badge]: https://img.shields.io/npm/v/@logtape/express?logo=npm
+[LogTape]: https://logtape.org/
+[Express]: https://expressjs.com/
+[Morgan]: https://github.com/expressjs/morgan
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@logtape/express  # for Deno
+npm  add     @logtape/express  # for npm
+pnpm add     @logtape/express  # for pnpm
+yarn add     @logtape/express  # for Yarn
+bun  add     @logtape/express  # for Bun
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+import { expressLogger } from "@logtape/express";
+import express from "express";
+
+await configure({
+  sinks: { console: getConsoleSink() },
+  loggers: [
+    { category: ["express"], sinks: ["console"], lowestLevel: "info" }
+  ],
+});
+
+const app = express();
+app.use(expressLogger());
+
+app.get("/", (req, res) => {
+  res.json({ hello: "world" });
+});
+
+app.listen(3000);
+~~~~
+
+
+Options
+-------
+
+~~~~ typescript
+app.use(expressLogger({
+  category: ["myapp", "http"],  // Custom category (default: ["express"])
+  level: "debug",                // Log level (default: "info")
+  format: "dev",                 // Predefined format (default: "combined")
+  skip: (req, res) => res.statusCode < 400,  // Skip successful requests
+  immediate: false,              // Log after response (default)
+}));
+~~~~
+
+
+Predefined Formats
+------------------
+
+- **combined**: Apache Combined Log Format with all properties (default)
+- **common**: Apache Common Log Format (without referrer/userAgent)
+- **dev**: Concise output for development (`GET /path 200 1.234 ms - 123`)
+- **short**: Shorter format with remote address
+- **tiny**: Minimal output
+
+
+Custom Format Function
+----------------------
+
+~~~~ typescript
+app.use(expressLogger({
+  format: (req, res, responseTime) => ({
+    method: req.method,
+    path: req.path,
+    status: res.statusCode,
+    duration: responseTime,
+    user: req.user?.id,
+  }),
+}));
+~~~~
+
+
+Docs
+----
+
+The docs of this package is available at
+<https://logtape.org/manual/integrations#express>.
+For the API references, see <https://jsr.io/@logtape/express/doc>.

package/deno.json

@@ -0,0 +1,34 @@
+{
+  "name": "@logtape/express",
+  "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,192 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __logtape_logtape = require_rolldown_runtime.__toESM(require("@logtape/logtape"));
+
+//#region src/mod.ts
+/**
+* Get remote address from request.
+*/
+function getRemoteAddr(req) {
+	return req.ip || req.socket?.remoteAddress;
+}
+/**
+* Get content length from response headers.
+*/
+function getContentLength(res) {
+	const contentLength = res.getHeader("content-length");
+	if (contentLength === void 0 || contentLength === null) return void 0;
+	return String(contentLength);
+}
+/**
+* Get referrer from request headers.
+*/
+function getReferrer(req) {
+	return req.get("referrer") || req.get("referer");
+}
+/**
+* Get user agent from request headers.
+*/
+function getUserAgent(req) {
+	return req.get("user-agent");
+}
+/**
+* Build structured log properties from request/response.
+*/
+function buildProperties(req, res, responseTime) {
+	return {
+		method: req.method,
+		url: req.originalUrl || req.url,
+		status: res.statusCode,
+		responseTime,
+		contentLength: getContentLength(res),
+		remoteAddr: getRemoteAddr(req),
+		userAgent: getUserAgent(req),
+		referrer: getReferrer(req),
+		httpVersion: req.httpVersion
+	};
+}
+/**
+* Combined format (Apache Combined Log Format).
+* Returns all structured properties.
+*/
+function formatCombined(req, res, responseTime) {
+	return { ...buildProperties(req, res, responseTime) };
+}
+/**
+* Common format (Apache Common Log Format).
+* Like combined but without referrer and userAgent.
+*/
+function formatCommon(req, res, responseTime) {
+	const props = buildProperties(req, res, responseTime);
+	const { referrer: _referrer, userAgent: _userAgent,...rest } = props;
+	return rest;
+}
+/**
+* Dev format (colored output for development).
+* :method :url :status :response-time ms - :res[content-length]
+*/
+function formatDev(req, res, responseTime) {
+	const contentLength = getContentLength(res) ?? "-";
+	return `${req.method} ${req.originalUrl || req.url} ${res.statusCode} ${responseTime.toFixed(3)} ms - ${contentLength}`;
+}
+/**
+* Short format.
+* :remote-addr :method :url HTTP/:http-version :status :res[content-length] - :response-time ms
+*/
+function formatShort(req, res, responseTime) {
+	const remoteAddr = getRemoteAddr(req) ?? "-";
+	const contentLength = getContentLength(res) ?? "-";
+	return `${remoteAddr} ${req.method} ${req.originalUrl || req.url} HTTP/${req.httpVersion} ${res.statusCode} ${contentLength} - ${responseTime.toFixed(3)} ms`;
+}
+/**
+* Tiny format (minimal output).
+* :method :url :status :res[content-length] - :response-time ms
+*/
+function formatTiny(req, res, responseTime) {
+	const contentLength = getContentLength(res) ?? "-";
+	return `${req.method} ${req.originalUrl || req.url} ${res.statusCode} ${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 Express 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.
+*
+* @example Basic usage
+* ```typescript
+* import express from "express";
+* import { configure, getConsoleSink } from "@logtape/logtape";
+* import { expressLogger } from "@logtape/express";
+*
+* await configure({
+*   sinks: { console: getConsoleSink() },
+*   loggers: [
+*     { category: ["express"], sinks: ["console"], lowestLevel: "info" }
+*   ],
+* });
+*
+* const app = express();
+* app.use(expressLogger());
+*
+* app.get("/", (req, res) => {
+*   res.json({ hello: "world" });
+* });
+*
+* app.listen(3000);
+* ```
+*
+* @example With custom options
+* ```typescript
+* app.use(expressLogger({
+*   category: ["myapp", "http"],
+*   level: "debug",
+*   format: "dev",
+*   skip: (req, res) => res.statusCode < 400,
+* }));
+* ```
+*
+* @example With custom format function
+* ```typescript
+* app.use(expressLogger({
+*   format: (req, res, responseTime) => ({
+*     method: req.method,
+*     path: req.path,
+*     status: res.statusCode,
+*     duration: responseTime,
+*   }),
+* }));
+* ```
+*
+* @param options Configuration options for the middleware.
+* @returns Express middleware function.
+* @since 1.3.0
+*/
+function expressLogger(options = {}) {
+	const category = normalizeCategory(options.category ?? ["express"]);
+	const logger = (0, __logtape_logtape.getLogger)(category);
+	const level = options.level ?? "info";
+	const formatOption = options.format ?? "combined";
+	const skip = options.skip ?? (() => false);
+	const immediate = options.immediate ?? false;
+	const formatFn = typeof formatOption === "string" ? predefinedFormats[formatOption] : formatOption;
+	const logMethod = logger[level].bind(logger);
+	return (req, res, next) => {
+		const startTime = Date.now();
+		if (immediate) {
+			if (!skip(req, res)) {
+				const result = formatFn(req, res, 0);
+				if (typeof result === "string") logMethod(result);
+				else logMethod("{method} {url}", result);
+			}
+			next();
+			return;
+		}
+		const logRequest = () => {
+			if (skip(req, res)) return;
+			const responseTime = Date.now() - startTime;
+			const result = formatFn(req, res, responseTime);
+			if (typeof result === "string") logMethod(result);
+			else logMethod("{method} {url} {status} - {responseTime} ms", result);
+		};
+		res.on("finish", logRequest);
+		next();
+	};
+}
+
+//#endregion
+exports.expressLogger = expressLogger;

package/dist/mod.d.cts

@@ -0,0 +1,192 @@
+import { LogLevel, LogLevel as LogLevel$1 } from "@logtape/logtape";
+
+//#region src/mod.d.ts
+
+/**
+ * Minimal Express Request interface for compatibility.
+ * @since 1.3.0
+ */
+interface ExpressRequest {
+  method: string;
+  url: string;
+  originalUrl?: string;
+  path?: string;
+  httpVersion: string;
+  ip?: string;
+  socket?: {
+    remoteAddress?: string;
+  };
+  get(header: string): string | undefined;
+}
+/**
+ * Minimal Express Response interface for compatibility.
+ * @since 1.3.0
+ */
+interface ExpressResponse {
+  statusCode: number;
+  on(event: string, listener: () => void): void;
+  getHeader(name: string): string | number | string[] | undefined;
+}
+/**
+ * Express NextFunction type.
+ * @since 1.3.0
+ */
+type ExpressNextFunction = (err?: unknown) => void;
+/**
+ * Express middleware function type.
+ * @since 1.3.0
+ */
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => 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 req The Express request object.
+ * @param res The Express response object.
+ * @param responseTime The response time in milliseconds.
+ * @returns A string message or an object with structured properties.
+ * @since 1.3.0
+ */
+type FormatFunction = (req: ExpressRequest, res: ExpressResponse, 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;
+  /** HTTP response status code */
+  status: number;
+  /** Response time in milliseconds */
+  responseTime: number;
+  /** Response content-length header value */
+  contentLength: string | undefined;
+  /** Remote client address */
+  remoteAddr: string | undefined;
+  /** User-Agent header value */
+  userAgent: string | undefined;
+  /** Referrer header value */
+  referrer: string | undefined;
+  /** HTTP version (e.g., "1.1") */
+  httpVersion: string;
+}
+/**
+ * Options for configuring the Express LogTape middleware.
+ * @since 1.3.0
+ */
+interface ExpressLogTapeOptions {
+  /**
+   * The LogTape category to use for logging.
+   * @default ["express"]
+   */
+  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 successful requests
+   * ```typescript
+   * app.use(expressLogger({
+   *   skip: (req, res) => res.statusCode < 400,
+   * }));
+   * ```
+   *
+   * @default () => false
+   */
+  readonly skip?: (req: ExpressRequest, res: ExpressResponse) => 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 `immediate` is `true`, response-related properties
+   * (status, responseTime, contentLength) will not be available.
+   *
+   * @default false
+   */
+  readonly immediate?: boolean;
+}
+/**
+ * Creates Express 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.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import express from "express";
+ * import { configure, getConsoleSink } from "@logtape/logtape";
+ * import { expressLogger } from "@logtape/express";
+ *
+ * await configure({
+ *   sinks: { console: getConsoleSink() },
+ *   loggers: [
+ *     { category: ["express"], sinks: ["console"], lowestLevel: "info" }
+ *   ],
+ * });
+ *
+ * const app = express();
+ * app.use(expressLogger());
+ *
+ * app.get("/", (req, res) => {
+ *   res.json({ hello: "world" });
+ * });
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * app.use(expressLogger({
+ *   category: ["myapp", "http"],
+ *   level: "debug",
+ *   format: "dev",
+ *   skip: (req, res) => res.statusCode < 400,
+ * }));
+ * ```
+ *
+ * @example With custom format function
+ * ```typescript
+ * app.use(expressLogger({
+ *   format: (req, res, responseTime) => ({
+ *     method: req.method,
+ *     path: req.path,
+ *     status: res.statusCode,
+ *     duration: responseTime,
+ *   }),
+ * }));
+ * ```
+ *
+ * @param options Configuration options for the middleware.
+ * @returns Express middleware function.
+ * @since 1.3.0
+ */
+declare function expressLogger(options?: ExpressLogTapeOptions): ExpressMiddleware;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { ExpressLogTapeOptions, ExpressMiddleware, ExpressNextFunction, ExpressRequest, ExpressResponse, FormatFunction, LogLevel, PredefinedFormat, RequestLogProperties, expressLogger };
+//# 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":";;;;;AAWA;AAeA;AAUA;AAMY,UA/BK,cAAA,CA+BY;EAAA,MAAA,EAAA,MAAA;EAAA,GACtB,EAAA,MAAA;EAAc,WACd,CAAA,EAAA,MAAA;EAAe,IACd,CAAA,EAAA,MAAA;EAAmB,WAAA,EAAA,MAAA;EAOf,EAAA,CAAA,EAAA,MAAA;EAWA,MAAA,CAAA,EAAA;IAAc,aAAA,CAAA,EAAA,MAAA;EAAA,CAAA;EACL,GACd,CAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;AAEa;AAMpB;AAyBA;;AAWmB,UAnFF,eAAA,CAmFE;EAAQ,UAeP,EAAA,MAAA;EAAgB,EAAA,CAAG,KAAA,EAAA,MAAA,EAAA,QAAA,EAAA,GAAA,GAAA,IAAA,CAAA,EAAA,IAAA;EAAc,SAe7B,CAAA,IAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,MAAA,GAAA,MAAA,EAAA,GAAA,SAAA;;AAAoC;AAsN5D;;;AAEG,KA/TS,mBAAA,GA+TT,CAAA,GAAA,CAAA,EAAA,OAAA,EAAA,GAAA,IAAA;AAAiB;;;;KAzTR,iBAAA,SACL,qBACA,uBACC;;;;;KAOI,gBAAA;;;;;;;;;;KAWA,cAAA,SACL,qBACA,mDAEO;;;;;UAMG,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;UAyBA,qBAAA;;;;;;;;;;mBAWE;;;;;;;;;;;;;;oBAeC,mBAAmB;;;;;;;;;;;;;;wBAef,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsN7B,aAAA,WACL,wBACR"}