@logtape/file 1.1.1 → 1.1.2

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "license": "MIT",
   "exports": "./src/mod.ts",
   "imports": {

package/dist/dist/filesink.base.d.cts

@@ -0,0 +1,74 @@
+import { StreamSinkOptions } from "@logtape/logtape";
+
+//#region dist/filesink.base.d.ts
+
+//#region src/filesink.base.d.ts
+/**
+ * Options for the {@link getBaseFileSink} function.
+ */
+type FileSinkOptions = StreamSinkOptions & {
+  /**
+   * If `true`, the file is not opened until the first write.  Defaults to `false`.
+   */
+  lazy?: boolean;
+  /**
+   * The size of the buffer to use when writing to the file.  If not specified,
+   * a default buffer size will be used.  If it is less or equal to 0,
+   * the file will be written directly without buffering.
+   * @default 8192
+   * @since 0.12.0
+   */
+  bufferSize?: number;
+  /**
+   * The maximum time interval in milliseconds between flushes.  If this time
+   * passes since the last flush, the buffer will be flushed regardless of size.
+   * This helps prevent log loss during unexpected process termination.
+   * @default 5000
+   * @since 0.12.0
+   */
+  flushInterval?: number;
+  /**
+   * Enable non-blocking mode with background flushing.
+   * When enabled, flush operations are performed asynchronously to prevent
+   * blocking the main thread during file I/O operations.
+   *
+   * @default `false`
+   * @since 1.0.0
+   */
+  nonBlocking?: boolean;
+};
+/**
+ * A platform-specific file sink driver.
+ * @template TFile The type of the file descriptor.
+ */
+
+/**
+ * Get a platform-independent file sink.
+ *
+ * @template TFile The type of the file descriptor.
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
+ */
+
+/**
+ * Options for the {@link getBaseRotatingFileSink} function.
+ */
+interface RotatingFileSinkOptions extends Omit<FileSinkOptions, "lazy"> {
+  /**
+   * The maximum bytes of the file before it is rotated.  1 MiB by default.
+   */
+  maxSize?: number;
+  /**
+   * The maximum number of files to keep.  5 by default.
+   */
+  maxFiles?: number;
+}
+/**
+ * A platform-specific rotating file sink driver.
+ */
+//#endregion
+export { FileSinkOptions, RotatingFileSinkOptions };
+//# sourceMappingURL=filesink.base.d.cts.map

package/dist/dist/filesink.base.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.base.d.cts","names":["Sink","StreamSinkOptions","FileSinkOptions","FileSinkDriver","TFile","Uint8Array","AsyncFileSinkDriver","Promise","RotatingFileSinkOptions","Omit","RotatingFileSinkDriver","AsyncRotatingFileSinkDriver"],"sources":["../filesink.base.d.ts"],"sourcesContent":["import { Sink, StreamSinkOptions } from \"@logtape/logtape\";\n\n//#region src/filesink.base.d.ts\n\n/**\n * Options for the {@link getBaseFileSink} function.\n */\ntype FileSinkOptions = StreamSinkOptions & {\n  /**\n   * If `true`, the file is not opened until the first write.  Defaults to `false`.\n   */\n  lazy?: boolean;\n  /**\n   * The size of the buffer to use when writing to the file.  If not specified,\n   * a default buffer size will be used.  If it is less or equal to 0,\n   * the file will be written directly without buffering.\n   * @default 8192\n   * @since 0.12.0\n   */\n  bufferSize?: number;\n  /**\n   * The maximum time interval in milliseconds between flushes.  If this time\n   * passes since the last flush, the buffer will be flushed regardless of size.\n   * This helps prevent log loss during unexpected process termination.\n   * @default 5000\n   * @since 0.12.0\n   */\n  flushInterval?: number;\n  /**\n   * Enable non-blocking mode with background flushing.\n   * When enabled, flush operations are performed asynchronously to prevent\n   * blocking the main thread during file I/O operations.\n   *\n   * @default `false`\n   * @since 1.0.0\n   */\n  nonBlocking?: boolean;\n};\n/**\n * A platform-specific file sink driver.\n * @template TFile The type of the file descriptor.\n */\ninterface FileSinkDriver<TFile> {\n  /**\n   * Open a file for appending and return a file descriptor.\n   * @param path A path to the file to open.\n   */\n  openSync(path: string): TFile;\n  /**\n   * Write a chunk of data to the file.\n   * @param fd The file descriptor.\n   * @param chunk The data to write.\n   */\n  writeSync(fd: TFile, chunk: Uint8Array): void;\n  /**\n   * Write multiple chunks of data to the file in a single operation.\n   * This is optional - if not implemented, falls back to multiple writeSync calls.\n   * @param fd The file descriptor.\n   * @param chunks Array of data chunks to write.\n   */\n  writeManySync?(fd: TFile, chunks: Uint8Array[]): void;\n  /**\n   * Flush the file to ensure that all data is written to the disk.\n   * @param fd The file descriptor.\n   */\n  flushSync(fd: TFile): void;\n  /**\n   * Close the file.\n   * @param fd The file descriptor.\n   */\n  closeSync(fd: TFile): void;\n}\n/**\n * A platform-specific async file sink driver.\n * @template TFile The type of the file descriptor.\n * @since 1.0.0\n */\ninterface AsyncFileSinkDriver<TFile> extends FileSinkDriver<TFile> {\n  /**\n   * Asynchronously write multiple chunks of data to the file in a single operation.\n   * This is optional - if not implemented, falls back to multiple writeSync calls.\n   * @param fd The file descriptor.\n   * @param chunks Array of data chunks to write.\n   */\n  writeMany?(fd: TFile, chunks: Uint8Array[]): Promise<void>;\n  /**\n   * Asynchronously flush the file to ensure that all data is written to the disk.\n   * @param fd The file descriptor.\n   */\n  flush(fd: TFile): Promise<void>;\n  /**\n   * Asynchronously close the file.\n   * @param fd The file descriptor.\n   */\n  close(fd: TFile): Promise<void>;\n}\n/**\n * Get a platform-independent file sink.\n *\n * @template TFile The type of the file descriptor.\n * @param path A path to the file to write to.\n * @param options The options for the sink and the file driver.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\n\n/**\n * Options for the {@link getBaseRotatingFileSink} function.\n */\ninterface RotatingFileSinkOptions extends Omit<FileSinkOptions, \"lazy\"> {\n  /**\n   * The maximum bytes of the file before it is rotated.  1 MiB by default.\n   */\n  maxSize?: number;\n  /**\n   * The maximum number of files to keep.  5 by default.\n   */\n  maxFiles?: number;\n}\n/**\n * A platform-specific rotating file sink driver.\n */\ninterface RotatingFileSinkDriver<TFile> extends FileSinkDriver<TFile> {\n  /**\n   * Get the size of the file.\n   * @param path A path to the file.\n   * @returns The `size` of the file in bytes, in an object.\n   */\n  statSync(path: string): {\n    size: number;\n  };\n  /**\n   * Rename a file.\n   * @param oldPath A path to the file to rename.\n   * @param newPath A path to be renamed to.\n   */\n  renameSync(oldPath: string, newPath: string): void;\n}\n/**\n * A platform-specific async rotating file sink driver.\n * @since 1.0.0\n */\ninterface AsyncRotatingFileSinkDriver<TFile> extends AsyncFileSinkDriver<TFile> {\n  /**\n   * Get the size of the file.\n   * @param path A path to the file.\n   * @returns The `size` of the file in bytes, in an object.\n   */\n  statSync(path: string): {\n    size: number;\n  };\n  /**\n   * Rename a file.\n   * @param oldPath A path to the file to rename.\n   * @param newPath A path to be renamed to.\n   */\n  renameSync(oldPath: string, newPath: string): void;\n}\n/**\n * Get a platform-independent rotating file sink.\n *\n * This sink writes log records to a file, and rotates the file when it reaches\n * the `maxSize`.  The rotated files are named with the original file name\n * followed by a dot and a number, starting from 1.  The number is incremented\n * for each rotation, and the maximum number of files to keep is `maxFiles`.\n *\n * @param path A path to the file to write to.\n * @param options The options for the sink and the file driver.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\n//#endregion\nexport { AsyncRotatingFileSinkDriver, FileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions };\n//# sourceMappingURL=filesink.base.d.ts.map"],"mappings":";;;;;AA6E2D;;;KAtEtDE,eAAAA,GAAkBD,iBAuGmBQ,GAAAA;EAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAApCD,uBAAAA,SAAgCC,KAAKP"}

