@logtape/adaptor-winston 1.0.0-dev.257

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024 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,218 @@
+<!-- deno-fmt-ignore-file -->
+
+@logtape/adaptor-winston
+========================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+*@logtape/adaptor-winston* is a [LogTape] adapter that forwards log records to
+[winston] loggers, enabling seamless integration between LogTape-enabled libraries
+and applications using winston for logging infrastructure.
+
+[JSR]: https://jsr.io/@logtape/adaptor-winston
+[JSR badge]: https://jsr.io/badges/@logtape/adaptor-winston
+[npm]: https://www.npmjs.com/package/@logtape/adaptor-winston
+[npm badge]: https://img.shields.io/npm/v/@logtape/adaptor-winston?logo=npm
+[LogTape]: https://logtape.org/
+[winston]: https://github.com/winstonjs/winston
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@logtape/adaptor-winston  # for Deno
+npm  add     @logtape/adaptor-winston  # for npm
+pnpm add     @logtape/adaptor-winston  # for pnpm
+yarn add     @logtape/adaptor-winston  # for Yarn
+bun  add     @logtape/adaptor-winston  # for Bun
+~~~~
+
+
+Quick start
+-----------
+
+The simplest way to integrate LogTape with winston is to import the auto-installer:
+
+~~~~ typescript
+import "@logtape/adaptor-winston/install";
+
+// That's it! All LogTape logs will now be routed to winston's default logger
+import { getLogger } from "@logtape/logtape";
+const logger = getLogger("my-app");
+logger.info("This will be logged through winston");
+~~~~
+
+You can also use it with Node.js's `-r` flag:
+
+~~~~ sh
+node -r @logtape/adaptor-winston/install app.js
+~~~~
+
+For custom winston loggers or configuration options, see the [Usage](#usage) section below.
+
+
+Usage
+-----
+
+### Using the install() function
+
+If you need a custom winston logger or configuration options, you can use
+the `install()` function:
+
+~~~~ typescript
+import winston from "winston";
+import { install } from "@logtape/adaptor-winston";
+
+// With a custom winston logger
+const customLogger = winston.createLogger({
+  level: "info",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: "app.log" })
+  ]
+});
+
+install(customLogger);
+~~~~
+
+You can also pass configuration options:
+
+~~~~ typescript
+import { install } from "@logtape/adaptor-winston";
+
+// With default winston logger but custom options
+install({
+  category: {
+    position: "start",
+    decorator: "[]",
+    separator: "."
+  }
+});
+
+// Or with both custom logger and options
+install(customLogger, {
+  category: { position: "start", decorator: "[]" }
+});
+~~~~
+
+### Manual configuration
+
+For full control over the winston integration, configure LogTape manually:
+
+~~~~ typescript
+import { configure } from "@logtape/logtape";
+import { getWinstonSink } from "@logtape/adaptor-winston";
+import winston from "winston";
+
+const winstonLogger = winston.createLogger({
+  level: "info",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: "app.log" })
+  ]
+});
+
+await configure({
+  sinks: {
+    winston: getWinstonSink(winstonLogger, {
+      category: {
+        position: "start",
+        decorator: "[]",
+        separator: "."
+      }
+    })
+  },
+  loggers: [
+    { category: "my-library", sinks: ["winston"] }
+  ]
+});
+~~~~
+
+
+Level mapping
+-------------
+
+LogTape log levels are mapped to winston levels as follows:
+
+| LogTape Level | winston Level |
+|---------------|---------------|
+| `trace`       | `silly`       |
+| `debug`       | `debug`       |
+| `info`        | `info`        |
+| `warning`     | `warn`        |
+| `error`       | `error`       |
+| `fatal`       | `error`       |
+
+You can customize this mapping:
+
+~~~~ typescript
+import { install } from "@logtape/adaptor-winston";
+
+install({
+  levelsMap: {
+    "trace": "debug",  // Map trace to debug instead of silly
+    "debug": "debug",
+    "info": "info",
+    "warning": "warn",
+    "error": "error",
+    "fatal": "error"
+  }
+});
+~~~~
+
+
+Category formatting
+-------------------
+
+The adapter supports flexible category formatting options:
+
+~~~~typescript
+import { install } from "@logtape/adaptor-winston";
+
+// Hide categories completely
+install({ category: false });
+
+// Use default formatting (category with ":" separator)
+install({ category: true });
+
+// Custom formatting
+install({
+  category: {
+    position: "end",      // "start" or "end"
+    decorator: "[]",      // "[]", "()", "<>", "{}", ":", "-", "|", "/", ""
+    separator: "::"       // custom separator for multi-part categories
+  }
+});
+~~~~
+
+
+Value formatting
+----------------
+
+Customize how interpolated values are formatted in log messages:
+
+~~~~ typescript
+import { install } from "@logtape/adaptor-winston";
+
+install({
+  valueFormatter: (value) => JSON.stringify(value, null, 2)
+});
+~~~~
+
+
+Docs
+----
+
+See the [API reference] on JSR for further details.
+
+[API reference]: https://jsr.io/@logtape/adaptor-winston/doc

