@logtape/file 1.0.0-dev.237 → 1.0.0-dev.241

package/dist/mod.js

@@ -1,3 +1,4 @@
+import { getStreamFileSink } from "./streamfilesink.js";
 import { getFileSink, getRotatingFileSink } from "#filesink";
 
-export { getFileSink, getRotatingFileSink };
+export { getFileSink, getRotatingFileSink, getStreamFileSink };

package/dist/streamfilesink.cjs

@@ -0,0 +1,84 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __logtape_logtape = require_rolldown_runtime.__toESM(require("@logtape/logtape"));
+const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
+const node_stream = require_rolldown_runtime.__toESM(require("node:stream"));
+
+//#region streamfilesink.ts
+/**
+* Create a high-performance stream-based file sink that writes log records to a file.
+*
+* This sink uses Node.js PassThrough streams piped to WriteStreams for optimal
+* I/O performance. It leverages the Node.js stream infrastructure to provide
+* automatic backpressure management, efficient buffering, and asynchronous writes
+* without blocking the main thread.
+*
+* ## Performance Characteristics
+*
+* - **High Performance**: Optimized for high-volume logging scenarios
+* - **Non-blocking**: Uses asynchronous I/O that doesn't block the main thread
+* - **Memory Efficient**: Automatic backpressure prevents memory buildup
+* - **Stream-based**: Leverages Node.js native stream optimizations
+*
+* ## When to Use
+*
+* Use this sink when you need:
+* - High-performance file logging for production applications
+* - Non-blocking I/O behavior for real-time applications
+* - Automatic backpressure handling for high-volume scenarios
+* - Simple file output without complex buffering configuration
+*
+* For more control over buffering behavior, consider using {@link getFileSink}
+* instead, which provides options for buffer size, flush intervals, and
+* non-blocking modes.
+*
+* ## Example
+*
+* ```typescript
+* import { configure } from "@logtape/logtape";
+* import { getStreamFileSink } from "@logtape/file";
+*
+* await configure({
+*   sinks: {
+*     file: getStreamFileSink("app.log", {
+*       highWaterMark: 32768  // 32KB buffer for high-volume logging
+*     })
+*   },
+*   loggers: [
+*     { category: ["myapp"], sinks: ["file"] }
+*   ]
+* });
+* ```
+*
+* @param path The path to the file to write logs to. The file will be created
+*             if it doesn't exist, or appended to if it does exist.
+* @param options Configuration options for the stream-based sink.
+* @returns A sink that writes formatted log records to the specified file.
+*          The returned sink implements `Disposable` for proper resource cleanup.
+*
+* @since 1.0.0
+*/
+function getStreamFileSink(path, options = {}) {
+	const highWaterMark = options.highWaterMark ?? 16384;
+	const formatter = options.formatter ?? __logtape_logtape.defaultTextFormatter;
+	const passThrough = new node_stream.PassThrough({
+		highWaterMark,
+		objectMode: false
+	});
+	const writeStream = (0, node_fs.createWriteStream)(path, { flags: "a" });
+	passThrough.pipe(writeStream);
+	let disposed = false;
+	const sink = (record) => {
+		if (disposed) return;
+		passThrough.write(formatter(record));
+	};
+	sink[Symbol.dispose] = () => {
+		if (disposed) return;
+		disposed = true;
+		passThrough.end();
+		writeStream.end();
+	};
+	return sink;
+}
+
+//#endregion
+exports.getStreamFileSink = getStreamFileSink;

package/dist/streamfilesink.d.cts