package/dist/dist/filesink.node.d.cts

@@ -0,0 +1,45 @@
+import { FileSinkOptions, RotatingFileSinkOptions } from "./filesink.base.cjs";
+import { Sink } from "@logtape/logtape";
+
+//#region dist/filesink.node.d.ts
+
+/**
+ * Get a file sink.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
+ */
+declare function getFileSink(path: string, options?: FileSinkOptions): Sink & Disposable;
+declare function getFileSink(path: string, options: FileSinkOptions & {
+  nonBlocking: true;
+}): Sink & AsyncDisposable;
+/**
+ * Get a rotating file sink.
+ *
+ * This sink writes log records to a file, and rotates the file when it reaches
+ * the `maxSize`.  The rotated files are named with the original file name
+ * followed by a dot and a number, starting from 1.  The number is incremented
+ * for each rotation, and the maximum number of files to keep is `maxFiles`.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
+ */
+declare function getRotatingFileSink(path: string, options?: RotatingFileSinkOptions): Sink & Disposable;
+declare function getRotatingFileSink(path: string, options: RotatingFileSinkOptions & {
+  nonBlocking: true;
+}): Sink & AsyncDisposable;
+//# sourceMappingURL=filesink.node.d.ts.map
+//#endregion
+//#endregion
+export { getFileSink, getRotatingFileSink };
+//# sourceMappingURL=filesink.node.d.cts.map

