@logtape/file/dist/streamfilesink.cjs

File sink and rotating file sink for LogTape

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;