@@ -0,0 +1,95 @@
+import { Sink, TextFormatter } from "@logtape/logtape";
+
+//#region streamfilesink.d.ts
+
+/**
+ * Options for the {@link getStreamFileSink} function.
+ *
+ * This interface configures the high-performance stream-based file sink that
+ * uses Node.js PassThrough streams for optimal I/O performance with automatic
+ * backpressure management.
+ *
+ * @since 1.0.0
+ */
+interface StreamFileSinkOptions {
+  /**
+   * High water mark for the PassThrough stream buffer in bytes.
+   *
+   * This controls the internal buffer size of the PassThrough stream.
+   * Higher values can improve performance for high-volume logging but use
+   * more memory. Lower values reduce memory usage but may impact performance.
+   *
+   * @default 16384
+   * @since 1.0.0
+   */
+  readonly highWaterMark?: number;
+  /**
+   * A custom formatter for log records.
+   *
+   * If not specified, the default text formatter will be used, which formats
+   * records in the standard LogTape format with timestamp, level, category,
+   * and message.
+   *
+   * @default defaultTextFormatter
+   * @since 1.0.0
+   */
+  readonly formatter?: TextFormatter;
+}
+/**
+ * Create a high-performance stream-based file sink that writes log records to a file.
+ *
+ * This sink uses Node.js PassThrough streams piped to WriteStreams for optimal
+ * I/O performance. It leverages the Node.js stream infrastructure to provide
+ * automatic backpressure management, efficient buffering, and asynchronous writes
+ * without blocking the main thread.
+ *
+ * ## Performance Characteristics
+ *
+ * - **High Performance**: Optimized for high-volume logging scenarios
+ * - **Non-blocking**: Uses asynchronous I/O that doesn't block the main thread
+ * - **Memory Efficient**: Automatic backpressure prevents memory buildup
+ * - **Stream-based**: Leverages Node.js native stream optimizations
+ *
+ * ## When to Use
+ *
+ * Use this sink when you need:
+ * - High-performance file logging for production applications
+ * - Non-blocking I/O behavior for real-time applications
+ * - Automatic backpressure handling for high-volume scenarios
+ * - Simple file output without complex buffering configuration
+ *
+ * For more control over buffering behavior, consider using {@link getFileSink}
+ * instead, which provides options for buffer size, flush intervals, and
+ * non-blocking modes.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { configure } from "@logtape/logtape";
+ * import { getStreamFileSink } from "@logtape/file";
+ *
+ * await configure({
+ *   sinks: {
+ *     file: getStreamFileSink("app.log", {
+ *       highWaterMark: 32768  // 32KB buffer for high-volume logging
+ *     })
+ *   },
+ *   loggers: [
+ *     { category: ["myapp"], sinks: ["file"] }
+ *   ]
+ * });
+ * ```
+ *
+ * @param path The path to the file to write logs to. The file will be created
+ *             if it doesn't exist, or appended to if it does exist.
+ * @param options Configuration options for the stream-based sink.
+ * @returns A sink that writes formatted log records to the specified file.
+ *          The returned sink implements `Disposable` for proper resource cleanup.
+ *
+ * @since 1.0.0
+ */
+declare function getStreamFileSink(path: string, options?: StreamFileSinkOptions): Sink & Disposable;
+//# sourceMappingURL=streamfilesink.d.ts.map
+//#endregion
+export { StreamFileSinkOptions, getStreamFileSink };
+//# sourceMappingURL=streamfilesink.d.cts.map

package/dist/streamfilesink.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamfilesink.d.cts","names":[],"sources":["../streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AA+EA;;;;;AAGoB;UAlFH,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDP,iBAAA,yBAEL,wBACR,OAAO"}

package/dist/streamfilesink.d.ts