package/dist/dist/filesink.node.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.node.d.cts","names":["AsyncRotatingFileSinkDriver","FileSinkOptions","RotatingFileSinkDriver","RotatingFileSinkOptions","Sink","nodeDriver","nodeAsyncDriver","getFileSink","Disposable","AsyncDisposable","getRotatingFileSink"],"sources":["../filesink.node.d.ts"],"sourcesContent":["import { AsyncRotatingFileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions } from \"./filesink.base.js\";\nimport { Sink } from \"@logtape/logtape\";\n\n//#region src/filesink.node.d.ts\n\n/**\n * A Node.js-specific file sink driver.\n */\ndeclare const nodeDriver: RotatingFileSinkDriver<number | void>;\n/**\n * A Node.js-specific async file sink driver.\n * @since 1.0.0\n */\ndeclare const nodeAsyncDriver: AsyncRotatingFileSinkDriver<number | void>;\n/**\n * Get a file sink.\n *\n * Note that this function is unavailable in the browser.\n *\n * @param path A path to the file to write to.\n * @param options The options for the sink.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\ndeclare function getFileSink(path: string, options?: FileSinkOptions): Sink & Disposable;\ndeclare function getFileSink(path: string, options: FileSinkOptions & {\n  nonBlocking: true;\n}): Sink & AsyncDisposable;\n/**\n * Get a rotating file sink.\n *\n * This sink writes log records to a file, and rotates the file when it reaches\n * the `maxSize`.  The rotated files are named with the original file name\n * followed by a dot and a number, starting from 1.  The number is incremented\n * for each rotation, and the maximum number of files to keep is `maxFiles`.\n *\n * Note that this function is unavailable in the browser.\n *\n * @param path A path to the file to write to.\n * @param options The options for the sink and the file driver.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\ndeclare function getRotatingFileSink(path: string, options?: RotatingFileSinkOptions): Sink & Disposable;\ndeclare function getRotatingFileSink(path: string, options: RotatingFileSinkOptions & {\n  nonBlocking: true;\n}): Sink & AsyncDisposable;\n//# sourceMappingURL=filesink.node.d.ts.map\n//#endregion\nexport { getFileSink, getRotatingFileSink, nodeAsyncDriver, nodeDriver };\n//# sourceMappingURL=filesink.node.d.ts.map"],"mappings":";;;;;;AA4B0B;AAAA;;;;;AAiB8E;AAAA;;;iBApBvFO,WAAAA,CAuBbH,IAAAA,EAAAA,MAAAA,EAAAA,OAAAA,CAAAA,EAvBiDH,eAuBjDG,CAAAA,EAvBmEA,IAuBnEA,GAvB0EI,UAuB1EJ;iBAtBaG,WAAAA,CAsBNE,IAAAA,EAAAA,MAAAA,EAAAA,OAAAA,EAtByCR,eAsBzCQ,GAAAA;EAAe,WAAA,EAAA,IAAA;IApBtBL,OAAOK;;;;;;;;;;;;;;;;;iBAiBMC,mBAAAA,yBAA4CP,0BAA0BC,OAAOI;iBAC7EE,mBAAAA,wBAA2CP;;IAExDC,OAAOK"}