package/deno.json

@@ -0,0 +1,40 @@
+{
+  "name": "@logtape/adaptor-winston",
+  "version": "1.0.0-dev.257+f86501ac",
+  "license": "MIT",
+  "exports": {
+    ".": "./mod.ts",
+    "./install": "./install.ts"
+  },
+  "imports": {
+    "winston": "npm:winston@^3.17.0"
+  },
+  "exclude": [
+    "coverage/",
+    "npm/",
+    ".dnt-import-map.json"
+  ],
+  "tasks": {
+    "build": "pnpm build",
+    "test": "deno test --allow-env",
+    "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/install.cjs

@@ -0,0 +1,6 @@
+const require_mod = require('./mod.cjs');
+
+//#region install.ts
+require_mod.install();
+
+//#endregion

package/dist/install.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/install.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/install.js

@@ -0,0 +1,7 @@
+import { install } from "./mod.js";
+
+//#region install.ts
+install();
+
+//#endregion
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","names":[],"sources":["../install.ts"],"sourcesContent":["/**\n * Auto-installation module for @logtape/adaptor-winston.\n *\n * This module automatically configures LogTape to route all log records\n * to winston's default logger when imported. This provides the simplest\n * possible integration - just import this module and all LogTape-enabled\n * libraries will immediately start logging through winston.\n *\n * @example Automatic installation via import\n * ```typescript\n * // Simply import this module to automatically set up winston adapter\n * import \"@logtape/adaptor-winston/install\";\n *\n * // Now all LogTape logs will be routed to winston's default logger\n * import { getLogger } from \"@logtape/logtape\";\n * const logger = getLogger(\"my-app\");\n * logger.info(\"This will be logged through winston\");\n * ```\n *\n * @example Usage in package.json scripts\n * ```json\n * {\n *   \"scripts\": {\n *     \"start\": \"node -r @logtape/adaptor-winston/install app.js\"\n *   }\n * }\n * ```\n *\n * @example Usage with module bundlers\n * ```typescript\n * // webpack.config.js or similar\n * module.exports = {\n *   entry: [\n *     '@logtape/adaptor-winston/install',\n *     './src/index.js'\n *   ]\n * };\n * ```\n *\n * > [!NOTE]\n * > This module uses winston's default logger with default configuration.\n * > If you need a custom winston logger or configuration options (category\n * > formatting, level mapping, etc.), use the `install()` function from the\n * > main module instead:\n *\n * @example Custom winston logger\n * ```typescript\n * import winston from \"winston\";\n * import { install } from \"@logtape/adaptor-winston\";\n *\n * const customLogger = winston.createLogger({\n *   transports: [new winston.transports.File({ filename: \"app.log\" })]\n * });\n *\n * install(customLogger);\n * ```\n *\n * @example Custom configuration options\n * ```typescript\n * import { install } from \"@logtape/adaptor-winston\";\n *\n * install({\n *   category: { position: \"start\", decorator: \"[]\" }\n * });\n * ```\n *\n * @example Custom logger with custom options\n * ```typescript\n * import winston from \"winston\";\n * import { install } from \"@logtape/adaptor-winston\";\n *\n * const customLogger = winston.createLogger({\n *   transports: [new winston.transports.Console()]\n * });\n *\n * install(customLogger, {\n *   category: { position: \"start\", decorator: \"[]\" }\n * });\n * ```\n *\n * @module\n * @since 1.0.0\n */\n\nimport { install } from \"./mod.ts\";\n\ninstall();\n"],"mappings":";;;AAsFA,SAAS"}

package/dist/mod.cjs