@@ -0,0 +1,95 @@
+import { Sink, TextFormatter } from "@logtape/logtape";
+
+//#region streamfilesink.d.ts
+
+/**
+ * Options for the {@link getStreamFileSink} function.
+ *
+ * This interface configures the high-performance stream-based file sink that
+ * uses Node.js PassThrough streams for optimal I/O performance with automatic
+ * backpressure management.
+ *
+ * @since 1.0.0
+ */
+interface StreamFileSinkOptions {
+  /**
+   * High water mark for the PassThrough stream buffer in bytes.
+   *
+   * This controls the internal buffer size of the PassThrough stream.
+   * Higher values can improve performance for high-volume logging but use
+   * more memory. Lower values reduce memory usage but may impact performance.
+   *
+   * @default 16384
+   * @since 1.0.0
+   */
+  readonly highWaterMark?: number;
+  /**
+   * A custom formatter for log records.
+   *
+   * If not specified, the default text formatter will be used, which formats
+   * records in the standard LogTape format with timestamp, level, category,
+   * and message.
+   *
+   * @default defaultTextFormatter
+   * @since 1.0.0
+   */
+  readonly formatter?: TextFormatter;
+}
+/**
+ * Create a high-performance stream-based file sink that writes log records to a file.
+ *
+ * This sink uses Node.js PassThrough streams piped to WriteStreams for optimal
+ * I/O performance. It leverages the Node.js stream infrastructure to provide
+ * automatic backpressure management, efficient buffering, and asynchronous writes
+ * without blocking the main thread.
+ *
+ * ## Performance Characteristics
+ *
+ * - **High Performance**: Optimized for high-volume logging scenarios
+ * - **Non-blocking**: Uses asynchronous I/O that doesn't block the main thread
+ * - **Memory Efficient**: Automatic backpressure prevents memory buildup
+ * - **Stream-based**: Leverages Node.js native stream optimizations
+ *
+ * ## When to Use
+ *
+ * Use this sink when you need:
+ * - High-performance file logging for production applications
+ * - Non-blocking I/O behavior for real-time applications
+ * - Automatic backpressure handling for high-volume scenarios
+ * - Simple file output without complex buffering configuration
+ *
+ * For more control over buffering behavior, consider using {@link getFileSink}
+ * instead, which provides options for buffer size, flush intervals, and
+ * non-blocking modes.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { configure } from "@logtape/logtape";
+ * import { getStreamFileSink } from "@logtape/file";
+ *
+ * await configure({
+ *   sinks: {
+ *     file: getStreamFileSink("app.log", {
+ *       highWaterMark: 32768  // 32KB buffer for high-volume logging
+ *     })
+ *   },
+ *   loggers: [
+ *     { category: ["myapp"], sinks: ["file"] }
+ *   ]
+ * });
+ * ```
+ *
+ * @param path The path to the file to write logs to. The file will be created
+ *             if it doesn't exist, or appended to if it does exist.
+ * @param options Configuration options for the stream-based sink.
+ * @returns A sink that writes formatted log records to the specified file.
+ *          The returned sink implements `Disposable` for proper resource cleanup.
+ *
+ * @since 1.0.0
+ */
+declare function getStreamFileSink(path: string, options?: StreamFileSinkOptions): Sink & Disposable;
+//# sourceMappingURL=streamfilesink.d.ts.map
+//#endregion
+export { StreamFileSinkOptions, getStreamFileSink };
+//# sourceMappingURL=streamfilesink.d.ts.map

package/dist/streamfilesink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamfilesink.d.ts","names":[],"sources":["../streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AA+EA;;;;;AAGoB;UAlFH,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDP,iBAAA,yBAEL,wBACR,OAAO"}

package/dist/streamfilesink.js

