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

package/streamfilesink.test.ts

@@ -0,0 +1,336 @@
+import { getStreamFileSink } from "./streamfilesink.ts";
+import { suite } from "@alinea/suite";
+import type { LogRecord, Sink } from "@logtape/logtape";
+import { assert } from "@std/assert/assert";
+import { assertEquals } from "@std/assert/equals";
+import { delay } from "@std/async/delay";
+import { join } from "@std/path/join";
+import fs from "node:fs";
+import { tmpdir } from "node:os";
+import { debug, error, fatal, info, warning } from "../logtape/fixtures.ts";
+
+const test = suite(import.meta);
+
+function makeTempFileSync(): string {
+  return join(fs.mkdtempSync(join(tmpdir(), "logtape-")), "logtape.txt");
+}
+
+test("getStreamFileSink() basic functionality", async () => {
+  const path = makeTempFileSync();
+  const sink: Sink & Disposable = getStreamFileSink(path);
+
+  sink(debug);
+  sink(info);
+  sink(warning);
+  sink(error);
+  sink(fatal);
+
+  sink[Symbol.dispose]();
+
+  // Allow stream to fully flush
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assertEquals(
+    content,
+    "2023-11-14 22:13:20.000 +00:00 [DBG] my-app·junk: Hello, 123 & 456!\n" +
+      "2023-11-14 22:13:20.000 +00:00 [INF] my-app·junk: Hello, 123 & 456!\n" +
+      "2023-11-14 22:13:20.000 +00:00 [WRN] my-app·junk: Hello, 123 & 456!\n" +
+      "2023-11-14 22:13:20.000 +00:00 [ERR] my-app·junk: Hello, 123 & 456!\n" +
+      "2023-11-14 22:13:20.000 +00:00 [FTL] my-app·junk: Hello, 123 & 456!\n",
+  );
+});
+
+test("getStreamFileSink() with custom highWaterMark", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path, { highWaterMark: 1024 });
+
+  sink(debug);
+  sink(info);
+  sink[Symbol.dispose]();
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assertEquals(
+    content,
+    "2023-11-14 22:13:20.000 +00:00 [DBG] my-app·junk: Hello, 123 & 456!\n" +
+      "2023-11-14 22:13:20.000 +00:00 [INF] my-app·junk: Hello, 123 & 456!\n",
+  );
+});
+
+test("getStreamFileSink() with custom formatter", async () => {
+  const path = makeTempFileSync();
+  const customFormatter = (record: LogRecord) =>
+    `CUSTOM: ${record.message.join("")}\n`;
+  const sink = getStreamFileSink(path, { formatter: customFormatter });
+
+  sink(debug);
+  sink(info);
+  sink[Symbol.dispose]();
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assertEquals(
+    content,
+    "CUSTOM: Hello, 123 & 456!\n" +
+      "CUSTOM: Hello, 123 & 456!\n",
+  );
+});
+
+test("getStreamFileSink() appends to existing file", async () => {
+  const path = makeTempFileSync();
+
+  // Write initial content
+  fs.writeFileSync(path, "Initial content\n");
+
+  const sink = getStreamFileSink(path);
+  sink(debug);
+  sink[Symbol.dispose]();
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.startsWith("Initial content\n"));
+  assert(content.includes("Hello, 123 & 456!"));
+});
+
+test("getStreamFileSink() high-volume logging", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path, { highWaterMark: 1024 });
+
+  // Write many records quickly to test stream backpressure
+  for (let i = 0; i < 100; i++) {
+    const record: LogRecord = {
+      ...debug,
+      message: [`Log entry ${i}`],
+    };
+    sink(record);
+  }
+
+  sink[Symbol.dispose]();
+  await delay(100); // Allow streams to finish
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  const lines = content.split("\n").filter((line) => line.length > 0);
+  assertEquals(lines.length, 100);
+
+  // Verify first and last entries
+  assert(lines[0].includes("Log entry 0"));
+  assert(lines[99].includes("Log entry 99"));
+});
+
+test("getStreamFileSink() disposal stops writing", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  sink(debug);
+  sink[Symbol.dispose]();
+
+  // Writing after disposal should be ignored
+  sink(info);
+  sink(warning);
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  const lines = content.split("\n").filter((line) => line.length > 0);
+  assertEquals(lines.length, 1); // Only debug record
+  assert(content.includes("[DBG]"));
+  assert(!content.includes("[INF]"));
+  assert(!content.includes("[WRN]"));
+});
+
+test("getStreamFileSink() double disposal", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  sink(debug);
+  sink[Symbol.dispose]();
+  sink[Symbol.dispose](); // Should not throw
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  const lines = content.split("\n").filter((line) => line.length > 0);
+  assertEquals(lines.length, 1);
+});
+
+test("getStreamFileSink() handles rapid disposal", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  sink(debug);
+  // Dispose immediately without waiting
+  sink[Symbol.dispose]();
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes("Hello, 123 & 456!"));
+});
+
+test("getStreamFileSink() concurrent writes", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  // Simulate concurrent logging from different parts of application
+  const promises = [];
+  for (let i = 0; i < 10; i++) {
+    promises.push(
+      new Promise<void>((resolve) => {
+        setTimeout(() => {
+          const record: LogRecord = {
+            ...debug,
+            message: [`Concurrent log ${i}`],
+          };
+          sink(record);
+          resolve();
+        }, Math.random() * 10);
+      }),
+    );
+  }
+
+  await Promise.all(promises);
+  sink[Symbol.dispose]();
+  await delay(100);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  const lines = content.split("\n").filter((line) => line.length > 0);
+  assertEquals(lines.length, 10);
+
+  // All concurrent logs should be present
+  for (let i = 0; i < 10; i++) {
+    assert(content.includes(`Concurrent log ${i}`));
+  }
+});
+
+test("getStreamFileSink() with empty records", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  const emptyRecord: LogRecord = {
+    ...debug,
+    message: [""],
+  };
+
+  sink(emptyRecord);
+  sink[Symbol.dispose]();
+
+  await delay(50);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes("[DBG]"));
+  // Should still write the timestamp and level even with empty message
+  assert(content.includes("2023-11-14 22:13:20.000 +00:00"));
+});
+
+test("getStreamFileSink() with large messages", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  const largeMessage = "x".repeat(10000);
+  const largeRecord: LogRecord = {
+    ...debug,
+    message: [largeMessage],
+  };
+
+  sink(largeRecord);
+  sink[Symbol.dispose]();
+
+  await delay(100); // Give more time for large write
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes(largeMessage));
+  assert(content.includes("[DBG]"));
+});
+
+test("getStreamFileSink() memory efficiency", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  // Create many small records to test memory usage
+  for (let i = 0; i < 1000; i++) {
+    const record: LogRecord = {
+      ...debug,
+      message: [`Memory test ${i}`],
+    };
+    sink(record);
+
+    // Occasionally allow event loop to process
+    if (i % 100 === 0) {
+      await delay(1);
+    }
+  }
+
+  sink[Symbol.dispose]();
+  await delay(200);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  const lines = content.split("\n").filter((line) => line.length > 0);
+  assertEquals(lines.length, 1000);
+
+  // Verify first and last entries
+  assert(lines[0].includes("Memory test 0"));
+  assert(lines[999].includes("Memory test 999"));
+});
+
+test("getStreamFileSink() creates new file when it doesn't exist", async () => {
+  // Use a file that doesn't exist yet
+  const tempDir = fs.mkdtempSync(join(tmpdir(), "logtape-"));
+  const path = join(tempDir, "new-file.log");
+
+  const sink = getStreamFileSink(path);
+  sink(debug);
+  sink[Symbol.dispose]();
+
+  await delay(50);
+
+  // File should have been created
+  assert(fs.existsSync(path));
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes("Hello, 123 & 456!"));
+});
+
+test("getStreamFileSink() multiple instances on same file", async () => {
+  const path = makeTempFileSync();
+
+  const sink1 = getStreamFileSink(path);
+  const sink2 = getStreamFileSink(path);
+
+  sink1(debug);
+  sink2(info);
+
+  sink1[Symbol.dispose]();
+  sink2[Symbol.dispose]();
+
+  await delay(100);
+
+  const content = fs.readFileSync(path, { encoding: "utf-8" });
+  assert(content.includes("[DBG]"));
+  assert(content.includes("[INF]"));
+});
+
+test("getStreamFileSink() stream error handling", async () => {
+  const path = makeTempFileSync();
+  const sink = getStreamFileSink(path);
+
+  sink(debug);
+  sink[Symbol.dispose]();
+  await delay(50);
+
+  // Delete the file after disposal
+  try {
+    fs.unlinkSync(path);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+
+  // These writes after disposal should be ignored
+  sink(info);
+  sink(warning);
+
+  // Test should complete without throwing
+  assert(true);
+});

package/streamfilesink.ts

@@ -0,0 +1,136 @@
+import {
+  defaultTextFormatter,
+  type LogRecord,
+  type Sink,
+  type TextFormatter,
+} from "@logtape/logtape";
+import { createWriteStream } from "node:fs";
+import { PassThrough } from "node:stream";
+
+/**
+ * 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
+ */
+export 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
+ */
+export function getStreamFileSink(
+  path: string,
+  options: StreamFileSinkOptions = {},
+): Sink & Disposable {
+  const highWaterMark = options.highWaterMark ?? 16384;
+  const formatter = options.formatter ?? defaultTextFormatter;
+
+  // Create PassThrough stream for optimal performance
+  const passThrough = new PassThrough({
+    highWaterMark,
+    objectMode: false,
+  });
+
+  // Create WriteStream immediately (not lazy)
+  const writeStream = createWriteStream(path, { flags: "a" });
+
+  // Pipe PassThrough to WriteStream for automatic backpressure handling
+  passThrough.pipe(writeStream);
+
+  let disposed = false;
+
+  // Stream-based sink function for high performance
+  const sink: Sink & Disposable = (record: LogRecord) => {
+    if (disposed) return;
+
+    // Direct write to PassThrough stream
+    passThrough.write(formatter(record));
+  };
+
+  // Minimal disposal
+  sink[Symbol.dispose] = () => {
+    if (disposed) return;
+    disposed = true;
+    passThrough.end();
+    writeStream.end();
+  };
+
+  return sink;
+}

package/tsdown.config.ts

@@ -6,13 +6,13 @@ export default defineConfig({
     sourcemap: true,
   },
   format: ["esm", "cjs"],
-  platform: "neutral",
+  platform: "node",
   unbundle: true,
   inputOptions: {
     onLog(level, log, defaultHandler) {
       if (
         level === "warn" && log.code === "UNRESOLVED_IMPORT" &&
-        ["node:fs", "node:util", "#filesink"].includes(log.exporter ?? "")
+        log.exporter === "#filesink"
       ) {
         return;
       }