package/dist/mod.d.cts

@@ -1,4 +1,4 @@
 import { FileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions } from "./filesink.base.cjs";
 import { StreamFileSinkOptions, getStreamFileSink } from "./streamfilesink.cjs";
-import { getFileSink, getRotatingFileSink } from "#filesink";
+import { getFileSink, getRotatingFileSink } from "./dist/filesink.node.cjs";
 export { FileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions, StreamFileSinkOptions, getFileSink, getRotatingFileSink, getStreamFileSink };

package/dist/streamfilesink.cjs

@@ -53,7 +53,8 @@ const node_stream = require_rolldown_runtime.__toESM(require("node:stream"));
 *             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.
+*          The returned sink implements `AsyncDisposable` for proper resource cleanup
+*          that waits for all data to be flushed to disk.
 *
 * @since 1.0.0
 */

package/dist/streamfilesink.d.cts

@@ -84,7 +84,8 @@ interface StreamFileSinkOptions {
  *             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.
+ *          The returned sink implements `AsyncDisposable` for proper resource cleanup
+ *          that waits for all data to be flushed to disk.
  *
  * @since 1.0.0
  */

package/dist/streamfilesink.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"streamfilesink.d.cts","names":[],"sources":["../src/streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AA+EA;;;;;AAGyB;UAlFR,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDP,iBAAA,yBAEL,wBACR,OAAO"}
+{"version":3,"file":"streamfilesink.d.cts","names":[],"sources":["../src/streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AAgFA;;;;;AAGyB;UAnFR,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyDP,iBAAA,yBAEL,wBACR,OAAO"}

package/dist/streamfilesink.d.ts

@@ -84,7 +84,8 @@ interface StreamFileSinkOptions {
  *             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.
+ *          The returned sink implements `AsyncDisposable` for proper resource cleanup
+ *          that waits for all data to be flushed to disk.
  *
  * @since 1.0.0
  */

package/dist/streamfilesink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamfilesink.d.ts","names":[],"sources":["../src/streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AA+EA;;;;;AAGyB;UAlFR,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDP,iBAAA,yBAEL,wBACR,OAAO"}
+{"version":3,"file":"streamfilesink.d.ts","names":[],"sources":["../src/streamfilesink.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AAgFA;;;;;AAGyB;UAnFR,qBAAA;;;;;;;;;;;;;;;;;;;;;;uBAuBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyDP,iBAAA,yBAEL,wBACR,OAAO"}

package/dist/streamfilesink.js

@@ -52,7 +52,8 @@ import { PassThrough } from "node:stream";
 *             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.
+*          The returned sink implements `AsyncDisposable` for proper resource cleanup
+*          that waits for all data to be flushed to disk.
 *
 * @since 1.0.0
 */

package/dist/streamfilesink.js.map

@@ -1 +1 @@
-{"version":3,"file":"streamfilesink.js","names":["path: string","options: StreamFileSinkOptions","sink: Sink & AsyncDisposable","record: LogRecord"],"sources":["../src/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 & AsyncDisposable {\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 & AsyncDisposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Direct write to PassThrough stream\n    passThrough.write(formatter(record));\n  };\n\n  // Asynchronous disposal with sequential stream closure\n  sink[Symbol.asyncDispose] = async () => {\n    if (disposed) return;\n    disposed = true;\n\n    // Wait for PassThrough to drain if needed\n    if (passThrough.writableNeedDrain) {\n      await new Promise<void>((resolve) => {\n        passThrough.once(\"drain\", resolve);\n      });\n    }\n\n    // End the PassThrough stream first and wait for it to finish\n    await new Promise<void>((resolve) => {\n      passThrough.once(\"finish\", resolve);\n      passThrough.end();\n    });\n\n    // Wait for WriteStream to finish and close (piped streams auto-close)\n    await new Promise<void>((resolve) => {\n      if (writeStream.closed || writeStream.destroyed) {\n        resolve();\n        return;\n      }\n      writeStream.once(\"close\", resolve);\n    });\n  };\n\n  return sink;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiGA,SAAgB,kBACdA,MACAC,UAAiC,CAAE,GACX;CACxB,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,OAA+B,CAACC,WAAsB;AAC1D,MAAI,SAAU;AAGd,cAAY,MAAM,UAAU,OAAO,CAAC;CACrC;AAGD,MAAK,OAAO,gBAAgB,YAAY;AACtC,MAAI,SAAU;AACd,aAAW;AAGX,MAAI,YAAY,kBACd,OAAM,IAAI,QAAc,CAAC,YAAY;AACnC,eAAY,KAAK,SAAS,QAAQ;EACnC;AAIH,QAAM,IAAI,QAAc,CAAC,YAAY;AACnC,eAAY,KAAK,UAAU,QAAQ;AACnC,eAAY,KAAK;EAClB;AAGD,QAAM,IAAI,QAAc,CAAC,YAAY;AACnC,OAAI,YAAY,UAAU,YAAY,WAAW;AAC/C,aAAS;AACT;GACD;AACD,eAAY,KAAK,SAAS,QAAQ;EACnC;CACF;AAED,QAAO;AACR"}
+{"version":3,"file":"streamfilesink.js","names":["path: string","options: StreamFileSinkOptions","sink: Sink & AsyncDisposable","record: LogRecord"],"sources":["../src/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 `AsyncDisposable` for proper resource cleanup\n *          that waits for all data to be flushed to disk.\n *\n * @since 1.0.0\n */\nexport function getStreamFileSink(\n  path: string,\n  options: StreamFileSinkOptions = {},\n): Sink & AsyncDisposable {\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 & AsyncDisposable = (record: LogRecord) => {\n    if (disposed) return;\n\n    // Direct write to PassThrough stream\n    passThrough.write(formatter(record));\n  };\n\n  // Asynchronous disposal with sequential stream closure\n  sink[Symbol.asyncDispose] = async () => {\n    if (disposed) return;\n    disposed = true;\n\n    // Wait for PassThrough to drain if needed\n    if (passThrough.writableNeedDrain) {\n      await new Promise<void>((resolve) => {\n        passThrough.once(\"drain\", resolve);\n      });\n    }\n\n    // End the PassThrough stream first and wait for it to finish\n    await new Promise<void>((resolve) => {\n      passThrough.once(\"finish\", resolve);\n      passThrough.end();\n    });\n\n    // Wait for WriteStream to finish and close (piped streams auto-close)\n    await new Promise<void>((resolve) => {\n      if (writeStream.closed || writeStream.destroyed) {\n        resolve();\n        return;\n      }\n      writeStream.once(\"close\", resolve);\n    });\n  };\n\n  return sink;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkGA,SAAgB,kBACdA,MACAC,UAAiC,CAAE,GACX;CACxB,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,OAA+B,CAACC,WAAsB;AAC1D,MAAI,SAAU;AAGd,cAAY,MAAM,UAAU,OAAO,CAAC;CACrC;AAGD,MAAK,OAAO,gBAAgB,YAAY;AACtC,MAAI,SAAU;AACd,aAAW;AAGX,MAAI,YAAY,kBACd,OAAM,IAAI,QAAc,CAAC,YAAY;AACnC,eAAY,KAAK,SAAS,QAAQ;EACnC;AAIH,QAAM,IAAI,QAAc,CAAC,YAAY;AACnC,eAAY,KAAK,UAAU,QAAQ;AACnC,eAAY,KAAK;EAClB;AAGD,QAAM,IAAI,QAAc,CAAC,YAAY;AACnC,OAAI,YAAY,UAAU,YAAY,WAAW;AAC/C,aAAS;AACT;GACD;AACD,eAAY,KAAK,SAAS,QAAQ;EACnC;CACF;AAED,QAAO;AACR"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "File sink and rotating file sink for LogTape",
   "keywords": [
     "logging",
@@ -57,7 +57,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@logtape/logtape": "^1.1.1"
+    "@logtape/logtape": "^1.1.2"
   },
   "devDependencies": {
     "@alinea/suite": "^0.6.3",

package/src/streamfilesink.test.ts

@@ -138,8 +138,6 @@ test("getStreamFileSink() disposal stops writing", async () => {
   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

package/src/streamfilesink.ts

@@ -91,7 +91,8 @@ export interface StreamFileSinkOptions {
  *             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.
+ *          The returned sink implements `AsyncDisposable` for proper resource cleanup
+ *          that waits for all data to be flushed to disk.
  *
  * @since 1.0.0
  */