@@ -0,0 +1,84 @@
+import { defaultTextFormatter } from "@logtape/logtape";
+import { createWriteStream } from "node:fs";
+import { PassThrough } from "node:stream";
+
+//#region streamfilesink.ts
+/**
+* Create a high-performance stream-based file sink that writes log records to a file.
+*
+* This sink uses Node.js PassThrough streams piped to WriteStreams for optimal
+* I/O performance. It leverages the Node.js stream infrastructure to provide
+* automatic backpressure management, efficient buffering, and asynchronous writes
+* without blocking the main thread.
+*
+* ## Performance Characteristics
+*
+* - **High Performance**: Optimized for high-volume logging scenarios
+* - **Non-blocking**: Uses asynchronous I/O that doesn't block the main thread
+* - **Memory Efficient**: Automatic backpressure prevents memory buildup
+* - **Stream-based**: Leverages Node.js native stream optimizations
+*
+* ## When to Use
+*
+* Use this sink when you need:
+* - High-performance file logging for production applications
+* - Non-blocking I/O behavior for real-time applications
+* - Automatic backpressure handling for high-volume scenarios
+* - Simple file output without complex buffering configuration
+*
+* For more control over buffering behavior, consider using {@link getFileSink}
+* instead, which provides options for buffer size, flush intervals, and
+* non-blocking modes.
+*
+* ## Example
+*
+* ```typescript
+* import { configure } from "@logtape/logtape";
+* import { getStreamFileSink } from "@logtape/file";
+*
+* await configure({
+*   sinks: {
+*     file: getStreamFileSink("app.log", {
+*       highWaterMark: 32768  // 32KB buffer for high-volume logging
+*     })
+*   },
+*   loggers: [
+*     { category: ["myapp"], sinks: ["file"] }
+*   ]
+* });
+* ```
+*
+* @param path The path to the file to write logs to. The file will be created
+*             if it doesn't exist, or appended to if it does exist.
+* @param options Configuration options for the stream-based sink.
+* @returns A sink that writes formatted log records to the specified file.
+*          The returned sink implements `Disposable` for proper resource cleanup.
+*
+* @since 1.0.0
+*/
+function getStreamFileSink(path, options = {}) {
+	const highWaterMark = options.highWaterMark ?? 16384;
+	const formatter = options.formatter ?? defaultTextFormatter;
+	const passThrough = new PassThrough({
+		highWaterMark,
+		objectMode: false
+	});
+	const writeStream = createWriteStream(path, { flags: "a" });
+	passThrough.pipe(writeStream);
+	let disposed = false;
+	const sink = (record) => {
+		if (disposed) return;
+		passThrough.write(formatter(record));
+	};
+	sink[Symbol.dispose] = () => {
+		if (disposed) return;
+		disposed = true;
+		passThrough.end();
+		writeStream.end();
+	};
+	return sink;
+}
+
+//#endregion
+export { getStreamFileSink };
+//# sourceMappingURL=streamfilesink.js.map