@@ -0,0 +1,120 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __logtape_logtape = require_rolldown_runtime.__toESM(require("@logtape/logtape"));
+const winston = require_rolldown_runtime.__toESM(require("winston"));
+const node_util = require_rolldown_runtime.__toESM(require("node:util"));
+
+//#region mod.ts
+const DEFAULT_LEVELS_MAP = {
+	"trace": "silly",
+	"debug": "debug",
+	"info": "info",
+	"warning": "warn",
+	"error": "error",
+	"fatal": "error"
+};
+/**
+* Creates a LogTape sink that forwards log records to a winston logger.
+*
+* This function creates a sink function that can be used with LogTape's
+* configuration system. The sink will format LogTape log records and
+* forward them to the provided winston logger instance.
+*
+* @example Basic usage
+* ```typescript
+* import winston from "winston";
+* import { configure } from "@logtape/logtape";
+* import { getWinstonSink } from "@logtape/adaptor-winston";
+*
+* const winstonLogger = winston.createLogger({
+*   level: "info",
+*   format: winston.format.combine(
+*     winston.format.timestamp(),
+*     winston.format.json()
+*   ),
+*   transports: [new winston.transports.Console()]
+* });
+*
+* await configure({
+*   sinks: {
+*     winston: getWinstonSink(winstonLogger)
+*   },
+*   loggers: [
+*     { category: ["myapp"], sinks: ["winston"] }
+*   ]
+* });
+* ```
+*
+* @example With custom options
+* ```typescript
+* const sink = getWinstonSink(winstonLogger, {
+*   category: {
+*     separator: ".",
+*     position: "start",
+*     decorator: "[]"
+*   },
+*   levelsMap: {
+*     "trace": "debug",  // Map trace to debug instead of silly
+*     "debug": "debug",
+*     "info": "info",
+*     "warning": "warn",
+*     "error": "error",
+*     "fatal": "error"
+*   }
+* });
+* ```
+*
+* @param logger The winston logger instance to forward logs to. Must implement
+*               the Logger interface with error, warn, info, http, verbose,
+*               debug, and silly methods.
+* @param options Configuration options for the sink behavior.
+* @returns A sink function that can be used with LogTape's configure() function.
+* @since 1.0.0
+*/
+function getWinstonSink(logger, options = {}) {
+	const { levelsMap = DEFAULT_LEVELS_MAP, valueFormatter = node_util.inspect } = options;
+	const categoryOptions = !options.category ? void 0 : typeof options.category === "object" ? options.category : {};
+	const category = categoryOptions == null ? void 0 : {
+		separator: categoryOptions.separator ?? "·",
+		position: categoryOptions.position ?? "start",
+		decorator: categoryOptions.decorator ?? ":"
+	};
+	return (record) => {
+		const level = levelsMap[record.level];
+		let message = "";
+		if (category?.position === "start" && record.category.length > 0) {
+			const joinedCategory = record.category.join(category.separator);
+			message += category.decorator === "[]" ? `[${joinedCategory}] ` : category.decorator === "()" ? `(${joinedCategory}) ` : category.decorator === "<>" ? `<${joinedCategory}> ` : category.decorator === "{}" ? `{${joinedCategory}} ` : category.decorator === ":" ? `${joinedCategory}: ` : category.decorator === "-" ? `${joinedCategory} - ` : category.decorator === "|" ? `${joinedCategory} | ` : category.decorator === "/" ? `${joinedCategory} / ` : `${joinedCategory} `;
+		}
+		for (let i = 0; i < record.message.length; i += 2) {
+			message += record.message[i];
+			if (i + 1 < record.message.length) message += valueFormatter(record.message[i + 1]);
+		}
+		if (category?.position === "end" && record.category.length > 0) {
+			const joinedCategory = record.category.join(category.separator);
+			message += category.decorator === "[]" ? ` [${joinedCategory}]` : category.decorator === "()" ? ` (${joinedCategory})` : category.decorator === "<>" ? ` <${joinedCategory}>` : category.decorator === "{}" ? ` {${joinedCategory}}` : category.decorator === ":" ? `: ${joinedCategory}` : category.decorator === "-" ? ` - ${joinedCategory}` : category.decorator === "|" ? ` | ${joinedCategory}` : category.decorator === "/" ? ` / ${joinedCategory}` : ` ${joinedCategory}`;
+		}
+		logger[level](message, record.properties);
+	};
+}
+function install(loggerOrOptions, options = {}) {
+	let logger;
+	let sinkOptions;
+	if (loggerOrOptions && ("error" in loggerOrOptions || "info" in loggerOrOptions)) {
+		logger = loggerOrOptions;
+		sinkOptions = options;
+	} else {
+		logger = winston.default;
+		sinkOptions = loggerOrOptions || {};
+	}
+	(0, __logtape_logtape.configureSync)({
+		sinks: { winston: getWinstonSink(logger, sinkOptions) },
+		loggers: [{
+			category: [],
+			sinks: ["winston"]
+		}]
+	});
+}
+
+//#endregion
+exports.getWinstonSink = getWinstonSink;
+exports.install = install;