package/dist/streamfilesink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamfilesink.js","names":["path: string","options: StreamFileSinkOptions","sink: Sink & Disposable","record: LogRecord"],"sources":["../streamfilesink.ts"],"sourcesContent":["import {\n  defaultTextFormatter,\n  type LogRecord,\n  type Sink,\n  type TextFormatter,\n} from \"@logtape/logtape\";\nimport { createWriteStream } from \"node:fs\";\nimport { PassThrough } from \"node:stream\";\n\n/**\n * Options for the {@link getStreamFileSink} function.\n *\n * This interface configures the high-performance stream-based file sink that\n * uses Node.js PassThrough streams for optimal I/O performance with automatic\n * backpressure management.\n *\n * @since 1.0.0\n */\nexport interface StreamFileSinkOptions {\n  /**\n   * High water mark for the PassThrough stream buffer in bytes.\n   *\n   * This controls the internal buffer size of the PassThrough stream.\n   * Higher values can improve performance for high-volume logging but use\n   * more memory. Lower values reduce memory usage but may impact performance.\n   *\n   * @default 16384\n   * @since 1.0.0\n   */\n  readonly highWaterMark?: number;\n\n  /**\n   * A custom formatter for log records.\n   *\n   * If not specified, the default text formatter will be used, which formats\n   * records in the standard LogTape format with timestamp, level, category,\n   * and message.\n   *\n   * @default defaultTextFormatter\n   * @since 1.0.0\n   */\n  readonly formatter?: TextFormatter;\n}\n\n/**\n * Create a high-performance stream-based file sink that writes log records to a file.\n *\n * This sink uses Node.js PassThrough streams piped to WriteStreams for optimal\n * I/O performance. It leverages the Node.js stream infrastructure to provide\n * automatic backpressure management, efficient buffering, and asynchronous writes\n * without blocking the main thread.\n *\n * ## Performance Characteristics\n *\n * - **High Performance**: Optimized for high-volume logging scenarios\n * - **Non-blocking**: Uses asynchronous I/O that doesn't block the main thread\n * - **Memory Efficient**: Automatic backpressure prevents memory buildup\n * - **Stream-based**: Leverages Node.js native stream optimizations\n *\n * ## When to Use\n *\n * Use this sink when you need:\n * - High-performance file logging for production applications\n * - Non-blocking I/O behavior for real-time applications\n * - Automatic backpressure handling for high-volume scenarios\n * - Simple file output without complex buffering configuration\n *\n * For more control over buffering behavior, consider using {@link getFileSink}\n * instead, which provides options for buffer size, flush intervals, and\n * non-blocking modes.\n *\n * ## Example\n *\n * ```typescript\n * import { configure } from \"@logtape/logtape\";\n * import { getStreamFileSink } from \"@logtape/file\";\n *\n * await configure({\n *   sinks: {\n *     file: getStreamFileSink(\"app.log\", {\n *       highWaterMark: 32768  // 32KB buffer for high-volume logging\n *     })\n *   },\n *   loggers: [\n *     { category: [\"myapp\"], sinks: [\"file\"] }\n *   ]\n * });\n * ```\n *\n * @param path The path to the file to write logs to. The file will be created\n *             if it doesn't exist, or appended to if it does exist.\n * @param options Configuration options for the stream-based sink.\n * @returns A sink that writes formatted log records to the specified file.\n *          The returned sink implements `Disposable` for proper resource cleanup.\n *\n * @since 1.0.0\n */\nexport function getStreamFileSink(\n  path: string,\n  options: StreamFileSinkOptions = {},\n): Sink & Disposable {\n  const highWaterMark = options.highWaterMark ?? 16384;\n  const formatter = options.formatter ?? defaultTextFormatter;\n\n  // Create PassThrough stream for optimal performance\n  const passThrough = new PassThrough({\n    highWaterMark,\n    objectMode: false,\n  });\n\n  // Create WriteStream immediately (not lazy)\n  const writeStream = createWriteStream(path, { flags: \"a\" });\n\n  // Pipe PassThrough to WriteStream for automatic backpressure handling\n  passThrough.pipe(writeStream);\n\n  let disposed = false;\n\n  // Stream-based sink function for high performance\n  const sink: Sink & Disposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Direct write to PassThrough stream\n    passThrough.write(formatter(record));\n  };\n\n  // Minimal disposal\n  sink[Symbol.dispose] = () => {\n    if (disposed) return;\n    disposed = true;\n    passThrough.end();\n    writeStream.end();\n  };\n\n  return sink;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiGA,SAAgB,kBACdA,MACAC,UAAiC,CAAE,GAChB;CACnB,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,MAAM,YAAY,QAAQ,aAAa;CAGvC,MAAM,cAAc,IAAI,YAAY;EAClC;EACA,YAAY;CACb;CAGD,MAAM,cAAc,kBAAkB,MAAM,EAAE,OAAO,IAAK,EAAC;AAG3D,aAAY,KAAK,YAAY;CAE7B,IAAI,WAAW;CAGf,MAAMC,OAA0B,CAACC,WAAsB;AACrD,MAAI,SAAU;AAGd,cAAY,MAAM,UAAU,OAAO,CAAC;CACrC;AAGD,MAAK,OAAO,WAAW,MAAM;AAC3B,MAAI,SAAU;AACd,aAAW;AACX,cAAY,KAAK;AACjB,cAAY,KAAK;CAClB;AAED,QAAO;AACR"}